Получение действий от бота в API Direct Line 3.0

Статья
03/08/2023

С помощью протокола Direct Line 3.0 клиенты могут получать действия через поток WebSocket или извлекать действия путем выполнения запросов HTTP GET.

WebSocket и запрос GET HTTP

Потоковая передача WebSocket эффективно передает сообщения клиентам, тогда как интерфейс GET позволяет клиентам точно запрашивать сообщения. Несмотря на то что механизм WebSocket часто является предпочтительным благодаря своей эффективности, механизм GET может быть полезен клиентам, которые не могут использовать WebSocket.

Служба позволяет только 1 подключение WebSocket для диалога. Direct Line может закрыть дополнительные подключения WebSocket со значением причины collision.

Не все типы действий доступны как через WebSocket, так и через запрос GET HTTP. В следующей таблице описана доступность различных типов действий для клиентов, использующих протокол Direct Line.

тип действия;	Доступность
message	HTTP GET и WebSocket
typing	Только WebSocket
conversationUpdate	Недоступно для отправки и получения через клиент
contactRelationUpdate	Не поддерживается в Direct Line
endOfConversation	HTTP GET и WebSocket
Все другие типы действий	HTTP GET и WebSocket

Получение действий через потоковую передачу WebSocket

Когда клиент отправляет запрос Начало общения для открытия общения с помощью бота, ответ службы включает в себя свойство streamUrl, которое клиент может впоследствии использовать для подключения через WebSocket. URL-адрес потока предварительно одобрен, поэтому запрос клиента на подключение через WebSocket не требует заголовка Authorization.

В следующем примере показан запрос, который использует streamUrl для подключения через WebSocket.

-- connect to wss://directline.botframework.com --
GET /v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA..."
Upgrade: websocket
Connection: upgrade
[other headers]

Служба возвращает код состояния HTTP 101 ("Переключение протоколов").

HTTP/1.1 101 Switching Protocols
[other headers]

Получение сообщений

После подключения через WebSocket клиент может получать эти типы сообщений из службы Direct Line.

Сообщение, содержащее объект ActivitySet, который включает в себя одно или несколько действий и водяной знак (описание приведено ниже).
Пустое сообщение, которое используется службой Direct Line для подтверждения того, что подключение по-прежнему действительно.
Дополнительные типы будут определены позже. Эти типы идентифицируются свойствами в корне JSON.

ActivitySet содержит сообщения, отправленные ботом и всеми пользователями в общении. В следующем примере показан объект ActivitySet, содержащий одно сообщение.

{
    "activities": [
        {
            "type": "message",
            "channelId": "directline",
            "conversation": {
                "id": "abc123"
            },
            "id": "abc123|0000",
            "from": {
                "id": "user1"
            },
            "text": "hello"
        }
    ],
    "watermark": "0000a-42"
}

Обработка сообщений

Клиент должен отслеживать значение свойства watermark, которое оно получает в каждом ActivitySet, чтобы иметь возможность использовать водяной знак для гарантии того, что ни одно сообщение не будет утрачено, если потеряется подключение и потребуется повторно подключиться к общению. Если клиент получает ActivitySet, где свойство watermark равняется null или отсутствует, он должен игнорировать это значение и не перезаписывать полученный ранее водяной знак.

Клиент должен игнорировать пустые сообщения, которые получает из службы Direct Line.

Клиент может отправить пустое сообщение в службу Direct Line, чтобы проверить подключение. Служба Direct Line проигнорирует пустые сообщения, получаемые от клиента.

Служба Direct Line может принудительно закрыть подключение к WebSocket при определенных условиях. Если клиент не получил действие endOfConversation, он может создать новый URL-адрес потока WebSocket, который можно использовать для повторного подключения к общению.

Поток WebSocket содержит динамические обновления и последние сообщения (так как был выполнен вызов для подключения через WebSocket), но не включает сообщения, отправленные до последнего POST в /v3/directline/conversations/{id}. Для получения более ранних сообщений из общения используйте HTTP GET, как описано ниже.

Извлечение действий с помощью запроса GET HTTP

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

Для получения сообщений из конкретного общения отправьте запрос GET в конечную точку /v3/directline/conversations/{conversationId}/activities, при необходимости задавая параметр watermark, чтобы указать последнее сообщение, отображаемое клиенту.

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

Запрос

GET https://directline.botframework.com/v3/directline/conversations/abc123/activities?watermark=0001a-94
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

Ответ

HTTP/1.1 200 OK
[other headers]

{
    "activities": [
        {
            "type": "message",
            "channelId": "directline",
            "conversation": {
                "id": "abc123"
            },
            "id": "abc123|0000",
            "from": {
                "id": "user1"
            },
            "text": "hello"
        }, 
        {
            "type": "message",
            "channelId": "directline",
            "conversation": {
                "id": "abc123"
            },
            "id": "abc123|0001",
            "from": {
                "id": "bot1"
            },
            "text": "Nice to see you, user1!"
        }
    ],
    "watermark": "0001a-95"
}

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