ユニバーサルアクションモデル

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

Context

アダプティブカードは、軽量の JSON 形式を使用して作成された、プラットフォームに依存しない UI のスニペットです。アプリやサービスから共有できます。アダプティブカードは、ホストの外観に適応できるだけでなく、豊富な対話機能も備えています。アダプティブカードの詳細については、adaptivecards.io を参照してください。

アダプティブカードが普及するにつれて、さまざまなホストがさまざまなアクションモデルをサポートするようになり、それが断片化につながりました。この問題を解決するために、Teams、Outlook、および Adaptive Cards の各チームは、ホスト間で互換性のある新しいユニバーサルボットアクションモデルの作成に取り組みました。この取り組みの結果、次のような成果がありました。

Teams (ボット) と Outlook (アクション可能メッセージ) の両方に対応するアダプティブカードベースのシナリオを実装する方法としてのボットと Bot Framework の汎用化
Action.Submit (現在ボットで使用されています) と Action.Http (アクション可能メッセージで現在使用されています) の両方の代わりとなる Action.Execute
次のような、ボットから使用できるアクション可能メッセージでのみサポートされている人気のある機能。
- カードの表示時に更新される機能
- 更新されたカードを返し、クライアントにすぐに表示する Action.Execute アクションの機能

Outlook のアクション可能メッセージの詳細については、アクション可能メッセージのドキュメントを参照してください。

Teams のユニバーサルアクションで可能なさまざまなシナリオの詳細については、Teams カードのリファレンスを参照してください。

`Action.Execute` の前	With `Action.Execute`

ソース: Microsoft Build 2020 のアダプティブカード

このドキュメントの残りの部分では、Teams と Outlook のコンテキストでユニバーサルボットアクションモデルについて説明することに焦点を当てています。ボットを使用する Teams 上で既にアダプティブカードを使用している場合は、Action.Execute をサポートするようにいくつか変更を加えて同じボットを使用することができます。 Outlook でアクション可能メッセージを使用している場合は、Action.Execute をサポートするボットを開発する必要があります。現在、ユニバーサルボットアクションモデル用 Outlook クライアントのサポートは活発に開発されています。

[スキーマ]

重要

ユニバーサルボットアクションモデルは、アダプティブカードスキーマバージョン 1.4 で導入されました。これらの新機能を使用するには、以下の例に示すように、アダプティブカードの version プロパティを 1.4 以上に設定する必要があります。これにより、アダプティブカードがユニバーサルボットアクションモデルをサポートしていない古いクライアント (Outlook または Teams) と互換性がなくなることに注意してください。

refresh プロパティや Action.Execute を使用し、1.4 より前のカードバージョンを指定すると、次のようになります。

クライアント Behavior

Outlook カードは動作しません。 refresh は考慮されず、Action.Execute はレンダリングされません。カードが完全に拒否される可能性もあります。

Teams Teams クライアントのバージョンによっては、カードが動作しない場合があります (refresh が考慮されない場合があり、Action.Execute アクションがレンダリングされない場合があります)。

Teams で最大限の互換性を確保するには、fallback プロパティで Action.Submit アクションを使用して Action.Execute アクションを定義することを検討してください。

詳細については、後述する「旧バージョンとの互換性」セクションを参照してください。

クライアント	Behavior
Outlook	カードは動作しません。 `refresh` は考慮されず、`Action.Execute` はレンダリングされません。カードが完全に拒否される可能性もあります。
Teams	Teams クライアントのバージョンによっては、カードが動作しない場合があります (`refresh` が考慮されない場合があり、`Action.Execute` アクションがレンダリングされない場合があります)。 Teams で最大限の互換性を確保するには、`fallback` プロパティで `Action.Submit` アクションを使用して `Action.Execute` アクションを定義することを検討してください。

Action.Execute

アダプティブカードを作成するときは、Action.Submit と Action.Http の両方ではなく Action.Execute を使用します。 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"
        }
      ]
    }
  ]
}

プロパティ

