Ta emot aktiviteter från roboten i Direct Line API 3.0

Artikel
10/09/2024

Med hjälp av Direct Line 3.0-protokollet kan klienter ta emot aktiviteter via WebSocket ström eller hämta aktiviteter genom att utfärda HTTP GET begäranden.

WebSocket jämfört med HTTP GET

En strömmande WebSocket skickar effektivt meddelanden till klienter, medan GET-gränssnittet gör det möjligt för klienter att uttryckligen begära meddelanden. Även om WebSocket-mekanismen ofta föredras på grund av dess effektivitet kan GET-mekanismen vara användbar för klienter som inte kan använda WebSockets.

Tjänsten tillåter endast 1 WebSocket-anslutning per konversation. Direct Line kan stänga ytterligare WebSocket-anslutningar med orsaksvärdet collision.

Alla aktivitetstyper är inte tillgängliga både via WebSocket och via HTTP GET. I följande tabell beskrivs tillgängligheten för de olika aktivitetstyperna för klienter som använder Direct Line protokollet.

Aktivitetstyp	Tillgänglighet
meddelande	HTTP GET och WebSocket
Skriva	Endast WebSocket
conversationUpdate	Skickas/tas inte emot via klienten
contactRelationUpdate	Stöds inte i Direct Line
endOfConversation	HTTP GET och WebSocket
alla andra aktivitetstyper	HTTP GET och WebSocket

Ta emot aktiviteter via WebSocket-dataström

När en klient skickar en begäran om att starta konversation för att öppna en konversation med en robot innehåller tjänstens svar en streamUrl egenskap som klienten senare kan använda för att ansluta via WebSocket. Ström-URL:en är förauktoriserat och därför kräver klientens begäran om att ansluta via WebSocket INTE ett Authorization huvud.

I följande exempel visas en begäran som använder en streamUrl för att ansluta via WebSocket.

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

Tjänsten svarar med statuskoden HTTP 101 ("Switching Protocols").

HTTP/1.1 101 Switching Protocols
[other headers]

Ta emot meddelanden

När den har anslutit via WebSocket kan en klient få dessa typer av meddelanden från Direct Line-tjänsten:

Ett meddelande som innehåller en ActivitySet som innehåller en eller flera aktiviteter och en vattenstämpel (beskrivs nedan).
Ett tomt meddelande som Direct Line-tjänsten använder för att säkerställa att anslutningen fortfarande är giltig.
Ytterligare typer som ska definieras senare. Dessa typer identifieras av egenskaperna i JSON-roten.

En ActivitySet innehåller meddelanden som skickas av roboten och av alla användare i konversationen. I följande exempel visas ett ActivitySet som innehåller ett enda meddelande.

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

Bearbeta meddelanden

En klient bör hålla reda på watermark det värde som tas emot i varje ActivitySet, så att den kan använda vattenstämpeln för att garantera att inga meddelanden går förlorade om den förlorar sin anslutning och behöver återansluta till konversationen. Om klienten får en ActivitySet plats där watermark egenskapen saknas eller saknas null bör den ignorera det värdet och inte skriva över den tidigare vattenstämpeln som den tog emot.

En klient bör ignorera tomma meddelanden som tas emot från Direct Line-tjänsten.

En klient kan skicka tomma meddelanden till Direct Line-tjänsten för att verifiera anslutningen. Tjänsten Direct Line ignorerar tomma meddelanden som tas emot från klienten.

Den Direct Line tjänsten kan med tvåtvinga stänga WebSocket-anslutningen under vissa förhållanden. Om klienten inte har tagit emot en endOfConversation aktivitet kan den generera en ny WebSocket-ström-URL som den kan använda för att återansluta till konversationen.

WebSocket-strömmen innehåller liveuppdateringar och mycket senaste meddelanden (eftersom anropet för att ansluta via WebSocket utfärdades), men den innehåller inte meddelanden som skickades före det senaste POST till /v3/directline/conversations/{id}. Om du vill hämta meddelanden som skickades tidigare i konversationen använder HTTP GET du enligt beskrivningen nedan.

Hämta aktiviteter med HTTP GET

Klienter som inte kan använda WebSockets kan hämta aktiviteter med hjälp HTTP GETav .

Om du vill hämta meddelanden för en specifik konversation skickar du en GET begäran till /v3/directline/conversations/{conversationId}/activities slutpunkten. Du kan också ange parametern watermark för att ange det senaste meddelandet som visas av klienten.

Följande kodfragment innehåller ett exempel på begäran och svar för Hämta konversationsaktiviteter. Svaret Hämta konversationsaktiviteter innehåller watermark som en egenskap för ActivitySet. Klienter bör bläddra igenom de tillgängliga aktiviteterna watermark genom att flytta fram värdet tills inga aktiviteter returneras.

Förfrågan

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

Svarsåtgärder

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

Tidsöverväganden

De flesta klienter vill behålla en fullständig meddelandehistorik. Även om Direct Line är ett protokoll i flera delar med potentiella tidsluckor, är protokollet och tjänsten utformade för att göra det enkelt att skapa en tillförlitlig klient.

Egenskapen watermark som skickas i WebSocket-strömmen och svaret Hämta konversationsaktiviteter är tillförlitlig. En klient kommer inte att missa några meddelanden så länge den spelar upp vattenstämpeln ordagrant igen.
När en klient startar en konversation och ansluter till WebSocket-strömmen, spelas alla aktiviteter som skickas efter POST men innan socketen öppnas upp igen före nya aktiviteter.
När en klient utfärdar en Begäran om att hämta konversationsaktiviteter (för att uppdatera historiken) när den är ansluten till WebSocket-strömmen kan aktiviteter dupliceras över båda kanalerna. Klienter bör hålla reda på alla kända aktivitets-ID:t så att de kan avvisa duplicerade aktiviteter om de inträffar.

Klienter som avsöks med bör HTTP GET välja ett avsökningsintervall som matchar deras avsedda användning.

Tjänst-till-tjänst-program använder ofta avsökningsintervallet 5s eller 10s.
Klientinriktade program använder ofta avsökningsintervallet 1:a och skickar en ytterligare begäran kort efter varje meddelande som klienten skickar (för att snabbt hämta en robots svar). Den här fördröjningen kan vara så kort på 300 ms men bör justeras baserat på robotens hastighet och överföringstid. Avsökningen bör inte vara vanligare än en gång per sekund under en längre tidsperiod.

Dela via