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