プロパティ	タイプ	Required	説明
type	`"Action.Execute"`	はい	`"Action.Execute"`である必要があります。
verb	string	いいえ	開発者がアクションを識別するために使用できる便宜的な文字列
data	`string`、`object`	いいえ	入力フィールドが結合される初期データ。これらは基本的に "隠された" プロパティです。
title	`string`	いいえ	このアクションを表すボタンまたはリンクのラベル。
iconUrl	`uri`	いいえ	タイトルと組み合わせてアクションに表示される省略可能なアイコン。アダプティブカードバージョン 1.2 以降でデータ URI がサポートされます
スタイル	`ActionStyle`	いいえ	アクションのスタイルを制御します。これは、アクションの表示方法、話し方などに影響があります。
fallback	`<action object>`、`"drop"`	いいえ	カードを表示しているクライアントが Action.Execute をサポートしていない場合の対処方法について記述します。
requires	`Dictionary<string>`	いいえ	項目に必要な機能と対応する最小バージョンを示す一連のキーと値のペア。機能がない場合、またはバージョンが不十分な場合、fallback がトリガーされます。

更新メカニズム

Action.Execute とは別に、新しい更新メカニズムがサポートされ、表示時に自動的に更新されるアダプティブカードを作成できるようになりました。これにより、ユーザーは常に最新のデータを表示できます。一般的な更新のユースケースとして、承認要求があります。承認された場合、既に完了している承認を求めるカードがユーザーに表示されるのではなく、要求が承認された日時とユーザーに関する情報が表示されることが最適です。

アダプティブカードを自動的に更新できるようにするには、その refresh プロパティを定義します。これには、型 Action.Execute の action と userIds 配列が埋め込まれています。

プロパティ	タイプ	Required	説明
action	`"Action.Execute"`	はい	型 `"Action.Execute"` のアクションインスタンスである必要があります。
userIds	`Array<string>`	はい	自動更新を有効にする必要があるユーザーの `MRI` の配列。重要:`userIds` リストプロパティがカードの `refresh` セクションに含まれていない場合、カードは表示時に自動的に更新されません。そうではなく、手動で更新する機能を持つボタンがユーザーに表示されます。この理由は、Teams 内のチャット/チャネルには多数のメンバーが含まれている可能性があるためです。多数のメンバー全員が同時にそのチャネルを表示している場合、無条件の自動更新により、ボットに対する多数の同時呼び出しが発生します。これはスケーリングされません。スケールの問題が発生する可能性を軽減するために、`userIds` プロパティを常に含めて、自動更新を取得する必要があるユーザーを特定するようにします。現在、最大 60 ユーザーの ID が許可されています。詳細については、「更新中のユーザー ID」を参照してください。 Outlook では `userIds` プロパティは無視され、`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 は、ボットが Outlook チャネルにサブスクライブするときに生成されるグローバル一意識別子 (GUID) です。これは、承認済みのボットからアダプティブカードが送信されたことを検証するために Outlook によって使用されます。 originator がない場合、アダプティブカードは Outlook に表示されません。 originator は Teams では無視されます。

`adaptiveCard/action` Invoke アクティビティ

クライアントで Action.Execute が実行されると (更新アクション、またはユーザーがボタンをクリックして明示的に実行したアクション)、新しい種類の Invoke アクティビティ (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.Submit` と同様に、アクションの `data` プロパティには、カード内のさまざまな入力の値が含まれています (存在する場合)。
value.trigger	アクションが明示的に (ユーザーがボタンをクリックすることによって) トリガーされたか、暗黙的に (自動更新を介して) トリガーされたかを示します

応答形式

ボットが受信の adaptiveCard/action Invoke アクティビティを処理した場合 (つまり、ボットのコードが要求の処理にまったく関与していない場合)、ボットから返される HTTP 応答の状態コードを必ず 200 にし、HTTP 応答の本文を次のような書式に設定する必要があります。

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

フィールド	説明
statusCode	HTTP 応答の状態コード 200 は、必ずしもボットによって要求が正常に処理されたことを意味するわけではありません。クライアントアプリケーション側で、ボットによって要求がどのように処理されたかを把握するには、常に応答の本文の `statucCode` プロパティを確認する必要があります。 `statusCode` は、HTTP 状態コード値を反映する 200 から 599 の範囲の数値であり、ボットによる呼び出しの処理結果のサブ状態として使用するためのものです。 `statusCode` の値がない、null、または未定義の場合は、200 (成功) を意味します。
type	value プロパティの予想される形状を記述する、既知の文字列定数のセット
value	応答本文の種類に固有のオブジェクト

サポートされている状態コード

ボットの応答本文内で使用される statusCode、type、および value の値を次の表に示します。

