Compartilhar via

Documents - Suggest Post

Serviço:
Search Service
Versão da API:
2025-09-01

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

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

Parâmetros de URI

Nome Em Obrigatório Tipo Description
endpoint
 path True

string

A URL do ponto de extremidade do serviço de pesquisa.
indexName
 path True

string

O nome do índice.
api-version
 query True

string

Versão da API do cliente.

Cabeçalho da solicitação

Nome Obrigatório Tipo Description
x-ms-client-request-id

string (uuid)

O ID de rastreamento enviado com a solicitação para ajudar na depuraçã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 que 100 caracteres.
suggesterName True

string

O nome do sugestor, conforme especificado na coleção de sugestores que faz parte da definição do í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 tag de string anexada aos destaques da ocorrência. Deve ser definido com highlightPreTag. Se omitido, o realce de sugestões é desativado.
highlightPreTag

string

Uma tag de string que é anexada para atingir os destaques. 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 da 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 é ordem crescente. Os empates serão desfeitos pelas pontuações dos documentos da partida. 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

Resposta contendo documentos sugeridos que correspondem à entrada parcial.
Other Status Codes

ErrorResponse

Resposta de erro.

Exemplos

SearchIndexSuggestDocumentsPost

Solicitação de exemplo

POST https://stableexampleservice.search.windows.net/indexes('stable-test')/docs/search.post.suggest?api-version=2025-09-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
ErrorAdditionalInfo

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

O detalhe do erro.
ErrorResponse

Resposta de erro
SuggestDocumentsResult

Resposta contendo resultados de 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.

ErrorAdditionalInfo

Objeto

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

Nome Tipo Description
info

object

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 de erro

Nome Tipo Description
error

ErrorDetail

O objeto de erro.

SuggestDocumentsResult

Objeto

Resposta contendo resultados de 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 tag de string anexada aos destaques da ocorrência. Deve ser definido com highlightPreTag. Se omitido, o realce de sugestões é desativado.
highlightPreTag

string

Uma tag de string que é anexada para atingir os destaques. 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 da 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 é ordem crescente. Os empates serão desfeitos pelas pontuações dos documentos da partida. 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 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 do í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.