Azure Cognitive Search サービス RESTAzure Cognitive Search Service REST

Azure Cognitive Search は、カスタムアプリケーションに高度な検索機能を提供する、完全に管理されたクラウド検索サービスです。Azure Cognitive Search is a fully managed cloud search service that provides a rich search experience to custom applications. 検索機能を追加する方法の1つとして、REST Api を使用します。これには、インデックスの作成と管理、データの読み込み、検索機能の実装、クエリの実行、および結果の処理を行う操作が含まれます。One way to add search capability is through the REST APIs, with operations that create and manage indexes, load data, implement search features, execute queries, and handle results.

検索サービスの構成をプロビジョニングおよび変更するには、別の REST API を使用します。A separate REST API is used to provision and alter a search service configuration. 別の方法として、ポータルを使用することもできます。Alternatively, you can use the portal. 詳細については、「Azure portal またはAzure Cognitive Search 管理 RESTでの Search サービスの作成」を参照してください。For more information, see Create a search service in Azure portal or Azure Cognitive Search Management REST.

主要な概念Key concepts

Cognitive Search には、 Search サービスインデックス 、および ドキュメント の概念があります。Cognitive Search has the concepts of search services and indexes and documents:

  • Search サービスに1つ以上のインデックスが含まれています。A search service contains one or more indexes.
  • インデックスは、検索ドキュメントの永続的なストレージを提供します。An index provides persistent storage of search documents.
  • 検索ドキュメントは、JSON ドキュメントの形式で外部ソースから読み込まれ、インデックスにプッシュされて、検索できるようになります。Search documents are loaded from external sources in the form of JSON documents and pushed to an index to make it searchable.

インデクサー を使用してインデックスを読み込む場合は、データのアップロード操作を自動化できます。If you use an indexer to load an index, you can automate data upload operations. インデクサーは、データソースをクロールし、そのコンテンツを JSON としてシリアル化して、宛先インデックスにルーティングできます。An indexer can crawl a data source and serialize the content as JSON, in route to a destination index.

Cognitive Search の AI 強化には、スキルセット という概念があります。AI enrichment in Cognitive Search has the concept of skillsets. スキルセットは、インデクサーに関連付けられています。A skillset is attached to an indexer. データの取り込み中に、他の方法では検索不可能なコンテンツを検出、構造、または変換する一連の手順を定義します。During data ingestion, it defines a sequence of steps that detect, structure, or transform content that is otherwise unsearchable.

このサービスに対して実行できる操作には、次の5種類があります。All together, there are five types of operations that can be executed against the service:

操作Operation 説明Description
IndexIndex 検索インデックスを作成、削除、更新、または構成します。Create, delete, update, or configure a search index.
ドキュメントDocument インデックス内のドキュメントを追加、更新、または削除したり、インデックスを照会したり、ID で特定のドキュメントを検索したりします。Add, update, or delete documents in the index, query the index, or look up specific documents by ID.
インデクサーIndexer データソースインデクサー を構成してインデックス作成操作の側面を自動化し、必要に応じてスケジュールまたは実行することができます。Automate aspects of an indexing operation by configuring a data source and an indexer that you can schedule or run on demand. この機能は、Azure でサポートされているデータソースの種類の数が限られています。This feature is supported for a limited number of data source types on Azure.
スキルセットSkillset AI 強化ワークロードの一部であるスキルセットは、一連の強化処理を定義します。Part of an AI enrichment workload, a skillset defines a series of enrichment processing. スキルセットは、インデクサーによって使用されます。A skillset is consumed by an indexer.
シノニムマップSynonym map シノニムマップは、ユーザー定義のシノニムを含むサービスレベルリソースです。A synonym map is service-level resource that contains user-defined synonyms. このリソースは、検索インデックスとは別に保持されます。This resource is maintained independently from search indexes. アップロードが完了すると、検索可能なフィールドをシノニムマップ (フィールドごとに1つ) にすることができます。Once uploaded, you can point any searchable field to the synonym map (one per field).

Api の呼び出しCalling the APIs

このセクションに記載されている API は、インデックスの作成と設定、ドキュメントのアップロード、クエリなど、検索データに対する操作へのアクセスを提供します。The APIs documented in this section provide access to operations on search data, such as index creation and population, document upload, and queries. Api を呼び出すときは、次の点に注意してください。When calling APIs, keep the following points in mind:

  • 要求は HTTPS 経由で発行する必要があります (既定のポート 443)。Requests must be issued over HTTPS (on the default port 443).

  • 要求の URI には、 api バージョン が含まれている必要があります。Requests must include the api-version in the URI. この値は、次の例に示すように、サポートされているバージョンに設定する必要があります。 GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30The value must be set to a supported version, formatted as shown in this example: GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • 要求ヘッダーには、プロビジョニングした検索サービスに対して生成された api キー を含める必要があります。Request headers must include an api-key that was generated for the search service you provisioned. 有効なキーがあれば、要求を送信するアプリケーションとそれを処理するサービスの間で、要求ごとに信頼を確立できます。Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

    必要に応じて、Accept HTTP ヘッダーを設定できます。Optionally, you can set the Accept HTTP header. ヘッダーが設定されていない場合、既定値はと見なされ application/json ます。If the header is not set, the default is assumed to be application/json.

