ダイレクトライン API 3.0 でボットからアクティビティを受け取るReceive activities from the bot in Direct Line API 3.0

クライアントは、Direct Line 3.0 プロトコルを使用して、WebSocket ストリーム経由でアクティビティを受信するか、HTTP GET 要求を発行してアクティビティを取得できます。Using the Direct Line 3.0 protocol, clients can receive activities via WebSocket stream or retrieve activities by issuing HTTP GET requests.

WebSocket と HTTP GETWebSocket vs HTTP GET

WebSocket のストリーミング はメッセージを効率的にクライアントにプッシュし、GET インターフェイスはクライアントがメッセージを明示的に要求できるようにします。A streaming WebSocket efficiently pushes messages to clients, whereas the GET interface enables clients to explicitly request messages. 多くの場合、効率の良さから WebSocket メカニズムが推奨されますが、WebSocket を使用できないクライアントでは、GET メカニズムが役立ちます。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.

このサービスでは、会話ごとに WebSocket 接続を 1 つだけ許可します。The service allows only 1 WebSocket connection per conversation. Direct Line では、collision の理由の値で追加の WebSocket 接続を閉じる可能性があります。Direct Line may close additional WebSocket connections with a reason value of collision.

WebSocket と HTTP GET は、どちらも、すべてのアクティビティの種類を利用できるわけではありません。Not all activity types are available both via WebSocket and via HTTP GET. 次の表で、Direct Line プロトコルを使用するクライアントで利用可能なさまざまな種類のアクティビティについて説明します。The following table describes the availability of the various activity types for clients that use the Direct Line protocol.

アクティビティの種類Activity type 可用性Availability
messagemessage HTTP GET と WebSocketHTTP GET and WebSocket
typingtyping WebSocket のみWebSocket only
conversationUpdateconversationUpdate クライアント経由では送信/受信されないNot sent/received via client
contactRelationUpdatecontactRelationUpdate Direct Line ではサポートされないNot supported in Direct Line
endOfConversationendOfConversation HTTP GET と WebSocketHTTP GET and WebSocket
その他のすべてのアクティビティの種類all other activity types HTTP GET と WebSocketHTTP GET and WebSocket

WebSocket ストリーム経由でアクティビティを受信するReceive activities via WebSocket stream

クライアントが会話の開始要求を送信してボットとの会話を開くと、サービスの応答には、クライアントが後で WebSocket 経由で接続するために使用できる streamUrl プロパティが含まれます。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. ストリーム URL は事前に承認されているため、WebSocket 経由で接続するクライアントの要求には、Authorization ヘッダーは必要ありません。The stream URL is preauthorized and therefore the client's request to connect via WebSocket does NOT require an Authorization header.

次の例は、streamUrl を使用して WebSocket 経由で接続する要求を示しています。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]

サービスは、状態コード HTTP 101 ("プロトコルの切り替え中") で応答します。The service responds with status code HTTP 101 ("Switching Protocols").

HTTP/1.1 101 Switching Protocols
[other headers]

メッセージを受信するReceive messages

WebSocket 経由で接続した後、クライアントは、Direct Line サービスから次の種類のメッセージを受信できます。After it connects via WebSocket, a client may receive these types of messages from the Direct Line service:

  • ActivitySet を含むメッセージ。これには、1 つまたは複数のアクティビティとウォーターマーク (後述) が含まれています。A message that contains an ActivitySet that includes one or more activities and a watermark (described below).
  • 接続がまだ有効であることを確認するために Direct Line サービスが使用する空のメッセージ。An empty message, which the Direct Line service uses to ensure the connection is still valid.
  • その他の種類。後で定義されます。Additional types, to be defined later. これらの種類は、JSON ルートのプロパティによって識別されます。These types are identified by the properties in the JSON root.

ActivitySet には、ボットと会話のすべてのユーザーによって送信されたメッセージが含まれます。An ActivitySet contains messages sent by the bot and by all users in the conversation. 次の例は、1 つのメッセージを含む ActivitySet を示しています。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"
}

メッセージを処理するProcess messages

クライアントは、各 ActivitySet で受信する watermark 値を追跡して、接続が失われたために会話を再接続する必要がある場合に、ウォーターマークを使用してメッセージが失われていないことを保証できるようにする必要があります。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. クライアントは、watermark プロパティが null である ActivitySet を受信した場合は、その値を無視する必要があり、前に受信したウォーターマークを上書きしてはなりません。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.

