API 參考 - Direct Line API 3.0

發行項
02/29/2024

您可以讓用戶端應用程式使用 Direct Line API 3.0 與 Bot 通訊。 Direct Line API 3.0 使用業界標準的 REST 和 JSON over HTTPS。

基底 URI

若要存取 Direct Line API 3.0，請將下列其中一個基底 URI 用於所有 API 要求：

針對全域 Bot，請使用 https://directline.botframework.com
針對區域 Bot，根據選取的區域輸入下列 URI：

區域基底 URI

歐洲 https://europe.directline.botframework.com

印度 https://india.directline.botframework.com

區域	基底 URI
歐洲	`https://europe.directline.botframework.com`
印度	`https://india.directline.botframework.com`

提示

如果您使用區域 Bot 的全域基底 URI，要求可能會失敗，因為某些要求可能會超出地理界限。

標頭

除了標準 HTTP 要求標頭之外，Direct Line API 要求還必須包含 Authorization 標頭，以指定秘密或令牌來驗證發出要求的用戶端。使用此格式指定 Authorization 標頭：

Authorization: Bearer SECRET_OR_TOKEN

如需如何取得用戶端可用來驗證其 Direct Line API 要求之秘密或令牌的詳細資訊，請參閱驗證。

HTTP 狀態碼

每個回應所傳回的 HTTP 狀態代碼會指出對應要求的結果。

HTTP 狀態碼	意義
200	要求成功。
201	要求成功。
202	要求已接受進行處理。
204	要求成功，但未傳回任何內容。
400	要求的格式不正確或不正確。
401	用戶端未獲授權提出要求。此狀態代碼通常會因為 `Authorization` 標頭遺失或格式不正確而發生。
403	用戶端不允許執行要求的作業。作業可能會因為下列原因而失敗。無效的令牌：當要求使用先前有效的令牌但已過期時，`code`ErrorResponse 物件內傳回的 Error 屬性會設定為 `TokenExpired`。數據界限違規：如果您的 Bot 是區域 Bot，但基底 URI 不是區域，某些要求可能會超出地理界限。無效的目標資源：目標 Bot 或網站無效或已刪除。
404	找不到要求的資源。此狀態代碼通常表示要求 URI 無效。
500	Direct Line 服務內發生內部伺服器錯誤。
502	Bot 無法使用或傳回錯誤。這是常見的錯誤碼。

注意

HTTP 狀態代碼 101 用於 WebSocket 連線路徑，但 WebSocket 用戶端可能會處理此情況。

錯誤

任何指定 4xx 範圍或 5xx 範圍中 HTTP 狀態代碼的回應，都會在提供錯誤相關信息的響應主體中包含 ErrorResponse 物件。如果您在 4xx 範圍內收到錯誤回應，請檢查 ErrorResponse 對象以識別錯誤的原因，並在重新提交要求之前解決您的問題。

注意

ErrorResponse 物件內屬性中指定的 code HTTP 狀態代碼和值是穩定的。 ErrorResponse 物件內屬性中指定的message值可能會隨著時間而變更。

下列代碼段顯示範例要求和產生的錯誤回應。

要求

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]

回應

HTTP/1.1 502 Bad Gateway
[other headers]

{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

令牌作業

使用這些作業來建立或重新整理用戶端可用來存取單一交談的令牌。

作業	描述
產生令牌	產生新交談的令牌。
重新整理令牌	重新整理令牌。

產生令牌

產生一個交談有效的令牌。

POST /v3/directline/tokens/generate

Content	描述
要求本文	TokenParameters 物件
傳回	Conversation 物件

重新整理令牌

重新整理令牌。

POST /v3/directline/tokens/refresh

Content	描述
要求本文	n/a
傳回	Conversation 物件

交談作業

使用這些作業來開啟與 Bot 的交談，並在用戶端和 Bot 之間交換活動。

作業	描述
開始交談	開啟與 Bot 的新交談。
取得交談資訊	取得現有交談的相關信息。此作業會產生新的 WebSocket 數據流 URL，用戶端可用來重新連線至交談。
取得活動	從 Bot 擷取活動。
傳送活動	將活動傳送至 Bot。
上傳和傳送檔案（s）	上傳並傳送檔案作為附件（s）。

開始交談

開啟與 Bot 的新交談。

POST /v3/directline/conversations

Content	描述
要求本文	TokenParameters 物件
傳回	Conversation 物件

取得交談資訊

取得現有交談的相關信息，也會產生用戶端可用來重新連線至交談的新 WebSocket 數據流 URL。您可以選擇性地在要求 URI 中提供 watermark 參數，以指出用戶端看到的最新訊息。

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}

