Какой формат запроса API?
В этом разделе описывается структура запроса REST API и используется IAM API для получения пользовательского токена в качестве примера, демонстрирующего, как вызывать API. Полученный токен затем можно использовать для аутентификации в других API-запросах.
Формат запроса URI
Используется формат запроса URI:
{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}
Несмотря на то, что URI запроса включен в заголовок запроса, большинство языков программирования или фреймворков требуют, чтобы URI запроса передавался отдельно.
URI-scheme — протокол для передачи запросов. Все API-интерфейсы используют HTTPS.
Endpoint — доменное имя или IP-адрес сервера, на котором находится служба REST. Endpoint варьируется в зависимости от служб в разных регионах.
По умолчанию следует использовать регион ru-moscow-1 для iam.ru-moscow-1.hc.sbercloud.ru.
resource-path — путь доступа по API для выполнения указанной операции. Получите путь из URI API. Например, путь к ресурсу API, используемого для получения пользовательского токена будет выглядеть так: /v3/auth/tokens.
query-string — необязательный параметр. Убедитесь, что перед каждым запросом, имеющим формат «Parameter name=Parameter value», стоит знак вопроса (?). Например, «?limit=10» указывает, что будет отображено не более 10 записей данных.
Чтобы упростить отображение URI, каждому API предоставляется только путь к ресурсу и метод запроса. URI-схема всех API-интерфейсов — HTTPS, а Endpoints всех API-интерфейсов в одном регионе идентичны.
Методы запроса
Следующие методы запроса по протоколу HTTP используются для отправки запроса на сервер:
GET
PUSH
POST
DELETE
HEAD
PATCH
Например, для метода POST запрос может выглядеть следующим образом:
POST https://iam.ru-moscow-1.hc.sbercloud.ru/v3/auth/tokens
Заголовок запроса
К заголовку запроса можно добавить дополнительные поля. Например, для запроса информации об аутентификации необходимо добавить параметр Content-Type, который определяет тип тела запроса.
В таблице показаны популярные заголовки запросов:
Параметр | Описание | Обязательно или нет | Пример |
|---|---|---|---|
Host | Указывает доменное имя сервера и номер порта запрашиваемых ресурсов. Значение может быть получено из URL-адреса API-интерфейса сервиса. Значение задается в формате «Имя хоста:Номер порта». Если номер порта не указан, используется порт по умолчанию. Номер порта по умолчанию для https — «443». | Не обязательно. Это поле является обязательным для аутентификации по AK/SK. | code.test.com или code.test.com:443 |
Content-Type | Задает тип (или формат) тела сообщения. Рекомендуется использовать значение по умолчанию application/json. | Обязательно | application/json |
Content-Length | Задает длину тела запроса. Единица измерения — байт. | Не обязательно | 3495 |
X-Project-Id | ID проекта. Для его получения следуйте шагам в инструкции Obtaining the Account ID, Project ID, Log Group ID, and Log Stream ID (en). | Не обязательно | e9993fc787d94b6c886cbaa340f9c0f4 |
X-Auth-Token | Токен пользователя. Это ответ на API для получения пользовательского токена. Этот API не требует аутентификации. После обработки запроса значение X-Subject-Token в заголовке ответа является значением токена. | Не обязательно. Обязательно только аутентификации токена. | MIIPAgYJKoZIhvcNAQcCo…ggg1BBIINPXsidG9rZ (токен для примера) |
- Формат запроса URI
- Методы запроса
- Заголовок запроса