アダプティブ カードのユーザー ピッカー

ユーザー ピッカーは、ユーザーがアダプティブ カードでユーザーを検索して選択するのに役立ちます。 ユーザー 選択ウィンドウをアダプティブ カードに入力コントロールとして追加できます。これは、チャット、チャネル、ダイアログ (TeamsJS v1.x のタスク モジュールと呼ばれます)、タブ間で機能します。 People Picker では、次の機能がサポートされています。

• 1 人または複数のユーザーを検索します。
• 1 つまたは複数のユーザーを選択します。
• 1 人または複数のユーザーに再割り当てします。
• 選択したユーザーの名前を事前入力します。

一般的なシナリオ

次の表に、アダプティブ カードの People Picker の一般的なシナリオと、対応するアクションを示します。

People Picker を実装する

People Picker は、 Input.ChoiceSet コントロールの拡張機能として実装されます。 入力コントロールには、次の選択項目が含まれます。

• 展開された選択などのドロップダウン。
• 1 つの選択など、ラジオ ボタン。
• 複数の選択などのチェック ボックス。

スキーマを更新する

次のプロパティは、カードで People Picker エクスペリエンスを有効にするために、 Input.ChoiceSet スキーマに追加されています。

Input.ChoiceSet コントロール

Data.Query

データセット

次の表に、ユーザー 選択ウィンドウの データセット として定義済みの値を示します。

例

組織検索を使用して People Picker を作成するコード例は次のとおりです。

{
 "type": "AdaptiveCard",
 "body": [
  {
   "type": "TextBlock",
   "size": "Medium",
   "weight": "Bolder",
   "text": "People Picker with Org search enabled"
  },
  {
   "type": "Input.ChoiceSet",
   "choices": [],
   "choices.data": {
    "type": "Data.Query",
    "dataset": "graph.microsoft.com/users"
   },
   "id": "people-picker",
   "isMultiSelect": true
  }
 ],
 "actions": [
  {
   "type": "Action.Submit",
   "title": "Submit"
  }
 ],
 "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
 "version": "1.2"
}

次の図は、組織検索を使用したアダプティブ カードの People Picker を示しています。

会話メンバーの一覧内で検索を有効にするには、データセット テーブルで定義されている適切な データセット を使用します。 isMultiSelect プロパティは、コントロール内の複数のユーザーの選択を有効にするために使用されます。 既定では false に設定されており、この設定では 1 人のユーザーのみを選択できます。

データ送信

Action.SubmitまたはAction.Executeを使用して、選択したデータをボットに送信できます。 ボットで受信した invoke ペイロードは、Microsoft Entra ID または静的リストで提供される ID の一覧です。 People Picker で、ユーザーがコントロールで選択されている場合、ユーザーの Microsoft Entra ID は戻される値です。 Microsoft Entra IDは文字列であり、ディレクトリ内のユーザーを一意に識別します。

ボットに送信される値の形式は、 isMultiSelect プロパティの値によって異なります。

Microsoft Entra IDでは、People Picker によって対応するユーザーが事前に選択されます。

ユーザーの事前選択

People Picker では、アダプティブ カードを作成して送信するときに、コントロール内のユーザーの事前選択がサポートされます。 Input.ChoiceSet は、ユーザーの事前選択に使用される value プロパティをサポートします。 この value プロパティの形式は、 データ送信で送信された値の形式と同じです。
次の一覧では、ユーザーの事前選択に関する情報を示します。

• コントロール内の単一ユーザーの場合は、ユーザーの Microsoft Entra ID を valueとして指定します。
• isMultiSelectがtrueなど、複数のユーザーの場合は、Microsoft Entra IDのコンマ区切り文字列を指定します。

次の例では、1 人のユーザーの事前選択について説明します。

{
 "type": "AdaptiveCard",
 "body": [
  {
   "type": "TextBlock",
   "size": "Medium",
   "weight": "Bolder",
   "text": "People Picker with Org search enabled"
  },
  {
   "type": "Input.ChoiceSet",
   "choices": [],
   "choices.data": {
    "type": "Data.Query",
    "dataset": "graph.microsoft.com/users"
   },
   "id": "people-picker",
   "value": "<Microsoft Entra ID 1>"
  }
 ],
 "actions": [
  {
   "type": "Action.Submit",
   "title": "Submit"
  }
 ],
 "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
 "version": "1.2"
}

次の例では、複数のユーザーの事前選択について説明します。

{
 "type": "AdaptiveCard",
 "body": [
  {
   "type": "TextBlock",
   "size": "Medium",
   "weight": "Bolder",
   "text": "People Picker with Org search enabled"
  },
  {
   "type": "Input.ChoiceSet",
   "choices": [],
   "choices.data": {
    "type": "Data.Query",
    "dataset": "graph.microsoft.com/users"
   },
   "id": "people-picker",
   "isMultiSelect": true,
   "value": "<Microsoft Entra ID 1>,<Microsoft Entra ID 2>,<Microsoft Entra ID 3>"
  }
 ],
 "actions": [
  {
   "type": "Action.Submit",
   "title": "Submit"
  }
 ],
 "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
 "version": "1.2"
}

静的な選択肢

静的な選択肢では、定義済みのデータセットにカスタム プロファイルを挿入する必要があるシナリオがサポートされています。 Input.ChoiceSet では、json で静的に choices を指定できます。 静的な選択は、ユーザーが選択できる選択肢を作成するために使用されます。

選択は、 title と valueで構成されます。 People Picker と共に使用すると、これらの選択肢は、名前として title を持ち、識別子として value を持つユーザー プロファイルに変換されます。 これらのカスタム プロファイルは、検索クエリが指定された titleと一致する場合にも検索結果の一部です。 次の例では、静的な選択肢について説明します。

{
 "type": "AdaptiveCard",
 "body": [
  {
   "type": "TextBlock",
   "size": "Medium",
   "weight": "Bolder",
   "text": "People Picker with Org search enabled"
  },
  {
   "type": "Input.ChoiceSet",
   "choices": [
    {
     "title": "Custom Profile 1",
     "value": "Profile1"
    },
    {
     "title": "Custom Profile 2",
     "value": "Profile2"
    }
   ],
   "choices.data": {
    "type": "Data.Query",
    "dataset": "graph.microsoft.com/users"
   },
   "id": "people-picker",
   "isMultiSelect": true
  }
 ],
 "actions": [
  {
   "type": "Action.Submit",
   "title": "Submit"
  }
 ],
 "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
 "version": "1.2"
}

次の図は、組織の検索で静的な選択肢を持つアダプティブ カードのユーザー 選択ウィンドウを示しています。

さまざまなシナリオで効率的なタスク管理を行うには、People Picker を実装できます。

コード サンプル

関連項目

• カードの種類
• ボットと SDK
• Teams のメッセージ拡張機能をビルドする
• Microsoft 365 グループのコネクタを作成する
• アダプティブ カードのメディア要素
• タグメンション