Empfangen von Aktivitäten vom bot in der Direct Line-API 3,0Receive activities from the 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.Using the Direct Line 3.0 protocol, clients can receive activities via WebSocket stream or retrieve activities by issuing HTTP GET requests.

WebSocket oder HTTP GETWebSocket vs HTTP GET

Ein streamender WebSocket sendet Nachrichten effizient per Push an Clients, während die GET-Schnittstelle Clients ermöglicht, Nachrichten explizit anzufordern.A streaming WebSocket efficiently pushes messages to clients, whereas the GET interface enables clients to explicitly request messages. 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.Although the WebSocket mechanism is often preferred due to its efficiency, the GET mechanism can be useful for clients that are unable to use WebSockets.

Der Dienst lässt nur eine WebSocket-Verbindung pro Konversation zu.The service allows only 1 WebSocket connection per conversation. Direct Line kann zusätzliche WebSocket-Verbindungen mit dem Wert collision als Grund schließen.Direct Line may close additional WebSocket connections with a reason value of collision.

Nicht alle Aktivitätstypen sind sowohl über WebSocket als auch über HTTP GET verfügbar.Not all activity types are available both via WebSocket and via HTTP GET. Die folgende Tabelle beschreibt die Verfügbarkeit der verschiedenen Aktivitätstypen für Clients, die das Direct Line-Protokoll verwenden.The following table describes the availability of the various activity types for clients that use the Direct Line protocol.

AktivitätstypActivity type VerfügbarkeitAvailability
messagemessage HTTP GET und WebSocketHTTP GET and WebSocket
typingtyping Nur WebSocketWebSocket only
conversationUpdateconversationUpdate Über Client nicht gesendet/empfangenNot sent/received via client
contactRelationUpdatecontactRelationUpdate In Direct Line nicht unterstütztNot supported in Direct Line
endOfConversationendOfConversation HTTP GET und WebSocketHTTP GET and WebSocket
Alle anderen Aktivitätstypenall other activity types HTTP GET und WebSocketHTTP GET and WebSocket

-Empfangsaktivität über WebSocket-StreamReceive activities via 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.When a client sends a Start Conversation request to open a conversation with a bot, the service's response includes a streamUrl property that the client can subsequently use to connect via WebSocket. Die Stream-URL ist vorautorisiert und daher erfordert die Anforderung des Clients, die Verbindung über WebSocket herzustellen, KEINEN Authorization-Header.The stream URL is preauthorized and therefore the client's request to connect via WebSocket does NOT require an Authorization header.

Das folgende Beispiel zeigt eine Anforderung, die eine streamUrl für die Verbindung über WebSocket verwendet.The following example shows a request that uses a streamUrl to connect via WebSocket.

-- 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“).The service responds with status code HTTP 101 ("Switching Protocols").

HTTP/1.1 101 Switching Protocols
[other headers]

Empfangen von NachrichtenReceive messages

Nachdem die Verbindung über WebSocket hergestellt wurde, kann ein Client diese Arten von Nachrichten vom Direct Line-Dienst empfangen:After it connects via WebSocket, a client may receive these types of messages from the Direct Line service:

  • Eine Nachricht mit einem ActivitySet, das eine oder mehrere Aktivitäten und ein Wasserzeichen (siehe unten) enthält.A message that contains an ActivitySet that includes one or more activities and a watermark (described below).
  • Eine leere Nachricht, die der Direct Line-Dienst verwendet, um sicherzustellen, dass die Verbindung noch gültig ist.An empty message, which the Direct Line service uses to ensure the connection is still valid.
  • Zusätzliche Typen, die später definiert werden.Additional types, to be defined later. Diese Typen werden durch die Eigenschaften im JSON-Stamm identifiziert.These types are identified by the properties in the JSON root.

Ein ActivitySet enthält vom Bot und allen Benutzern in der Konversation gesendete Nachrichten.An ActivitySet contains messages sent by the bot and by all users in the conversation. Das folgende Beispiel zeigt ein ActivitySet, das eine einzelne Nachricht enthält.The following example shows an ActivitySet that contains a single message.

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

Verarbeiten von NachrichtenProcess messages

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.A client should keep track of the watermark value that it receives in each ActivitySet, so that it may use the watermark to guarantee that no messages are lost if it loses its connection and needs to reconnect to the conversation. 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.If the client receives an ActivitySet wherein the watermark property is null or missing, it should ignore that value and not overwrite the prior watermark that it received.

Ein Client sollte vom Direct Line-Dienst empfangene leere Nachrichten ignorieren.A client should ignore empty messages that it receives from the Direct Line service.

