ドキュメントの検索 (Azure Cognitive Search REST API)Search Documents (Azure Cognitive Search REST API)

クエリ要求では、search サービスの単一インデックスのドキュメントコレクションが対象となります。A query request targets the documents collection of a single index on a search service. これには、一致条件を定義するパラメーターと、応答を形成するパラメーターが含まれます。It includes parameters that define the match criteria, and parameters that shape the response.

GET または POST を使用できます。You can use GET or POST. クエリパラメーター は、GET 要求の場合はクエリ文字列、POST 要求の場合は要求本文に指定されます。Query parameters are specified on the query string in the case of GET requests, and in the request body in the case of POST requests.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters] 
  Content-Type: application/json   
  api-key: [admin or query key]  
POST https://[service name].search.windows.net/indexes/[index name]/docs/search?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]  

GET を使用して呼び出された場合、要求 URL の長さが 8 KB を超えることはできません。When called with GET, the length of the request URL cannot exceed 8 KB. この長さは通常、ほとんどのアプリケーションに対して十分です。This length is usually enough for most applications. ただし、一部のアプリケーションでは、特に OData フィルター式が使用される場合に、非常に大きなクエリが生成されます。However, some applications produce very large queries, specifically when OData filter expressions are used. これらのアプリケーションでは、GET よりも大きなフィルターが許可されるため、HTTP POST の方が適しています。For these applications, HTTP POST is a better choice because it allows larger filters than GET.

POST 要求のサイズ制限がほぼ 16 MB であるため、POST を使用する場合は、フィルター文字列のサイズそのものではなく、フィルターに含まれる句の数が制限要因になります。With POST, the number of clauses in a filter is the limiting factor, not the size of the raw filter string since the request size limit for POST is approximately 16 MB. POST 要求のサイズ制限が非常に大きいとはいえ、フィルター式を任意に複雑にすることはできません。Even though the POST request size limit is very large, filter expressions cannot be arbitrarily complex. フィルターの複雑さの制限の詳細については、「 Azure Cognitive Search の OData 式の構文」を参照してください。For more information about filter complexity limitations, see OData Expression Syntax for Azure Cognitive Search.

URI パラメーターURI Parameters

パラメーターParameter 説明Description
[サービス名][service name] 必須です。Required. これを、検索サービスの一意のユーザー定義名に設定します。Set this to the unique, user-defined name of your search service.
[インデックス名]/ドキュメント[index name]/docs 必須です。Required. 名前付きインデックスのドキュメントコレクションを指定します。Specifies the documents collection of a named index.
[クエリパラメーター][query parameters] クエリパラメーターは、GET 要求の場合は URI で、POST 要求の場合は要求本文に指定されます。Query parameters are specified on the URI for GET requests and in the request body for POST requests.
api-versionapi-version 必須です。Required. 現行バージョンは api-version=2020-06-30です。The current version is api-version=2020-06-30. サポートされているすべてのバージョンの一覧については、「 Azure Cognitive Search の API バージョン」を参照してください。For a list of all supported versions, see API versions in Azure Cognitive Search. 検索ドキュメント の場合、api バージョンは常に GET と POST の両方の URI パラメーターとして指定されます。For Search Documents, the api-version is always specified as a URI parameter for both GET and POST.

URL エンコードに関する推奨事項URL-encoding recommendations

GET REST API を直接呼び出すときは、特定のクエリパラメーターを URL エンコード することを忘れないでください。Remember to URL-encode specific query parameters when calling the GET REST API directly. 検索ドキュメント 操作の場合、次のクエリパラメーターには URL エンコードが必要になることがあります。For a Search Documents operation, URL-encoding might be necessary for the following query parameters:

  • searchsearch
  • $filter$filter
  • facetfacet
  • highlightPreTaghighlightPreTag
  • highlightPostTaghighlightPostTag

URL エンコードは、個々のパラメーターに対してのみ推奨されます。URL encoding is only recommended for individual parameters. クエリ文字列全体 (? の後の全部) を気付かずに URL エンコードした場合、要求が壊れます。If you inadvertently URL-encode the entire query string (everything after the ?), requests will break.

また、URL エンコードは、GET を使用して REST API を直接呼び出すときにのみ必要です。Also, URL encoding is only necessary when calling the REST API directly using GET. POST を使用する場合や、エンコードを処理する Azure Cognitive Search .net クライアントライブラリを使用する場合は、URL エンコードは必要ありません。No URL encoding is necessary when using POST, or when using the Azure Cognitive Search .NET client library, which handles encoding for you.

要求ヘッダーRequest Headers

次の表では、必須と省略可能の要求ヘッダーについて説明します。The following table describes the required and optional request headers.

フィールドFields 説明Description
Content-TypeContent-Type 必須です。Required. これを "application/json" に設定します。Set this to "application/json"
api-keyapi-key 必須です。Required. 検索サービスへの要求を認証する、システムによって生成される一意の文字列。A unique, system-generated string that authenticates the request to your search service. Documents コレクションに対するクエリ要求では、管理者キーまたはクエリキーを API キーとして指定できます。Query requests against the documents collection can specify either an admin-key or query-key as the API key. クエリキーは、ドキュメントコレクションに対する読み取り専用操作に使用されます。The query-key is used for read-only operations against the documents collection. Azure portal からキーを取得できます。You can get keys from the Azure portal. 詳細については、「 既存のキーを検索する」を参照してください。For more information, see Find existing keys.