状態コード	Type	値スキーマ	メモ
200	`application/vnd.microsoft.card.adaptive`	`Adaptive Card`	要求は正常に処理されました。また、応答には、クライアント側で現在のカードの代わりに表示する必要があるアダプティブカードが含まれています。
200	`application/vnd.microsoft.activity.message`	`string`	要求は正常に処理されました。また、応答には、クライアント側で表示する必要のあるメッセージが含まれています。
400	`application/vnd.microsoft.error`	エラーオブジェクト (TODO: リンクが必要)	受信要求が無効でした。
401	`application/vnd.microsoft.activity.loginRequest`	OAuthCard (TODO: リンクが必要)	クライアント側で、ユーザーに認証を求める必要があります。
401	`application/vnd.microsoft.error.inccorectAuthCode`	null	クライアントから渡された認証状態が正しくないため、認証に失敗しました。
412	`application/vnd.microsoft.error.preconditionFailed`	エラーオブジェクト (TODO: リンクが必要)	SSO 認証フローに失敗しました。
500	`application/vnd.microsoft.error`	エラーオブジェクト (TODO: リンクが必要)	予期しないエラーが発生しました。

概要: ユニバーサルボットアクションモデルを活用する方法

Action.Submit ではなく Action.Execute を使用します。 Teams の既存のシナリオを更新するには、Action.Submit のすべてのインスタンスを Action.Execute に置き換えます。 Outlook での既存のシナリオをアップグレードする方法については、後述する「旧バージョンとの互換性」セクションを参照してください。
カードを Outlook に表示するには、originator フィールドを追加します。前述のサンプル JSON を参照してください。
自動更新メカニズムを利用する場合、またはシナリオにユーザー固有のビューが必要な場合は、アダプティブカードに refresh 句を追加します。自動更新を受けるユーザー (最大 60) を識別するために、userIds プロパティを必ず指定してください。
ボットで adaptiveCard/action 呼び出し要求を処理します
Action.Execute の処理の結果としてボットから新しいカードを返す必要があるときは常に、Invoke 要求のコンテキストを使用して、特定のユーザー向けに特別に作成されたカードを生成することができます。応答が上で定義された応答スキーマに準拠していることを確認します。

下位互換性

Outlook

新しい Action.Execute ユニバーサルアクションモデルは、Outlook のアクション可能メッセージで現在使用されている Action.Http アクションモデル (アクションは明示的な HTTP 呼び出しとしてアダプティブカードにエンコードされています) を出発点としたものです。 Action.Execute モデルを使用すると、開発者は Outlook と Teams の両方で "正しく機能する" シナリオを実装できます。アクション可能メッセージのシナリオでは、Action.Http モデルまたは新しい Action.Execute モデルのいずれかを使用できますが、両方を使用することはできません。ユニバーサル Action.Execute モデルを使用するシナリオは、ボットとして実装し、Outlook Actionable Messages チャネルにサブスクライブする必要があります。

重要な注意事項

ユニバーサル Action.Execute モデルを使用して実装されたシナリオは、以前のバージョンの Outlook と互換性がありません

既存のアクション可能メッセージシナリオをユニバーサル Action.Execute モデルにシームレスに移行できるようにする取り組みが進行中です

Teams

カードに下位互換性を持たせ、以前のバージョンの Teams のユーザーでも利用できるようにするには、Action.Submit として定義された fallback プロパティを Action.Execute アクションに含める必要があります。ボットは、Action.Execute と Action.Submit の両方を処理できるようにコーディングする必要があります。 Action.Submit の処理時にボットから新しいカードを返すことはできないため、Action.Submit を介したフォールバック動作によって、エンドユーザーのエクスペリエンスが低下することに注意してください。

重要:

一部の古い Teams クライアントでは、ActionSet でラップされていない fallback プロパティがサポートされていません。このようなクライアントで中断が発生しないように、すべての Action.Execute を ActionSet でラップすることを強くお勧めします。 Action.Execute を ActionSet でラップする方法については、以下の例を参照してください。

以下の例では、カードの version プロパティが 1.2 に設定されており、fallback である Action.Submit を使用して Action.Execute が定義されていることに注意してください。アダプティブカード 1.4 をサポートする Teams クライアントでレンダリングすると、Action.Execute は期待どおりにレンダリングされ、動作します。アダプティブカード 1.4 をサポートしていない Teams クライアントの場合、Action.Execute ではなく Action.Submit がレンダリングされます。

{
  "$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"
          }  
        }
      ]
    }
  ]
}

ユニバーサル アクション モデル