Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Ponto de extremidade:POST https://api.microsoft.ai/v3/search/web
Solicitação 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
| Parâmetro | Required | Tipo | Default | Description |
|---|---|---|---|---|
| consulta | Yes | cadeia | - | Uma cadeia de caracteres de consulta de pesquisa. O comprimento máximo é de 1000 caracteres. Dá suporte a operadores "site:" e "-site:" para incluir ou excluir resultados de sites específicos (por exemplo, "consulta site:example.com"). Use esses operadores somente quando necessário, pois eles reduzem inerentemente a relevância do resultado. |
| maxResults | No | inteiro | 10 | Número máximo de resultados a serem retornados. O padrão é 10 e o valor máximo é 50. |
| linguagem | No | cadeia | "en" | Um código de idioma ISO 639-1 de 2 letras para linguagem de interface nos resultados da pesquisa. Consulte idiomas com suporte para a lista completa. |
| região | No | cadeia | "US" | Um código de país/região de duas letras de onde os resultados devem vir (por exemplo, "EUA", "JP", "GB", etc.). Consulte regiões com suporte para obter a lista completa. |
| local | No | cadeia | - | Informações de localização no formato "lat:<float>; long:<float>", por exemplo, "lat:40.753250; long:-74.003807". Se não for especificado, o local na consulta será inferido. |
| formato de conteúdo | No | cadeia | "passagem" ("html" com acesso completo ao documento) |
passage retorna as partes de cada resultado mais relevantes para a consulta (recomendado para aterramento).
texte htmlmarkdown retorne o documento completo e aplique-se somente a aplicativos com acesso completo a documentos; consulte Passagens e formatos de conteúdo. Defina-o em cada solicitação. Observação: a API Web não retorna um snippet campo. |
| comprimento máximo | No | inteiro | 3000 (10000 com acesso completo a documentos) | Máximo de caracteres content por resultado, de 1 a 500000. Sem acesso completo ao documento, content há no máximo 3.000 caracteres. Consulte Padrões e limites. Defina-o em cada solicitação. |
| safeSearch | No | cadeia | "estrito" | Nível de filtragem de pesquisa segura. Valores: "off", "strict". O padrão é "estrito". |
| scopeName | No | cadeia | - | Um escopo nomeado da coleção atribuída à conta de cobrança do IQ AppID da Web selecionada. Use 1-128 letras ASCII, dígitos, ., _ou -, sem espaço em branco. Omitido ou null significa que nenhum escopo nomeado é solicitado. Veja os resultados do filtro com escopos. |
| failOnMissingScope | No | boolean | true |
Controla o fallback para scopeName; omitido ou null significa true. Se o serviço relatar que o escopo não pôde ser aplicado, true retornará HTTP 400 (HandlerInvalidInput) para um escopo ausente confirmado ou HTTP 500 (ScopeFailedToApply) para outras falhas de escopo.
false permite a pesquisa sem o escopo, com scopeApplied: false quando esse resultado é relatado. Um escopo válido é aplicado com qualquer um dos valores; zero resultados correspondentes não são uma falha de escopo. Não tem efeito sem um escopo nomeado. Consulte erros de escopo nomeado. |
Formatos de conteúdo
Defina 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 é passagee por que usá-lo nas perguntas frequentes. Aplicativos com acesso completo a documentos também podem solicitar o documento completo como text, html ou markdown; para outros aplicativos, esses formatos retornam HTTP 403. Consulte Passagens e formatos de conteúdo.
SafeSearch
Os modos SafeSearch permitem controlar a quantidade de conteúdo confidencial da Web que a API Web filtra antes que os resultados sejam retornados. Conteúdo confidencial inclui violência, automutilação e outras categorias. O valor padrão é strict.
| Value | Description | Recomendado para |
|---|---|---|
strict |
Bloqueia o conteúdo relacionado a tópicos adultos, picantes, violentos, de ódio e de automutilação. | Implantações seguras para crianças, educação, consumidor/conservador. |
off |
Ainda bloqueia conteúdo ilegal. Para outro conteúdo potencialmente prejudicial, desloca a responsabilidade pela filtragem final para o usuário. | Pesquisa, análise, aceitação corporativa, casos avançados de uso 3P. |
Note
Se você usar o site: operador de consulta, a resposta poderá conter conteúdo adulto, independentemente do safeSearch valor. Use site: somente se você estiver ciente do conteúdo no site e seu cenário oferecer suporte à possibilidade de conteúdo adulto.
Cabeçalhos da solicitação
| Field | Tipo | Description |
|---|---|---|
| hospedar | cadeia | Host para APIs de IA Microsoft: api.microsoft.ai. |
| x-apikey ou Autorização | cadeia | Sua chave de API ou Entra ID token de acesso para autenticação. |
| tipo de conteúdo | cadeia | Tipo MIME do corpo da solicitação. Use application/json. |
Resposta
Resposta da Web
| Field | Tipo | Description |
|---|---|---|
| WebResults | matriz de webResult | Lista de resultados da página da Web. |
| querySignals | querySignals | Sinais de classificação no nível da consulta para a consulta de pesquisa. |
| scopeApplied | booliano (opcional) |
true significa que o escopo solicitado foi aplicado, não necessariamente sua definição mais recente.
false significa que o escopo não foi aplicado; failOnMissingScope: false permite essa resposta não copiada. Omitido quando o serviço não relata um resultado do aplicativo. Sem scopeName, nenhum escopo nomeado é solicitado; não suponha que o campo esteja presente ou sempre false. Descreve a solicitação atual, não a propagação global. |
| riskLevel | cadeia | O nível de risco de segurança avaliado para a consulta. Valores possíveis: low, , moderatehigh, veryHigh. |
| instrumentationClickBase | cadeia | URL base para clicar em solicitações de ping. Acrescente um instrumentationSuffix valor de um item de resultado para formar a URL de ping completa. Presente apenas para aplicativos com o sinalizador de perfil EnableInstrumentationPing. Observação: os cliques do usuário também podem ser registrados usando o redirecionamento de URL. Quando o redirecionamento estiver habilitado, nenhuma ação será necessária para registrar cliques do usuário e instrumentationClickBase não será incluída na resposta. Consulte o guia de Instrumentação para obter instruções de instalação. |
| instrumentationCitationBase | cadeia | URL base para solicitações de ping de log llm. Acrescente um conteúdo de DADOS para formar a URL de ping completa. Presente apenas para aplicativos com o sinalizador de perfil EnableInstrumentationPing. |
| traceId | cadeia | ID de rastreamento para depuração. |
querySignals
| Field | Tipo | Description |
|---|---|---|
| freshness | boolean | Indica se novos documentos devem ser priorizados em relação a outros documentos para essa consulta. |
WebResult
| Field | Tipo | Description |
|---|---|---|
| title | cadeia | O título da página da Web. |
| url | cadeia | A URL de origem da página da Web. Para usuários da China com redirecionamento de URL habilitado, esse campo contém a mesma URL de redirecionamento que clickUrl. |
| domínio | cadeia | O host de destino para o resultado. Retornado somente para usuários da China com redirecionamento de URL habilitado. |
| conteúdo | cadeia | O conteúdo detalhado (também conhecido como aterramento) da página da Web. |
| crawledAt | cadeia | A última data rastreada da página da Web segue ISO8601 formato. |
| lastUpdatedAt | cadeia | A última data atualizada da página da Web segue ISO8601 formato. |
| linguagem | cadeia | O idioma da página da Web usa o código de idioma ISO 639-1. |
| isAdult | boolean | Indica se o resultado inclui conteúdo adulto. |
| clickUrl | cadeia | URL de redirecionamento que faz o proxie do clique por meio do Bing. Só está presente quando o redirecionamento de clique está habilitado. |
| instrumentationSuffix | cadeia | Sufixo a ser acrescentado à base de URL de ping de instrumentação para este item de resultado. Usado como o valor K para a URL de ping de instrumentação e o clickUrl redirecionamento. Presente quando o ping de instrumentação estiver habilitado. |
Note
Valores e crawledAtlastUpdatedAt campos são opcionais. Ou seja, a cobertura deles não é de 100%. Você pode ver valores vazios para esses campos.
Códigos de erro
| Código de Status | Categoria do Erro | Description | Causas comuns |
|---|---|---|---|
| 200 | Êxito | O pedido foi bem-sucedido. | - |
| 400 | Solicitação incorreta | Parâmetros de solicitação inválidos. | Campos necessários ausentes, valores de parâmetro inválidos, JSON malformado |
| 401 | Unauthorized | Falha ou falha na autenticação. | Chave de API inválida, cabeçalho x-apikey ausente |
| 403 | Proibido | Credenciais válidas, mas permissões insuficientes. | A chave de API não tem permissões necessárias |
| 410 | Sumiu (Gone) | HTTPS necessário. | Solicitação feita por HTTP em vez de HTTPS |
| 415 | Tipo de mídia sem suporte | Não há suporte para o tipo de conteúdo. | Cabeçalho de tipo de conteúdo ausente ou incorreto |
| 429 | Número Excessivo de Solicitações | Limite de taxa excedido. | Muitas solicitações na janela de tempo |
| 500 | Erro interno do servidor | Erro de servidor inesperado. | Problema temporário do servidor |
| 503 | Serviço indisponível | Serviço temporariamente indisponível. | Manutenção ou interrupção temporária |
| 504 | Tempo de Espera do Gateway (Gateway Timeout) | A solicitação expirou. | Tempo limite do serviço upstream |
Para obter diretrizes detalhadas de tratamento de erros, consulte Tratamento de Erros.
Consulte também:Pesquisa de Vídeos | Procurar | Imagens dePesquisa | deNotícias Pesquisa | MCP