Web Search Referência da API REST

Ponto final:POST https://api.microsoft.ai/v3/search/web

Pedido de Exemplo:

curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "latest trends in LLM RAG",
    "maxResults": 10,
    "language": "en",
    "region": "US",
    "maxLength": 3000,
    "contentFormat": "passage"
  }'

Parameters

Parameter Required Tipo Default Description
consulta Yes cadeia (de caracteres) - Uma cadeia de consulta de pesquisa. O comprimento máximo é de 1000 caracteres. Suporta operadores "site:" e "-site:" para incluir ou excluir resultados de sites específicos (por exemplo, "query site:example.com"). Use estes operadores apenas quando necessário, pois reduzem inerentemente a relevância dos resultados.
maxResultados No número inteiro 10 Número máximo de resultados a devolver. O valor padrão é 10 e o valor máximo é 50.
linguagem No cadeia (de caracteres) "en" Um código de língua ISO 639-1 de 2 letras para a linguagem de interface nos resultados de pesquisa. Consulte Linguagens Suportadas para a lista completa.
região No cadeia (de caracteres) "US" Um código de país/região de 2 letras para indicar de onde devem vir os resultados (por exemplo, "EUA", "JP", "GB", etc.). Consulte Regiões Suportadas para a lista completa.
localização No cadeia (de caracteres) - Informação de localização no formato "lat:<float>; long:<float>", por exemplo, "lat:40.753250; long:-74.003807". Se não especificado, a localização na consulta seria inferida.
contentFormat No cadeia (de caracteres) "passage" ("html" com acesso completo ao documento) passage devolve as partes de cada resultado mais relevantes para a consulta (recomendado para aterramento). text, html e markdown devolver o documento completo e aplicar-se apenas a aplicações com acesso completo ao documento; ver Passagens e formatos de conteúdo. Define-o em todos os pedidos. Nota: a API web não devolve um snippet campo.
comprimento máximo No número inteiro 3000 (10000 com acesso completo ao documento) Número máximo de caracteres por content resultado, de 1 a 500000. Sem acesso completo a documentos, content são no máximo 3000 caracteres. Veja Padrões e limites. Define-o em todos os pedidos.
safeSearch No cadeia (de caracteres) "Rigoroso" Nível de filtragem segura na pesquisa. Valores: "off", "strict". O padrão é "estrito".

Formatos de conteúdo

Define contentFormat = passage para obter as partes de cada resultado mais relevantes para a consulta, até maxLength caracteres (3000 é um bom ponto de partida). É o formato recomendado para aterramento; veja O que é passage, e por que usá-lo? na FAQ. Aplicações com acesso total a documentos também podem solicitar o documento completo como text, html ou markdown; para outras aplicações, esses formatos retornam HTTP 403. Ver Passagens e formatos de conteúdo.

Pesquisa Segura

Os modos SafeSearch permitem-lhe controlar quanto conteúdo web sensível a Web API filtra antes de os resultados serem devolvidos. Conteúdos sensíveis incluem violência, auto-mutilação e outras categorias. O valor predefinido é strict.

Value Description Recomendado para
strict Bloqueia conteúdos relacionados com adultos, picantes, violência, ódio e autoagressão. Segurança para crianças, educação, implementações para consumidores/conservadores.
off Continua a bloquear conteúdos ilegais. Para outros conteúdos potencialmente prejudiciais, a responsabilidade pelo filtro final é transferida para o utilizador. Investigação, análise, participação voluntária em empresas, casos de uso avançados em 3P.

Note

Se usar o operador de site: consulta, a resposta pode conter conteúdo adulto independentemente do safeSearch valor. Use site: apenas se tiver conhecimento do conteúdo do site e o seu cenário apoiar a possibilidade de conteúdo adulto.

Cabeçalhos dos Pedidos

Field Tipo Description
alojar cadeia (de caracteres) Alojamento para APIs de IA da Microsoft: api.microsoft.ai.
x-apikey ou Autorização cadeia (de caracteres) A sua chave API ou token de acesso do Entra ID para autenticação.
tipo de conteúdo cadeia (de caracteres) Tipo MIME do corpo do pedido. Utilize application/json.

Resposta

Web Response