要求本文Request Body

GET の場合: なし。For GET: None.

POST の場合:For POST:

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }  

部分的な検索応答の継続Continuation of Partial Search Responses

Azure Cognitive Search は、要求されたすべての結果を単一の検索応答で返すことはできません。Sometimes Azure Cognitive Search can't return all the requested results in a single Search response. これは、$top を指定しなかったり、大きすぎる $top の値を指定したりすることによって、クエリが大量のドキュメントを要求する場合など、さまざまな理由で発生する可能性があります。This can happen for different reasons, such as when the query requests too many documents by not specifying $top or specifying a value for $top that is too large. このような場合、Azure Cognitive Search には、 @odata.nextLink 応答本文に注釈が含められ @search.nextPageParameters ます。また、POST 要求の場合も同様です。In such cases, Azure Cognitive Search will include the @odata.nextLink annotation in the response body, and also @search.nextPageParameters if it was a POST request. これらの注釈の値を使用して別の Search 要求を作成して、検索応答の次の部分を取得できます。You can use the values of these annotations to formulate another Search request to get the next part of the search response. これは元の Search 要求の 継続 と呼ばれ、注釈は一般に 継続トークン と呼ばれます。This is called a continuation of the original Search request, and the annotations are generally called continuation tokens. これらの注釈の構文の詳細と、応答本文に表示される場所については、後述の「応答」の例を参照してください。See the example in Response below for details on the syntax of these annotations and where they appear in the response body.

Azure Cognitive Search が継続トークンを返す理由は実装固有であり、変更される可能性があります。The reasons why Azure Cognitive Search might return continuation tokens are implementation-specific and subject to change. 堅牢なクライアントでは、返されたドキュメントが予想よりも少なく、ドキュメントの取得を継続するために継続トークンが含まれている場合を処理する準備が常にできている必要があります。Robust clients should always be ready to handle cases where fewer documents than expected are returned and a continuation token is included to continue retrieving documents. また、継続するためには、元の要求と同じ HTTP メソッドを使用する必要がある点にも注意してください。Also note that you must use the same HTTP method as the original request in order to continue. たとえば、GET 要求を送信した場合、送信する継続の要求でも GET を使用する必要があります (POST の場合も同様です)。For example, if you sent a GET request, any continuation requests you send must also use GET (and likewise for POST).

注意

