ym88659208ym87991671
Получение токена доступа для авторизации запросов к API сервиса синтеза и распознавания речи SaluteSpeech | Документация для разработчиков

Получаем Access Token

Обновлено 20 марта 2024

Доступ к сервису SaluteSpeech осуществляется через Access Token. Для вызова API используется протокол авторизации OAuth 2.0: для запроса API нужно получить токен (Access Token). API защищен от несанкционированного доступа. Перед подключением проводятся проверки:

  • проверка наличия действующей подписки у приложения, которое инициирует вызов,
  • проверка сессии токена,
  • проверка запроса и ответа на соответствие схемам API.

Чтобы подключить API:

  1. Получите авторизационные данные для вашего приложения.
  2. Добавьте сценарий получения Access Token в сервис для вызова API.
  3. Используйте Access Token для отправки запросов в сервис SaluteSpeech.

Токен имеет срок действия не более 30 минут. Сервис аутентификации в открытом виде передает срок окончания действия токена. Полученный токен включает в себя срок действия в отдельном поле.

Шаг 1. Получите авторизационные данные

Чтобы получить авторизационные данные:

  1. Создайте проект SaluteSpeech.
  2. Отправьте проект на модерацию.
  3. Если вы регистрировались в личном кабинете с помощью электронной почты, то подтвердите адрес в Настройках профиля.

После завершения модерации вы получите доступ к авторизационным данным: на странице появится поле, где вы сможете скопировать Client Id, и кнопка для генерации Client Secret.

Client Secret могут получить только пользователи с ролями Владелец и Администратор — для остальных ролей кнопка Сгенерировать новый Client Secret будет неактивна. Подробнее о ролях и их возможностях — в разделе Настройка команды в пространстве.

Client Secret отображается только один раз и не хранится в Studio.

При компрометации или утере параметра вы можете сгенерировать новый Client Secret.

Шаг 2. Добавьте Access Token в сервис API

На этом шаге необходимо добавить сценарий получения Access Token в сервис вызова API.

Формат запроса

Запрос отправляется на адрес:

https://ngw.devices.sberbank.ru:9443/api/v2/oauth

Заголовки запроса

ПолеОписание

Authorization

Обязательное

Авторизационные данные. В проекте SaluteSpeech нажмите Сгенерировать новый Client Secret и скопируйте значение из поля Авторизационные данные.

Подробнее — в разделе Подключаем сервис

RqUID

Обязательное

Уникальный идентификатор запроса. Формируется по паттерну

(([0-9a-fA-F-])36)

Параметр для журналирования входящих вызовов и разбора инцидентов. Для создания уникального идентификатора можно использовать стандартные библиотеки и классы для генерации UUID и GUID.

Content-Type

Обязательное

Формат данных, передаваемых в теле запроса.

Единственное возможное значение: application/x-www-form-urlencoded

Тело запроса

ПолеОписание

scope

Обязательное

Версия API, к которой предоставляется доступ. Указана в проекте SaluteSpeech.

Возможные значения:

  • SALUTE_SPEECH_PERS — для физических лиц.
  • SALUTE_SPEECH_CORP — для юридических лиц.
  • SBER_SPEECH — устаревшее значение для юридических лиц

curl --location --request POST 'https://ngw.devices.sberbank.ru:9443/api/v2/oauth' \
--header 'Authorization: Basic <Авторизационные_данные>' \
--header 'RqUID: <Значение UUID или GUID>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'scope=<Версия API>'

Формат ответа

ПолеОписание

access_token

Обязательное

Сгенерированный Access Token

expires_at

Обязательное

Unix-время завершения действия Access Token в миллисекундах

{
"access_token": "eyJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.DCXAAnwXjmRleOrIJcXDWbQwsP5UGSptcY3x5XXRkYZm6x3QkDQBL63DKQZzwrwmtuFbKajq6ULHuQhsmGax-l_R6AhRkr7pWzJi1jpzCenq9PAN2UjF0BX_IiDRgmEExH6_2OtHaJ_7KbudukIOLEgxD9l8WcXFY992dgqLL6eK2nnnUvyfmr4ITc9PWuAFsMIO6jweNFw0e9vRYEDkAbnv9EGR-w9CGwfBsHNWZwZlo7fyu07fkSfmqmGdBvU4344344luNNrHwktSGOzNhpLhu0-0A3KI950vmp_37QY8isDi3epGU3HShdrBZkk70fdXxBKQA.MV2IksoyxTV_c-qm6hSXaQ.LUT4JqOzKqmFOR07-Asq7Fhqj_eYSTXcsJAK-JchmM1QUqhPLBXsUyXXh6ZcjsnN7Q0QXzuBlSjaBWekgWANDirI6HP_MsEM4FxfJAOh73aowC700cEQPPYAxzPYG0d4bOqsZh8Ss57lJB2VM7M6Y2FcG2hb5Q0i2zPskqSWxXejuCyr2uIlY7Fe4bu4NUqtCaKJVwqriVWLfbA0OzZyA0osDc42Ba0u1adFAdaZDCE.IlKOixP8hSUimEI2pdP118Tx0StZjcLdbSauE5R0YAA",
"expires_at": 1617814516729
}

Коды ошибок

ОшибкаПример
400
Некорректные авторизационные данные
{"code": 4, "message": "Can't decode 'Authorization' header"}
400
Некорректный scope
{"code": 1, "message": "scope data format invalid"}
или
{"code": 7, "message": "scope from db not fully includes consumed scope"}
400
Не указан scope
{"code": 5, "message": "scope is empty"}
401
Не авторизован
500
Внутренняя ошибка сервиса

Шаг 3. Используйте токен

Сделайте запрос с заголовком Authorization с Bearer Access token.

  1. Если токен валиден, то запрос передастся дальше в сервис SaluteSpeech для синтеза текста из запроса.
  2. Если токена нет или формат токена неверен, то придет ошибка с сообщением о неудачной аутентификации.
  3. Если токен есть, но просрочен, то придет ошибка с сообщением о токене с истекшим сроком действия. В этом случае вам нужно получить новый валидный токен.

Перед каждым запросом всегда проверяйте время жизни токена. Если до его истечения остается менее минуты, получите новый токен доступа к сервису SaluteSpeech.

ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.