Příjem aktivit od robota v rozhraní API Direct Line 3.0

Článek
03/08/2023

Pomocí protokolu Direct Line 3.0 můžou klienti přijímat aktivity prostřednictvím WebSocket streamu nebo načítat aktivity vydáváním HTTP GET požadavků.

WebSocket vs. HTTP GET

Streamovací protokol WebSocket efektivně odesílá zprávy klientům, zatímco rozhraní GET umožňuje klientům explicitně vyžadovat zprávy. I když je mechanismus WebSocket často preferován kvůli své účinnosti, může být mechanismus GET užitečný pro klienty, kteří nemohou používat protokol WebSocket.

Služba umožňuje pouze 1 připojení WebSocket na konverzaci. Direct Line může ukončit další připojení WebSocket s hodnotou collisiondůvodu .

Ne všechny typy aktivit jsou k dispozici prostřednictvím protokolu WebSocket i prostřednictvím http GET. Následující tabulka popisuje dostupnost různých typů aktivit pro klienty, kteří používají protokol Direct Line.

Typ aktivity	Dostupnost
zpráva	HTTP GET a WebSocket
Psaní	Pouze protokol WebSocket
conversationUpdate	Neodeslané nebo přijaté prostřednictvím klienta
contactRelationUpdate	Nepodporuje se v Direct Line
endOfConversation	HTTP GET a WebSocket
všechny ostatní typy aktivit	HTTP GET a WebSocket

Příjem aktivit prostřednictvím streamu WebSocket

Když klient odešle žádost o zahájení konverzace k otevření konverzace s robotem, odpověď služby obsahuje streamUrl vlastnost, kterou může klient následně použít k připojení prostřednictvím protokolu WebSocket. Adresa URL streamu je předem autorizována, a proto požadavek klienta na připojení prostřednictvím protokolu WebSocket NEVYŽADUJE hlavičku Authorization .

Následující příklad ukazuje požadavek, který používá streamUrl k připojení přes WebSocket.

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

Služba odpoví stavovým kódem HTTP 101 ("Přepínání protokolů").

HTTP/1.1 101 Switching Protocols
[other headers]

Příjem zpráv

Po připojení přes protokol WebSocket může klient obdržet z Direct Line služby tyto typy zpráv:

Zpráva obsahující sadu aktivit obsahující jednu nebo více aktivit a vodoznak (popsaný níže).
Prázdná zpráva, kterou služba Direct Line používá k zajištění platnosti připojení.
Další typy, které budou definovány později. Tyto typy jsou identifikované vlastnostmi v kořenovém adresáři JSON.

Obsahuje ActivitySet zprávy odeslané robotem a všemi uživateli v konverzaci. Následující příklad ukazuje, ActivitySet že obsahuje jednu zprávu.

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

Zpracování zpráv

Klient by měl sledovat watermark hodnotu, kterou obdrží v každé sadě aktivit, aby mohl pomocí vodoznaku zaručit, že se žádné zprávy neztratí, pokud ztratí připojení a potřebuje se znovu připojit ke konverzaci. Pokud klient obdrží ActivitySet hodnotu , kde watermark vlastnost je null nebo chybí, měl by tuto hodnotu ignorovat a nepřepsat předchozí vodoznak, který obdržel.

Klient by měl ignorovat prázdné zprávy, které obdrží ze služby Direct Line.

Klient může odesílat prázdné zprávy službě Direct Line za účelem ověření připojení. Služba Direct Line bude ignorovat prázdné zprávy, které obdrží od klienta.

Služba Direct Line může za určitých podmínek vynutit ukončení připojení WebSocket. Pokud klient neobdržel endOfConversation aktivitu, může vygenerovat novou adresu URL streamu Protokolu WebSocket , kterou může použít k opětovnému připojení ke konverzaci.

Datový proud Protokolu WebSocket obsahuje živé aktualizace a velmi nedávné zprávy (protože bylo vydáno volání pro připojení prostřednictvím protokolu WebSocket), ale neobsahuje zprávy odeslané před nejnovější POST zprávou do /v3/directline/conversations/{id}. Pokud chcete načíst zprávy odeslané dříve v konverzaci, použijte následující HTTP GET postup.

Načtení aktivit pomocí HTTP GET

Klienti, kteří nemůžou používat protokol WebSocket, můžou načíst aktivity pomocí .HTTP GET

Pokud chcete načíst zprávy pro určitou konverzaci, zadejte GET požadavek na /v3/directline/conversations/{conversationId}/activities koncový bod a volitelně zadejte watermark parametr, který označuje poslední zprávu zobrazenou klientem.

Následující fragmenty kódu poskytují příklad požadavku a odpovědi na získání aktivit konverzace. Odpověď Získat aktivity konverzace obsahuje watermark jako vlastnost ActivitySet. Klienti by měli procházet dostupné aktivity posouváním hodnoty, watermark dokud se nevrátí žádné aktivity.

Žádost

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

Odpověď

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

Důležité informace o načasování

Většina klientů si přeje zachovat úplnou historii zpráv. I když je Direct Line vícedílný protokol s možnými časovacími mezerami, protokol a služba jsou navržené tak, aby usnadnily vytvoření spolehlivého klienta.

Vlastnost odeslaná watermark v datovém proudu WebSocket a odpovědi Získat aktivity konverzace je spolehlivá. Klientovi neuniknou žádné zprávy, pokud přehraje doslovné znění vodoznaku.
Když klient zahájí konverzaci a připojí se ke streamu WebSocket, všechny aktivity odeslané po post, ale před otevřením soketu se přehrají před novými aktivitami.
Když klient během připojení k datovému proudu WebSocket vydá žádost o získání aktivit konverzací (kvůli aktualizaci historie), můžou se aktivity duplikovat v obou kanálech. Klienti by měli sledovat všechna známá ID aktivit, aby v případě výskytu duplicitních aktivit mohli odmítnout.

Klienti, kteří používají HTTP GET dotazování, by měli zvolit interval dotazování, který odpovídá jejich zamýšlenému použití.

Aplikace mezi službami často používají interval dotazování 5 nebo 10 s.
Klientské aplikace často používají interval dotazování 1s a krátce po každé zprávě odesílané klientem zasílají jeden další požadavek (za účelem rychlého načtení odpovědi robota). Tato prodleva může být krátká na 300 ms, ale měla by se vyladit na základě rychlosti robota a doby přepravy. Cyklické dotazování by nemělo být po delší časové období častější než jednou za sekundu.

Sdílet prostřednictvím