Direct Line API 3.0 でボットからアクティビティを受信する

[アーティクル]
03/08/2023

クライアントは、Direct Line 3.0 プロトコルを使用して、WebSocket ストリーム経由でアクティビティを受信するか、HTTP GET 要求を発行してアクティビティを取得できます。

WebSocket と HTTP GET

WebSocket のストリーミングはメッセージを効率的にクライアントにプッシュし、GET インターフェイスはクライアントがメッセージを明示的に要求できるようにします。多くの場合、効率の良さから WebSocket メカニズムが推奨されますが、WebSocket を使用できないクライアントでは、GET メカニズムが役立ちます。

このサービスでは、会話ごとに WebSocket 接続を 1 つだけ許可します。 Direct Line では、collision の理由の値で追加の WebSocket 接続を閉じる可能性があります。

WebSocket と HTTP GET は、どちらも、すべてのアクティビティの種類を利用できるわけではありません。次の表で、Direct Line プロトコルを使用するクライアントで利用可能なさまざまな種類のアクティビティについて説明します。

アクティビティの種類	可用性
message	HTTP GET と WebSocket
typing	WebSocket のみ
conversationUpdate	クライアント経由では送信/受信されない
contactRelationUpdate	Direct Line ではサポートされない
endOfConversation	HTTP GET と WebSocket
その他のすべてのアクティビティの種類	HTTP GET と WebSocket

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

クライアントが会話の開始要求を送信してボットとの会話を開くと、サービスの応答には、クライアントが後で WebSocket 経由で接続するために使用できる streamUrl プロパティが含まれます。ストリーム URL は事前に承認されているため、WebSocket 経由で接続するクライアントの要求には、Authorization ヘッダーは必要ありません。

次の例は、streamUrl を使用して 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 ("プロトコルの切り替え中") で応答します。

HTTP/1.1 101 Switching Protocols
[other headers]

メッセージを受信する

WebSocket 経由で接続した後、クライアントは、Direct Line サービスから次の種類のメッセージを受信できます。

ActivitySet を含むメッセージ。これには、1 つまたは複数のアクティビティとウォーターマーク (後述) が含まれています。
接続がまだ有効であることを確認するために Direct Line サービスが使用する空のメッセージ。
その他の種類。後で定義されます。これらの種類は、JSON ルートのプロパティによって識別されます。

ActivitySet には、ボットと会話のすべてのユーザーによって送信されたメッセージが含まれます。次の例は、1 つのメッセージを含む ActivitySet を示しています。

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

メッセージを処理する

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

クライアントは、Direct Line サービスから受信する空のメッセージを無視する必要があります。

クライアントは、接続を確認するために Direct Line サービスに空のメッセージを送信できます。 Direct Line サービスは、クライアントから受信する空のメッセージを無視します。

Direct Line サービスが、特定の条件下で WebSocket 接続を強制的に閉じる場合があります。クライアントは、endOfConversation アクティビティが受信されない場合は、会話に再接続するために使用できる新しい WebSocket ストリーム URL を生成できます。

WebSocket ストリームには、ライブ更新と最新のメッセージ (WebSocket 経由で接続するための呼び出しが発行されたため) が含まれていますが、の最新POST/v3/directline/conversations/{id}の前に送信されたメッセージは含まれません。会話内でこれまでに送信されたメッセージを取得するには、次に説明する HTTP GET を使用します。

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

WebSocket を使用できないクライアントは、HTTP GET を使用してアクティビティを取得できます。

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

以下のスニペットは、会話アクティビティ取得要求と応答の例を示しています。会話アクティビティ取得応答には、ActivitySet のプロパティとして watermark が含まれます。クライアントは、アクティビティが返らなくなるまで watermark 値を進めることで、入手できるアクティビティをすべて取得する必要があります。

Request

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

Response

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

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

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

WebSocket ストリームと会話アクティビティ取得応答で送信される watermark プロパティは信頼できます。ウォーターマークを逐語的に再生する限り、クライアントはメッセージを見逃しません。
クライアントが会話を開始して WebSocket ストリームに接続すると、POST の後で送信されたが、ソケットが開く前に送信されたすべてのアクティビティは、新しいアクティビティの前に再生されます。
クライアントが WebSocket ストリームに接続しているときに (履歴を更新するために) 会話アクティビティの取得要求を発行すると、両方のチャネルでアクティビティが重複する可能性があります。クライアントは、発生した場合に重複するアクティビティを拒否できるように、すべての既知のアクティビティ ID を追跡する必要があります。

HTTP GET を使用してポーリングを行うクライアントは、その使用目的と一致するポーリング間隔を選択する必要があります。

サービス間アプリケーションは、多くの場合、5 秒または 10 秒のポーリング間隔を使用します。
多くの場合、クライアント向けアプリケーションでは 1 秒のポーリング間隔を使用し、(ボットの応答を迅速に取得するために) クライアントが送信する各メッセージの直後に単一の追加要求を発行します。この遅延は 300 ミリ秒程度ですが、ボットの速度と転送時間に基づいて調整する必要があります。ポーリングは、長時間にわたって 1 秒に 1 回より頻繁に行うべきではありません。

次の方法で共有