Azure Cognitive Search Service REST

Azure Cognitive Searchは、ユーザーが所有するコンテンツに対する豊富な検索エクスペリエンスを提供するフル マネージドのクラウド検索サービスです。 検索機能を追加する方法の 1 つは、インデックスの作成と管理、データの読み込み、検索機能の実装、クエリの実行、結果の処理を行う操作を含む Search REST API を使用することです。

別の Management REST API を使用して、サービス自体を作成または変更できます。 または、多くのサービスおよびコンテンツ管理タスクにポータルを使用することもできます。 開始するには、「Azure portalで検索サービスを作成する」を参照してください。

主要な概念

Cognitive Search には、 検索サービスインデックスドキュメントの概念があります。

  • 検索サービスには、1 つ以上のインデックスが含まれています。
  • インデックスは、検索ドキュメントの永続的なストレージを提供します。
  • 検索ドキュメントは、JSON ドキュメントの形式で外部ソースから読み込まれ、インデックスにプッシュされて検索可能になります。

インデクサーを作成してインデックス作成を自動化することもできます。 インデクサーには データ ソース があり、インデックスを指します。 必要に応じて、インデクサー パイプラインに AI を追加する スキルセット もあります。

AI エンリッチメント は、テキストを抽出または生成する機械学習変換を追加したり、検索サービスによってインデックスを作成できるようにコンテンツに構造を追加したりするインデクサーの拡張機能です。 AI エンリッチメントを推進するコンストラクトを スキルセットと呼びます。 データ インジェスト中に、検索不可能なコンテンツ (画像コンテンツなど) を検出、構造化、または変換する一連の手順を定義します。

まとめて、サービスに対して実行できる操作には、次の 5 種類があります。

操作 説明
Index 検索インデックスを作成、削除、更新、または構成します。
Document インデックス内のドキュメントの追加、更新、削除、インデックスのクエリ、または ID による特定のドキュメントの検索。
インデクサー 必要に応じてスケジュールまたは実行できる データ ソースインデクサー を構成して、インデックス作成操作の側面を自動化します。 この機能は、Azure 上の限られた数のデータ ソースの種類でサポートされています。
スキルセット AI エンリッチメント ワークロードの一部であるスキルセットは、非構造化テキスト、アプリケーション ファイル、またはイメージ ファイルから検索可能なテキストを抽出または作成する一連のエンリッチメント処理を定義します。 スキルセットはインデクサーによって呼び出されます。
シノニム マップ シノニム マップは、ユーザー定義のシノニムを含むサービス レベルのリソースです。 このリソースは、検索インデックスとは別に管理されます。 アップロードすると、検索可能なフィールドをシノニム マップ (フィールドごとに 1 つ) にポイントできます。

API の呼び出し

このセクションに記載されている API は、インデックスの作成と設定、ドキュメントのアップロード、クエリなど、検索データに対する操作へのアクセスを提供します。 API を呼び出すときは、次の点に注意してください。

  • 要求は HTTPS 経由で発行する必要があります (既定のポート 443)。

  • 要求には、 API バージョン を URI に含める必要があります。 この値は、次の例に示すように、サポートされているバージョンに設定する必要があります。 GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • 要求ヘッダー には、プロビジョニングした検索サービス用に生成された API キー が含まれている必要があります。 有効なキーがあれば、要求を送信するアプリケーションとそれを処理するサービスの間で、要求ごとに信頼を確立できます。 必要に応じて、ACCEPT HTTP ヘッダーを設定できます。 ヘッダーが設定されていない場合、既定値は application/json.

キー認証

検索サービスに対するすべての HTTP 要求は、2 つの情報に基づいて認証されます。検索サービスの URL と、要求が信頼されたエンティティからのであることを証明する API キー です。 異なるレベルの操作には、2 種類の API キー があります。

Key 説明 制限
[Admin] 管理者キーは、サービスの管理、状態とオブジェクトの定義の取得、 インデックスインデクサーデータ ソースの作成と削除を行う機能を含め、すべての操作に完全な権限を付与します。

ポータルでプライマリ キーとセカンダリ キーと呼ばれる 2 つの管理 API キーは、サービスの作成時に自動的に生成され、必要に応じて個別に再生成できます。 キーが 2 つあることで、サービスへの継続的なアクセスに 1 つのキーを使用している間に、もう 1 つのキーをロールオーバーできます。

管理キーは、HTTP 要求ヘッダーでのみ指定されます。 URL に管理 API キー を配置することはできません。
最大でサービスあたり 2 つ
クエリ クエリ キーは、インデックス (ドキュメント) 内のコンテンツへの読み取り専用アクセス権を付与し、通常は検索要求を発行するクライアント アプリケーションに配布されます。

クエリ キーはオンデマンドで作成されます。 これらはポータルで手動で作成できるほか、管理 REST API を通じてプログラムで作成できます。

クエリ キーは、検索、提案、または検索操作の HTTP 要求ヘッダーで指定できます。 または、クエリ キーは URL 上のパラメーターとして渡すことができます。 クライアント アプリケーションが要求を作成する方法によっては、クエリ パラメーターとしてキーを渡す方が簡単な場合があります。

GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]
サービスあたり 50 個

管理者キーとクエリ キーに見た目の違いはありません。 どちらのキーも、ランダムに生成された 32 個の英数字からなる文字列です。 アプリケーションで指定されているキーの種類を確認できない場合は、 ポータルでキーの値を確認 するか、 Management REST API を使用して値とキーの種類を返すことができます。

注意

api-key などの機密データを要求 URI で渡すことは、セキュリティ上推奨されません。 このため、Azure Cognitive Searchはクエリ文字列内のクエリ キーapi-keyのみを受け入れるため、インデックスの内容を公開する必要がない限り、これを避ける必要があります。 一般的なルールとして、api-key は要求ヘッダーとして渡すことをお勧めします。

承認

Cognitive Search では、所有者、共同作成者、閲覧者の各ロールを通じて、検索サービスを管理するための Azure ロールベースのアクセス制御 (Azure RBAC) がサポートされています。

必要に応じて、プレビュー機能を使用できる検索ソリューションでは、Azure RBAC を使用して、検索サービス上のインデックスやその他のオブジェクトへのアクセスを制御できます。 この方法では、データ プレーンで Azure RBAC 用に構成された検索サービスと、Azure Active Directoryを使用して認証される REST API 呼び出しの承認ヘッダーが必要です。

関連項目