通用動作模型

發行項
01/18/2024

上下文

調適型卡片是與平台無關的 UI 代碼段，由輕量型 JSON 格式撰寫，應用程式和服務可以共用。調適型卡片不僅適應主機的外觀和風格，也提供豐富的互動功能。如需調適型卡片的詳細資訊，請流覽 adaptivecards.io。

隨著調適型卡片的普及，不同的主機開始支援不同的動作模型，這導致了分散。為了解決這個問題，Teams、Outlook 和調適型卡片小組致力於建立跨主機相容的新通用 Bot 動作模型。這項努力導致下列各項：

Bot 和 Bot Framework 的一般化，作為針對 Teams（Bots）和 Outlook 實作調適型卡片型案例的方式（可採取動作的訊息）
Action.Execute 作為兩者的 Action.Submit 替代專案（目前由 Bot 使用）和 Action.Http （目前由可採取動作的郵件使用）
只有可採取動作的訊息才支援熱門功能提供給 Bot，也就是：
- 卡片在顯示時重新整理的能力
- 動作傳回更新卡片的能力 Action.Execute ，以立即顯示在用戶端中

如需 Outlook 中可採取動作的郵件的詳細資訊，請參閱可採取動作的郵件檔

如需Teams中通用動作可能的各種案例詳細數據，請參閱 Teams卡片參考。

之前 `Action.Execute`	使用 `Action.Execute`

來源：調適型卡片 @ Microsoft Build 2020

本文件的其餘部分著重於在 Teams 和 Outlook 的內容中記錄通用 Bot 動作模型。如果您已經在 Teams 上搭配 Bot 使用調適型卡片，您可以使用相同的 Bot 搭配幾個變更來支援 Action.Execute。如果您在 Outlook 上使用可採取動作的郵件，則必須開發支援 Action.Execute的 Bot。目前，通用 Bot 動作模型的 Outlook 用戶端支援正在進行中開發。

結構描述

重要

通用 Bot 動作模型是在調適型卡片架構 1.4 版中引進。若要使用這些新功能， version 調適型卡片的屬性必須設定為 1.4 或更新版本，如下列範例所示。請注意，這會讓您的調適型卡片與不支援通用 Bot 動作模型的舊版用戶端（Outlook 或 Teams）不相容。

如果您使用 refresh 屬性和/或 Action.Execute 並指定卡片 1.4 版 < ，則會發生下列情況：

用戶端行為

Outlook 您的卡片 將無法 運作。 refresh 將不會接受且 Action.Execute 不會轉譯。您的卡片甚至可能完全被拒絕。

Teams 您的卡片 可能無法 運作（ refresh 可能不接受，且 Action.Execute 動作可能無法轉譯），視 Teams 用戶端的版本而定。

若要確保 Teams 中的最大相容性，請考慮使用屬性中的fallback動作來定義您的Action.Execute動作Action.Submit。

如需詳細資訊，請參閱下方的 回溯相容性 一節。

用戶端	行為
Outlook	您的卡片將無法運作。 `refresh` 將不會接受且 `Action.Execute` 不會轉譯。您的卡片甚至可能完全被拒絕。
Teams	您的卡片可能無法運作（ `refresh` 可能不接受，且 `Action.Execute` 動作可能無法轉譯），視 Teams 用戶端的版本而定。若要確保 Teams 中的最大相容性，請考慮使用屬性中的`fallback`動作來定義您的`Action.Execute`動作`Action.Submit`。

Action.Execute

撰寫調適型卡片時，請使用 Action.Execute 來取代和 Action.SubmitAction.Http。架構與架構 Action.Execute 相當類似 Action.Submit。

範例 JSON

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

屬性

屬性	型別	必要	描述
type	`"Action.Execute"`	Yes	必須是 `"Action.Execute"`。
動詞	string	No	開發人員可用來識別動作的便利字串
data	`string`, `object`	No	將結合輸入欄位的初始數據。這些基本上是「隱藏」屬性。
title	`string`	No	代表此動作的按鈕或連結標籤。
iconUrl	`uri`	No	要與標題一起顯示在動作上的選擇性圖示。支援調適型卡片 1.2+ 版中的數據 URI
style	`ActionStyle`	No	控制動作的樣式，這會影響動作的顯示方式、口語等。
後備	`<action object>`, `"drop"`	No	描述當顯示卡片的客戶端不支援 Action.Execute 時該怎麼辦。
需要	`Dictionary<string>`	No	一系列的索引鍵/值組，指出專案需要具有對應最低版本的功能。當功能遺失或版本不足時，就會觸發後援。

重新整理機制