Content	描述
要求本文	n/a
傳回	Conversation 物件

取得活動

從 Bot 擷取指定交談的活動。您可以選擇性地在要求 URI 中提供 watermark 參數，以指出用戶端看到的最新訊息。

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}

Content	描述
要求本文	n/a
傳回	ActivitySet 物件。回應包含 `watermark` 做為對象的屬性 `ActivitySet` 。客戶端應該藉由將值往前推進 `watermark` ，以逐頁查看可用的活動，直到未傳回任何活動為止。

傳送活動

將活動傳送至 Bot。

POST /v3/directline/conversations/{conversationId}/activities

Content	描述
要求本文	Activity 物件
傳回	ResourceResponse，其中包含`id`屬性，指定傳送至 Bot 的活動識別碼。

上傳和傳送檔案（s）

上傳並傳送檔案作為附件（s）。 userId在要求 URI 中設定參數，以指定傳送附件的使用者識別碼。

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}

Content	描述
要求本文	針對單一附件，使用檔案內容填入要求本文。針對多個附件，建立多部分要求本文，其中包含每個附件的一個部分，同時為 Activity 物件建立一個元件，該部分應做為指定附件的容器。如需詳細資訊，請參閱將活動傳送至 Bot。
傳回	ResourceResponse，其中包含`id`屬性，指定傳送至 Bot 的活動識別碼。

注意

上傳的檔案會在 24 小時後刪除。

結構描述

Direct Line 3.0 架構包含 Bot Framework 架構所定義的所有物件，以及 Direct Line 特有的某些物件。

ActivitySet 物件

定義一組活動。

屬性	類型	描述
活動	Activity[]	Activity 對象的陣列。
浮浮水印	string	集合內活動的最大水位線。用戶端可能會使用 `watermark` 值來指出從 Bot 擷取活動或產生新的 WebSocket 資料流 URL 時，它所看到的最新訊息。

Conversation 物件

定義 Direct Line 交談。

屬性	類型	描述
conversationId	string	可唯一識別指定令牌有效之交談的標識碼。
Etag	string	HTTP ETag （實體標籤）。
expires_in	數值	令牌到期之前的秒數。
referenceGrammarId	string	此 Bot 參考文法的識別碼。
streamUrl	string	交談訊息數據流的 URL。
令牌	string	適用於指定交談的令牌。

TokenParameters 物件

建立令牌的參數。

屬性	類型	描述
Etag	string	HTTP ETag （實體標籤）。
trustedOrigins	string[]	要內嵌在令牌中的受信任來源。
user	ChannelAccount	要內嵌在令牌中的用戶帳戶。

活動

針對用戶端透過 Direct Line 從 Bot 接收的每個活動：

附件卡片會保留下來。
上傳附件的 URL 會以私人連結隱藏。
屬性 channelData 會保留而不修改。

用戶端可能會從 Bot 接收多個活動，做為 ActivitySet 的一部分。

當用戶端透過 Direct Line 將傳送 Activity 至 Bot 時：

屬性 type 會指定其傳送的類型活動（通常是訊息）。
from屬性必須填入客戶端選擇的使用者識別碼。
附件可能包含透過 Direct Line 附件端點上傳之現有資源的 URL 或 URL。
屬性 channelData 會保留而不修改。
當串行化為 JSON 並加密時，活動的總大小不得超過 256K 個字元。建議您讓活動保持在 150K 之下。如果需要更多數據，請考慮將活動分割起來或使用附件。

用戶端可能會為每個要求傳送單一活動。

其他資源

Bot Framework 活動規格

共用方式為

API 參考 - Direct Line API 3.0

基底 URI

標頭

HTTP 狀態碼

錯誤

要求

回應

令牌作業

產生令牌

重新整理令牌

交談作業

開始交談

取得交談資訊

取得活動

傳送活動

上傳和傳送檔案（s）

結構描述

ActivitySet 物件

Conversation 物件

TokenParameters 物件

活動

其他資源

其他資源