Получаем доступ к API

Обновлено 12 ноября 2024

Токен доступа необходим для авторизации запросов:

• API синтеза речи.
• API распознавания речи.

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

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

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

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

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

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

Авторизационные данные — строка, полученная в результате кодирования клиентского идентификатора (Client ID) и ключа (Client Secret) API в Base64.

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

1. Создайте проект SaluteSpeech.

Если вы регистрировались в личном кабинете с помощью электронной почты, подтвердите адрес в Настройках профиля.

2. Перейдите на главную страницу проекта.

На главной странице проекта вы можете найти следующие параметры:

• Client Id - идентификатор пользователя;
• SCOPE - тип использования в системе.

Чтобы получить авторизационные данные в первый раз, нажмите Получить Client Secret на странице справа.

Откроется новое окно Client Secret. Скопируйте значение из поля Авторизационные данные, чтобы получить токен доступа для вызова API.

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

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

Client Secret могут получить только пользователи с ролями Владелец и Администратор — для остальных ролей кнопка Получить 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 — для юридических лиц (постоплата); SALUTE_SPEECH_B2B — для юридических лиц (предоплата); SBER_SPEECH — устаревшее значение для юридических лиц.

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

RqUID — уникальный идентификатор запроса. Соответствует формату uuid4.

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

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

Поле	Описание
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. Если токен есть, но просрочен, то придет ошибка с сообщением о токене с истекшим сроком действия. В этом случае вам нужно получить новый валидный токен.

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