Odbieranie działań od bota w interfejsie API Direct Line w wersji 3.0

Artykuł
03/08/2023

Korzystając z protokołu Direct Line 3.0, klienci mogą odbierać działania za pośrednictwem strumienia lub pobierania działań, WebSocket wysyłając HTTP GET żądania.

Protokół WebSocket a HTTP GET

Funkcja WebSocket przesyłania strumieniowego efektywnie wypycha komunikaty do klientów, natomiast interfejs GET umożliwia klientom jawne żądanie komunikatów. Mimo że mechanizm Protokołu WebSocket jest często preferowany ze względu na jego wydajność, mechanizm GET może być przydatny dla klientów, którzy nie mogą używać obiektów WebSocket.

Usługa umożliwia tylko 1 połączenie protokołu WebSocket na konwersację. Direct Line może zamknąć dodatkowe połączenia protokołu WebSocket z wartością collisionprzyczyny .

Nie wszystkie typy działań są dostępne zarówno za pośrednictwem protokołu WebSocket, jak i protokołu HTTP GET. W poniższej tabeli opisano dostępność różnych typów działań dla klientów korzystających z protokołu Direct Line.

Typ działania	Dostępność
message	HTTP GET i WebSocket
Wpisując	Tylko protokół WebSocket
conversationUpdate	Nie wysłano/odebrano za pośrednictwem klienta
contactRelationUpdate	Nieobsługiwane w Direct Line
endOfConversation	HTTP GET i WebSocket
wszystkie inne typy działań	HTTP GET i WebSocket

Odbieranie działań za pośrednictwem strumienia protokołu WebSocket

Gdy klient wysyła żądanie rozpoczęcia konwersacji w celu otwarcia konwersacji z botem, odpowiedź usługi zawiera streamUrl właściwość, za pomocą którego klient może następnie nawiązać połączenie za pośrednictwem protokołu WebSocket. Adres URL strumienia jest wstępnie uwierzytelniony, dlatego żądanie klienta do nawiązania połączenia za pośrednictwem protokołu WebSocket nie wymaga nagłówka Authorization .

W poniższym przykładzie pokazano żądanie, które używa streamUrl elementu do nawiązania połączenia za pośrednictwem protokołu WebSocket.

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

Usługa odpowiada przy użyciu kodu stanu HTTP 101 ("Przełączanie protokołów").

HTTP/1.1 101 Switching Protocols
[other headers]

Odbieranie komunikatów

Po nawiązaniu połączenia za pośrednictwem protokołu WebSocket klient może odbierać te typy komunikatów z usługi Direct Line:

Komunikat zawierający element ActivitySet zawierający co najmniej jedno działanie i znak wodny (opisany poniżej).
Pusty komunikat używany przez usługę Direct Line w celu zapewnienia, że połączenie jest nadal prawidłowe.
Dodatkowe typy, które mają być zdefiniowane później. Te typy są identyfikowane przez właściwości w katalogu głównym JSON.

Element ActivitySet zawiera komunikaty wysyłane przez bota i wszystkich użytkowników w konwersacji. W poniższym przykładzie pokazano element ActivitySet zawierający pojedynczy komunikat.

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

Przetwarzanie komunikatów

Klient powinien śledzić watermark wartość, którą otrzymuje w każdym zestawie Działań, tak aby mógł używać znaku wodnego, aby zagwarantować, że żadne komunikaty nie zostaną utracone, jeśli utraci połączenie i konieczne będzie ponowne nawiązanie połączenia z konwersacją. Jeśli klient otrzyma element ActivitySet wherein the watermark property is null or missing, powinien zignorować tę wartość i nie zastąpić poprzedniego znaku wodnego, który otrzymał.

Klient powinien ignorować puste komunikaty odbierane z usługi Direct Line.

Klient może wysyłać puste komunikaty do usługi Direct Line w celu zweryfikowania łączności. Usługa Direct Line zignoruje puste komunikaty odbierane od klienta.

Usługa Direct Line może przymusowo zamknąć połączenie Protokołu WebSocket w określonych warunkach. Jeśli klient nie otrzymał endOfConversation działania, może wygenerować nowy adres URL strumienia protokołu WebSocket , którego może użyć do ponownego nawiązania połączenia z konwersacją.

Strumień Protokołu WebSocket zawiera aktualizacje na żywo i bardzo ostatnie komunikaty (ponieważ wywołanie nawiązywania połączenia za pośrednictwem protokołu WebSocket zostało wydane), ale nie zawiera komunikatów wysłanych wcześniej do POST/v3/directline/conversations/{id}. Aby pobrać wiadomości, które zostały wysłane wcześniej w konwersacji, użyj polecenia HTTP GET zgodnie z poniższym opisem.

Pobieranie działań za pomocą żądania HTTP GET

Klienci, którzy nie mogą używać obiektów WebSocket, mogą pobierać działania przy użyciu polecenia HTTP GET.

Aby pobrać wiadomości dla określonej konwersacji, należy wysłać GET żądanie do /v3/directline/conversations/{conversationId}/activities punktu końcowego, opcjonalnie określając watermark parametr w celu wskazania najnowszego komunikatu widocznego przez klienta.

Poniższe fragmenty kodu zawierają przykład żądania i odpowiedzi Get Conversation Activities. Odpowiedź Pobierz działania konwersacji zawiera watermark wartość właściwości ActivitySet. Klienci powinni stronicować dostępne działania, rozwijając watermark wartość do momentu, gdy żadne działania nie zostaną zwrócone.

Żądanie

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

Reakcja

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"
}

Zagadnienia dotyczące chronometrażu

Większość klientów chce zachować pełną historię komunikatów. Mimo że Direct Line jest protokołem wieloczęściowym z potencjalnymi przerwami w czasie, protokół i usługa zostały zaprojektowane tak, aby ułatwić tworzenie niezawodnego klienta.

Właściwość watermark , która jest wysyłana w strumieniu Protokołu WebSocket i odpowiedź Pobierz działania konwersacji, jest niezawodna. Klient nie przegapi żadnych komunikatów, o ile powtarza znak wodny dosłowne.
Gdy klient rozpoczyna konwersację i nawiązuje połączenie ze strumieniem Protokołu WebSocket, wszelkie działania wysyłane po post, ale przed otwarciem gniazda zostaną ponownie odtworzone przed nowymi działaniami.
Gdy klient wysyła żądanie Pobierania działań konwersacji (w celu odświeżenia historii), gdy jest połączony ze strumieniem Protokołu WebSocket, działania mogą być duplikowane w obu kanałach. Klienci powinni śledzić wszystkie znane identyfikatory działań, aby móc odrzucać zduplikowane działania, jeśli wystąpią.

Klienci korzystający z sondowania HTTP GET powinni wybrać interwał sondowania zgodny z ich zamierzonym użyciem.

Aplikacje typu usługa-usługa często używają interwału sondowania 5s lub 10s.
Aplikacje dostępne dla klientów często używają interwału sondowania 1 i wysyłają jedno dodatkowe żądanie wkrótce po każdym komunikacie wysyłanym przez klienta (w celu szybkiego pobrania odpowiedzi bota). To opóźnienie może być krótkie o prędkości 300 ms, ale należy je dostosować na podstawie szybkości i czasu tranzytowego bota. Sondowanie nie powinno być częstsze niż raz na sekundę przez dłuższy czas.

Udostępnij za pośrednictwem