Autenticar com Microsoft Web IQ

Há duas maneiras de autenticar e obter acesso às APIs 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.

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 do aplicativo (cliente), que identifica o aplicativo em seu tenant e é o valor que você associa à sua conta do Web IQ. 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 o ID do aplicativo (cliente). As atualizações de perfil podem levar até um minuto para serem sincronizadas.

    Note

    Se a guia IDs do aplicativo (cliente) não estiver disponível, a autenticação do Microsoft Entra ID poderá não estar habilitada para sua avaliação. Entre em contato com seu representante Microsoft para solicitar acesso dedicado.

  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 de aplicativo (cliente) pode ser associada a mais de uma AppID do Web IQ, por exemplo, uma AppID por recurso do Web IQ 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 o Web IQ AppID, não a ID do aplicativo (cliente). Seu contato Microsoft fornece seus AppIDs de IQ da Web.

Sua ID do aplicativo 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 foi 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.

  • Última atualização em