Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Note
Auto e Auto Advanced estão geralmente disponíveis para todos os AppID Web IQ a partir de 17 de novembro de 2026. AppIDs sem acesso completo a documentos obtêm passages.
Ponto final:POST https://api.microsoft.ai/v3/auto
Todos os pedidos requerem uma chave API ou token de acesso Microsoft Entra ID. Consulte Autenticação para instruções de configuração.
Pedido de amostra
curl -X POST "https://api.microsoft.ai/v3/auto" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"query": "Microsoft AI announcements",
"language": "en",
"region": "US",
"location": "lat:47.6062;long:-122.3321",
"mode": "lite",
"maxResponseLength": 30000,
"maxCitations": 10,
"responseFilter": ["web", "news"]
}'
Exemplo de pedido com âmbito
Para filtrar a recuperação Web e de Notícias em Auto usando um âmbito nomeado (ver Filtrar resultados com Escopos), inclua scopeName e failOnMissingScope:
curl -X POST "https://api.microsoft.ai/v3/auto" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"query": "product setup guide",
"scopeName": "ProductDocs",
"failOnMissingScope": true,
"mode": "lite",
"responseFilter": ["web", "news"]
}'
Parameters
| Parameter | Required | Tipo | Default | Description |
|---|---|---|---|---|
query |
Yes | cadeia (de caracteres) | - | Consulta de pesquisa, de 1 a 1.000 caracteres. |
language |
No | cadeia (de caracteres) | en |
Linguagem de interface ISO 639-1 de duas letras. |
region |
No | cadeia (de caracteres) | US |
Código de mercado ou país/região de duas letras. |
mode |
No | cadeia (de caracteres) | lite |
lite prioriza a velocidade; advanced prioriza a abrangência. |
maxResponseLength |
No | número inteiro | 30000 | Comprimento máximo do conteúdo para resultados web, não o comprimento total da resposta. Valores abaixo de 1500 são fixados em 1500; valores acima de 500000 são fixados em 500000. Para AppIDs sem acesso total a documentos, o máximo é 30000. |
maxCitations |
No | número inteiro | 10 | Número máximo de citações web a solicitar, de 1 a 50. Valores abaixo de 1 são fixados a 1; valores acima de 50 são limitados a 50. |
location |
No | cadeia (de caracteres) | - | Contexto geográfico no lat:<latitude>;long:<longitude> formato, por lat:47.6062;long:-122.3321exemplo. |
responseFilter |
No | matriz de strings | - | Tipos de resposta elegíveis: web, news, timezone, weather, images, . videos |
includeSites |
No | matriz de strings | - | Restringe resultados Web elegíveis a estes sites (domínios com caminhos opcionais), com no máximo 250 entradas. Notícias e outros tipos de respostas não são filtrados. Mantenha a lista curta e relevante para melhores resultados. Os caminhos suportam até dois segmentos; os caminhos mais profundos são truncados, pelo que example.com/a/b/c é tratado como example.com/a/b. |
excludeSites |
No | matriz de strings | - | Omite resultados Web destes sites (domínios com caminhos opcionais), com no máximo 250 entradas e as mesmas regras de caminho que includeSites. Se um site aparecer em ambas as listas, está excluído. Notícias e outros tipos de respostas não são filtrados. |
scopeName |
No | cadeia (de caracteres) | - | Um âmbito nomeado da coleção atribuída à conta de faturação do AppID Web IQ selecionado. Use 1-128 letras ASCII, dígitos, ., _, ou -, sem espaço em branco. Para Auto, os sensores restringem apenas resultados Web e Notícias. Outros tipos de resposta não são filtrados pelo âmbito e podem conter resultados fora dele, mesmo quando scopeApplied é true. Omitido ou null significa que não é solicitado nenhum âmbito nomeado.
Veja Resultados do Filtro com Oscilos. |
failOnMissingScope |
No | boolean | true |
Controla o recuo para scopeName; omitido ou null significa true. Se o serviço reportar que o scope não pôde ser aplicado, true devolve HTTP 400 (HandlerInvalidInput) para um scope confirmado em falta, ou HTTP 500 (ScopeFailedToApply) para outras falhas de escopo.
false permite a pesquisa sem o escopo, com scopeApplied: false quando esse resultado é reportado. Um âmbito válido é aplicado com qualquer um dos valores; resultados de zero correspondência não são uma falha do escopo. Não tem efeito sem uma mira nomeada. Ver Erros de âmbito nomeado. |
Resposta
Uma resposta bem-sucedida à evidência retorna 200 OK. Cada resultado contém um objeto de evidência tipado e as citações que o apoiam. Provas não fundamentadas ou deformadas são omitidas juntamente com as suas citações. Se todos os resultados de evidência fornecidos forem omitidos, results é vazio.
AutoEvidênciaResposta
| Field | Tipo | Description |
|---|---|---|
results |
array de AutoEvidenceResult | Itens de evidência, acompanhados de citações, ajustados a esse resultado. |
querySignals |
QuerySignals | O ranking ao nível da consulta indica a consulta de pesquisa. |
scopeApplied |
Booleano (opcional) |
true significa que o âmbito solicitado foi aplicado, não necessariamente a sua definição mais recente.
false significa que o âmbito não foi aplicado; failOnMissingScope: false permite esta resposta sem âmbito definido. É omitido quando o serviço não reporta o resultado da candidatura. Sem scopeName, não é solicitado nenhum âmbito nomeado; não assuma que o campo está presente ou sempre false. Descreve o pedido atual, não a propagação global. |
traceId |
cadeia (de caracteres) | ID de correlação para depuração e suporte. |
QuerySignals
| Field | Tipo | Description |
|---|---|---|
freshness |
boolean | Indica se documentos novos devem ser priorizados em relação a outros documentos para esta consulta. |
AutoEvidenceResult
| Field | Tipo | Description |
|---|---|---|
evidence |
AutoEvidência | Evidência datilografada gerada. |
citations |
array de AutoEvidenceCitation | Citações que apoiam apenas esta evidência resultam. |
AutoEvidência
O próprio type discriminador do objeto de evidência seleciona o esquema de content. Use o índice de tipos de evidência para encontrar a definição correspondente.
| Field | Tipo | Description |
|---|---|---|
type |
cadeia (de caracteres) | O discriminador identifica o esquema das provas. Os valores são sensíveis a maiúsculas minúsculas, por structured/timeZoneexemplo. |
content |
string ou objeto | Texto ou conteúdo estruturado cuja forma depende de type. |
AutoEvidênciaCitação
Os campos de citação variam consoante o tipo de resposta e os metadados de origem disponíveis. Nem todos os campos estão presentes em todas as citações.
| Field | Tipo | Description |
|---|---|---|
contentSource |
cadeia (de caracteres) | Fonte da citação. |
source |
cadeia (de caracteres) | Nome do site citado. |
siteIcon |
cadeia (de caracteres) | URL do ícone do site citado. |
title |
cadeia (de caracteres) | Título da citação. |
url |
cadeia (de caracteres) | URL de citação. |
publishedBy |
cadeia (de caracteres) | Publisher do conteúdo citado. |
hostPageUrl |
cadeia (de caracteres) | URL da página que aloja o conteúdo citado. |
lastUpdatedAt |
cadeia (de caracteres) | Carimbo temporal da última atualização. |
crawledAt |
cadeia (de caracteres) | Carimbo temporal do crawl. |
language |
cadeia (de caracteres) | Linguagem de conteúdo. |
isAdult |
boolean | Se a citação contém conteúdo para adultos. Devolvido explicitamente quando true; trata um campo omitido como false. |
As citações específicas da resposta podem também incluir os seguintes metadados:
| Field | Tipo | Aplica-se a | Description |
|---|---|---|---|
observedAt |
cadeia (de caracteres) | Weather | Carimbo temporal da observação fornecido pela fonte da citação. |
Resposta de exemplo
{
"results": [
{
"evidence": {
"type": "text",
"content": "Microsoft announced a new set of AI capabilities."
},
"citations": [
{
"contentSource": "web",
"url": "https://www.microsoft.com/en-us/ai",
"title": "Microsoft AI",
"language": "en"
}
]
}
],
"querySignals": { "freshness": true },
"traceId": "00000000000000000000000000000000"
}
Neste exemplo, isAdult é omitido, pelo que os clientes devem tratá-lo como false.
Tipos de provas
Use este índice para consultar o esquema de content um objeto de evidência. As categorias de resposta nos pedidos responseFilter não são as mesmas que discriminadores de evidências na resposta: por exemplo, timezone os pedidos respondem em fuso horário, enquanto o tipo de evidência devolvido é structured/timeZone.
| Categoria de resposta | Evidências type |
Definição de conteúdo |
|---|---|---|
web |
text |
Evidência de texto: conteúdo em cadeias. |
news |
text/news |
Prova de texto: conteúdo em cadeia com uma miniatura opcional. |
images |
media/image |
Evidência da imagem: dimensões da imagem, legenda e miniatura. |
videos |
media/video |
Provas em vídeo: metadados de reprodução, miniatura e momentos opcionais. |
weather |
structured/weather |
Objeto meteorológico: condições, previsões, alertas e dados de luz solar. |
timezone |
structured/timeZone |
Objeto de fuso horário: horas locais, deslocamentos UTC e comparações. |
As definições abaixo descrevem áreas públicas. Os campos podem ser omitidos quando não estão disponíveis; um campo omitido não implica uma medição de zero ou uma resposta vazia. Os metadados de origem e a atribuição pertencem às citações do resultado anexo, em vez de um envelope de resposta repetida em cada definição.
Os exemplos são fragmentos ilustrativos evidence , não respostas completas. Veja a resposta de exemplo para o anexo results e citations a estrutura.
Evidência textual
Para text (Web) e text/news (Notícias), content é uma cadeia em vez de um objeto. As evidências noticiosas também podem incluir um thumbnail ao lado contentde .
| Field | Tipo | Description |
|---|---|---|
content |
cadeia (de caracteres) | Evidência por texto para o resultado. |
thumbnail |
objeto (opcional) | Miniatura de notícias com url (string), width (inteiro) e height (inteiro). As dimensões estão em píxeis. |
{
"type": "text/news",
"content": "An example news summary.",
"thumbnail": {
"url": "https://example.com/news-thumbnail.jpg",
"width": 320,
"height": 180
}
}
Evidência da imagem
Para media/image, content é um objeto imagem. A URL da imagem de origem, a URL da página de alojamento, o título e as datas de origem são fornecidos nas citações do resultado quando disponíveis.
| Campo de conteúdo | Tipo | Description |
|---|---|---|
caption |
cadeia (de caracteres) | Descrição gerada da imagem. |
width |
número inteiro | Largura da imagem em pixels. |
height |
número inteiro | Altura da imagem em pixels. |
thumbnailUrl |
cadeia (de caracteres) | URL da imagem em miniatura. |
lastUpdatedAt |
cadeia (de caracteres) | Data da fonte em formato ISO 8601, quando disponível. |
{
"type": "media/image",
"content": {
"caption": "An example city skyline.",
"width": 1920,
"height": 1080,
"thumbnailUrl": "https://example.com/skyline-thumbnail.jpg"
}
}
Evidência em vídeo
Para media/video, content é um objeto de vídeo. Detalhes da fonte, como o título do vídeo, URL, editora e data da fonte, são fornecidos nas citações do resultado quando disponíveis.
| Campo de conteúdo | Tipo | Description |
|---|---|---|
description |
cadeia (de caracteres) | Descrição do conteúdo do vídeo. |
summary |
cadeia (de caracteres) | Resumo curto ou destaque do vídeo. |
viewCount |
número inteiro | Número de visualizações de vídeo. |
length |
cadeia (de caracteres) | Duração do vídeo em HH:MM:SS formato. |
allowHttpsEmbedding |
boolean | Se a incorporação HTTPS é permitida. |
allowMobileEmbedding |
boolean | Se a incorporação móvel é permitida. |
embeddingUrl |
cadeia (de caracteres) | URL para incorporar o vídeo. |
thumbnailUrl |
cadeia (de caracteres) | URL da miniatura do vídeo. |
width |
número inteiro | Largura do vídeo em píxeis. |
height |
número inteiro | Altura do vídeo em pixels. |
lastUpdatedAt |
cadeia (de caracteres) | Data da fonte em formato ISO 8601, quando disponível. |
bestMomentIndex |
número inteiro | Índice do melhor momento ou destaque, quando disponível. |
moments |
array do VideoMoment | Segmentos de vídeo, quando disponíveis. O array pode estar vazio. |
{
"type": "media/video",
"content": {
"viewCount": 1200,
"length": "00:02:30",
"thumbnailUrl": "https://example.com/video-thumbnail.jpg",
"moments": []
}
}
VideoMoment
| Field | Tipo | Description |
|---|---|---|
title |
cadeia (de caracteres) | Título do segmento. |
description |
cadeia (de caracteres) | Descrição do segmento. |
startTime |
cadeia (de caracteres) | Hora de início do segmento no d.hh:mm:ss formato. |
endTime |
cadeia (de caracteres) | Hora de término do segmento no d.hh:mm:ss formato. |
momentUrl |
cadeia (de caracteres) | URL direto para o segmento. |
Objeto meteorológico
Quando uma consulta é sobre o tempo, o Auto pode devolver um structured/weather resultado por localização. Os campos estão incluídos quando disponíveis. Leia medições numéricas juntamente com units; não assuma um sistema de unidades fixas.
| Campo de conteúdo | Tipo | Description |
|---|---|---|
location |
cadeia (de caracteres) | Nome do local, Seattle, Washingtonpor exemplo. |
url |
cadeia (de caracteres) | URL de atribuição do tempo para a localização. A mesma URL está na citação do resultado. |
units |
objecto | Sistema unitário (system) e as unidades para temperature, speed, pressure, distance, height, e time. |
alerts |
array do WeatherAlert | Alertas meteorológicos ativos ou recentes para a localização, filtrados pelo país ou região do utilizador. |
currentWeather |
objecto | Condições atuais, incluindo condition, dayPeriod, feelsLiketemperature, , universalThermalClimateIndexhumidity, dewPoint, , pressure, , visibility, , uv, windSpeedwindDirectionwindGustuvLevelairQualitye observedAt quando disponíveis. |
forecastedWeather |
Matriz de objetos | Previsões diárias com validDate, condition, temperatureHigh, temperatureLow, feelsLikeHigh, feelsLikeLowprecipitationChancee previsões almanachumiditydaynighthourly quando disponíveis. |
sunlight |
objecto | Nascer do sol, pôr do sol, nascer da lua, pôr da lua e fase da lua para uma data específica, quando a consulta pedir uma. |
A corrente airQuality pode conter index, severity, primaryPollutant, e validAt. Uma previsão humidity diária pode conter high e low. As suas day subprevisões e night podem conter condition, precipitationChance, windSpeed, e windDirection. Contém almanac dados do sol e da lua para validDate.
{
"type": "structured/weather",
"content": {
"location": "Seattle, Washington",
"units": {
"system": "Imperial",
"temperature": "F"
},
"currentWeather": {
"condition": "Cloudy",
"temperature": 50
}
}
}
WeatherAlert
| Field | Tipo | Description |
|---|---|---|
id |
cadeia (de caracteres) | Identificador de alerta do fornecedor, quando disponível. |
name |
cadeia (de caracteres) | Nome do evento meteorológico, por Frostexemplo. |
severity |
cadeia (de caracteres) | Gravidade, por exemplo Advisory, Watch, ou Warning. |
status |
cadeia (de caracteres) | Estado de alerta, por Ongoingexemplo. |
issuingAuthority |
cadeia (de caracteres) | Organização que emitiu o alerta, por National Weather Serviceexemplo. |
url |
cadeia (de caracteres) | Ligação à autoridade emissora. Incluído quando a fonte o fornece. |
description |
cadeia (de caracteres) | Descrição do perigo e área afetada. |
safetyGuidance |
cadeia (de caracteres) | Ações de segurança recomendadas, quando disponíveis. |
issuedAt, effectiveAt, expiresAt |
cadeia (de caracteres) | Quando o alerta foi emitido, entra em vigor e expira. |
Objeto do fuso horário
Para structured/timeZone, content descreve os horários locais ou compara dois fusos horários. Uma pesquisa de localização pode devolver timeZones; uma comparação pode, em vez disso, devolver startTimeZone, endTimeZone, e timeDifference. Não exija todos estes campos em todas as respostas.
| Campo de conteúdo | Tipo | Description |
|---|---|---|
description |
cadeia (de caracteres) | Resumo da resposta legível por humanos, quando disponível. |
timeZones |
array de TimeZoneEntry | Entradas para uma resposta temporal de localização única ou múltiplas localizações. |
startTimeZone |
TimezoneEntry | Consulte o fuso horário da fonte para uma comparação. |
endTimeZone |
TimezoneEntry | Fuso horário alvo para comparação. |
timeDifference |
cadeia (de caracteres) | Descrição legível para humanos da diferença de tempo para comparação. |
{
"type": "structured/timeZone",
"content": {
"timeZones": [
{
"timeZoneName": "Pacific Standard Time",
"timeZoneAbbreviation": "PST",
"location": "Seattle, Washington",
"utcOffset": -8,
"utcTime": "Monday, 2026-11-16T05:00:00Z",
"localTime": "Sunday, 2026-11-15T21:00:00-08:00"
}
]
}
}
TimezoneEntry
| Field | Tipo | Description |
|---|---|---|
timeZoneName |
cadeia (de caracteres) | Nome do fuso horário completo. |
timeZoneAbbreviation |
cadeia (de caracteres) | Abreviatura, por exemplo PST ou IST. |
location |
cadeia (de caracteres) | Cidade, país ou região associada à entrada. |
utcOffset |
number | Offset UTC em horas. Pode ser fracionado, por exemplo 5.5, ou omitido quando não está disponível. |
utcTime |
cadeia (de caracteres) | Hora UTC como uma cadeia formatada. |
localTime |
cadeia (de caracteres) | Hora local como uma cadeia formatada. |
As cadeias de tempo podem incluir um prefixo de um dia da semana; não assumas que são carimbos de data ISO 8601 simples.
Códigos de erro
| Código de estado | Description |
|---|---|
| 200 | O pedido foi bem-sucedido, incluindo uma pesquisa válida sem resultados. |
| 400 | Parâmetros inválidos ou JSON malformado. |
| 401 | Credenciais de autenticação em falta ou inválidas. |
| 403 | O AppID Web IQ autenticado não está ativado para Auto. |
| 429 | Limite de taxa ou quota ultrapassado. |
| 500 | Falha do serviço interno. |
| 503 | Um serviço obrigatório não está disponível. |
| 504 | O pedido expirou. |
Para o esquema de erro partilhado e a orientação de retentativa, veja Gestão de erros.