Referência da API Auto REST

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.