Field Tipo Description
webResultados array de webResult Lista de resultados da página web.
QuerySignals QuerySignals O ranking ao nível da consulta indica a consulta de pesquisa.
Nível de risco cadeia (de caracteres) O nível de risco de segurança avaliado para a consulta. Valores possíveis: low, moderate, high, veryHigh.
instrumentaçãoClickBase cadeia (de caracteres) URL base para pedidos de ping de clique. Adicione um instrumentationSuffix valor a partir de um item de resultado para formar o URL completo do ping. Está presente apenas para aplicações com a flag de perfil EnableInstrumentationPing. Nota: Os cliques do utilizador também podem ser registados usando redirecionamento de URL. Quando o redirecionamento está ativado, não é necessária qualquer ação para registar os cliques do Utilizador, e instrumentationClickBase não será incluído na resposta. Consulte o guia de instrumentação para instruções de configuração.
instrumentaçãoCitaçãoBase cadeia (de caracteres) URL base para pedidos de ping de registo LLM. Adicione um payload DATA para formar o URL completo do ping. Está presente apenas para aplicações com a flag de perfil EnableInstrumentationPing.
traceId cadeia (de caracteres) ID de rastreio para depuração.

QuerySignals

Field Tipo Description
freshness boolean Indica se documentos novos devem ser priorizados em relação a outros documentos para esta consulta.

webResult

Field Tipo Description
title cadeia (de caracteres) O título da página web.
url cadeia (de caracteres) A URL de origem da página web. Para utilizadores da China com redirecionamento de URL ativada, este campo contém o mesmo URL de redirecionamento que clickUrl.
domínio cadeia (de caracteres) O anfitrião de destino para o resultado. Devolvido apenas para utilizadores chineses com redirecionamento de URL ativado.
conteúdo cadeia (de caracteres) O conteúdo detalhado (também conhecido como fundamento) da página web.
rastejou cadeia (de caracteres) A última data rastreada da página web segue ISO8601 formato.
lastUpdatedAt cadeia (de caracteres) A data de última atualização da página segue ISO8601 formato.
linguagem cadeia (de caracteres) A linguagem da página web utiliza o código da língua ISO 639-1.
éAdulto boolean Indica se o resultado inclui conteúdo para adultos.
clickUrl cadeia (de caracteres) URL de redirecionamento que proxie o clique através do Bing. Só está presente quando o redirecionamento por clique está ativado.
InstrumentaçãoSufixo cadeia (de caracteres) Sufixo para anexar à base de URL de ping da instrumentação para este item de resultado. Usado como valor K tanto para o ping URL da instrumentação como para o clickUrl redirecionamento. Presente quando o ping de instrumentação estiver ativado.
contentTier cadeia (de caracteres) O nível de conteúdo do resultado, que descreve as características de acesso comercial da fonte de conteúdo. Valores possíveis: standard (conteúdo padrão disponível para todos os clientes sob a oferta de serviço padrão), entitled (conteúdo disponível através de acordos de licenciamento existentes para clientes, incluindo conteúdo Bring Your Own License (BYOL) que os clientes licenciaram diretamente dos editores e acedem através dos seus próprios acordos contratuais), premium (conteúdo premium que oferece valor adicional para além da oferta padrão e está sujeito a faturação).

Note

Os valores dos campos e crawledAtlastUpdatedAt são opcionais. Ou seja, a cobertura deles não é de 100%. Pode ver valores vazios para estes campos.

Códigos de erro

Código de estado Categoria de Erro Description Causas Comuns
200 Sucesso O pedido foi bem-sucedido. -
400 Pedido Incorreto Parâmetros de pedido inválidos. Campos obrigatórios em falta, valores de parâmetros inválidos, JSON mal formado
401 Não autorizado Autenticação falhada ou em falta. Chave API inválida, falta do cabeçalho x-apikey
403 Proibido Credenciais válidas mas permissões insuficientes. A chave API não tem as permissões necessárias
410 Desapareceu HTTPS necessário. Pedido feito por HTTP em vez de HTTPS
415 Tipo de Media Não Suportado Tipo de conteúdo não suportado. Cabeçalho de tipo de conteúdo em falta ou incorreto
429 Demasiados Pedidos Limite de taxa ultrapassado. Demasiados pedidos numa janela temporal
500 Erro interno do servidor Erro inesperado do servidor. Problema temporário com o servidor
503 Serviço Indisponível Serviço temporariamente indisponível. Manutenção ou interrupção temporária
504 Tempo limite do gateway O tempo limite da solicitação expirou. Tempo de extinção do serviço a montante

Para orientações detalhadas sobre o tratamento de erros, consulte Gestão de Erros.

Ver também:Vídeos Pesquisa | Navegar | por Notícias Pesquisa | Imagens Pesquisar | MCP

  • Última atualização a