Documents - Suggest Post

Serviço:: Search Service

Versão da API:: 2026-04-01

Sugere documentos no índice que correspondem ao texto de consulta parcial fornecido.

POST {endpoint}/indexes('{indexName}')/docs/search.post.suggest?api-version=2026-04-01

Parâmetros de URI

Nome	Em	Obrigatório	Tipo	Description
endpoint	path	True	string (uri)	A URL do ponto de extremidade do serviço de pesquisa.
indexName	path	True	string	O nome do índice.
api-version	query	True	string minLength: 1	A versão da API a ser usada para esta operação.

Cabeçalho da solicitação

Nome	Obrigatório	Tipo	Description
Accept		Accept	O cabeçalho Aceitar.
x-ms-client-request-id		string (uuid)	Um identificador de cadeia de caracteres opaco, globalmente exclusivo e gerado pelo cliente para a solicitação.

Corpo da solicitação

Nome	Obrigatório	Tipo	Description
search	True	string	O texto de pesquisa a ser usado para sugerir documentos. Deve ter pelo menos 1 caractere e não mais do que 100 caracteres.
suggesterName	True	string	O nome do sugestor conforme especificado na coleção de sugestores que faz parte da definição de índice.
filter		string	Uma expressão OData que filtra os documentos considerados para sugestões.
fuzzy		boolean	Um valor que indica se a correspondência difusa deve ser usada para a consulta de sugestão. O padrão é false. Quando definida como true, a consulta encontrará sugestões mesmo que haja um caractere substituído ou ausente no texto da pesquisa. Embora isso forneça uma experiência melhor em alguns cenários, ele tem um custo de desempenho, pois as pesquisas de sugestões difusas são mais lentas e consomem mais recursos.
highlightPostTag		string	Uma marca de cadeia de caracteres que é acrescentada a realces de clique. Deve ser definido com highlightPreTag. Se omitido, o realce de sugestões é desativado.
highlightPreTag		string	Uma marca de cadeia de caracteres que é acrescentada a realces de clique. Deve ser definido com highlightPostTag. Se omitido, o realce de sugestões é desativado.
minimumCoverage		number (double)	Um número entre 0 e 100 que indica a porcentagem do índice que deve ser coberta por uma consulta de sugestão para que a consulta seja relatada como bem-sucedida. Esse parâmetro pode ser útil para garantir a disponibilidade de pesquisa mesmo para serviços com apenas uma réplica. O padrão é 80.
orderby		string	A lista separada por vírgulas de expressões OData $orderby para classificar os resultados. Cada expressão pode ser um nome de campo ou uma chamada para as funções geo.distance() ou search.score(). Cada expressão pode ser seguida por asc para indicar crescente ou desc para indicar decrescente. O padrão é a ordem crescente. Os empates serão interrompidos pelas pontuações de correspondência de documentos. Se nenhuma $orderby for especificada, a ordem de classificação padrão será decrescente por pontuação de correspondência do documento. Pode haver no máximo 32 cláusulas $orderby.
searchFields		string	A lista separada por vírgulas de nomes de campo para pesquisar o texto de pesquisa especificado. Os campos de destino devem ser incluídos no sugestor especificado.
select		string	A lista separada por vírgulas de campos a serem recuperados. Se não for especificado, somente o campo-chave será incluído nos resultados.
top		integer (int32)	O número de sugestões a serem recuperadas. Deve ser um valor entre 1 e 100. O padrão é 5.

Respostas

Nome	Tipo	Description
200 OK	SuggestDocumentsResult	A solicitação foi bem-sucedida.
Other Status Codes	ErrorResponse	Uma resposta de erro inesperada.

Segurança

api-key

Tipo: apiKey
Em: header

OAuth2Auth

Tipo: oauth2
Flow: implicit
URL de Autorização: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Escopos

Nome	Description
https://search.azure.com/.default

Exemplos

SearchIndexSuggestDocumentsPost

Solicitação de exemplo

HTTP

POST https://exampleservice.search.windows.net/indexes('example-index')/docs/search.post.suggest?api-version=2026-04-01


{
  "filter": "ownerId eq 'sam' and id lt '15'",
  "fuzzy": true,
  "highlightPostTag": "</em>",
  "highlightPreTag": "<em>",
  "minimumCoverage": 80,
  "orderby": "id desc",
  "search": "p",
  "searchFields": "category",
  "select": "id,name,category,ownerId",
  "suggesterName": "sg",
  "top": 10
}

Resposta de exemplo

Código de status:: 200

{
  "@search.coverage": 100,
  "value": [
    {
      "@search.text": "<em>pu</em>rple",
      "id": "14",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "13",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "11",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "1",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    }
  ]
}

Definições

