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.
Note
O Auto e o Auto Advanced estão disponíveis para todas as IQ AppID da Web a partir de 17 de novembro de 2026. AppIDs sem acesso completo a documentos obtêm passagens.
Ponto de extremidade:POST https://api.microsoft.ai/v3/auto
Todas as solicitações exigem uma chave de API ou um token de acesso Microsoft Entra ID. Consulte Autenticação para obter instruções de instalação.
Solicitação de exemplo
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 solicitação com escopo
Para filtrar a recuperação da Web e de notícias em Auto usando um escopo nomeado (consulte Os resultados do filtro 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
| Parâmetro | Required | Tipo | Default | Description |
|---|---|---|---|---|
query |
Yes | cadeia | - | Consulta de pesquisa, de 1 a 1.000 caracteres. |
language |
No | cadeia | en |
Linguagem de interface ISO 639-1 de duas letras. |
region |
No | cadeia | US |
Código de mercado de duas letras ou país/região. |
mode |
No | cadeia | lite |
lite prioriza a velocidade; advanced prioriza a integralidade. |
maxResponseLength |
No | inteiro | 30000 | Comprimento máximo de conteúdo para resultados da Web, não o tamanho total da resposta. Os valores abaixo de 1500 são fixados em 1500; os valores acima de 500000 são fixados em 500000. Para AppIDs sem acesso completo a documentos, o máximo é 30000. |
maxCitations |
No | inteiro | 10 | Número máximo de citações da Web a serem solicitadas, de 1 a 50. Os valores abaixo de 1 são fixados a 1; os valores acima de 50 são limitados a 50. |
location |
No | cadeia | - | Contexto geográfico em lat:<latitude>;long:<longitude> formato, por exemplo lat:47.6062;long:-122.3321. |
responseFilter |
No | Matriz de cadeias de caracteres | - | Tipos de resposta qualificados: web, , news, timezone, weather, images, videos. |
includeSites |
No | Matriz de cadeias de caracteres | - | Restringe os resultados qualificados da Web a esses sites (domínios com caminhos opcionais), com no máximo 250 entradas. As notícias e outros tipos de resposta não são filtrados. Mantenha a lista curta e relevante para obter melhores resultados. Os caminhos dão suporte a até dois segmentos; caminhos mais profundos são truncados, por isso example.com/a/b/c é tratado como example.com/a/b. |
excludeSites |
No | Matriz de cadeias de caracteres | - | Omite os resultados da Web desses 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, ele será excluído. As notícias e outros tipos de resposta não são filtrados. |
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. Para o Auto, os escopos restringem apenas os resultados da Web e do News. Outros tipos de resposta não são filtrados pelo escopo e podem conter resultados fora dele, mesmo quando scopeApplied é true. 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. |
Resposta
Uma resposta de evidência bem-sucedida retorna 200 OK. Cada resultado contém um objeto de evidência tipado e as citações que dão suporte a ele. Evidências sem suporte ou malformadas são omitidas junto com suas citações. Se cada resultado de evidência fornecido for omitido, results estará vazio.
AutoEvidenceResponse
| Field | Tipo | Description |
|---|---|---|
results |
matriz de AutoEvidenceResult | Itens de evidência emparelhados com citações com escopo para esse resultado. |
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. |
traceId |
cadeia | ID de correlação para depuração e suporte. |
QuerySignals
| Field | Tipo | Description |
|---|---|---|
freshness |
boolean | Indica se novos documentos devem ser priorizados em relação a outros documentos para essa consulta. |
AutoEvidenceResult
| Field | Tipo | Description |
|---|---|---|
evidence |
AutoEvidência | Evidência digitada gerada. |
citations |
matriz de AutoEvidenceCitation | Citações que dão suporte apenas a esse resultado de evidência. |
AutoEvidência
O próprio discriminador do objeto type de evidência seleciona o esquema de content. Use o índice de tipo de evidência para localizar a definição correspondente.
| Field | Tipo | Description |
|---|---|---|
type |
cadeia | Discriminador identificando o esquema de evidências. Os valores diferenciam maiúsculas de minúsculas, por exemplo structured/timeZone. |
content |
cadeia de caracteres ou objeto | Texto ou conteúdo estruturado cuja forma depende type. |
AutoEvidenceCitation
Os campos de citação variam de acordo com o tipo de resposta e os metadados de origem disponíveis. Nem todos os campos estão presentes em cada citação.
| Field | Tipo | Description |
|---|---|---|
contentSource |
cadeia | Fonte de citação. |
source |
cadeia | Nome do site citado. |
siteIcon |
cadeia | URL do ícone do site citado. |
title |
cadeia | Título da citação. |
url |
cadeia | URL de citação. |
publishedBy |
cadeia | Publisher do conteúdo citado. |
hostPageUrl |
cadeia | URL da página que hospeda o conteúdo citado. |
lastUpdatedAt |
cadeia | Carimbo de data/hora atualizado pela última vez. |
crawledAt |
cadeia | Carimbo de data/hora de rastreamento. |
language |
cadeia | Linguagem de conteúdo. |
isAdult |
boolean | Se a citação contém conteúdo adulto. Retornado explicitamente quando true; tratar um campo omitido como false. |
Citações específicas de resposta também podem incluir os seguintes metadados:
| Field | Tipo | Aplica-se a | Description |
|---|---|---|---|
observedAt |
cadeia | Weather | Carimbo de data/hora de observação fornecido pela origem 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, portanto, os clientes devem tratá-lo como false.
Tipos de evidência
Use esse índice para pesquisar o esquema de um objeto de content evidência. As categorias de resposta na solicitação responseFilter não são iguais aos discriminadores de evidência na resposta: por exemplo, timezone solicita respostas de fuso horário, enquanto o tipo de evidência retornado é structured/timeZone.
| Categoria de resposta | Evidência type |
Definição de conteúdo |
|---|---|---|
web |
text |
Evidência de texto: conteúdo da cadeia de caracteres. |
news |
text/news |
Evidência de texto: conteúdo da cadeia de caracteres com uma miniatura opcional. |
images |
media/image |
Evidência de imagem: dimensões de imagem, legenda e miniatura. |
videos |
media/video |
Evidência de 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: horários locais, deslocamentos UTC e comparações. |
As definições abaixo descrevem campos públicos. Os campos podem ser omitidos quando não disponíveis; um campo omitido não implica uma medida zero ou uma resposta vazia. Os metadados de origem e a atribuição pertencem às citações do resultado delimitador, em vez de um envelope de resposta repetido em cada definição.
Exemplos são fragmentos ilustrativos evidence , não respostas completas. Consulte a resposta de exemplo para a estrutura e citations o delimitamentoresults.
Evidência de texto
For text (Web) and text/news (News), content é uma cadeia de caracteres em vez de um objeto. As evidências de notícias também podem incluir um thumbnail lado content.
| Field | Tipo | Description |
|---|---|---|
content |
cadeia | Evidência de texto para o resultado. |
thumbnail |
objeto (opcional) | Miniatura de notícias com url (cadeia de caracteres), width (inteiro) e height (inteiro). As dimensões estão em pixels. |
{
"type": "text/news",
"content": "An example news summary.",
"thumbnail": {
"url": "https://example.com/news-thumbnail.jpg",
"width": 320,
"height": 180
}
}
Evidência de imagem
For media/image, content is an image object. A URL da imagem de origem, a URL da página de hospedagem, o título e as datas de origem são fornecidos nas citações do resultado quando disponíveis.
| Campo do conteúdo | Tipo | Description |
|---|---|---|
caption |
cadeia | Descrição gerada da imagem. |
width |
inteiro | Largura da imagem em pixels. |
height |
inteiro | Altura da imagem em pixels. |
thumbnailUrl |
cadeia | URL da imagem em miniatura. |
lastUpdatedAt |
cadeia | Data de origem no 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 de vídeo
For media/video, content is a video object. Os detalhes da origem, como o título do vídeo, a URL, o publicador e a data de origem, são fornecidos nas citações do resultado quando disponíveis.
| Campo do conteúdo | Tipo | Description |
|---|---|---|
description |
cadeia | Descrição do conteúdo do vídeo. |
summary |
cadeia | Resumo curto ou realce do vídeo. |
viewCount |
inteiro | Número de exibições de vídeo. |
length |
cadeia | Duração do vídeo em HH:MM:SS formato. |
allowHttpsEmbedding |
boolean | Se a inserção HTTPS é permitida. |
allowMobileEmbedding |
boolean | Se a inserção móvel é permitida. |
embeddingUrl |
cadeia | URL para inserir o vídeo. |
thumbnailUrl |
cadeia | URL de miniatura de vídeo. |
width |
inteiro | Largura do vídeo em pixels. |
height |
inteiro | Altura do vídeo em pixels. |
lastUpdatedAt |
cadeia | Data de origem no formato ISO 8601, quando disponível. |
bestMomentIndex |
inteiro | Índice do melhor momento ou realce, quando disponível. |
moments |
matriz de VideoMoment | Segmentos de vídeo, quando disponíveis. A matriz pode estar vazia. |
{
"type": "media/video",
"content": {
"viewCount": 1200,
"length": "00:02:30",
"thumbnailUrl": "https://example.com/video-thumbnail.jpg",
"moments": []
}
}
VideoMoment
| Field | Tipo | Description |
|---|---|---|
title |
cadeia | Título do segmento. |
description |
cadeia | Descrição do segmento. |
startTime |
cadeia | Hora de início do segmento no d.hh:mm:ss formato. |
endTime |
cadeia | Hora de término do segmento no d.hh:mm:ss formato. |
momentUrl |
cadeia | Direcionar a URL para o segmento. |
Objeto weather
Quando uma consulta é sobre o clima, o Auto pode retornar um structured/weather resultado por local. Os campos são incluídos quando disponíveis. Leia medidas numéricas junto com units; não suponha que um sistema de unidade fixo.
| Campo do conteúdo | Tipo | Description |
|---|---|---|
location |
cadeia | Nome do local, por exemplo Seattle, Washington. |
url |
cadeia | URL de atribuição de clima para o local. A mesma URL está na citação do resultado. |
units |
objeto | Sistema de unidade (system) e as unidades para temperature, speed, , pressure, distance, heighte time. |
alerts |
matriz de WeatherAlert | Alertas meteorológicos ativos ou recentes para o local, filtrados pelo país ou região do usuário. |
currentWeather |
objeto | Condições atuais, incluindo condition, dayPeriod, , temperature, feelsLike, universalThermalClimateIndex, humidity, dewPoint, pressure, visibility, , uv, , uvLevel, windSpeed, , windDirection, , windGust, airQualitye observedAt quando disponível. |
forecastedWeather |
matriz de objetos | Previsões diárias com validDate, condition, , temperatureHigh, feelsLikeHightemperatureLow, feelsLikeLow, , precipitationChancechuva e quantidades de neve, humidity, day, , nighte almanachourly previsões quando disponíveis. |
sunlight |
objeto | Nascer do sol, pôr do sol, nascer da lua, conjunto de luas e fase da lua para uma data específica, quando a consulta pede uma. |
A corrente airQuality pode conter index, severitye primaryPollutantvalidAt. Uma previsão humidity diária pode conter high e low. Suas day sub-previsões night podem conter condition, precipitationChancee windSpeedwindDirection. Contém almanac dados de sol e 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 | Identificador de alerta do provedor, quando disponível. |
name |
cadeia | Nome do evento meteorológico, por exemplo Frost. |
severity |
cadeia | Severidade, por exemplo Advisory, Watchou Warning. |
status |
cadeia | Status do alerta, por exemplo Ongoing. |
issuingAuthority |
cadeia | Organização que emitiu o alerta, por exemplo National Weather Service. |
url |
cadeia | Link para a autoridade emissora. Incluído quando a origem o fornece. |
description |
cadeia | Descrição do perigo e área afetada. |
safetyGuidance |
cadeia | Ações de segurança recomendadas, quando disponíveis. |
issuedAt
effectiveAt
expiresAt
|
cadeia | Quando o alerta foi emitido, entra em vigor e expira. |
Objeto de fuso horário
Para structured/timeZone, content descreve os horários locais ou compara dois fusos horários. Uma pesquisa de local pode retornartimeZones; uma comparação pode, em vez disso, retornar startTimeZonee endTimeZonetimeDifference. Não exija todos esses campos em todas as respostas.
| Campo do conteúdo | Tipo | Description |
|---|---|---|
description |
cadeia | Resumo da resposta legível por humanos, quando disponível. |
timeZones |
matriz de TimeZoneEntry | Entradas para uma resposta de hora de local único ou de vários locais. |
startTimeZone |
TimeZoneEntry | Fuso horário de origem para uma comparação. |
endTimeZone |
TimeZoneEntry | Fuso horário de destino para uma comparação. |
timeDifference |
cadeia | Descrição de diferença de tempo legível para uma 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 | Nome do fuso horário completo. |
timeZoneAbbreviation |
cadeia | Abreviação, por exemplo PST ou IST. |
location |
cadeia | Cidade, país ou região associada à entrada. |
utcOffset |
número | Deslocamento UTC em horas. Pode ser fracionário, por exemplo 5.5, ou omitido quando não disponível. |
utcTime |
cadeia | Hora UTC como uma cadeia de caracteres formatada. |
localTime |
cadeia | Hora local como uma cadeia de caracteres formatada. |
As cadeias de caracteres de tempo podem incluir um prefixo de dia da semana; não suponha que sejam carimbos de data/hora ISO 8601.
Códigos de erro
| Código de status | Description |
|---|---|
| 200 | A solicitação foi bem-sucedida, incluindo uma pesquisa válida sem resultados. |
| 400 | Parâmetros inválidos ou JSON malformado. |
| 401 | Credenciais de autenticação ausentes ou inválidas. |
| 403 | O IQ AppID da Web autenticado não está habilitado para Auto. |
| 429 | Taxa ou limite de cota excedido. |
| 500 | Falha de serviço interno. |
| 503 | Um serviço necessário não está disponível. |
| 504 | A solicitação atingiu o tempo limite. |
Para obter o esquema de erro compartilhado e as diretrizes de repetição, consulte Tratamento de erro.