此外 Action.Execute，現在也支援新的重新整理機制，讓您能夠建立在顯示調適型卡片時自動更新的調適型卡片。這可確保使用者一律會看到最新的數據。典型的重新整理使用案例是核准要求：一旦核准，使用者最好不會出示卡片，提示他們在完成核准時核准，而是提供要求核准時間的相關信息，以及由誰核准。

若要允許調適型卡片自動重新整理，請定義其 refresh 屬性，以內嵌 action 型 Action.Execute 別和 userIds 數位。

屬性	型別	必要	描述
action	`"Action.Execute"`	Yes	必須是類型的 `"Action.Execute"`動作實例。
userIds	`Array<string>`	Yes	必須啟用自動重新整理的用戶陣列 `MRI`。重要：如果 `userIds` 清單屬性未包含在 `refresh` 卡片的區段中，卡片將不會在顯示時自動重新整理。相反地，系統會向用戶顯示按鈕，以允許他們手動重新整理。這是因為 Teams 中的聊天/頻道可以包含大量成員;如果許多成員同時檢視通道，則無條件自動重新整理會導致對 Bot 進行許多並行呼叫，而不會進行調整。為了緩解潛在的縮放問題， `userIds` 應該一律包含屬性來識別哪些用戶應該自動重新整理，目前最多允許 60 個使用者標識碼。如需詳細資訊，請參閱重新整理中的userId。請注意， `userIds` Outlook 中會忽略屬性，而且 `refresh` 屬性一律會自動接受。 Outlook 中沒有任何縮放問題，因為使用者通常會在不同的時間檢視卡片。

