Поделиться через

Справочник по программному интерфейсу Direct Line API 3.0

  • Статья

C помощью API Direct Line 3.0 можно взаимодействовать с ботом в клиентском приложении. Direct Line API 3.0 использует отраслевые стандарты REST и JSON по протоколу HTTPS.

Базовый универсальный код ресурса (URI)

Чтобы получить доступ к API Direct Line 3.0, используйте один из этих базовых URI для всех запросов API:

  • Для глобальных ботов используйте https://directline.botframework.com

  • Для регионального бота введите следующий универсальный код ресурса (URI) в соответствии с выбранным регионом:

    Область/регион Базовый универсальный код ресурса (URI)
    Европа https://europe.directline.botframework.com
    Индия https://india.directline.botframework.com

Совет

Запрос может завершиться ошибкой, если вы используете глобальный базовый универсальный код ресурса (URI) для регионального бота, так как некоторые запросы могут выйти за рамки географических границ.

Заголовки

Кроме стандартных заголовков HTTP-запроса запрос Direct Line API должен включать заголовок Authorization, определяющий секрет или токен для аутентификации клиента, который выполняет запрос. Используйте для заголовка Authorization следующий формат:

Authorization: Bearer SECRET_OR_TOKEN

Дополнительные сведения о том, как получить секрет или токен, который клиент может использовать для аутентификации запросов Direct Line API, см. в руководстве по аутентификации.

Коды состояния HTTP

Код состояния HTTP, который возвращается с каждым ответом, указывает результат соответствующего запроса.

Код состояния HTTP Значение
200 Запрос выполнен успешно.
201 Запрос выполнен успешно.
202 Запрос принят для обработки.
204 Запрос успешно выполнен, но содержимое не было возвращено.
400 Запрос неправильный или имеет недопустимый формат.
401 Клиент не авторизован для выполнения запроса. Часто этот код состояния возникает, когда заголовок Authorization отсутствует или имеет недопустимый формат.
403 Клиент не может выполнять запрошенную операцию. Операция может завершиться ошибкой по следующим причинам.
  • Недопустимый маркер: если запрос использует маркер, который ранее был допустимым, но истек, свойство Error, возвращаемое в объекте ErrorResponse, code имеет TokenExpiredзначение .
  • Нарушение границ данных: если бот является региональным ботом, но базовый URI не является региональным, некоторые запросы могут выйти за рамки географических границ.
  • Недопустимый целевой ресурс: целевой бот или сайт является недопустимым или удален.
404 Запрошенный ресурс не найден. Обычно этот код состояния обозначает, что в запросе указан недопустимый URI.
500 Внутренняя ошибка сервера в службе Direct Line
502 Бот недоступен или вернул ошибку. Это обобщенный код ошибки.

Примечание.

Также в пути подключения WebSocket используется код состояния HTTP 101, но, вероятно, его уже обрабатывает ваш клиент WebSocket.

ошибки

Любой ответ, указывающий код состояния HTTP в диапазоне 4xx или 5xx, будет содержать в тексте ответа объект ErrorResponse, который предоставляет сведения об ошибке. Если вы получите сообщение об ошибке в диапазоне 4xx, проверьте объект ErrorResponse, чтобы определить причину ошибки и устранить проблему, прежде чем повторно отправлять запрос.

Примечание.

Коды состояния HTTP и значения в свойстве code в объекте ErrorResponse являются неизменными. Значения, указанные в свойстве message в объекте ErrorResponse, могут изменяться со временем.

В следующих фрагментах кода представлены пример запроса и ответ на него, содержащий ошибку.

Запросить

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]

Response

HTTP/1.1 502 Bad Gateway
[other headers]