キー認証Key authentication

検索サービスへのすべての HTTP 要求は、検索サービスの URL と、要求を証明する api キー の2つの情報に基づいて、信頼されたエンティティから認証されます。Every HTTP request to your search service is authenticated based on two pieces of information: a search service URL and an api-key that provides proof the request is from a trusted entity. さまざまなレベルの操作に対して、2種類の api キー があります。There are two types of api-keys for different levels of operation.

KeyKey 説明Description 制限Limits
[Admin]Admin 管理者キーは、サービスを管理する機能、状態とオブジェクトの定義を取得する機能、 インデックスインデクサーデータソース を作成および削除する機能など、すべての操作に対する完全な権限を付与します。Admin keys grant full rights to all operations, including the ability to manage the service, get status and object definitions, and create and delete indexes, indexers, and data sources.

ポータルで プライマリ キーと セカンダリ キーと呼ばれる2つの管理 api キー が、サービスの作成時に自動的に生成され、要求に応じて個別に再生成できます。Two admin api-keys, referred to as primary and secondary keys in the portal, are automatically generated when the service is created and can be individually regenerated on demand. キーが 2 つあることで、サービスへの継続的なアクセスに 1 つのキーを使用している間に、もう 1 つのキーをロールオーバーできます。Having two keys allows you to roll over one key while using the second key for continued access to the service.

管理者キーは、HTTP 要求ヘッダーでのみ指定されます。Admin keys are only specified in HTTP request headers. URL に管理者 api キー を配置することはできません。You cannot place an admin api-key in a URL.
最大でサービスあたり 2 つMaximum of 2 per service
クエリQuery クエリキーは、インデックス (ドキュメント) 内のコンテンツへの読み取り専用アクセスを付与します。通常、検索要求を発行するクライアントアプリケーションに配布されます。Query keys grant read-only access to content within an index (documents), and are typically distributed to client applications that issue search requests.

クエリ キーは要求に応じて作成されます。Query keys are created on demand. これらはポータルで手動で作成できるほか、管理 REST API を通じてプログラムで作成できます。You can create them manually in the portal or programmatically via the Management REST API.

クエリ キーは、検索、推奨、または参照の操作に使用するために HTTP 要求ヘッダーで指定できます。Query keys can be specified in an HTTP request header for search, suggestion, or lookup operation. または、クエリ キーは URL 上のパラメーターとして渡すことができます。Alternatively, you can pass a query key as a parameter on a URL. クライアント アプリケーションが要求を作成する方法によっては、キーをクエリ パラメーターとして渡すほうが簡単な場合があります。Depending on how your client application formulates the request, it might be easier to pass the key as a query parameter:

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

管理者キーとクエリ キーに見た目の違いはありません。Visually, there is no distinction between an admin key or query key. どちらのキーも、ランダムに生成された32の英数字で構成される文字列です。Both keys are strings composed of 32 randomly-generated alpha-numeric characters. アプリケーションで指定されているキーの種類がわからなくなった場合、ポータルでキーの値を確認したり、REST API を使用して値とキーの種類を返したりできます。If you lose track of what type of key is specified in your application, you can check the key values in the portal or use the REST API to return the value and key type.

注意

api-key などの機微なデータを要求 URI で渡すことは、セキュリティ上推奨されません。It is considered a poor security practice to pass sensitive data such as an api-key in the request URI. このため、Azure Cognitive Search はクエリキーをクエリ文字列のとしてのみ受け入れ api-key ます。インデックスの内容をパブリックに使用できるようにしない限り、この操作は避ける必要があります。For this reason, Azure Cognitive Search will only accept a query key as an api-key in the query string, and you should avoid doing so unless the contents of your index should be publicly available. 一般的なルールとして、api-key は要求ヘッダーとして渡すことをお勧めします。As a general rule, we recommend passing your api-key as a request header.

承認Authorization

承認は、Azure portal に用意されているロールベースのアクセス制御 (RBAC) を介して管理操作を行うことができます。Authorization is available for administrative operations via the role-based access controls (RBAC) provided in the Azure portal. RBAC ロールは、サービス管理のアクセスレベルを、すべてのサービスで一貫した方法で設定するために使用されます。RBAC roles are used to set levels of access for service administration in a way that is consistent across all services. たとえば、機微なデータ (管理者キーなど) の表示は所有者ロールと共同作成者ロールに制限されるのに対し、サービスの状態はすべてのロールのメンバーが表示できます。For example, viewing sensitive data, such as the admin key, is restricted to the Owner and Contributor roles, whereas viewing service status is available to members of any role.

独自の検索中心の操作では、Azure Cognitive Search には承認モデルが用意されていません。For its own search-centric operations, Azure Cognitive Search does not provide an authorization model. ただし、ドキュメントとユーザーの関連付けを使用してインデックスを読み込むことができる場合は、ユーザー id に基づいて検索結果をフィルター処理できます。However, if you have the ability to load an index with document and user associations, you can filter search results based on user identity. 詳細については、「 Azure Cognitive Search で結果をトリミングするためのセキュリティフィルター」を参照してください。For more information, see Security filters for trimming results in Azure Cognitive Search.

関連項目See also