提案 (Azure Cognitive Search REST API)Suggestions (Azure Cognitive Search REST API)

提案 要求は、suggester 対応フィールドで一致する値を検索し、一致を含むドキュメントを返す、入力としての検索クエリです。A Suggestions request is a search-as-you-type query that looks for matching values in suggester-aware fields and returns documents that contain a match. たとえば、 city フィールドで候補を有効にした場合、「sea」と入力すると、そのフィールドの "Seattle"、"sea vs-tac"、および "seaside" (すべての実際の市区町村名) を含むドキュメントが生成されます。For example, if you enable suggestions on a city field, typing "sea" produces documents containing "Seattle", "Sea Tac", and "Seaside" (all actual city names) for that field.

応答は、一致するドキュメントからドキュメントキーまでのコンテンツです。The response is a content from a matching document plus the document key. セカンダリクエリで使用される完成した用語または語句を返すオートコンプリートとは対照的に、この要求は実際のドキュメントに解決される情報を返します。In contrast with Autocomplete, which returns a completed term or phrase used in a secondary query, this request returns information that resolves to actual documents. 一致する用語や語句がドキュメント間で同一である場合は、一致する内容が繰り返されます。If matching terms or phrases are identical across documents, the matching content is repeated. 結果の構造を改善するには、フィルターを使用して、 $select より多くの区別とコンテキストを提供する追加のフィールドを返すことを検討してください。To improve the structure of results, consider using the $select filter to return additional fields that provide more differentiation and context.

サービス要求には HTTPS が必要です。HTTPS is required for service requests. 提案 要求は、GET メソッドまたは POST メソッドを使用して作成できます。The Suggest request can be constructed using the GET or POST methods.

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

検索ドキュメントの要求とは異なり、候補の呼び出しをキーボード入力にバインドし、検索呼び出しをクリックイベントにバインドすることができます。In contrast with a Search Documents request, you might bind a Suggestions call to keyboard input, whereas a Search call might be bound to a click event.

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.
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 queries, 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. Suggestions 操作の場合、以下が含まれます。For Suggestions operations, this includes:

  • searchsearch
  • $filter$filter
  • 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 calling Suggestions using POST, or when using the Azure Cognitive Search .NET client library handles URL encoding for you.

要求ヘッダーRequest Headers

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

フィールドFields 説明Description
Content-TypeContent-Type 必須です。Required. これを application/jsonSet this to application/json
api-keyapi-key 必須です。Required. api-key は Search サービスに対する要求の認証に使用されます。The api-key is used to authenticate the request to your Search service. これはサービス URL に固有の文字列値です。It is a string value, unique to your service URL. コレクションに対するクエリ要求 docs では、管理者キーまたはクエリキーのいずれかをとして指定でき api-key ます。Query requests against the docs collection can specify either an admin-key or query-key as the api-key. クエリ キーは、クエリのみの操作に使用されます。The query-key is used for query-only operations.

Api キーの値は、Azure portal のサービスダッシュボードから取得できます。You can get the api-key value from your service dashboard in the Azure portal. 詳細については、「 既存のキーを検索する」を参照してください。For more information, see Find existing keys.

要求本文Request Body

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

POST の場合:For POST:

{  
      "filter": "odata_filter_expression",  
      "fuzzy": true | false (default),  
      "highlightPreTag": "pre_tag",  
      "highlightPostTag": "post_tag",  
      "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),  
      "orderby": "orderby_expression",  
      "search": "partial_search_input",  
      "searchFields": "field_name_1, field_name_2, ...",  
      "select": "field_name_1, field_name_2, ...",  
      "suggesterName": "suggester_name",  
      "top": # (default 5)  
    }  

