Аутентификация

Чтобы начать использовать API, уточните актуальную версию API, создайте новую сессию и добавьте полученный токен во все запросы данной сессии.

Запрос версий API

Получите актуальную версию API и URL для создание сессии.

Request

Отправьте GET-запрос на https://{SITE}/api/versions.

{SITE} — зависит от региона, в котором размещается ваш виртуальный ЦОД. Он отображается в ссылке на консоль управления Enterprise https://{SITE}/tenant/my-tenant/. Ее мы отправляем при подключении услуги. Например, для региона PD01 параметр {SITE} принимает значение vcd.sbercloud.ru, для PD11 — vcd11.msk.sbercloud.ru.

curl -k --request GET "https://{SITE}/api/versions"

Response

<SupportedVersions>

   <VersionInfo deprecated="true">
      <Version>30.0</Version>
      <LoginUrl>https://vcd.sbercloud.ru/api/sessions</LoginUrl>
   </VersionInfo>

   <VersionInfo deprecated="true">
        <Version>31.0</Version>
        <LoginUrl>https://vcd.sbercloud.ru/api/sessions</LoginUrl>
   </VersionInfo>

   <VersionInfo deprecated="false">
       <Version>34.0</Version>
       <LoginUrl>https://vcd.sbercloud.ru/api/sessions</LoginUrl>
   </VersionInfo>

   <VersionInfo deprecated="false">
      <Version>35.0</Version>
      <LoginUrl>https://vcd.sbercloud.ru/api/sessions</LoginUrl>
   </VersionInfo>

   ...

</SupportedVersions>
  1. Выберите из списка любую актуальную версию API. Если номер версии не принципиален, рекомендуем выбрать последнюю актуальную.

    У актуальных версий атрибут deprecated принимает значение false, у неактуальных true. Актуальных и неактуальных версий может быть несколько. В примере ответа выше первые две версии не актуальны, а вторые две актуальны.

  2. Для выбранной версии узнайте ее номер (Version) и URL для создания сессии (LoginUrl). Они понадобятся для создания сессии.

    В примере ответа выше для последней актуальной версии API:

    • {VERSION}35.0;

    • {LOGINURL}https://vcd.sbercloud.ru/api/sessions.

Создание сессии

Примечание

Ниже рассмотрен способ создания сессии с помощью указания логина и пароля для доступа к тенанту. Вы также можете сгенерировать специальный токен API, чтобы не вводить учетные данные каждый раз при создании сессии. Подробнее — API Token.

Чтобы создать сессию и получить токен необходимо знать:

  • {VERSION} — номер версии API из предыдущего шага.

  • {LOGINURL} — URL для создания сессии из предыдущего шага.

  • tenant_name — название тенанта, которое можно посмотреть в URL-адресе для входа в консоль управления Enterprise https://vcd.sbercloud.ru/tenant/{tenant_name}.

  • user — логин для входа в консоль управления Enterprise.

  • password — пароль для входа в консоль управления Enterprise.

Данные для входа в консоль управления Enterprise мы отправляем при подключении услуги.

Request

Отправьте POST-запрос на {LOGINURL}.

curl -k -I --header "Accept: application/*;version={VERSION}" --header "Authorization: Basic {CREDENTIALS}" --request POST "{LOGINURL}"
  • Basic / Basic Auth — тип утентификации.

  • {CREDENTIALS} — учетные данные для доступа к консоли управления Enterprise в формате user@tenant_name:password в кодировке MIME Base64.

    Чтобы получить {CREDENTIALS} вы можете воспользоваться любым инструментом для перевода из текстового формата в MIME Base64, например Base64-онлайн декодировщик.

Подсказка

Для формирования заголовка Authorization удобно использовать Postman, поскольку не нужно отдельно переводить данные в формат MIME Base64. На вкладке Authorization:

  1. В поле Type выберите «Basic Auth».

  2. В поле Username укажите логин и название тенанта в формате user@tenant_name.

  3. В поле Password укажите пароль.

Чтобы скопировать полученный заголовок Authorization, откройте код запроса.

Response

Если запрос составлен корректно, сервер вернет:

  • статус 200 ОК;

  • заголовок c токеном eyJhbG...;

  • заголовок c типом токена Bearer;

  • объекты, к которым есть доступ для указанной учетной записи.

После отправки запроса могут появиться следующие ошибки:

Код ошибки

Причина ошибки

Возможное решение

403

В запросе отсутствует заголовок Authorization.

Добавьте в запрос заголовок Authorization с учетными данными для входа.

401

Учетные данные некорректные.

В заголовке Authorization проверьте корректность учетных данных и формата, в котором они указаны.

Добавление токена в заголовок Authorization

Для последующих запросов в данной сессии добавьте в заголовок Authorization полученные токен и тип токена.

--header "Authorization: {TYPE} {TOKEN}"

После добавления токена в запросы может появиться ошибка:

Код ошибки

Причина ошибки

Возможное решение

403: Forbidden

Срок действия токена истекает, если REST-клиент 30 минут не отправляет запросы. Ошибка указывает на то, что пользователь не авторизован или запрашиваемый объект не существует.

После истечения срока действия токена, создайте новую сессию. Если срок действия токена не истек, рекомендуем проверить наличие запрашиваемых объектов и правильность указания их идентификаторов в запросе.

См.также

Полное описание конечных точек, методов и параметров запросов можно посмотреть по ссылке https://{SITE}/docs/.