{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

Операции с токенами

Используйте эти операции для создания или обновления токена, который клиент может использовать для доступа к одному диалогу.

Операция Description
Создание токена Создает токен для нового диалога.
Обновление токена Обновляет токен.

Создать маркер

Создает токен, действующий для одного диалога.

POST /v3/directline/tokens/generate
Содержимое Description
Текст запроса Объект TokenParameters
Возвраты Объект Conversation.

Refresh Token

Обновляет токен.

POST /v3/directline/tokens/refresh
Содержимое Description
Текст запроса Н/Д
Возвраты Объект Conversation.

Операции диалога

Используйте эти операции, чтобы открыть диалог с ботом и обменяться сообщениями между клиентом и ботом.

Операция Description
Начало диалога Открывает новый диалог с ботом.
Получение сведений о диалоге Получает сведения о существующем диалоге. Эта операция создает URL-адрес потока WebSocket, который позволяет клиенту повторно подключиться к диалогу.
Получение действий Получает действия от бота.
Отправка действия Отправляет действие боту.
Загрузка и отправка файлов Загружает и отправляет файлы в виде вложений.

Начало диалога

Открывает новый диалог с ботом.

POST /v3/directline/conversations
Содержимое Description
Текст запроса Объект TokenParameters
Возвраты Объект Conversation.

Получение сведений о диалоге

Получает информацию о существующем диалоге и создает URL-адрес потока WebSocket, который позволяет клиенту повторно подключиться к диалогу. Вы можете включить необязательный параметр watermark в URI запроса, чтобы указать последнее сообщение, увиденное клиентом.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
Содержимое Description
Текст запроса Н/Д
Возвраты Объект Conversation.

Получение действий

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

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
Содержимое Description
Текст запроса Н/Д
Возвраты Объект ActivitySet. Ответ содержит watermark как свойство объекта ActivitySet. Клиенты должны постранично просмотреть доступные действия, переходя по значению watermark, пока действия не перестанут возвращаться.

Отправка действия

Отправляет действие боту.

POST /v3/directline/conversations/{conversationId}/activities
Содержимое Description
Текст запроса Объект Activity
Возвраты Объект ResourceResponse, который содержит свойство id с идентификатором действия, отправленного боту.

Загрузка и отправка файлов

Загружает и отправляет файлы в виде вложений. Задайте параметр userId в URI запроса, чтобы указать идентификатор пользователя, отправляющего вложения.

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
Содержимое Description
Текст запроса Для одного вложения заполните текст запроса содержимым файла. Для нескольких вложений создайте текст запроса из нескольких частей, по одной для каждого вложения, а также (необязательно) одну часть для объекта Activity, которая будет служить контейнером для всех вложений. Дополнительные сведения см. в руководстве по отправке действия боту.
Возвраты Объект ResourceResponse, который содержит свойство id с идентификатором действия, отправленного боту.

Примечание.

Загруженные файлы удаляются через 24 часа.

Схема

Схема Direct Line 3.0 включает все объекты, которые определены в схеме Bot Framework, а также объекты, которые связаны с Direct Line.

Объект ActivitySet

Определяет набор действий.

Свойство Type Описание
действия Activity[] Массив объектов Activity.
watermark строка Максимальное значение для водяного знака действий в наборе. Клиент может использовать значение watermark, чтобы указать последнее полученное им сообщение, при получении новых действий от бота или при создании нового URL-адреса потока WebSocket.

Объект Conversation

Определяет диалог Direct Line.

Свойство Type Описание
conversationId строка Идентификатор, который уникально идентифицирует диалог, для которого действует указанный токен.
eTag строка ETag HTTP (тег сущности).
expires_in number Число секунд до истечения срока действия токена.
referenceGrammarId строка Идентификатор справочной грамматики для этого бота.
streamUrl строка URL-адрес для потока сообщений диалога.
token строка Токен, действующий для указанного диалога.

Объект TokenParameters

Параметры для создания токена.

Свойство Type Описание
eTag строка ETag HTTP (тег сущности).
trustedOrigins string[] Доверенные источники для внедрения в токен.
user ChannelAccount Учетная запись пользователя для внедрения в маркер.

Процедуры

Для каждого объекта Activity, полученного клиентом от бота через Direct Line, выполняется следующее:

  • сохраняются карточки, включенные как вложения;
  • URL-адреса отправленных вложений подменяются частной ссылкой;
  • свойство channelData сохраняется без изменений.

Клиенты могут получать несколько действий от бота как набор действий (ActivitySet).

Когда клиент отправляет боту объект Activity через Direct Line, происходит следующее:

  • Свойство type указывает действие типа, которое он отправляет (обычно сообщение).
  • свойство from заполняется идентификатором пользователя, выбранным клиентом;
  • вложения могут содержать URL-адреса, ведущие к существующим ресурсам или ресурсам, отправленным через конечную точку вложений Direct Line;
  • свойство channelData сохраняется без изменений.
  • Общий размер действия, сериализованного и зашифрованного в формате JSON, не должен превышать 256 тысяч символов. Рекомендуется хранить действия в возрасте до 150K. Если требуется больше данных, рекомендуется разделить действие вверх или использовать вложения.

В каждом запросе клиент может отправить только одно действие.

Дополнительные ресурсы