との目的は、 @odata.nextLink @search.nextPageParameters ページングのための一般的なメカニズムを提供するのではなく、多数の結果を要求するクエリからサービスを保護することです。The purpose of @odata.nextLink and @search.nextPageParameters is to protect the service from queries that request too many results, not to provide a general mechanism for paging. 結果を表示するには、$top を使用し、$skip します。If you want to page through results, use $top and $skip together. たとえば、サイズが10のページが必要な場合、最初の要求には $top = 10 および $skip = 0、2番目の要求には $top = 1、$skip = 10、3番目の要求には $top = 10 および $skip = 20 を指定する必要があります。For example, if you want pages of size 10, your first request should have $top=10 and $skip=0, the second request should have $top=1` and $skip=10, the third request should have $top=10 and $skip=20, and so on.

クエリ パラメーターQuery Parameters

クエリでは、GET で呼び出された場合は URL に対して複数のパラメーターを受け取り、POST で呼び出された場合は要求本文の JSON プロパティとしてを受け取ります。A query accepts several parameters on the URL when called with GET, and as JSON properties in the request body when called with POST. いくつかのパラメーターの構文は、GET および POST の間で多少異なります。The syntax for some parameters is slightly different between GET and POST. これらの違いについては、以下で説明します。These differences are noted as applicable below.

名前Name 種類Type 説明Description
api-versionapi-version stringstring 必須。Required. 要求に使用された REST API のバージョン。Version of the REST API used for the request. サポートされているバージョンの一覧については、「 API のバージョン管理」を参照してください。For a list of supported versions, see API versioning. この操作では、GET または POST を使用して 検索ドキュメント を呼び出すかどうかにかかわらず、api バージョンは URI パラメーターとして指定されます。For this operation, the api-version is specified as a URI parameter regardless of whether you call Search Documents with GET or POST.
$count$count booleanboolean 任意。Optional. 有効な値は "true" または "false" です。Valid values are "true" or "false". 既定値は "false" です。Defaults to "false". POST で呼び出された場合、このパラメーターは $count ではなく、count という名前になります。When called with POST, this parameter is named count instead of $count. 結果の合計数を取得するかどうかを指定します。Specifies whether to fetch the total count of results. これは、検索パラメーターと $filter パラメーターに一致し、$top と $skip を無視するすべてのドキュメントの数です。This is the count of all documents that match the search and $filter parameters, ignoring $top and $skip. この値を "true" に設定すると、パフォーマンスが低下する可能性があります。Setting this value to "true" may degrade performance. 返されるカウントは概数です。The count returned is an approximation. ドキュメントを含まない数のみを取得する場合は、$top = 0 を使用できます。If you’d like to get only the count without any documents, you can use $top=0.
facetfacet stringstring 省略可能。Optional. ファセットの対象となるフィールド。A field to facet by. 文字列には、コンマ区切りの名前と値のペアとして表現されるファセットをカスタマイズするためのパラメーターを含めることができます。The string may contain parameters to customize the faceting, expressed as comma-separated name-value pairs. POST で呼び出された場合、このパラメーターはファセットではなく、ファセットとして指定されます。When called with POST, this parameter is named facets instead of facet.

有効な値は、"count"、"sort"、"values"、"interval"、および "timeoffset" です。Valid are "count", "sort", "values", "interval", and "timeoffset".

"count" はファセット用語の最大数です。既定値は10です。"count" is the maximum number of facet terms; default is 10. 用語の数に上限はありませんが、値を大きくするとパフォーマンスが低下します。ファセットフィールドに一意の用語が多数含まれている場合は特にそうです。There is no upper limit on the number of terms, but higher values will degrade performance, especially if the faceted field contains a large number of unique terms. たとえば、"facet = category, count: 5" は、ファセットの結果の上位5つのカテゴリを取得します。For example, "facet=category,count:5" gets the top five categories in facet results. Count パラメーターが一意の用語の数より小さい場合、結果が正確ではない可能性があります。If the count parameter is less than the number of unique terms, the results may not be accurate. これは、ファセット クエリがシャード間に分散される方法のためです。This is due to the way faceting queries are distributed across shards. カウントを増やすと、一般に、用語の数の精度が向上しますが、パフォーマンスは低下します。Increasing count generally increases the accuracy of term counts, but at a performance cost.

"sort" は "count"、"-count"、"value"、"-value" に設定できます。"sort" can be set to "count", "-count", "value", "-value". カウントで降順に並べ替えるには、count を使用します。Use count to sort descending by count. カウントを使用して昇順で並べ替えるには、-count を使用します。Use -count to sort ascending by count. 値で昇順に並べ替えるには、値を使用します。Use value to sort ascending by value. 値で降順に並べ替えるには-value を使用します (たとえば、"facet = category, count: 3, sort: count" は、ファセットの結果内の上位3つのカテゴリを、各都市名を持つドキュメントの数の降順で取得します)。Use -value to sort descending by value (for example, "facet=category,count:3,sort:count" gets the top three categories in facet results in descending order by the number of documents with each city name). 上位 3 つのカテゴリが「予算」、「ホテル」、および「高級」であり、「予算」のヒット数が 5、「ホテル」のヒット数が 6、「高級」のヒット数が 4 である場合、バケットは「ホテル」、「予算」、「高級」の順番に並べられます。If the top three categories are Budget, Motel, and Luxury, and Budget has 5 hits, Motel has 6, and Luxury has 4, then the buckets will be in the order Motel, Budget, Luxury. -Value、"facet = 格付け、sort:-value" は、すべての可能な評価のバケットを値で降順に生成します (たとえば、評価が 1 ~ 5 の場合、各評価が一致するドキュメントの数に関係なく、バケットは5、4、3、2、1の順に並べ替えられます)。For -value, "facet=rating,sort:-value" produces buckets for all possible ratings, in descending order by value (for example, if the ratings are from 1 to 5, the buckets will be ordered 5, 4, 3, 2, 1, irrespective of how many documents match each rating).

"値" は、パイプで区切られた数値または Edm に設定できます。ファセットエントリ値の動的セットを指定する DateTimeOffset 値 (たとえば、"facet = baseRate, values:10 | 20" は3つのバケットを生成します。1つは基本速度0、10を除く10、20以上、20以上) です。"values" can set to pipe-delimited numeric or Edm.DateTimeOffset values specifying a dynamic set of facet entry values (for example, "facet=baseRate,values:10 | 20" produces three buckets: one for base rate 0 up to but not including 10, one for 10 up to but not including 20, and one for 20 and higher). 文字列 "facet = Lastrrenovated Vationdate, values: 2010-02-01T00:00: 00Z" は2つのバケットを生成します。1つは2010年2月より前のホテル renovated、もう1つはホテル2月1日2010以降のバケットです。A string "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" produces two buckets: one for hotels renovated before February 2010, and one for hotels renovated February 1, 2010 or later.

"interval" は、数値、分、時、日、週、月、四半期、日付と時刻の値について、0より大きい整数間隔です。"interval" is an integer interval greater than 0 for numbers, or minute, hour, day, week, month, quarter, year for date time values. たとえば、"facet = baseRate, interval: 100" は、サイズ100の基本料金範囲に基づいてバケットを生成します。For example, "facet=baseRate,interval:100" produces buckets based on base rate ranges of size 100. 基本料金がすべて $60 と $600 の間にある場合は、0-100、100-200、200-300、300-400、400-500、および500-600 のバケットが存在します。If base rates are all between $60 and $600, there will be buckets for 0-100, 100-200, 200-300, 300-400, 400-500, and 500-600. 文字列 "facet = Lastrrenovated Vationdate, interval: year" は、ホテルがされた年ごとに1つのバケットを生成します。The string "facet=lastRenovationDate,interval:year" produces one bucket for each year when hotels were renovated.

"timeoffset" は、([+-] hh: mm、[+-] hhmm、または [+-] hh) に設定できます。"timeoffset" can be set to ([+-]hh:mm, [+-]hhmm, or [+-]hh). Timeoffset パラメーターを使用する場合は、interval オプションと組み合わせて使用する必要があります。これは、型のフィールドに適用されている場合のみです。If used, the timeoffset parameter must be combined with the interval option, and only when applied to a field of type Edm.DateTimeOffset. この値によって、時間の境界の設定における UTC 時刻のオフセットを指定します。The value specifies the UTC time offset to account for in setting time boundaries. たとえば、"facet = Lastrの Vationdate, interval: day, timeoffset:-01:00" は、01:00:00 UTC (ターゲットタイムゾーンでは深夜 0) から始まる日の境界を使用します。For example: "facet=lastRenovationDate,interval:day,timeoffset:-01:00" uses the day boundary that starts at 01:00:00 UTC (midnight in the target time zone).

count と sort は同じファセットの仕様で組み合わせることができますが、間隔や値と組み合わせることはできません。また、間隔と値を一緒に組み合わせることはできません。count and sort can be combined in the same facet specification, but they cannot be combined with interval or values, and interval and values cannot be combined together.

日付時刻の間隔ファセットは、timeoffset が指定されていない場合の UTC 時刻に基づいて計算されます。Interval facets on date time are computed based on the UTC time if timeoffset is not specified. 例: "facet = Lastrの Vationdate, interval: day" の場合、日の境界は 00:00:00 UTC で開始されます。For example: for "facet=lastRenovationDate,interval:day", the day boundary starts at 00:00:00 UTC.
$filter$filter stringstring 省略可能。Optional. 標準の OData 構文で構造化された検索式です。A structured search expression in standard OData syntax. フィルターで使用できるのは、フィルター可能なフィールドのみです。Only filterable fields can be used in a filter. POST を使用してを呼び出す場合、このパラメーターは $filter ではなく filter という名前になります。When calling with POST, this parameter is named filter instead of $filter. Azure Cognitive Search でサポートされている OData 式の文法の詳細については、「 azure Cognitive Search の Odata 式の構文 」を参照してください。See OData Expression Syntax for Azure Cognitive Search for details on the subset of the OData expression grammar that Azure Cognitive Search supports.
highlighthighlight stringstring 省略可能。Optional. ヒット ハイライトに使用する一連のフィールド名で、コンマで区切ります。A set of comma-separated field names used for hit highlights. 検索可能なフィールドだけを、ヒットの強調表示に使用できます。Only searchable fields can be used for hit highlighting. 既定では、Azure Cognitive Search によって、フィールドごとに最大5個のハイライトが返されます。By default, Azure Cognitive Search returns up to 5 highlights per field. この制限は、フィールド名の後に "-<max # of ハイライト>" を追加することで、フィールドごとに構成できます。The limit is configurable per field by appending "-<max # of highlights>" following the field name. たとえば、"強調表示 = タイトル-3, 説明-10" は、[タイトル] フィールドから最大3個の強調表示されたヒットを返し、[説明] フィールドから最大10件のヒットを返します。For example, "highlight=title-3,description-10" returns up to 3 highlighted hits from the title field and up to 10 hits from the description field. ハイライトの最大数は、1 ~ 1000 の範囲の整数である必要があります。The maximum number of highlights must be an integer between 1 and 1000 inclusive.
highlightPostTaghighlightPostTag stringstring 任意。Optional. 既定値は "</em>" です。Defaults to "</em>". 強調表示された語句に追加する文字列タグ。A string tag that appends to the highlighted term.. HighlightPreTag を使用して設定する必要があります。Must be set with highlightPreTag. URL の予約済みの文字は、パーセントでエンコードする必要があります (たとえば、# ではなく %23)。Reserved characters in URL must be percent-encoded (for example, %23 instead of #).
highlightPreTaghighlightPreTag stringstring 任意。Optional. 既定値は "</em>" です。Defaults to "</em>". 強調表示された語句の前に付加する文字列タグ。A string tag that prepends to the highlighted term. HighlightPostTag を使用して設定する必要があります。Must be set with highlightPostTag. URL の予約済みの文字は、パーセントでエンコードする必要があります (たとえば、# ではなく %23)。Reserved characters in URL must be percent-encoded (for example, %23 instead of #).
minimumCoverageminimumCoverage 整数 (integer)integer 省略可能。Optional. 有効な値は、0から100までの数値です。これは、クエリを成功として報告するために必要なインデックスの割合を示します。Valid values are a number between 0 and 100, indicating the percentage of the index that must be available to service the query before it can be reported as a success. 既定値は "100" です。Defaults to "100".

100% カバレッジは、すべてのシャードが要求に応答したことを意味します (サービス正常性の問題もメンテナンスアクティビティも対象外)。One hundred percent coverage means that all shards responded to the request (neither service health issues nor maintenance activities reduced coverage). 既定の設定では、全カバレッジより小さい場合、HTTP 状態コード503が返されます。Under the default setting, less than full coverage will return HTTP status code 503.

MinimumCoverage を下げることは、503エラーが発生しており、クエリの成功率を上げる必要がある場合 (特に、1つのレプリカ用に構成されたサービスの場合) に役立ちます。Lowering minimumCoverage can be useful if 503 errors are occurring and you want to increase the probability of query success, especially for services that are configured for one replica. MinimumCoverage を設定して検索が成功した場合は、HTTP 200 が返され、 @search.coverage クエリに含まれていたインデックスの割合を示す値が応答に含まれます。If you set minimumCoverage and Search succeeds, it will return HTTP 200 and include a @search.coverage value in the response indicating the percentage of the index that was included in the query. このシナリオでは、一致するすべてのドキュメントが検索結果に存在することが保証されるわけではありませんが、検索の可用性がリコールよりも重要な場合、カバレッジを減らすことは、実行可能な軽減策になります。In this scenario, not all matching documents are guaranteed to be present in the search results, but if search availability is more important than recall, then reducing coverage can be a viable mitigation strategy.
$orderby$orderby stringstring 省略可能。Optional. 結果を並べ替える式の一覧で、コンマで区切ります。A list of comma-separated expressions to sort the results by. POST で呼び出された場合、このパラメーターは $orderby ではなく orderby という名前になります。When called with POST, this parameter is named orderby instead of $orderby. 各式には、フィールド名または geo. distance () 関数の呼び出しのいずれかを指定できます。Each expression can be either a field name or a call to the geo.distance() function. 各式の後に "asc" を付けて昇順を示すことができ、"desc" を使用して降順を示すことができます。Each expression can be followed by "asc" to indicate ascending, and "desc" to indicate descending. 並べ替えフィールドに null 値がある場合は、null 値が最初に昇順で、最後に降順で表示されます。If there are null values in the sort field, nulls appear first in ascending order and last in descending order. 既定値は昇順です。The default is ascending order. 結び付きは、ドキュメントの一致スコアによって切り離されます。Ties will be broken by the match scores of documents. $Orderby が指定されていない場合、既定の並べ替え順序はドキュメントの一致スコアによって降順になります。If no $orderby is specified, the default sort order is descending by document match score. $Orderby には、32の句の制限があります。There is a limit of 32 clauses for $orderby.
queryTypequeryType stringstring 省略可能。Optional. 有効な値は、"simple" または "full" です。Valid values are "simple" or "full". 既定値は "simple" です。Defaults to "simple".

"simple" は、、、などのシンボルを許可する 単純なクエリ構文 を使用して、クエリ文字列を解釈し + * "" ます。"simple" interprets query strings using the simple query syntax that allows for symbols such as +, * and "". クエリは、既定では、各ドキュメントの検索可能なフィールド (または searchFields に示されているフィールド) 全体で評価されます。Queries are evaluated across all searchable fields (or fields indicated in searchFields) in each document by default.

"full" は、フィールド固有の検索と重み付け検索を可能にする 完全な Lucene クエリ構文 を使用して、クエリ文字列を解釈します。"full" interprets query strings using the full Lucene query syntax which allows field-specific and weighted searches. Lucene クエリ言語の範囲検索は、同様の機能を提供する $filter が用意されているため、サポートされません。Range search in the Lucene query language is not supported in favor of $filter which offers similar functionality.
scoringParameterscoringParameter stringstring 省略可能。Optional. "Name-value1, value2,..." の形式を使用して、スコアリング関数 (referencePointParameter など) で定義されている各パラメーターの値を示します。POST で呼び出された場合、このパラメーターは scoringParameter ではなく scoringParameters という名前になります。Indicates the values for each parameter defined in a scoring function (such as referencePointParameter) using the format "name-value1,value2,..." When called with POST, this parameter is named scoringParameters instead of scoringParameter. また、各文字列が個別の名前と値のペアである文字列の JSON 配列として指定します。Also, you specify it as a JSON array of strings where each string is a separate name-values pair.

関数を含むスコアリングプロファイルの場合は、関数を入力リストから文字で区切り - ます。For scoring profiles that include a function, separate the function from its input list with a - character. たとえば、という関数は、 "mylocation" "&scoringParameter = mylocation--122.2, 44.8" になります。For example, a function called "mylocation" would be "&scoringParameter=mylocation--122.2,44.8". 最初のダッシュは、値リストから関数名を区切ります。2番目のダッシュは最初の値の一部です (この例では経度)。The first dash separates the function name from the value list, while the second dash is part of the first value (longitude in this example).

タグ ブーストなどに使用するスコア パラメーターは、コンマを含む場合があります。その場合、リスト内では単一引用符を使用してこのような値をエスケープすることができます。For scoring parameters such as for tag boosting that can contain commas, you can escape any such values in the list using single quotes. 値自体に単一引用符が含まれる場合は、2 個入力することでエスケープできます。If the values themselves contain single quotes, you can escape them by doubling. タグブーストパラメーターが呼び出され、 "mytag" タグ値 "hello, O'Brien" および "Smith" でブーストする場合、クエリ文字列オプションは "&scoringParameter = mytag-' Hello, O ' ' Brien ', Smith" になります。Suppose you have a tag boosting parameter called "mytag" and you want to boost on the tag values "Hello, O'Brien" and "Smith", the query string option would then be "&scoringParameter=mytag-'Hello, O''Brien',Smith". 引用符は、コンマを含む値に対してのみ必要です。Quotes are only required for values that contain commas.
scoringProfilescoringProfile stringstring 省略可能。Optional. 結果を並び替えるために一致ドキュメントの一致スコアを評価するスコア付けプロファイルの名前。The name of a scoring profile to evaluate match scores for matching documents in order to sort the results.
scoringStatisticsscoringStatistics stringstring 省略可能。Optional. 有効な値は、"local" または "global" です。Valid values are "local" or "global". 既定値は "local" です。Defaults to "local". ドキュメントの頻度、グローバルに (すべてのシャードを対象)、より一貫性のあるスコアリングのために (または、現在のシャードで) ローカル (現在のシャードで) の待機時間の統計を計算するかどうかを指定します。Specify whether to calculate scoring statistics, such as document frequency, globally (across all shards) for more consistent scoring, or locally (on the current shard) for lower latency. Azure Cognitive Search でのスコア付けの統計」を参照してください。See Scoring Statistics in Azure Cognitive Search. スコアリング統計は、あいまい検索を使用する用語 (' ~ ')に対して常にローカルで計算されます。Scoring statistics will always be calculated locally for terms that use fuzzy search ('~').
searchsearch stringstring 省略可能。Optional. 検索するテキストです。The text to search for. SearchFields が指定されていない限り、検索可能なすべてのフィールドが既定で検索されます。All searchable fields are searched by default unless searchFields is specified. インデックスでは、検索可能フィールド内のテキストがトークン化されるため、複数の用語を空白で区切ることができます (例: ' search = hello world ')。In the index, text in a searchable field is tokenized, so multiple terms can be separated by white space (for example: 'search=hello world'). 任意の語句と一致させるには、 * を使用します (これはブール型フィルターのクエリに便利です)。To match any term, use * (this can be useful for boolean filter queries). このパラメーターを省略することは、 *に設定するのと同じ効果を持ちます。Omitting this parameter has the same effect as setting it to *. 検索構文の詳細については、 簡単なクエリ構文 に関するページを参照してください。See Simple query syntax for specifics on the search syntax.

検索可能なフィールドに対してクエリを実行すると、結果が意外になることがあります。Results can sometimes be surprising when querying over searchable fields. トークナイザには、アポストロフィや数字の中のコンマのように、英語のテキストによく使用されているケースを処理するロジックが含まれています。The tokenizer includes logic to handle cases common to English text like apostrophes, commas in numbers, and so forth. たとえば、' search = 123456 ' は個別の用語 ' 123 ' および ' 456 ' ではなく、1つの用語 ' 123456 ' と一致します。これは、英語では、コンマが大きな数値の桁区切り記号として使用されるためです。For example, 'search=123,456' will match a single term '123,456' rather than the individual terms '123' and '456', since commas are used as thousand-separators for large numbers in English. このため、検索パラメーターで用語を区切るには、句読点ではなく空白文字を使用することをお勧めします。For this reason, we recommend using white space rather than punctuation to separate terms in the search parameter.
searchModesearchMode stringstring 省略可能。Optional. 有効な値は "any" または "all" で、既定値は "any" です。Valid values are "any" or "all" Defaults to "any". 一致ドキュメントをカウントする上で、検索用語の一部が一致すればよいか、それともすべて一致する必要があるかを指定します。Specifies whether any or all of the search terms must be matched in order to count the document as a match.
searchFieldssearchFields stringstring 省略可能。Optional. 指定したテキストを検索するフィールド名の一覧であり、コンマで区切ります。The list of comma-separated field names to search for the specified text. ターゲットフィールドは、インデックススキーマで検索可能としてマークされている必要があります。Target fields must be marked as searchable in the index schema.
$select$select stringstring 省略可能。Optional. 結果セットに含めるコンマ区切りのフィールドの一覧。A list of comma-separated fields to include in the result set. この句には、取得可能としてマークされているフィールドのみを含めることができます。Only fields marked as retrievable can be included in this clause. 指定しない場合、または *に設定した場合は、スキーマで取得可能とマークされているすべてのフィールドが含まれます。If unspecified or set to *, all fields marked as retrievable in the schema are included in the projection. POST で呼び出された場合、このパラメーターは $select ではなく select という名前になります。When called with POST, this parameter is named select instead of $select.
sessionIDsessionId stringstring 省略可能。Optional. SessionId を使用すると、複数のレプリカを持つ検索サービスの関連性スコアの一貫性が向上します。Using sessionId help improve relevance score consistency for search services with multiple replicas. マルチレプリカ構成では、同じクエリに対して個々のドキュメントの関連性スコアがわずかに異なる場合があります。In multi-replica configurations, there can be slight differences between relevance scores of individual documents for the same query. セッション ID を指定すると、サービスは、そのセッションの同じレプリカに対して、指定された要求をルーティングするためのベストエフォートを行います。When a session ID is provided, the service will make best-effort to route a given request to the same replica for that session. 同じセッション ID 値を繰り返し再利用すると、複数のレプリカ間で要求の負荷分散が妨げられ、search サービスのパフォーマンスに悪影響を及ぼす可能性があります。Be wary that reusing the same session ID values repeatedly can interfere with load balancing of the requests across replicas and adversely affect the performance of the search service. sessionId として使用される値は、'' 文字で始めることはできません。The value used as sessionId cannot start with a '' character. サービスにレプリカがない場合、このパラメーターはパフォーマンスやスコアの一貫性に影響しません。If a service doesn't have any replicas, this parameter has no effect on performance or score consistency.
$skip$skip 整数 (integer)integer 省略可能。Optional. スキップする検索結果の数です。The number of search results to skip. POST で呼び出された場合、このパラメーターには $skip ではなく skip という名前が付けられます。When called with POST, this parameter is named skip instead of $skip. この値を10万より大きくすることはできません。This value cannot be greater than 100,000. ドキュメントを順番にスキャンする必要があり、この制限のために $skip を使用できない場合は、インデックス内のすべてのドキュメントに対して一意の値を持つフィールド (たとえば、ドキュメントキーなど) に対して $orderby を使用することを検討してください。代わりに、範囲クエリを使用して $filter します。If you need to scan documents in sequence, but cannot use $skip due to this limitation, consider using $orderby on a field that has unique values for every document in the index (like the document key, for example) and $filter with a range query instead.
$top$top 整数 (integer)integer 省略可能。Optional. 取得する検索結果の数です。The number of search results to retrieve. 既定値は 50 です。This defaults to 50. POST で呼び出された場合、このパラメーターの名前は $top ではなく、top になります。When called with POST, this parameter is named top instead of $top. 1000より大きい値を指定し、1000を超える結果がある場合は、最初の1000の結果だけが結果の次のページへのリンクと共に返されます (次の例の「」を参照してください @odata.nextLink )。If you specify a value greater than 1000 and there are more than 1000 results, only the first 1000 results will be returned, along with a link to the next page of results (see @odata.nextLink in the example below).

Azure Cognitive Search では、 サーバー側のページング を使用して、クエリが大量のドキュメントを一度に取得するのを防ぐことができます。Azure Cognitive Search uses server-side paging to prevent queries from retrieving too many documents at once. 既定のページサイズは50ですが、ページの最大サイズは1000です。The default page size is 50, while the maximum page size is 1000. これは、$top を指定しない場合、既定では、 検索ドキュメント は最大50件の結果を返すことを意味します。This means that by default Search Documents returns at most 50 results if you don't specify $top. 50件を超える結果がある場合、応答には、最大50件の結果の次のページを取得するための情報が含まれ @odata.nextLink @search.nextPageParameters ます (以下の では、「」および「」を参照してください)。If there are more than 50 results, the response includes information to retrieve the next page of at most 50 results (see "@odata.nextLink" and "@search.nextPageParameters" in the Examples below. 同様に、$top に1000より大きい値を指定し、1000以上の結果がある場合は、最初の1000の結果だけが返され、最大で1000の結果の次のページを取得するための情報も返されます。Similarly, if you specify a value greater than 1000 for $top and there are more than 1000 results, only the first 1000 results are returned, along with information to retrieve the next page of at most 1000 results.

ResponseResponse

状態コード: 応答の成功に対して「200 OK」が返されます。Status Code: 200 OK is returned for a successful response.

  {
    "@odata.count": # (if $count=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

Examples

その他の例については、「 Azure Cognitive Search の OData 式の構文」を参照してください。You can find additional examples in OData Expression Syntax for Azure Cognitive Search.

  1. 日付に基づいて降順で並べ替えられたインデックスを検索します。Search the Index sorted descending by date:

    GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "*",  
          "orderby": "LastRenovationDate desc"
        }  
    
  2. ファセット検索では、インデックスを検索し、カテゴリ、評価、タグ、および特定の範囲内の baseRate を持つ項目のファセットを取得します。In a faceted search, search the index and retrieve facets for categories, ratings, tags, as well as items with baseRate in specific ranges.

    GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "test",  
          "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
        }  
    

    最後のファセットがサブフィールドにあることに注意してください。Notice the last facet is on a sub-field. ファセットは、中間のサブドキュメント (部屋) ではなく、親ドキュメント (ホテル) をカウントするので、応答によって、各価格バケットにルームがあるホテルの数が決定されます。Facets count the parent document (Hotels) and not intermediate sub-documents (Rooms), so the response will determine the number of hotels that have any rooms in each price bucket.

  3. フィルターを使用して、ユーザーが評価3とカテゴリ "Motel" を選択した後に、前のファセットクエリの結果を絞り込みます。Using a filter, narrow down the previous faceted query result after the user selects Rating 3 and category "Motel".

    GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "test",  
          "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
          "filter": "Rating eq 3 and Category eq 'Motel'"  
        }  
    
  4. ファセット検索で、クエリで返される一意の語句に上限を設定します。In a faceted search, set an upper limit on unique terms returned in a query. 既定値は 10 ですが、ファセット属性でカウント パラメーターを使用することで、この値を増減できます。The default is 10, but you can increase or decrease this value using the count parameter on the facet attribute. この例では、5 に制限された、都市のファセットを返します。This example returns facets for city, limited to 5.

    GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "test",  
          "facets": [ "Address/City,count:5" ]  
        }  
    
  5. 特定のフィールド (たとえば、言語フィールド) 内のインデックスを検索します。Search the Index within specific fields (for example, a language field):

    GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "hôtel",  
          "searchFields": "Description_fr"
        }  
    
  6. 複数のフィールドにまたがるインデックスを検索します。Search the Index across multiple fields. たとえば、複数の言語の検索可能なフィールドをすべて同じインデックスに格納してクエリできます。For example, you can store and query searchable fields in multiple languages, all within the same index. 英語とフランス語の説明が同じドキュメントに共存している場合、いずれかまたはすべてをクエリ結果で返すことができます。If English and French descriptions co-exist in the same document, you can return any or all in the query results:

    GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "hotel",  
          "searchFields": "Description, Description_fr"
        }  
    

    インデックスのクエリを実行できるのは一度に1つだけです。You can only query index at a time. 一度に 1 つをクエリするのでない限り、言語ごとに複数のインデックスを作成しないでください。Do not create multiple indexes for each language unless you plan to query one at a time.

  7. ページング-項目の最初のページを取得します (ページサイズは 10)。Paging - Get the first page of items (page size is 10):

    GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "*",  
          "skip": 0,  
          "top": 10  
        }  
    
  8. ページング-項目の2番目のページを取得します (ページサイズは 10)。Paging - Get the second page of items (page size is 10):

    GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "*",  
          "skip": 10,  
          "top": 10  
        }  
    
  9. 特定のフィールドのセットを取得します。Retrieve a specific set of fields:

    GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "*",  
          "select": "HotelName, Description"
        }  
    
  10. 特定のフィルター式に一致するドキュメントを取得します。Retrieve documents matching a specific filter expression:

    GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
        }  
    
  11. インデックスを検索し、ヒット ハイライトでフラグメントを返します。Search the index and return fragments with hit highlights:

    GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "something",  
          "highlight": "Description"  
        }  
    
  12. インデックスを検索し、参照場所に近いものから順番に並べられたドキュメントを返します。Search the index and return documents sorted from closer to farther away from a reference location:

    GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "something",  
          "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
        }  
    
  13. 2 つの distance スコア付け関数 (1 つは "currentLocation" というパラメーターを定義し、もう 1 つは "lastLocation" というパラメーターを定義している) を使用した "geo" と呼ばれるスコア付けプロファイルがあると仮定して、インデックを検索します。Search the index assuming there's a scoring profile called "geo" with two distance scoring functions, one defining a parameter called "currentLocation" and one defining a parameter called "lastLocation":

    GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "something",  
          "scoringProfile": "geo",  
          "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
        }  
    
  14. 簡単なクエリ構文を使用して、インデックス内のドキュメントを検索します。Find documents in the index using simple query syntax. このクエリは、検索可能なフィールドに語句 "comfort" および "location" が含まれていて "motel" が含まれないホテルを返します。This query returns hotels where searchable fields contain the terms "comfort" and "location" but not "motel":

    Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=22020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "comfort +location -motel",  
          "searchMode": "all"  
        }  
    

    ヒント

    searchMode=all を使用すると、既定の searchMode=any がオーバーライドされ、-motel が「OR NOT」ではなく「AND NOT」を意味します。The use of searchMode=all overrides the default of searchMode=any, ensuring that -motel means "AND NOT" instead of "OR NOT". searchMode=allを指定しないと、検索結果を制限するのではなく拡大する "OR NOT" になり、一部のユーザーにとっては直感に反している可能性があります。Without searchMode=all, you get "OR NOT" which expands rather than restricts search results, and this can be counter-intuitive to some users.

  15. Lucene クエリ構文を使用して、インデックス内のドキュメントを検索します)。Find documents in the index using Lucene query syntax). このクエリは、カテゴリ フィールドに "budget" (低料金) が含まれ、すべての検索可能なフィールドに "recently renovated" (最近改修済み) というフレーズが含まれるホテルを返します。This query returns hotels where the category field contains the term "budget" and all searchable fields containing the phrase "recently renovated". "recently renovated" というフレーズを含むドキュメントは、用語のブースト値 (3) の結果、高いランクになります。Documents containing the phrase "recently renovated" are ranked higher as a result of the term boost value (3)

    GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2020-06-30&querytype=full` 
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
         "search": "Category:budget AND \"recently renovated\"^3",  
          "queryType": "full",  
          "searchMode": "all"  
    }  
    
  16. インデックス内のドキュメントを検索し、待機時間を短くして優先に一貫性のあるスコア付けを行います。Find documents in the index while favoring consistent scoring over lower latency. このクエリでは、インデックス全体でドキュメントの頻度が計算され、同じ "セッション" 内のすべてのクエリに対して同じレプリカをターゲットにすることが最善の方法となります。これは、安定した再現可能なランキングを生成するのに役立ちます。This query will calculate document frequencies across the whole index, and will do a best effort to target the same replica for all queries within the same "session", which will help generating stable and reproducible ranking.

    GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2020-06-30
    
    POST /indexes/hotels/docs/search?api-version=2020-06-30
        {  
          "search": "hotel",  
          "sessionId": "mySessionId",
          "scoringStatistics" :"global"
        }  
    

関連項目See also