次の方法で共有


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

この記事では、カスタム フェデレーション検索プロバイダー (ボットによる機能) を作成し、検索チャネルに接続する方法について説明します。 テナント管理者がテナントでプロバイダーを有効にすると、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 SDK でサポートされている任意の言語でボットを実装できます。 この記事では、C# 統合検索ボット を例として使用します。

ヒント

この手順は、ボットが保護されたユーザー リソースへのアクセスを必要とする場合にのみ必要です。

一部のビジネス ワークフローでは、ボットがユーザーの代わりにアクションを実行するためにユーザー資格情報を必要とする場合があります。 検索チャンネルでボットのシングル サインオン (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. [検索設定] タブで、ボットの情報を入力します。

    Sample of the Search Settings tab

    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 日間の天気予報
  • 今日の最高気温
  • 今日の降水確率
  • 明日雪が降りますか
  • 明日の風速
  • 外は風が強いですか
  • ロンドンの天気

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

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

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

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

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

重要

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

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

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

次のステップ