Cluster · разработчикам

Session

Базовый URL и общие заголовки запросов. Объект не является отдельным сетевым профилем ядра.

Все методы SDK · Типы и ошибки

Получение объекта

session = app.web.session("https://example.org/api/")

__init__

Создаёт Session. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

def __init__(web: Web, url: str, headers: dict[str, str] | None = None) -> None: ...

Аргументы

• web: Web, обязательный. Сетевая служба текущего приложения.
• url: str, обязательный. Полный HTTPS-адрес; для Socket требуется WSS. Ядро проверяет домен и допустимость адреса.
• headers: dict[str, str] | None, по умолчанию None. HTTP-заголовки. Копируются в объект; None означает пустой набор.

Результат

None. Создаёт Session. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

Права

Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.

Ошибки

• Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.

Пример

# Обычный способ получения объекта:
session = app.web.session("https://example.org/api/")

request

Соединяет базовый URL с путём и создаёт запрос. Другой протокол или хост запрещены, чтобы не передавать туда общие заголовки.

def request(path: str = '', method: str = 'GET') -> Request: ...

Аргументы

• path: str, по умолчанию ''. Относительный путь внутри того же origin. Абсолютный URL другого origin отклоняется.
• method: str, по умолчанию 'GET'. Имя метода выбранного API. Регистр значим.

Результат

Request. Соединяет базовый URL с путём и создаёт запрос. Другой протокол или хост запрещены, чтобы не передавать туда общие заголовки.

Права

Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.

Ошибки

• ValueError('A session cannot send its headers to another origin'): условие проверяется до продолжения операции.

Пример

result = session.request()

get

Выполняет GET по относительному пути с query-параметрами.

async def get(path: str = '', **query: QueryValue) -> Response: ...

Аргументы

• path: str, по умолчанию ''. Относительный путь внутри того же origin. Абсолютный URL другого origin отклоняется.
• query: QueryValue, произвольные именованные аргументы. Именованные параметры URL. None удаляет параметр; список создаёт повторения.

Результат

Response. Выполняет GET по относительному пути с query-параметрами.

Права

Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await session.get(page=1)

post

Выполняет POST по относительному пути с JSON-телом.

async def post(path: str = '', data: JSON = None) -> Response: ...

Аргументы

• path: str, по умолчанию ''. Относительный путь внутри того же origin. Абсолютный URL другого origin отклоняется.
• data: JSON, по умолчанию None. Данные выбранной операции. Форма и ограничения описаны ниже; передаваемые JSON-значения копируются.

Результат

Response. Выполняет POST по относительному пути с JSON-телом.

Права

Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await session.post()

header

Меняет общий заголовок для будущих запросов. Уже созданные запросы имеют собственные копии заголовков.

def header(name: str, value: str) -> Self: ...

Аргументы

• name: str, обязательный. Имя HTTP-заголовка без учёта регистра.
• value: str, обязательный. Строковое значение HTTP-заголовка.

Результат

Self. Тот же объект после успешной операции. Меняет общий заголовок для будущих запросов. Уже созданные запросы имеют собственные копии заголовков.

Права

Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.

Ошибки

• Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.

Пример

result = session.header("Accept", "application/json")