ボットを Search に接続する (プレビュー)

この記事では、カスタム フェデレーション検索プロバイダー (ボットによる機能) を作成し、検索チャネルに接続する方法について説明します。 テナント管理者がテナントでプロバイダーを有効にすると、Office.com、SharePoint.com、Bing.com からのエンタープライズ ユーザー検索に、カスタム検索プロバイダーからの結果を含めることができます。

Microsoft Federated Search Platform を使用すると、カスタムフェデレーション検索プロバイダーを構築して、情報を Microsoft 365 インデックスとマージすることなく、Microsoft Search の回答と垂直エクスペリエンスに情報を参加させることができます。 詳細については、「 Microsoft Federated Search Platform と Dynamics 365 フェデレーション検索の開発者プレビューの発表 (プレビュー)」を参照してください。

ボットを検索チャネルに接続するには、次の手順が必要です。 これらの手順については、この記事の後半で詳しく説明します。

1. 検索プロバイダーとして機能するようにボットを実装します。
2. ボットでユーザーのサインインが必要な場合:
   1. Azure portal で、ボット API を検索プラットフォームに公開します。
   2. ボット コードで、生成されたスコープ URI を使用してユーザー トークンを生成します。
3. ボットを Azure にデプロイします。
4. ボットに検索チャネルを追加します。
5. ボットの登録を確認し、テナントでボットを発行するように IT 管理者に依頼します。

[前提条件]

• Bot Framework サービスの基本と、Bot Framework SDK を使用してボットを作成する方法に関する知識。
• チャネルに接続するボット。
• Azure アカウントをお持ちでない場合は、開始する前に 無料アカウント を作成してください。

Bot Framework SDK でサポートされている任意の言語でボットを実装できます。 この記事では、C# フェデレーション検索ボット を例として使用します。

ボット API を検索に公開する

一部のビジネス ワークフローでは、ボットがユーザーの代わりにアクションを実行するためにユーザー資格情報を必要とする場合があります。 検索チャネルでボットのシングル サインオン (SSO) エクスペリエンスを作成するには、検索プラットフォームがユーザーに代わって Microsoft Entra ID からのアクセス トークンをセキュリティで保護できるようにする必要があります。

ボットのスコープ URI とアプリケーション ID を生成するには:

1. Azure ポータルにアクセスします。
2. ボット リソースがまだない場合は、Azure Bot リソースを作成します。
3. Microsoft Entra ID サービスに移動します。
4. [アプリの 登録 ] ウィンドウに移動します。
5. ボットに関連付けられているアプリケーションを選択します。
6. [API の 公開 ] ウィンドウに移動します。
7. [Scope の追加] を選択します。
   1. [ スコープの追加 ] ウィンドウでは、自動生成された アプリケーション ID URI をそのまま使用することをお勧めします。 [Save and continue] (保存して続行) を選択します。
   2. スコープ名を入力します。
   3. [ 同意できるユーザー] では、 管理者とユーザー が優先されますが、両方のオプションが機能します。
   4. 管理者の 同意の表示名 と 管理者の同意の説明を入力します。
   5. 必要に応じて、 ユーザーの同意の表示名 と ユーザーの同意の説明を入力します。
   6. [状態] が [有効] に設定されていることを確認します。
   7. [スコープの追加] を選択します。
8. [+ クライアント アプリケーションの追加] を選びます。
   1. [ クライアント アプリケーションの追加 ] ウィンドウで、[ クライアント ID] を [検索プラットフォームのクライアント ID] 81473081-50b9-469a-b9d8-303109583ecbに設定します。
   2. [ 承認されたスコープ] で、前の手順で作成したスコープ URI を選択します。
   3. アプリケーション追加を選択します。
9. [概要] ウィンドウに移動します。 アプリケーション ID URI をコピーします。 これは、ボットを検索チャネルに登録するときに必要になります。

ボットを実装する

検索チャネルは、"application/search" という名前の呼び出しアクティビティとして、各ユーザー クエリをボットに送信します。 ボットは、呼び出し応答でクエリ結果を返します。 検索チャネルに送り返されるクエリ結果には、アダプティブ カード形式を使用します。

