Empfangen von Aktivitäten vom Bot in Direct Line API 3.0
Mithilfe des Direct Line 3.0-Protokolls können Clients Aktivitäten über WebSocket-Stream empfangen oder Aktivitäten durch Ausgeben von HTTP GET-Anforderungen abrufen.
WebSocket oder HTTP GET
Ein streamender WebSocket sendet Nachrichten effizient per Push an Clients, während die GET-Schnittstelle Clients ermöglicht, Nachrichten explizit anzufordern. Aus Effizienzgründen wird zwar häufig der WebSocket-Mechanismus bevorzugt, der GET-Mechanismus kann allerdings für Clients hilfreich sein, die keine WebSockets verwenden können.
Der Dienst lässt nur eine WebSocket-Verbindung pro Konversation zu. Direct Line kann zusätzliche WebSocket-Verbindungen mit dem Wert collision als Grund schließen.
Nicht alle Aktivitätstypen sind sowohl über WebSocket als auch über HTTP GET verfügbar. Die folgende Tabelle beschreibt die Verfügbarkeit der verschiedenen Aktivitätstypen für Clients, die das Direct Line-Protokoll verwenden.
| Aktivitätstyp | Verfügbarkeit |
|---|---|
| message | HTTP GET und WebSocket |
| typing | Nur WebSocket |
| conversationUpdate | Über Client nicht gesendet/empfangen |
| contactRelationUpdate | In Direct Line nicht unterstützt |
| endOfConversation | HTTP GET und WebSocket |
| Alle anderen Aktivitätstypen | HTTP GET und WebSocket |
-Empfangsaktivität über WebSocket-Stream
Wenn ein Client eine Konversation starten-Anforderung sendet, um eine Konversation mit einem Bot zu öffnen, enthält die Antwort des Diensts eine streamUrl-Eigenschaft, die der Client anschließend für die Verbindungen über WebSocket verwenden kann. Die Stream-URL ist vorautorisiert und daher erfordert die Anforderung des Clients, die Verbindung über WebSocket herzustellen, KEINEN Authorization-Header.
Das folgende Beispiel zeigt eine Anforderung, die eine streamUrl für die Verbindung über WebSocket verwendet.
-- connect to wss://directline.botframework.com --
GET /v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA..."
Upgrade: websocket
Connection: upgrade
[other headers]
Der Dienst antwortet mit dem Statuscode HTTP 101 („Protokolle wechseln“).
HTTP/1.1 101 Switching Protocols
[other headers]
Empfangen von Nachrichten
Nachdem die Verbindung über WebSocket hergestellt wurde, kann ein Client diese Arten von Nachrichten vom Direct Line-Dienst empfangen:
- Eine Nachricht mit einem ActivitySet, das eine oder mehrere Aktivitäten und ein Wasserzeichen (siehe unten) enthält.
- Eine leere Nachricht, die der Direct Line-Dienst verwendet, um sicherzustellen, dass die Verbindung noch gültig ist.
- Zusätzliche Typen, die später definiert werden. Diese Typen werden durch die Eigenschaften im JSON-Stamm identifiziert.
Ein ActivitySet enthält vom Bot und allen Benutzern in der Konversation gesendete Nachrichten. Das folgende Beispiel zeigt ein ActivitySet, das eine einzelne Nachricht enthält.
{
"activities": [
{
"type": "message",
"channelId": "directline",
"conversation": {
"id": "abc123"
},
"id": "abc123|0000",
"from": {
"id": "user1"
},
"text": "hello"
}
],
"watermark": "0000a-42"
}
Verarbeiten von Nachrichten
Ein Client sollte den watermark-Wert nachverfolgen, den er in jedem ActivitySet empfängt, sodass er das Wasserzeichen verwenden kann, um sicherzustellen, dass keine Nachrichten verloren gehen, wenn die Verbindung unterbrochen wird und ein erneutes Verbinden mit der Konversation erforderlich ist. Wenn der Client ein ActivitySet empfängt, in dem die watermark-Eigenschaft null oder nicht vorhanden ist, sollte er diesen Wert ignorieren und das zuvor empfangene Wasserzeichen nicht überschreiben.
Ein Client sollte vom Direct Line-Dienst empfangene leere Nachrichten ignorieren.
Ein Client kann leere Nachrichten an den Direct Line-Dienst senden, um die Konnektivität zu überprüfen. Der Direct Line-Dienst ignoriert vom Client empfangene leere Nachrichten.
Der Direct Line-Dienst kann das Schließen der WebSocket-Verbindung unter bestimmten Bedingungen erzwingen. Wenn der Client keine endOfConversation-Aktivität empfangen hat, kann er eine neue WebSocket-Stream-URL generieren und verwenden, um die Verbindung mit der Konversation wieder herzustellen.
Der WebSocket-Stream enthält Liveupdates und sehr aktuelle Nachrichten (da der Aufruf zur Verbindung über WebSocket ausgegeben wurde), enthält jedoch keine Nachrichten, die vor der letzten POST an /v3/directline/conversations/{id}gesendet wurden. Verwenden Sie zum Abrufen von vorher in der Konversation gesendeten Nachrichten HTTP GET, wie unten beschrieben.
Abrufen von Aktivitäten mit HTTP-GET
Clients, die keine WebSockets verwenden können, können Aktivitäten mithilfe von HTTP GET abrufen.
Geben Sie zum Abrufen von Nachrichten für eine bestimmte Konversation eine GET-Anforderung an den /v3/directline/conversations/{conversationId}/activities-Endpunkt aus, wobei Sie optional den watermark-Parameter festlegen, um die neueste vom Client angezeigte Nachricht anzugeben.
Die folgenden Codeausschnitte enthalten ein Beispiel für die Get Conversation Activities-Anforderung und -Antwort. Die Get Conversation Activities-Antwort enthält watermark als Eigenschaft von ActivitySet. Clients sollten durch die verfügbaren Aktivitäten blättern, indem der watermark-Wert erhöht wird, bis keine Aktivitäten mehr zurückgegeben werden.
Anforderung
GET https://directline.botframework.com/v3/directline/conversations/abc123/activities?watermark=0001a-94
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Antwort
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"
}
Überlegungen zum Timing
Die meisten Clients möchten einen vollständige Nachrichtenverlauf speichern. Direct Line ist zwar ein mehrteiliges Protokoll mit möglichen Lücken im Timing, das Protokoll und der Dienst wurden jedoch entwickelt, um das Erstellen eines zuverlässigen-Clients zu erleichtern.
Die im WebSocket-Stream und der Get Conversation Activities-Antwort gesendete
watermark-Eigenschaft ist zuverlässig. Ein Client verpasst keine Nachrichten, solange er das Wasserzeichen wörtlich wiedergibt.Wenn ein Client eine Konversation startet und eine Verbindung mit dem WebSocket-Stream herstellt, werden alle Aktivitäten, die nach dem POST, aber vor dem Öffnen des Sockets gesendet werden, vor neuen Aktivitäten wiedergegeben.
Wenn ein Client eine Anforderung zum Abrufen von Unterhaltungsaktivitäten (zum Aktualisieren des Verlaufs) ausgibt, während er mit dem WebSocket-Stream verbunden ist, können Aktivitäten über beide Kanäle dupliziert werden. Clients sollten alle bekannten Aktivitäts-IDs nachverfolgen, damit sie doppelte Aktivitäten ablehnen können, falls sie auftreten.
Clients, die Polling mithilfe von HTTP GET durchführen, sollten ein Abrufintervall wählen, das ihrer vorgesehenen Verwendung entspricht.
Dienst-zu-Dienst-Anwendungen verwenden häufig ein Abrufintervall von 5 oder 10 Sekunden.
Clientseitige Anwendungen verwenden häufig ein Abrufintervall von einer Sekunde und geben kurz nach jeder vom Client gesendeten Nachricht eine einzelne zusätzliche Anforderung aus, um schnell die Antwort eines Bots abzurufen. Der kleinstmögliche Wert für diese Verzögerung beträgt 300 ms. Er sollte jedoch auf die Geschwindigkeit und Übertragungszeit des Bots abgestimmt werden. Die Abrufe sollten über einen längeren Zeitraum nicht häufiger als einmal pro Sekunde erfolgen.