クエリ パラメーター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. この操作の場合、api バージョンは GET または POST のどちらを使用して API を呼び出すかに関係なく、URL のクエリパラメーターとして指定されます。For this operation, the api-version is specified as a query parameter in the URL regardless of whether you call the API with GET or POST.
$filter$filter stringstring 省略可能。Optional. 検索候補と見なされるドキュメントをフィルター処理する式。An expression that filters the documents considered for suggestions. フィルターで使用できるのは、フィルター可能なフィールドのみです。Only filterable fields can be used in a filter. フィルター式 "ismatch" と "search. ismatchscoring *" は、Autocomplete API ではサポートされていません。Filter expressions "search.ismatch" and "search.ismatchscoring*" are not supported in the Autocomplete API. POST で呼び出された場合、このパラメーターは $filter ではなく filter という名前になります。When called 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.
あいまい一致fuzzy booleanboolean 任意。Optional. 既定値は false です。Defaults to false. True に設定すると、検索テキストに置換文字または見つからない文字がある場合でも、この API によって候補が検索されます。When set to true, this API finds suggestions even if there is a substituted or missing character in the search text. 編集距離はクエリ文字列ごとに1です。The edit distance is 1 per query string. クエリ文字列が複数の用語である場合は、文字列全体に1つの不足、余分、置換、または転置文字を使用できます。If the query string is multiple terms, there can only be one missing, extra, substituted, or transposed character in the entire string. あいまい一致を有効にすると、一部のシナリオではより優れたエクスペリエンスを実現できます。あいまい一致候補の検索が遅くなり、リソースが消費されるため、パフォーマンスが低下します。Enabling fuzzy match can be a better experience in some scenarios, it does come at a performance cost, as fuzzy suggestion searches are slower and consume more resources.
highlightPostTaghighlightPostTag stringstring 省略可能。Optional. 空の文字列を既定値に設定します。Defaults to an empty string. 強調表示された語句に追加する文字列タグ。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 #). GET を使用して呼び出された場合、URL の予約文字はパーセントでエンコードする必要があります (たとえば、# ではなく %23)。When called using GET, the reserved characters in the URL must be percent-encoded (for example, %23 instead of #).
highlightPreTaghighlightPreTag stringstring 省略可能。Optional. 空の文字列を既定値に設定します。Defaults to an empty string. 強調表示された語句の前に付加する文字列タグ。A string tag that prepends to the highlighted term. HighlightPostTag を使用して設定する必要があります。Must be set with highlightPostTag. GET を使用して呼び出された場合、URL の予約文字はパーセントでエンコードする必要があります (たとえば、# ではなく %23)。When called using GET, the reserved characters in the URL must be percent-encoded (for example, %23 instead of #).
$orderby$orderby stringstring 省略可能。Optional. 結果を並べ替える式の一覧で、コンマで区切ります。A list of comma-separated expressions to sort the results by. 各式は、フィールド名または 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" (ascending) or "desc" (descending). 既定値は昇順です。The default is ascending order. $Orderby には、32の句の制限があります。There is a limit of 32 clauses for $orderby. POST で呼び出された場合、このパラメーターは $orderby ではなく order という名前になります。When called with POST, this parameter is named order instead of $orderby.
minimumCoverageminimumCoverage 整数 (integer)integer 省略可能。Optional. 既定値は80です。Defaults to 80. クエリが成功として報告される前に、クエリの処理に使用できる必要があるインデックスの割合を示す 0 ~ 100 の数値。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.

既定値は、全カバレッジの速度と効率に対する時差を反映します。The default reflects a bias towards speed and efficiency over full coverage. カバレッジを減らすことで、クエリの拡張が制限され、結果を迅速に返すことができます。Reducing coverage constrains query expansion, allowing results to come back faster. また、サービスの正常性の問題やインデックスのメンテナンスのために1つのシャードの応答が遅くなったり、利用できなくなったりした場合でも、一部のインデックスの可用性でクエリを成功させることができます。It also allows the query to succeed on partial index availability, even if one shard is slow to respond or unavailable due to service health issues or index maintenance.

MinimumCoverage の値にかかわらず、インデックスの割合が使用可能である必要があるか、または提案が HTTP 状態コード503を返します。Whatever the value of minimumCoverage, that percentage of the index must be available or Suggestions returns HTTP status code 503. 推奨事項が minimumCoverage レベルで成功した場合、HTTP 200 を返し、 @search.coverage クエリを処理するときに使用できるインデックスの割合を示す値を応答に含めます。If Suggestions succeed at the minimumCoverage level, it returns HTTP 200 and includes a @search.coverage value in the response indicating the percentage of the index that was available when servicing the query.

503エラーが発生している場合は、この値を小さくすると役立つことがあります。Lowering this value might be helpful if 503 errors are occurring. それ以外の場合は、応答が不十分な一致を提供する場合に、値を上げることを検討してください。Otherwise, you might consider raising the value if the response is providing insufficient matches.
searchsearch stringstring 必須。Required. 検索するテキストです。The text to search for. 完了する検索テキスト。The search text to complete. 1 文字以上 100 文字以下で指定する必要があります。Must be at least 1 character, and no more than 100 characters. 演算子、クエリ構文、引用符で囲まれた語句を含めることはできません。It cannot contain operators, query syntax, or quoted phrases.
searchsearch stringstring 必須。Required. クエリの候補を示すために使用する検索テキスト。The search text to use to suggest queries. 1 文字以上 100 文字以下で指定する必要があります。Must be at least 1 character, and no more than 100 characters. 演算子、クエリ構文、引用符で囲まれた語句を含めることはできません。It cannot contain operators, query syntax, or quoted phrases.
searchFieldssearchFields stringstring 省略可能。Optional. 指定された検索テキストを検索するための、コンマ区切りのフィールド名の一覧。The list of comma-separated field names to search for the specified search text. ターゲットフィールドは、インデックスの サジェスター 定義に一覧表示されている必要があります。Target fields must be listed in the Suggesters definition in the index.
$select$select stringstring 省略可能。Optional. 取得するフィールドの一覧で、コンマで区切ります。A list of comma-separated fields to retrieve. 指定されていない場合は、ドキュメントのキーと候補のテキストだけが返されます。If unspecified, only the document key and suggestion text are returned. このパラメーターを *に設定することによって、明示的にすべてのフィールドを要求することができます。You can explicitly request all fields by setting this parameter to *. POST を使用してを呼び出す場合、このパラメーターには $select ではなく select という名前が付けられます。When calling with POST, this parameter is named select instead of $select.
suggesterNamesuggesterName stringstring 必須。Required. インデックス定義の一部である サジェスター コレクションで指定されている suggester の名前。The name of the suggester as specified in the Suggesters collection that's part of the index definition. Suggester は、推奨されるクエリ用語に対してスキャンされるフィールドを決定します。A suggester determines which fields are scanned for suggested query terms.
$top$top 整数 (integer)integer 省略可能。Optional. 既定値は 5) です。Defaults to 5). 取得する autocompleted の候補の数。The number of autocompleted suggestions to retrieve. 値は 1 ~ 100 の数値である必要があります。The value must be a number between 1 and 100. POST を使用してを呼び出す場合、このパラメーターには $top ではなく、top という名前が付けられます。When calling with POST, this parameter is named top instead of $top.

ResponseResponse

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

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
    },  
    ...  
  ]  
}  

予測オプションを使用してフィールドを取得する場合、フィールドは配列の各要素に含まれます。If the projection option is used to retrieve fields, they are included in each element of the array:

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}  

Examples

部分的な検索条件が "lux" の場合に、5 つの検索候補を取得します。Retrieve 5 suggestions where the partial search input is 'lux':

GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30 
POST /indexes/hotels/docs/suggest?api-version=2020-06-30 
    {  
      "search": "lux",  
      "top": 5,  
      "suggesterName": "sg"  
    }  

提案操作には suggesterName が必要であることに注意してください。Notice that suggesterName is required in a Suggestions operation.

関連項目See also