1. プロジェクト内のすべての Bot Framework パッケージとアダプティブ カード パッケージを最新バージョンに更新します。
2. 必要に応じて、ユーザー トークンを生成する 認証コードを追加 します。
3. 各データソースに含めるためのデータ検索メソッドを実装します。
4. アダプティブ カードを生成して 結果を表示します。

検索プラットフォームのトレース ID を取得する

Search プラットフォームは、ボットに送信する各クエリに一意のトレース ID を割り当てます。 プラットフォームは、これを呼び出しアクティビティのチャネル データに追加します。 要求のトレース ID をログに記録することもできます。 トレース ID を取得するには、チャネル データの traceId プロパティを使用します。

フェデレーション検索サンプルでは、SearchHelper.GetSearchTraceId メソッドは、呼び出しアクティビティからトレース ID を取得する方法を示しています。

認証を追加する

ボット API を Search に公開し、ボットを Search に接続したときに認証を要求した場合は、アクティビティのチャネル データからユーザー認証トークンを取得できます。

チャネル データの authorizations プロパティには、認証トークンの一覧を含めることができます。 ボット API を Search に公開すると、一覧には代理トークンが含まれます。 リスト内のトークンの構造は次のとおりです。

フェデレーション検索サンプルでは、次の手順を実行します。

• SearchBotAuthenticationToken クラスとAuthenticationTypes列挙体は、この情報を表します。
• SearchHelper.GetSearchOboToken メソッドは、呼び出しアクティビティからトークンを取得する方法を示しています。

トークンを取得したら、ユーザーの保護されたリソースを要求するときに使用できます。 代理トークンの使用については、 Microsoft ID プラットフォームと OAuth 2.0 On-Behalf-Of フローを参照してください。

各データ ストアに対してクエリを実行する

検索チャネルは、 invoke アクティビティとしてボットにクエリを送信し、アクティビティの value プロパティにクエリの詳細を送信します。これは、次の構造を持つ JSON オブジェクトを表します。

呼び出し応答で検索結果を返します。

• 呼び出し応答オブジェクトの Status プロパティを常に 200 に設定します。これは、ネットワーク接続が問題ありません。 オブジェクトの Body プロパティには、別の状態コードがあります。

• Body プロパティは、次の構造を持つ JSON オブジェクトを表します。

  プロパティ名	タイプ	Description
  ステータスコード	整数	ボットがクエリを正常に実行できたかどうかを示すために使用される HTTP 状態コード。
  型	文字列	値フィールドの形式を定義する呼び出し応答の型。 検索結果には "application/vnd.microsoft.search.searchResponse" を使用し、エラー メッセージには "application/vnd.microsoft.error" を使用します。
  value	オブジェクト	type値に対応する値。

  エラー メッセージの場合、 value オブジェクトには次のものが含まれます。

  プロパティ名	タイプ	Description
  コード	文字列	ボットによって定義されたエラー コード。指定されていない場合は null 。
  メッセージ	文字列	エラー メッセージ。指定されていない場合は null 。

  検索結果の場合、 value オブジェクトには次のものが含まれます。

  プロパティ名	タイプ	Description
  results	検索結果オブジェクトの配列	結果がない場合はnullです。
  ディスプレイレイアウト	表示レイアウト オブジェクトの配列	表示レイアウト。表示されていない場合は null 。
  totalResultCount	整数	ページ分割がサポートされている場合に使用できる結果の合計。それ以外の場合は null。
  さらに結果があります	ブール値	より多くの結果を使用できるかどうかを示します。

  検索結果オブジェクトには次のものが含まれます。

  プロパティ名	タイプ	Description
  value	文字列	この検索結果の一意の識別子または値。
  layoutId	文字列	この結果に使用する表示レイアウトの ID。
  データ.検索結果テキスト	文字列	この結果のテキスト。

  表示レイアウト オブジェクトには次のものが含まれます。

  プロパティ名	タイプ	Description
  layoutId	文字列	レイアウト ID。
  レイアウト本体	文字列	アダプティブ カードのJSON オブジェクトとしてのレイアウトボディ。

