Azure AI Search REST API リファレンス
Azure AI Search (旧称 Azure Cognitive Search) は、ユーザー所有のコンテンツに対する情報取得を提供するフル マネージド クラウド検索サービスです。
データ プレーン REST API は、インデックス作成とクエリ ワークフローに使用され、このセクションで説明されています。
コントロール プレーン操作には、別の Management REST API を使用してアクセスします。
バージョン管理された API ドキュメント
REST API ドキュメントのバージョン管理が行われます。 API 参照ページを開くと、目次の上にバージョン セレクターが表示されます。 API 参照が [ 参照 > データ プレーン ] フォルダーから取得されていることを確認します。
主要な概念
Azure AI Searchには、検索サービス、インデックス、ドキュメント、インデクサー、データ ソース、スキルセット、シノニム マップの概念があります。
- 検索サービスは、インデックス、インデクサー、データ ソース、スキルセット、シノニム マップを最上位のオブジェクトとしてホストします。
- 検索インデックスは、検索ドキュメントの永続的なストレージを提供します。 Searchドキュメントは、フィールドのコレクションとして明確に表現されたデータであり、外部ソースから読み込まれ、インデックスにプッシュされて検索可能になります。
- 検索インデクサーは、自動化を追加し、ネイティブ形式でデータを読み取り、JSON にシリアル化します。
- インデクサーにはデータ ソースがあり、インデックスを指します。
- インデクサーには、 AI エンリッチメント と 統合ベクター化 をインデックス作成パイプラインに追加するスキルセットもあります。 スキルセットは常にインデクサーにアタッチされます。 機械学習を呼び出して、テキストの抽出またはチャンク、コンテンツのベクター化、特徴の推論、コンテンツへの構造の追加を行って、検索サービスによってインデックスを作成できるようにします。
全体として、検索サービスで次のオブジェクトを作成できます。
| オブジェクト | 説明 |
|---|---|
| データ ソース | インデックス作成のためにドキュメントを取得および更新するためにインデクサーによって使用されるデータ ソース接続。 データ ソースには があります type。 Microsoft が提供する Azure 用の接続、またはパートナーを通じてサードパーティ製コネクタを使用できます。 完全な一覧については、「 データ ソース ギャラリー 」を参照してください。 |
| Documents | 概念的には、ドキュメントはインデックス内のエンティティです。 この概念をより使い慣れたデータベースに対応付けます。検索インデックスはテーブルに相当し、ドキュメントはテーブル内の行とほぼ同じです。 ドキュメントはインデックスにのみ存在し、インデックスのドキュメント コレクション (/docs) を対象とするクエリでのみ取得されます。 ドキュメントのアップロード、マージ、削除、クエリなど、コレクションに対して実行されるすべての操作は 1 つのインデックスのコンテキストで実行されるため、URL 形式のドキュメント操作には常に特定のインデックス名が含まれます /indexes/[index name]/docs 。 |
| インデックス | インデックスは検索サービスに格納され、情報取得のためにインデックスが作成されトークン化された JSON ドキュメントが設定されます。 インデックスの fields コレクションは、検索ドキュメントの構造を定義します。 フィールドには、その使用方法を決定する名前、データ型、および属性があります。 たとえば、 searchable フィールドはフルテキスト検索で使用されるため、インデックス作成中にトークン化されます。 インデックスでは、関連性チューニング、サジェスター、セマンティック構成、カスタム アナライザーのスコアリング プロファイルなど、他のコンストラクトも定義されます。 |
| インデクサー | インデクサーは、インデックス作成の自動化を提供します。 インデクサーは、データ ソースに接続し、データを読み取り、ターゲット検索インデックスにインデックスを作成するために検索エンジンに渡します。 インデクサーは、データ ソース内の接続情報を使用して外部ソースから読み取り、受信データを JSON 検索ドキュメントにシリアル化します。 インデクサーには、データ ソースに加えてインデックスも必要です。 インデックスは、検索ドキュメントのフィールドと属性を指定します。 |
| スキルセット | スキルセットは、インデクサーの実行に外部処理ステップを追加します。通常は、AI またはディープ ラーニング モデルを追加して、コンテンツを分析または変換してインデックス内で検索できるようにします。 スキルセットの内容は 1 つ以上の スキルであり、Microsoft によって作成された 組み込みのスキル 、カスタム スキル、またはその両方の組み合わせにすることができます。 OCR や自然言語処理など、画像分析には組み込みのスキルが存在します。 組み込みスキルの他の例としては、エンティティ認識、キー フレーズ抽出、テキストの論理ページへのチャンクなどがあります。 スキルセットは、インデックス、インデクサー、データ ソースと同等のレベルに存在する高レベルのスタンドアロン オブジェクトですが、インデクサー処理内でのみ動作します。 概要オブジェクトとして、スキルセットを 1 回設計し、複数のインデクサーで参照できます。 |
| シノニム マップ | シノニム マップは、ユーザー定義のシノニムを含むサービス レベルのオブジェクトです。 このオブジェクトは、検索インデックスとは無関係に保持されます。 アップロードしたら、検索可能なフィールドをシノニム マップ (フィールドごとに 1 つ) にポイントできます。 |
アクセス許可とアクセス制御
Microsoft Entra IDを使用して、キーベースの認証またはロールベースを使用できます。
キーベースの認証 は、検索サービス用に生成された API キーに依存します。 有効なキーがあれば、要求を送信するアプリケーションとそれを処理するサービスの間で、要求ごとに信頼を確立できます。 読み取り/書き込み操作には 管理 API キー、検索インデックスのドキュメント コレクションへの読み取りアクセスには Query API キーを使用できます。
認証とロールベースのアクセス制御Microsoft Entra ID、セキュリティ プリンシパルとロールの割り当てを使用して、Microsoft Entra IDにテナントが確立されている必要があります。 次のロールのメンバーは、データ プレーンにアクセスできます。 組み込みロールが不十分な場合は、カスタム ロールを作成できます。
ロール Access Search Service Contributor オブジェクトへのアクセス。ただし、インデックス コンテンツへのアクセスは行われません。 このロールでは、検索インデックスに対してクエリを実行したり、検索インデックス内のドキュメントを追加、削除、または更新したりすることはできません。 このロールは、オブジェクトを管理する必要があるが、オブジェクト データを表示またはアクセスする機能がない管理者向けです。 Search データ インデックス共同作成者 インデックス コンテンツへの読み取り/書き込みアクセス。 このロールは、インデックスのドキュメント コレクションのインポート、更新、またはクエリを行う必要がある開発者またはインデックス所有者向けです。 Search データ インデックス リーダー インデックス コンテンツへの読み取りアクセス。 このロールは、クエリを実行するアプリおよびユーザー向けです。
接続でロールを使用する場合、クライアント アプリは承認ヘッダーにベアラー トークンを提示します。 設定のヘルプについては、「Microsoft Entra ID を使用して検索アプリへのアクセスを承認する」を参照してください。
キーベースの認証またはロールベースの認証を無効にすることができます。 ロールベースの認証を無効にした場合でも、一部の組み込みロールには引き続きアクセス権が付与されます。 詳細については、「Azure AI Searchの認証とロールベースのアクセス制御をMicrosoft Entra IDする」を参照してください。
API の呼び出し
このセクションに記載されている API は、インデックスの作成と設定、ドキュメントのアップロード、クエリなど、検索データに対する操作へのアクセスを提供します。 API を呼び出すときは、次の点に注意してください。
要求は HTTPS 経由で発行する必要があります (既定のポート 443)。
要求 URI には api バージョンを含める必要があります。 この値は、次の例に示すように、サポートされているバージョンに設定する必要があります。
GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30要求ヘッダー には、認証された接続用の API キー またはベアラー トークンを含める必要があります。 必要に応じて、Accept HTTP ヘッダーを設定できます。 コンテンツ タイプ ヘッダーが設定されていない場合、既定値は であると見なされます
application/json。