クライアントは、Direct Line サービスから受信する空のメッセージを無視する必要があります。A client should ignore empty messages that it receives from the Direct Line service.

クライアントは、接続を確認するために Direct Line サービスに空のメッセージを送信できます。A client may send empty messages to the Direct Line service to verify connectivity. Direct Line サービスは、クライアントから受信する空のメッセージを無視します。The Direct Line service will ignore empty messages that it receives from the client.

Direct Line サービスが、特定の条件下で WebSocket 接続を強制的に閉じる場合があります。The Direct Line service may forcibly close the WebSocket connection under certain conditions. クライアントは、endOfConversation アクティビティが受信されない場合は、会話に再接続するために使用できる新しい WebSocket ストリーム URL を生成できます。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.

WebSocket ストリームにはライブ更新とごく最近のメッセージが含まれています (これは WebSocket 経由で接続するための呼び出しが発行されたためです) が、最新の POST の前に /v3/directline/conversations/{id} に送信されたメッセージは含まれていません。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}. 会話内でこれまでに送信されたメッセージを取得するには、次に説明する HTTP GET を使用します。To retrieve messages that were sent earlier in the conversation, use HTTP GET as described below.

HTTP GET を使用してアクティビティを取得するRetrieve activities with HTTP GET

WebSocket を使用できないクライアントは、HTTP GET を使用してアクティビティを取得できます。Clients that are unable to use WebSockets can retrieve activities by using HTTP GET.

特定の会話のメッセージを取得するには、GET 要求を /v3/directline/conversations/{conversationId}/activities エンドポイントに発行します。オプションで、クライアントが認識した最新のメッセージを示す watermark パラメーターを指定できます。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.

以下のスニペットは、会話アクティビティ取得要求と応答の例を示しています。The following snippets provide an example of the Get Conversation Activities request and response. 会話アクティビティ取得応答には、ActivitySet のプロパティとして watermark が含まれます。The Get Conversation Activities response contains watermark as a property of the ActivitySet. クライアントは、アクティビティが返らなくなるまで watermark 値を進めることで、入手できるアクティビティをすべて取得する必要があります。Clients should page through the available activities by advancing the watermark value until no activities are returned.

RequestRequest

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

ResponseResponse

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

タイミングに関する考慮事項Timing considerations

ほとんどのクライアントは、完全なメッセージの履歴を保持することを望んでいます。Most clients wish to retain a complete message history. Direct Line は潜在的なタイミングのギャップを伴うマルチパート プロトコルですが、そのプロトコルとサービスは信頼性の高いクライアントを簡単に構築できるように設計されています。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.

  • WebSocket ストリームと会話アクティビティ取得応答で送信される watermark プロパティは信頼できます。The watermark property that is sent in the WebSocket stream and Get Conversation Activities response is reliable. ウォーターマーク文字列を再生する限り、クライアントがメッセージを見逃すことはありません。A client will not miss any messages as long as it replays the watermark verbatim.

  • クライアントが会話を開始して WebSocket ストリームに接続すると、POST の後で送信されたが、ソケットが開く前に送信されたすべてのアクティビティは、新しいアクティビティの前に再生されます。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.

  • クライアントが WebSocket ストリームに接続されているときに (履歴を更新するために) 会話アクティビティ取得要求を発行した場合、両方のチャネルでアクティビティが重複することがあります。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. クライアントは、既知のすべてのアクティビティ ID を追跡して、重複するアクティビティが発生した場合にそれを拒否できるようにする必要があります。Clients should keep track of all known activity IDs so that they are able to reject duplicate activities, should they occur.

HTTP GET を使用してポーリングを行うクライアントは、その使用目的と一致するポーリング間隔を選択する必要があります。Clients that poll using HTTP GET should choose a polling interval that matches their intended use.

  • サービス間アプリケーションは、多くの場合、5 秒または 10 秒のポーリング間隔を使用します。Service-to-service applications often use a polling interval of 5s or 10s.

  • 多くの場合、クライアント向けアプリケーションでは 1 秒のポーリング間隔を使用し、(ボットの応答を迅速に取得するために) クライアントが送信する各メッセージの直後に単一の追加要求を発行します。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). この遅延は 300 ミリ秒程度ですが、ボットの速度と転送時間に基づいて調整する必要があります。This delay can be as short at 300ms but should be tuned based on the bot's speed and transit time. 長時間にわたって 1 秒に 1 回以上の頻度でポーリングを行わないようにしてください。Polling should not be more frequent than once per second for any extended period of time.

その他のリソースAdditional resources