範例 JSON

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "originator":"c9b4352b-a76b-43b9-88ff-80edddaa243b",
  "version": "1.4",
  "refresh": {
    "action": {
      "type": "Action.Execute",
      "title": "Submit",
      "verb": "personalDetailsCardRefresh"
    },
    "userIds": []
  },
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    { 
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

Outlook 可採取動作的郵件開發人員的重要注意事項

開發 Outlook 可採取動作的郵件案例時，必須指定調適型卡片的 originator 屬性。 originator 是 Bot 訂閱 Outlook 通道時產生的全域唯一識別（GUID）。 Outlook 會使用它來驗證調適型卡片是由授權的 Bot 所傳送。如果 originator 不存在，調適型卡片將不會在 Outlook 中轉譯。 originator 在 Teams 中會忽略。

`adaptiveCard/action` 叫用活動

Action.Execute在用戶端中執行時（無論是重新整理動作，還是使用者按下按鈕明確採取的動作），就會對 Bot 進行新的叫用活動 adaptiveCard/action 類型。 adaptiveCard/action典型的 Invoke 活動要求看起來如下：

要求格式

{ 
  "type": "invoke",
  "name": "adaptiveCard/action",

  // ... other properties omitted for brevity

  "value": { 
    "action": { 
      "type": "Action.Execute", 
      "id": "abc", 
      "verb": "def",
      "data": { ... } 
    },
    "trigger": "automatic | manual" 
  }
}

欄位	描述
value.action	調適型卡片中所定義的動作複本。如同，`Action.Submitdata`動作的屬性包含卡片中各種輸入的值，如果有的話
value.trigger	指出動作是否已明確觸發（由使用者按下按鈕）或隱含地觸發（透過自動重新整理）

回應格式

如果 Bot 確實處理傳入 adaptiveCard/action 的 Invoke 活動（亦即，如果 Bot 的程式代碼完全涉及處理要求），則 Bot 傳回的 HTTP 回應狀態代碼必須等於 200，且 HTTP 回應主體的格式必須如下：

{ 
    "statusCode": <number (200 – 599)>, 
    "type": "<string>", 
    "value": "<object>"
}

欄位	描述
statusCode	HTTP 回應狀態代碼 200 不一定表示 Bot 能夠成功處理要求。用戶端應用程式必須一律查看 `statucCode` 響應主體中的屬性，以瞭解 Bot 如何處理要求。 `statusCode` 是一個從 200-599 開始的數位，其會鏡像 HTTP 狀態代碼值，而且是處理 Invoke 之 Bot 結果的子狀態。的遺漏、Null 或未定義值 `statusCode` 表示 200 （成功）。
type	一組已知的字串常數，描述 value 屬性的預期形狀
value	回應主體類型特定的物件

支援的狀態代碼

下表列出 Bot 回應主體中、 type和 value 的允許值statusCode：

狀態碼	類型	值架構	附註
200	`application/vnd.microsoft.card.adaptive`	`Adaptive Card`	要求已成功處理，且回應包含調適型卡片，用戶端應顯示以取代目前的調適型卡片。
200	`application/vnd.microsoft.activity.message`	`string`	已成功處理要求，回應會包含客戶端應該顯示的訊息。
400	`application/vnd.microsoft.error`	Error 物件（TODO：需要連結）	傳入要求無效。
401	`application/vnd.microsoft.activity.loginRequest`	OAuthCard （TODO：需要連結）	客戶端必須提示用戶進行驗證。
401	`application/vnd.microsoft.error.inccorectAuthCode`	null	用戶端傳遞的驗證狀態不正確，驗證失敗。
412	`application/vnd.microsoft.error.preconditionFailed`	Error 物件（TODO：需要連結）	SSO 驗證流程失敗。
500	`application/vnd.microsoft.error`	Error 物件（TODO：需要連結）	發生未預期的錯誤。

摘要：如何使用通用 Bot 動作模型

使用 Action.Execute 取代 Action.Submit。若要更新小組的現有案例，請將的所有實例 Action.Submit 取代為 Action.Execute。如需升級 Outlook 上現有的案例，請參閱下方的回溯相容性一節。
若要讓卡片顯示在 Outlook 上，請新增 originator 欄位。請參閱上述範例 JSON。
refresh如果您想要利用自動重新整理機制，或您的案例需要使用者特定的檢視，請將子句新增至調適型卡片。請務必指定 userIds 屬性，以識別哪些使用者（最多 60 個）將取得自動更新。
處理 adaptiveCard/action Bot 中的叫用要求
每當 Bot 因處理 Action.Execute而需要傳回新的卡片時，您可以使用 Invoke 要求的內容來產生專為指定使用者製作的卡片。請確定回應符合上述定義的回應架構。

回溯相容性

Outlook

新的 Action.Execute 通用動作模型與 Outlook 可採取動作的郵件目前使用的動作模型背離 Action.Http ，其中動作會在調適型卡片中編碼為明確的 HTTP 呼叫。此 Action.Execute 模型可讓開發人員實作在 Outlook 和 Teams 中「只運作」的案例。可採取動作的訊息案例可以使用 Action.Http 模型或新的 Action.Execute 模型，但不能同時使用這兩者。使用通用 Action.Execute 模型的案例必須實作為 Bot 並訂閱 Outlook Actionable Messages 通道。

重要注意

使用通用 Action.Execute 模型實作的案例與舊版 Outlook 不相容

工作正在進行中，以允許現有的可採取動作的訊息案例順暢地遷移至通用 Action.Execute 模型

Teams

為了讓卡片在舊版 Teams 上相容且適用於使用者，您的 Action.Execute 動作應該包含 fallback 定義為 Action.Submit的屬性。您的 Bot 應該以 Action.Execute 處理和 Action.Submit的方式撰寫程式代碼。請注意，Bot 在處理 Action.Submit時無法傳回新的卡片，因此透過的後援行為 Action.Submit 將為終端使用者提供降級的體驗。

重要事項

某些較舊的Teams用戶端在未包裝於 ActionSet時，不支援後援屬性。為了不中斷這類客戶端，強烈建議您在中ActionSet包裝所有Action.Execute 。 請參閱下列範例，以瞭解如何在中ActionSet包裝Action.Execute。

在下列範例中，請注意version，卡片的屬性會設定為 1.2 ，且 Action.Execute 會以 Action.Submit 定義為。fallback 在支援調適型卡片 1.4 的 Teams 用戶端中轉譯時， Action.Execute 將會轉譯並如預期般運作。在不支援調適型卡片 1.4 的 Teams 用戶端中， Action.Submit 將會轉譯為取代 Action.Execute。

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": {
            "type": "Action.Submit",
            "title": "Submit"
          }  
        }
      ]
    }
  ]
}

共用方式為

通用動作模型

上下文

結構描述

重要

Action.Execute

重新整理機制

Outlook 可採取動作的郵件開發人員的重要注意事項

`adaptiveCard/action` 叫用活動

要求格式

回應格式

摘要：如何使用通用 Bot 動作模型

回溯相容性

Outlook

重要注意

Teams

重要事項

參考資料

其他資源

共用方式為

通用動作模型

上下文

結構描述

重要

Action.Execute

重新整理機制

Outlook 可採取動作的郵件開發人員的重要注意事項

adaptiveCard/action 叫用活動

要求格式

回應格式

摘要：如何使用通用 Bot 動作模型

回溯相容性

Outlook

重要注意

Teams

重要事項

參考資料

其他資源

`adaptiveCard/action` 叫用活動