フェデレーション検索サンプルでは、SearchHelper.RunFederatedSearch メソッドは、呼び出しアクティビティからクエリ情報を取得する方法と、呼び出し応答の書式を設定する方法を示しています。

検索結果を表示する

検索バーティカルと結果の種類を作成して、ユーザーが SharePoint、Office、Bingで検索するときに表示される検索結果をカスタマイズできます。 バーティカルを利用することで、ユーザーはアクセス許可を持った情報を簡単に見つけられます。 詳細については、「 サポートされているアダプティブ カード要素 」セクションを参照してください。

応答がないクエリをボットが受信した場合、その応答には空の応答が含まれている必要があります。

Azure にボットを登録する

ボットを Search チャネルに接続するには、Azure にボット リソースがプロビジョニングされている必要があります。 詳細については、ボットを Azure に 登録 する方法、またはボットを Azure にデプロイする方法を参照してください。

ボットを検索に接続する

次の手順では、ボットを Search に接続する方法を示します。

1. Azure ポータルにアクセスします。

2. ボット リソースを開きます。

3. [チャネル (プレビュー)] ウィンドウを開きます。

4. [検索] を選択します。

5. [ 検索設定] タブで、ボットの情報を入力します。

   

   1. [ 検索プロバイダー メタデータ] で、検索 UI に表示する名前を入力します。

   2. [ トリガー フレーズ] で、ボットが応答できるクエリを表すフレーズを定義します。

      注

      初期リリースでは、英語 (en-US) のみを使用できます。

      • 語句を含む .csv ファイルをアップロードします。 ファイルには、ヘッダーのない 1 列のデータが含まれている必要があります。
      • [ 言語] 基本設定 リストから、トリガー フレーズが書き込まれる言語を選択します。

   3. [ 認証] で、検索プロバイダーにユーザー認証が必要かどうかを示します。

      • 認証が必要な場合は、認証 URL を入力します。 ボットの API を公開したときにコピーしたアプリケーション ID URI を使用します。

   4. [次へ] を選択します。

6. [ バーティカル ] タブで、検索プロバイダーの結果を検索結果ページに独自の縦書きで表示する場合は、フィールドに縦書きの名前を入力します。それ以外の場合は、このフィールドを空のままにします。 次に、 [次へ] を選択します。
   検索結果ページは、Office.com、SharePoint.com、および Bing.com 用です。

7. [ テナント公開 ] タブで設定を確認し、公開情報を追加します。

   1. 検索プロバイダー名とサンプル クエリを確認します。 必要に応じて、前のタブに戻ってこの情報を変更します。
   2. 検索プロバイダーの説明を入力します。
   3. サポート連絡先の電子メールを入力します。 検索プロバイダーにアクセスできる開発者または開発者グループの電子メールを使用します。

8. IT 管理者に承認を要求するには、[ 追加] を 選択します。

テナントで検索プロバイダーを承認する

テナントの検索プロバイダーの承認は、Microsoft 365 管理センターの [検索とインテリジェンス] ページの IT 管理者によって行われます。

接続をテストします。

運用環境で有効にする前に、テスト テナントで検索プロバイダーを有効にすることをお勧めします。

検索プロバイダーを変更する

IT 管理者によるレビューのために検索プロバイダーを送信する前に、検索プロバイダーを編集できます。 最初の要求が拒否された場合、またはサービスが非アクティブ化されている場合は、これを行う必要がある場合があります。

1. Azure portal で、編集する検索プロバイダーを含むボット リソースに移動します。
2. [チャネル (プレビュー)] ウィンドウに移動します。
3. 検索チャネルを選択し、[編集] を選択します。
   1. Azure に [検索チャネル ] ウィンドウが表示されます。 このウィンドウでは、設定を編集できます。
   2. トリガーフレーズを変更するには、ファイルをダウンロードしてローカルで編集し、ファイルをアップロードします。
   3. 編集が完了したら、[ 追加] をもう一度選択して、IT 管理者によるレビューのために検索プロバイダーを送信します。

