從 Direct Line API 3.0 中的 Bot 接收活動

發行項
03/08/2023

透過使用直接線路 3.0 通訊協定，用戶端可以透過 WebSocket 串流來接收活動，或透過發出 HTTP GET 要求來擷取活動。

WebSocket 與 HTTP GET

串流 WebSocket 會有效率地將訊息推送到用戶端，而 GET 介面可讓用戶端明確地要求訊息。雖然 WebSocket 機制因其效率而較常被使用，但 GET 機制對於無法使用 WebSockets 的用戶端而言非常實用。

此服務只允許每個交談有 1 個 WebSocket 連線。 Direct Line 可能會關閉其他 WebSocket 連線，並顯示值為 collision 的原因。

並非所有活動類型都可透過 WebSocket 和 HTTP GET 這兩者使用。下表說明對於使用直接線路通訊協定的用戶端之各種活動類型的可用性。

活動類型	可用性
message	HTTP GET 和 WebSocket
typing	只有 WebSocket
conversationUpdate	不透過用戶端傳送/接收
contactRelationUpdate	直接線路中不支援
endOfConversation	HTTP GET 和 WebSocket
所有其他活動類型	HTTP GET 和 WebSocket

透過 WebSocket 串流接收活動

當用戶端傳送開始對話要求以開啟和 Bot 的對話時，服務的回應包含用戶端可以在後續用於透過 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 連線之後，用戶端可能會收到來自直接線路服務的這些訊息類型：

包含 ActivitySet 的訊息，其中包括一或多個活動和浮水印 (如下所述)。
空白訊息，直接線路服務用來確認連線仍然有效。
其他類型 (在稍後定義)。這些類型由 JSON 根中的屬性識別。

ActivitySet 包含由 Bot 及對話中所有使用者所傳送的訊息。下列範例顯示包含單一訊息的 ActivitySet。

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

處理訊息

用戶端應該持續追蹤收到的每個 ActivitySet 中的 watermark 值，這樣就能使用浮水印來保證在連線中斷時不會有任何訊息遺失而需要重新連線到對話。如果用戶端接收到的 ActivitySet 中的 watermark 屬性為 null 或已遺失，則它應該忽略該值且不覆寫之前收到的浮水印。

用戶端應該忽略從直接線路服務收到的空白訊息。

用戶端可能會傳送空白訊息至直接線路服務以驗證連線能力。直接線路服務將會忽略從用戶端收到的空白訊息。

直接線路服務在某些情況下可能會強制關閉 WebSocket 連線。如果用戶端尚未收到 endOfConversation 活動，它可能會產生新的 WebSocket 串流 URL，以用於重新連線到對話。

WebSocket 資料流程包含即時更新和最近的訊息 (，因為透過 WebSocket 的呼叫已發出) ，但不包含最近一次之前 POST/v3/directline/conversations/{id} 所傳送的訊息。若要擷取對話中稍早之前的訊息，請使用下述的 HTTP GET。

使用 HTTP GET 擷取活動

無法使用 WebSockets 的用戶端可以使用 HTTP GET 擷取活動。

若要擷取特定交談的訊息，請向 /v3/directline/conversations/{conversationId}/activities 端點發出 GET 要求，選擇性指定 watermark 參數以指出用戶端看到的最新訊息。

下列程式碼片段提供「取得對話活動」的要求和回應範例。「取得對話活動」回應包含 watermark 做為 ActivitySet 的屬性。用戶端應隨 watermark 值向前逐頁查詢可用的活動，直到沒有活動傳回。

要求

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

回應

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

計時考量

大部分的用戶端都希望建立完整的訊息記錄。雖然直接線路是有潛在計時間隔的多方通訊協定，但通訊協定和服務的設計旨在讓您更容易建置可靠的用戶端。

在 WebSocket 串流和「取得對話活動」回應中傳送的 watermark 屬性很可靠。只要用戶端重新執行浮水印逐字，用戶端就不會遺漏任何訊息。
當用戶端啟動對話並連線到 WebSocket 串流時，在 POST 之後且在通訊端開啟之前傳送的任何活動，都會在新的活動前重新執行。
當用戶端發出取得交談活動要求時， (連線到 WebSocket 串流時重新整理記錄) ，活動可能會跨這兩個通道重複。用戶端應該追蹤所有已知的活動識別碼，使其能夠拒絕重複的活動，應該會發生。

使用 HTTP GET 輪詢的用戶端應選擇符合其使用目的的輪詢間隔。

服務對服務應用程式通常會使用 5 秒或 10 秒的輪詢間隔。
面向用戶端的應用程式通常使用 1 秒的輪詢間隔，並在用戶端傳送的每則訊息後，迅速發出單一其他要求 (以快速擷取 Bot 的回應)。此延遲最短 300 毫秒，但應根據 Bot 的速度和傳輸時間調整。輪詢不應超過每秒一次，任何延長的時間。

共用方式為