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

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

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

Note

検索チャンネルはプライベート プレビュー段階です。 アクセスを要求するには、「Microsoft Search 開発者プライベート プレビュー フォーム」を使用します。 質問 7 で、[統合検索] を選択 します。

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

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. スコープの追加 を選択します。
   1. [スコープの追加] ウィンドウでは、自動生成されたアプリケーション ID URI をそのまま使用することをお勧めします。 [Save and continue](保存して続行) を選択します。
   2. [スコープ名] を入力します。
   3. [同意できるユーザー] には、[管理とユーザー] が優先されますが、両方のオプションが機能します。
   4. [管理者の同意の表示名] と [管理者の同意の説明] を入力します。
   5. 必要に応じて、[ユーザーの同意の表示名] と [ユーザーの同意の説明] を入力します。
   6. [状態] が [埋め込み] に設定されていることを確認します。
   7. スコープの追加を選択します。
8. クライアント アプリケーションの追加を選択します。
   1. [クライアント アプリケーションの追加] ウィンドウで、[クライアント ID] を 81473081-50b9-469a-b9d8-303109583ecb、[検索プラットフォームのクライアント ID] に設定します。
   2. [承認スコープ] で、前の手順で作成したスコープ URI を選択します。
   3. [アプリケーションの追加] をクリックします。
9. [概要] ウィンドウに移動します。 アプリケーション ID の URI をコピーします。 これは、ボットを検索チャンネルに登録するときに必要になります。

ボットの実装

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

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

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

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

統合検索サンプルでは、呼び出しアクティビティからトレース ID を取得する SearchHelper.GetSearchTraceId 方法を示します。

認証を追加する

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

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

プロパティ名	種類​​	説明
authType	integer	認証トークンの種類:不明または既定の場合は 0 、または代理トークンの場合は 2 。
token	string	認証トークン自体。

統合検索サンプルでは、次の手順を実行します。

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

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

各データ ストアをクエリする

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

プロパティ名	種類​​	説明
queryText	string	クエリ テキスト。
kind	string	クエリの種類: カスタムの垂直タブに結果が表示される場合は "検索"、結果が [すべて] タブに回答として表示される場合は "searchAnswer" です。
queryOptions	object	改ページ位置の自動修正に使用される追加のクエリ オプション。
queryOptions.skip	integer	送信する最初の結果のインデックス。
queryOptions.top	integer	送信する結果の最大件数

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

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

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

  プロパティ名	種類​​	説明
  statusCode	integer	ボットがクエリを正常に実行できたかどうかを示すために使用される HTTP 状態コード。
  type	string	値フィールドの形式を定義する呼び出し応答の型。 検索結果には "application/vnd.microsoft.search.searchResponse" を使用し、エラー メッセージには "application/vnd.microsoft.error" を使用します。
  値	object	値に対応する値 type。

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

  プロパティ名	種類​​	説明
  code	string	指定されていない場合、ボットまたは null によって定義されたエラー コード。
  message	string	指定されていない場合、エラー メッセージ、または null 。

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

  プロパティ名	種類​​	説明
  results	検索結果オブジェクトの配列	結果、または null 存在しない場合。
  displayLayouts	表示レイアウト オブジェクトの配列	表示レイアウト、または null 何も表示されない場合。
  totalResultCount	integer	ページ分割がサポートされている場合に使用できる結果の合計。それ以外の場合は null。
  moreResultsAvailable	Boolean	より多くの結果が利用可能かどうかを示します。

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

  プロパティ名	種類​​	説明
  値	string	この検索結果の一意識別子または値。
  layoutID	string	この結果に使用する表示レイアウトの ID。
  data.searchResultText	string	この結果のテキスト。

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

  プロパティ名	種類​​	説明
  layoutID	string	レイアウト ID。
  layoutBody	string	アダプティブ カード JSON オブジェクトとしてのレイアウト本文。

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

検索結果を表示する

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

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

ボットを Azure に登録します

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

ボットを検索に接続する

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

ヒント

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

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

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

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

4. 検索を選びます。

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

   

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

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

      Note

      初期リリースでは、英語 (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 つだけが選択されます。

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

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

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

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

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

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

• フライト時刻表
• フライトのステータス
• 675便出発時刻
• フライトはいつ出発しますか?
• フライト 468 到着時刻
• シアトル タコマのフライト ステータス
• ヒースローのフライト ステータス

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

• 現地の天気予報
• 天気情報
• 明日の天気
• 10 日間の天気予報
• 今日の最高気温
• 今日の降水確率
• 明日雪が降りますか
• 明日の風速
• 外は風が強いですか
• ロンドンの天気

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

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

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

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

統合検索では HTML がサポートされていません

重要

統合検索では、HTML を含むアダプティブ カード テキストはレンダリングされません。

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

1. <span> および <u> 要素を削除します。
2. <div>および <br> 要素を段落 (<p>) 要素に置き換えます。
3. 再メイン HTML を Markdown に変換します。

次のステップ

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