検索プロバイダーを削除する

ボット リソースから検索チャネルを削除すると、検索プロバイダーが削除されます。

ボットから検索チャネルを削除するには:

1. Azure portal で、ボット リソースに移動します。
2. [チャネル (プレビュー)] ウィンドウに移動します。
3. 検索チャネルを選択します。
4. [検索チャネル] ウィンドウの上部にある [チャネルの削除] を選択します。
5. はいを選択して操作を確認します。

ボット リソースを削除するには:

1. Azure portal で、ボット リソースに移動します。
2. まだ行っていない場合は、ボットから検索チャネルを削除します。
3. [ 概要 ] ウィンドウの上部にある [削除] を選択 します。
4. [ OK] を 選択して操作を確認します。

追加情報

検索チャネルでは、フェデレーション検索とアダプティブ カード スキーマが使用されます。

アダプティブ カード スキーマの詳細については、「 ボット開発者向けのアダプティブ カード」を参照してください。

トリガー フレーズについて

トリガー フレーズは、ボットを利用するカスタム検索プロバイダーにクエリをルーティングするために検索プラットフォームが使用する語句です。 フェデレーション検索は、発話がトリガー フレーズのいずれかに近い場合に、ユーザーの発話を検索プロバイダーに転送します。

たとえば、フライトのスケジュールと状態を管理するボットを考えてみましょう。

1. ユーザーがボットを参照または使用する一般的な方法をいくつか考えてください。 ボットは必ず他のボットと区別してください。

   学校やテレビ番組に適用できる "時刻表" などの一般的な用語の代わりに、"フライトタイム テーブル" や "フライト スケジュール" などのより具体的な語句を使用します。

2. 出発時刻や現在の状態など、ボットの機能の範囲をカバーする多様なフレーズを含めます。

   たとえば、到着または出発時刻と空港に関するクエリを含めます。

このような フライト スケジュールと状態 ボットのトリガー フレーズには、次のようなものがあります。

• フライト時刻表
• フライトの状態
• 675便出発時刻
• フライトはいつ出発しますか?
• フライト 468 到着時刻
• シアトル タコマのフライト状態
• 空港のフライト状態

別の例として、 天気予報 ボットのトリガー フレーズには次のようなものがあります。

• 地域の天気予報
• 天気情報
• 明日の天気
• 10 日間の天気予報
• 今日の高値
• 今日の雨の可能性
• 明日雪が降りますか?
• 明日の風速
• 外は風が吹いていますか
• ロンドン 天気

サポートされているアダプティブ カード要素

フェデレーション検索では、アダプティブ カード スキーマのサブセットがサポートされています。 検索結果の書式設定の詳細については、「検索結果 ページをカスタマイズする」を参照してください。

サポートには、TextBlock、RichTextBlock、Image、ColumnSet、ImageSet、FactSet のアダプティブ カード要素が含まれます。 詳細については、Microsoft Search の 検索結果レイアウトの管理 とアダプティブ カード スキーマ エクスプローラーに関するページを 参照してください。

各カードを JSON として直接作成することも、 AdaptiveCards NuGet パッケージを使用することもできます。

フェデレーション検索で HTML がサポートされない

検索プラットフォームには HTML パーサーは含まれません。 ただし、一部のタグを削除し、 Html2Markdown NuGet パッケージを使用して HTML を Markdown に変換できます。

1. <span>要素と<u>要素を削除します。
2. <div>要素と<br>要素を段落 (<p>) 要素に置き換えます。
3. 残りの HTML を Markdown に変換します。

次のステップ

• Bot Connector Service でのチャネルサポートの詳細については、「ボットを チャネルに接続する」を参照してください。
• ボットの構築の詳細については、「 ボット のしくみ」および Bot Framework SDK を使用したボットの作成に関する クイック スタートを参照してください。
• ボットのデプロイの詳細については、「ボット のデプロイ 」および 「継続的デプロイの設定」を参照してください。