Nome	Description
Accept	O cabeçalho Aceitar.
ErrorAdditionalInfo	As informações adicionais do erro de gerenciamento de recursos.
ErrorDetail	O detalhe do erro.
ErrorResponse	Resposta comum de erro para todas as APIs do Azure Resource Manager devolver detalhes de erro em operações falhadas. (Isso também segue o formato de resposta de erro OData.).
SuggestDocumentsResult	Resposta que contém os resultados da consulta de sugestão de um índice.
SuggestRequest	Parâmetros para filtragem, classificação, correspondência difusa e outros comportamentos de consulta de sugestões.
SuggestResult	Um resultado que contém um documento encontrado por uma consulta de sugestão, além de metadados associados.

Accept

Enumeração

O cabeçalho Aceitar.

Valor	Description
application/json;odata.metadata=none

ErrorAdditionalInfo

Objeto

As informações adicionais do erro de gerenciamento de recursos.

Nome	Tipo	Description
info		As informações adicionais.
type	string	O tipo de informação adicional.

ErrorDetail

Objeto

O detalhe do erro.

Nome	Tipo	Description
additionalInfo	ErrorAdditionalInfo[]	As informações adicionais do erro.
code	string	O código de erro.
details	ErrorDetail[]	Os detalhes do erro.
message	string	A mensagem de erro.
target	string	O destino do erro.

ErrorResponse

Objeto

Resposta comum de erro para todas as APIs do Azure Resource Manager devolver detalhes de erro em operações falhadas. (Isso também segue o formato de resposta de erro OData.).

Nome	Tipo	Description
error	ErrorDetail	O objeto de erro.

SuggestDocumentsResult

Objeto

Resposta que contém os resultados da consulta de sugestão de um índice.

Nome	Tipo	Description
@search.coverage	number (double)	Um valor que indica a porcentagem do índice que foi incluído na consulta ou null se minimumCoverage não tiver sido definido na solicitação.
value	SuggestResult[]	A sequência de resultados retornados pela consulta.

SuggestRequest

Objeto

Parâmetros para filtragem, classificação, correspondência difusa e outros comportamentos de consulta de sugestões.

Nome	Tipo	Description
filter	string	Uma expressão OData que filtra os documentos considerados para sugestões.
fuzzy	boolean	Um valor que indica se a correspondência difusa deve ser usada para a consulta de sugestão. O padrão é false. Quando definida como true, a consulta encontrará sugestões mesmo que haja um caractere substituído ou ausente no texto da pesquisa. Embora isso forneça uma experiência melhor em alguns cenários, ele tem um custo de desempenho, pois as pesquisas de sugestões difusas são mais lentas e consomem mais recursos.
highlightPostTag	string	Uma marca de cadeia de caracteres que é acrescentada a realces de clique. Deve ser definido com highlightPreTag. Se omitido, o realce de sugestões é desativado.
highlightPreTag	string	Uma marca de cadeia de caracteres que é acrescentada a realces de clique. Deve ser definido com highlightPostTag. Se omitido, o realce de sugestões é desativado.
minimumCoverage	number (double)	Um número entre 0 e 100 que indica a porcentagem do índice que deve ser coberta por uma consulta de sugestão para que a consulta seja relatada como bem-sucedida. Esse parâmetro pode ser útil para garantir a disponibilidade de pesquisa mesmo para serviços com apenas uma réplica. O padrão é 80.
orderby	string	A lista separada por vírgulas de expressões OData $orderby para classificar os resultados. Cada expressão pode ser um nome de campo ou uma chamada para as funções geo.distance() ou search.score(). Cada expressão pode ser seguida por asc para indicar crescente ou desc para indicar decrescente. O padrão é a ordem crescente. Os empates serão interrompidos pelas pontuações de correspondência de documentos. Se nenhuma $orderby for especificada, a ordem de classificação padrão será decrescente por pontuação de correspondência do documento. Pode haver no máximo 32 cláusulas $orderby.
search	string	O texto de pesquisa a ser usado para sugerir documentos. Deve ter pelo menos 1 caractere e não mais do que 100 caracteres.
searchFields	string	A lista separada por vírgulas de nomes de campo para pesquisar o texto de pesquisa especificado. Os campos de destino devem ser incluídos no sugestor especificado.
select	string	A lista separada por vírgulas de campos a serem recuperados. Se não for especificado, somente o campo-chave será incluído nos resultados.
suggesterName	string	O nome do sugestor conforme especificado na coleção de sugestores que faz parte da definição de índice.
top	integer (int32)	O número de sugestões a serem recuperadas. Deve ser um valor entre 1 e 100. O padrão é 5.

SuggestResult

Objeto

Um resultado que contém um documento encontrado por uma consulta de sugestão, além de metadados associados.

Nome	Tipo	Description
@search.text	string	O texto do resultado da sugestão.