Autenticar com Microsoft Web IQ

Há duas maneiras de autenticar com as APIs de runtime do Microsoft Web IQ. Use uma chave de API para começar mais rapidamente e o Microsoft Entra ID para cargas de trabalho de produção.

Importante

O gerenciamento de escopo usa a API de Gerenciamento de Clientes, que requer um token de portador Entra somente para aplicativo e uma concessão separada CustomerApiAccess na conta de cobrança de destino. Associações de perfil de runtime e chaves de API de pesquisa não concedem acesso de gerenciamento. Consulte Filtrar resultados com Escopos para ver as etapas de concessão de acesso do administrador da conta e criação de escopos.

chave de API

Crie uma chave de API no portal Microsoft Web IQ para autenticar com APIs do Microsoft Web IQ. Passe-o no x-apikey cabeçalho em cada solicitação:

x-apikey: <YOUR_API_KEY>

Warning

As chaves de API concedem acesso total à sua conta. Armazene-os em um gerenciador de segredos, não no código do lado do cliente ou no controle do código-fonte.

Microsoft Entra ID

Use as credenciais de cliente do OAuth 2.0 do Microsoft Entra ID (token somente de aplicativo) para autenticação com a API Microsoft Web IQ.

Note

Microsoft Entra ID é a plataforma de identidade. Um registro de aplicativo tem uma ID de aplicativo (cliente), que identifica o aplicativo em seu locatário e é o valor que você associa ao seu Aplicativo de IQ Web. Em runtime, seu aplicativo troca suas credenciais por um token de acesso Microsoft Entra a ser enviado com cada solicitação de API.

Prerequisites

  1. Configurar um tenant: Para registrar seu aplicativo, um tenant do Azure é necessário. Uma assinatura do Azure não é necessária, mas se sua organização já tiver uma ou mais assinaturas do Azure ou uma organização do Microsoft 365, então você já terá um locatário do Azure. Caso contrário, provisione um novo tenant.

  2. Crie um registro de aplicativo: Um registro de aplicativo estabelece uma relação de confiança entre seu aplicativo e o plataforma de identidade da Microsoft, permitindo que seu aplicativo autentique e acesse recursos com segurança.

    Quando você registra seu aplicativo, são criados um ID do cliente, um ID de objeto e um ID de diretório. Para criar credenciais para o registro do seu aplicativo, consulte Registrar um aplicativo com a plataforma de identidade da Microsoft.

Entra ID etapas de configuração

  1. Registro de aplicativo – use um registro de aplicativo Microsoft Entra ID existente ou crie um. Registre o ID do aplicativo (cliente). No portal Azure, localize-o em Microsoft Entra ID>Registros de aplicativo>seu aplicativo>Visão geral.

  2. Associar o registro do aplicativo – Vá para o Gerenciamento de Perfil, selecione a guia IDs do Aplicativo (Cliente) e, em seguida, selecione Associar ID do Aplicativo (Cliente). Insira a ID do aplicativo Entra (cliente). As atualizações de perfil podem levar até um minuto para serem sincronizadas.

  3. Adquirir um token – Use o fluxo de credenciais do cliente com a biblioteca Biblioteca do Microsoft Authenticator (MSAL) de sua preferência:

    • Autoridade: https://login.microsoftonline.com/{your-tenant-id}
    • Escopo: https://api.microsoft.ai/.default

Em seguida, passe o token de acesso em cada solicitação do Web IQ:

Authorization: Bearer <access-token>

Chamando mais de um AppID

Uma ID do aplicativo Entra (cliente) pode ser associada a mais de uma AppID de IQ Da Web, por exemplo, uma AppID por recurso de IQ da Web ou por carga de trabalho. Quando isso acontecer, adicione o parâmetro de consulta APPID a cada solicitação para escolher qual AppID a chamada usa. Os limites de taxa contam para esse AppID.

POST https://api.microsoft.ai/v3/search/web?APPID=<your-web-iq-appid>
Authorization: Bearer <access-token>
Content-Type: application/json

APPID usa a AppID do Web IQ, não a ID do aplicativo Entra (cliente). O Portal do Desenvolvedor cria um AppID quando você conecta o recurso do Web IQ; copie-o de Gerenciamento de Perfil.

Sua ID do aplicativo Entra (cliente) está associada a APPID na solicitação Result
Um AppID Ausente ou esse AppID A solicitação é bem-sucedida
Um AppID Uma AppID diferente HTTP 403 AuthUnauthorizedAppId
Vários AppIDs Ausente ou vazio HTTP 400 AuthAppIdSelectionRequired
Vários AppIDs Um de seus AppIDs associados A solicitação é bem-sucedida
Vários AppIDs Qualquer outro AppID HTTP 403 AuthUnauthorizedAppId
Sem AppID Qualquer HTTP 401 AuthUnauthorizedEntryId

Warning

As chaves de API não aceitam APPID. Cada chave de API pertence a um AppID. Uma solicitação autenticada por chave que inclui o APPID parâmetro, mesmo vazio, retorna HTTP 401 AuthUnauthorizedEntryId.


Cabeçalhos de solicitação

Header Value Description
x-apikey ou Authorization <your-api-key> ou Bearer <access-token> Sua chave de API ou token de acesso Microsoft Entra ID para autenticação
Content-Type application/json Formato do corpo da solicitação

Próximas Etapas 

Suporte e comentários

Envie problemas técnicos ou comentários para o Suporte do Web IQ.