ダイレクトライン API 1.1 でボットからメッセージを受信するReceive messages from the bot in Direct Line API 1.1

重要

この記事では、Direct Line API 1.1 を使用して、ボットからメッセージを受信する方法について説明します。This article describes how to receive messages from the bot using Direct Line API 1.1. クライアント アプリケーションとボットの間の新しい接続を作成する場合は、代わりに Direct Line API 3.0 を使用します。If you are creating a new connection between your client application and bot, use Direct Line API 3.0 instead.

クライアントは、メッセージを受信するには、Direct Line 1.1 プロトコルを使用して HTTP GET インターフェイスをポーリングする必要があります。Using the Direct Line 1.1 protocol, clients must poll an HTTP GET interface to receive messages.

HTTP GET でメッセージを取得するRetrieve messages with HTTP GET

特定の会話のメッセージを取得するには、GET 要求を api/conversations/{conversationId}/messages エンドポイントに発行します。オプションで、クライアントが認識した最新のメッセージを示す watermark パラメーターを指定できます。To retrieve messages for a specific conversation, issue a GET request to the api/conversations/{conversationId}/messages endpoint, optionally specifying the watermark parameter to indicate the most recent message seen by the client. メッセージが含まれていない場合でも、更新された watermark 値が JSON 応答内に返されます。An updated watermark value will be returned in the JSON response, even if no messages are included.

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

RequestRequest

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

ResponseResponse

HTTP/1.1 200 OK
[other headers]
{
    "messages": [
        {
            "conversation": "abc123",
            "id": "abc123|0000",
            "text": "hello",
            "from": "user1"
        }, 
        {
            "conversation": "abc123",
            "id": "abc123|0001",
            "text": "Nice to see you, user1!",
            "from": "bot1"
        }
    ],
    "watermark": "0001a-95"
}

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

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. メッセージ取得応答内に返される watermark プロパティは、信頼できます。The watermark property that is sent in the Get Messages response is reliable. ウォーターマーク文字列を再生する限り、クライアントがメッセージを見逃すことはありません。A client will not miss any messages as long as it replays the watermark verbatim.

クライアントは、その使用目的と一致するポーリング間隔を選択する必要があります。Clients 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 秒のポーリング間隔を使用し、クライアントが送信するすべてのメッセージの後で (ボットの応答を迅速に取得するために) 300 ミリ秒以内に追加要求を発行します。Client-facing applications often use a polling interval of 1s, and issue an additional request ~300ms after every message that the client sends (to rapidly retrieve a bot's response). この 300 ミリ秒の遅延は、ボットの速度と転送時間に基づいて調整する必要があります。This 300ms delay should be adjusted based on the bot's speed and transit time.

その他のリソースAdditional resources