Ein Client kann leere Nachrichten an den Direct Line-Dienst senden, um die Konnektivität zu überprüfen.A client may send empty messages to the Direct Line service to verify connectivity. Der Direct Line-Dienst ignoriert vom Client empfangene leere Nachrichten.The Direct Line service will ignore empty messages that it receives from the client.

Der Direct Line-Dienst kann das Schließen der WebSocket-Verbindung unter bestimmten Bedingungen erzwingen.The Direct Line service may forcibly close the WebSocket connection under certain conditions. 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.If the client has not received an endOfConversation activity, it may generate a new WebSocket stream URL that it can use to reconnect to the conversation.

Der WebSocket-Stream enthält Liveupdates und erst vor kurzem gesendete Nachrichten (seit der Aufruf zum Herstellen der Verbindung über WebSocket ausgegeben wurde), enthält aber keine Nachrichten, die vor dem letzten POST an /v3/directline/conversations/{id} gesendet wurden.The WebSocket stream contains live updates and very recent messages (since the call to connect via WebSocket was issued) but it does not include messages that were sent prior to the most recent POST to /v3/directline/conversations/{id}. Verwenden Sie zum Abrufen von vorher in der Konversation gesendeten Nachrichten HTTP GET, wie unten beschrieben.To retrieve messages that were sent earlier in the conversation, use HTTP GET as described below.

Abrufen von Aktivitäten mit HTTP-GETRetrieve activities with HTTP GET

Clients, die keine WebSockets verwenden können, können Aktivitäten mithilfe von HTTP GET abrufen.Clients that are unable to use WebSockets can retrieve activities by using HTTP GET.

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.To retrieve messages for a specific conversation, issue a GET request to the /v3/directline/conversations/{conversationId}/activities endpoint, optionally specifying the watermark parameter to indicate the most recent message seen by the client.

Die folgenden Codeausschnitte enthalten ein Beispiel für die Get Conversation Activities-Anforderung und -Antwort.The following snippets provide an example of the Get Conversation Activities request and response. Die Get Conversation Activities-Antwort enthält watermark als Eigenschaft von ActivitySet.The Get Conversation Activities response contains watermark as a property of the 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.Clients should page through the available activities by advancing the watermark value until no activities are returned.

AnforderungRequest

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

AntwortResponse

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 TimingTiming considerations

Die meisten Clients möchten einen vollständige Nachrichtenverlauf speichern.Most clients wish to retain a complete message history. 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.Even though Direct Line is a multi-part protocol with potential timing gaps, the protocol and service is designed to make it easy to build a reliable client.

  • Die im WebSocket-Stream und der Get Conversation Activities-Antwort gesendete watermark-Eigenschaft ist zuverlässig.The watermark property that is sent in the WebSocket stream and Get Conversation Activities response is reliable. Ein Client verpasst keine Nachrichten, solange er das Wasserzeichen wörtlich wiedergibt.A client will not miss any messages as long as it replays the watermark verbatim.

  • 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.When a client starts a conversation and connects to the WebSocket stream, any activities that are sent after the POST but before the socket is opened are replayed before new activities.

  • Wenn ein Client eine Get Conversation Activities-Anforderung ausgibt (um den Verlauf zu aktualisieren), während er mit dem WebSocket-Stream verbunden ist, können Aktivitäten über beide Kanäle dupliziert werden.When a client issues a Get Conversation Activities request (to refresh history) while it is connected to the WebSocket stream, activities may be duplicated across both channels. Clients sollten alle bekannten Aktivitäts-IDs nachverfolgen, damit sie in der Lage sind, doppelte Aktivitäten abzulehnen, sofern diese auftraten.Clients should keep track of all known activity IDs so that they are able to reject duplicate activities, should they occur.

Clients, die Polling mithilfe von HTTP GET durchführen, sollten ein Abrufintervall wählen, das ihrer vorgesehenen Verwendung entspricht.Clients that poll using HTTP GET should choose a polling interval that matches their intended use.

  • Dienst-zu-Dienst-Anwendungen verwenden häufig ein Abrufintervall von 5 oder 10 Sekunden.Service-to-service applications often use a polling interval of 5s or 10s.

  • 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.Client-facing applications often use a polling interval of 1s, and issue a single additional request shortly after every message that the client sends (to rapidly retrieve a bot's response). 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.This delay can be as short at 300ms but should be tuned based on the bot's speed and transit time. Das Abrufintervall sollte nicht über einen längeren Zeitraum unter einer Sekunde liegen.Polling should not be more frequent than once per second for any extended period of time.

Zusätzliche RessourcenAdditional resources