ユーザー ピッカーを統合する

  • [アーティクル]

ユーザー ピッカーは、ユーザーがユーザーを検索して選択できるようにする Teams の入力コントロールです。 入力コントロールユーザー ピッカー を Web アプリに統合できます。これにより、エンド ユーザーは、Teams 内のチャット、チャネル、組織全体のユーザーの検索や選択などのさまざまな機能を実行できます。 ユーザー ピッカー コントロールは、Web、デスクトップ、モバイルなど、すべての Teams クライアントで使用できます。

Microsoft Teams JavaScript クライアント ライブラリを使用できます。このライブラリでは、web アプリに People Picker 入力コントロールを統合するための API が用意selectPeopleされています。

ユーザー ピッカーを使用する利点

  • ダイアログ (TeamsJS v1.x ではタスク モジュールと呼ばれます)、チャット、チャネル、会議タブ、個人用アプリなど、すべての Teams 機能で機能します。
  • ユーザーが Teams 内のチャット、チャネル、または組織全体のユーザーを検索して選択できるようにします。
  • タスクの割り当て、タグ付け、ユーザーへの通知に関連するシナリオで役立ちます。
  • 同様のコントロールを構築する場合と比較して、大幅な時間と労力を節約できます。

Teams アプリでユーザー ピッカー入力コントロールを統合するには、selectPeople API を使用します。 API を統合して呼び出すには、付随する code スニペット をよく理解している必要があります。 また、API 応答エラー についての知識も必要です。

selectPeople API

selectPeople API を使用すると、Teams ユーザー ピッカー入力コントロールを Web アプリに追加したり、次の操作を行うこともできます。

  • ユーザーがリストから 1 人以上のユーザーを検索して選択できるようにします。
  • 選択したユーザーの ID、名前、電子メール アドレスを Web アプリに返します。

個人用アプリの場合、コントロールは Teams 内で組織全体の名前または電子メール ID を検索します。 アプリがチャットまたはチャネルに追加された場合、検索コンテキストはシナリオに基づいて構成されます。 検索は、そのチャットまたはチャネルのメンバー内で制限されます。

selectPeople API には、次の入力構成が付属しています。

構成パラメーター 型 説明 既定値
title String これは省略可能なパラメーターであり、ユーザー ピッカー コントロールのタイトルを設定します。 selectPeople
setSelected String 省略可能なパラメーターです。 事前に選択するには、ユーザー Microsoft Entra ID を渡す必要があります。 このパラメーターは、ユーザー ピッカー入力コントロールの起動中にユーザーを事前に選択します。 1 つの選択の場合、最初の有効なユーザーのみが事前設定され、残りは無視されます。 Null
openOrgWideSearchInChatOrChannel Boolean これは省略可能なパラメーターであり、TRUE に設定すると、アプリがチャットまたはチャネルに追加された場合でも、組織全体のスコープでユーザー ピッカーが起動されます。 False
singleSelect Boolean これは省略可能なパラメーターであり、TRUE に設定すると、ユーザー ピッカーが起動され、選択が 1 人のユーザーのみに制限されます。 False

次の図は、モバイル デバイスとデスクトップでのユーザー ピッカーのエクスペリエンスを示しています。

ユーザー ピッカー入力コントロールを使用すると、ユーザーは次の手順を使用してユーザーを検索して追加できます。

  1. 必要なユーザーの名前を入力します。 リストに名前の候補が表示されます。

  2. リストから必要なユーザーの名前を選択します。

    スクリーンショットは、モバイル上のピッカー ピッカーを示しています。

コード スニペット

次のコード スニペットでは、selectPeople API ユーザーの使用をリストから表示します。

people.selectPeople({ setSelected: ["aad id"], openOrgWideSearchInChatOrChannel: true, singleSelect: false, title: true}).then(people) => 
 {
    output(" People length: " + people.length + " " + JSON.stringify(people));
 }).catch((error) => { /*Unsuccessful operation*/ });

エラー処理

次の表に、エラー コードとその説明を示します。

エラー コード エラー名 説明
100 NOT_SUPPORTED_ON_PLATFORM API は現在のプラットフォームではサポートされていません。
500 内部エラーです(_E) ユーザー ピッカーの起動中に内部エラーが発生しました。
4000 引数が無効です API が間違った引数または不十分な必須引数で呼び出されました。
8000 USER_ABORT ユーザーが操作を取り消しました。
9000 OLD_PLATFORM ユーザーは、API の実装が利用できない古いプラットフォーム ビルドを使用しています。 問題を解決するには、ビルドの最新バージョンにアップグレードしてください。

コード サンプル

サンプルの名前 説明 .NET Node.js マニフェスト
タブユーザーピッカー このサンプルでは、Teams js クライアント sdk を使用したユーザー ピッカーの機能をタブ内で示します。 表示 表示 表示

関連項目