Autenticar com o Microsoft Web IQ

Existem duas formas de autenticar e aceder às APIs Web IQ da Microsoft. Use uma chave API para o início mais rápido e o Microsoft Entra ID para cargas de trabalho em produção.

chave de API

Crie uma chave API no portal Microsoft Web IQ para autenticar com as APIs Microsoft Web IQ. Inclua isso no cabeçalho x-apikey em cada pedido:

x-apikey: <YOUR_API_KEY>

Warning

As chaves API concedem acesso total à sua conta. Guarde-os num gestor de segredos, não em código do lado do cliente ou controlo de versão.

Microsoft Entra ID

Utilize as Credenciais de Cliente do Microsoft Entra ID OAuth 2.0 (token só de aplicação) para autenticação com a API Microsoft Web IQ.

Note

Microsoft Entra ID é a plataforma de identidade. O registo de uma aplicação tem um ID de Aplicação (cliente), que identifica a aplicação no seu tenant e é o valor que associa à sua conta Web IQ. Em tempo de execução, a sua aplicação troca as suas credenciais por um token de acesso Microsoft Entra para enviar com cada pedido de API.

Pré-requisitos

  1. Configure um tenant: Para registar a sua aplicação, é necessário um tenant Azure. Uma subscrição Azure não é obrigatória, mas se a sua organização já tiver uma ou mais subscrições Azure ou uma organização Microsoft 365, então já tem um tenant do Azure. Caso contrário, crie um novo tenant.

  2. Crie um registo de aplicação: Um registo de aplicação estabelece uma relação de confiança entre a sua aplicação e a plataforma de identidade da Microsoft, permitindo que a sua aplicação se autentique e aceda aos recursos de forma segura.

    Quando regista a sua aplicação, são criados um ID de cliente, ID de objeto e ID de diretório. Para criar credenciais para o registo da sua aplicação, consulte Registar uma aplicação com a plataforma de identidades da Microsoft.

Etapas de configuração do Entra ID

  1. Registo de aplicações - Use um registo de aplicação Microsoft Entra ID existente ou crie um. Registe o seu ID de Aplicação (cliente). No portal do Azure, encontre-o em Microsoft Entra ID>Registos de aplicações>a sua aplicação>Descrição geral.

  2. Associe o registo da sua aplicação - Vá a Gestão de Perfis, selecione o separador IDs da Aplicação (Cliente) e depois selecione Associar ID da Aplicação (Cliente). Introduza o ID da sua aplicação (cliente). As atualizações do perfil podem demorar até um minuto a sincronizar.

    Note

    Se o separador IDs da Aplicação (Cliente) não estiver disponível, a autenticação do Microsoft Entra ID pode não estar ativada para o seu período de experiência. Contacte o seu representante da Microsoft para solicitar acesso dedicado.

  3. Adquira um token - Use a concessão de credenciais do cliente com a sua Biblioteca de Autenticação da Microsoft (MSAL) preferida:

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

Depois passa o token de acesso a cada pedido Web IQ:

Authorization: Bearer <access-token>

Chamar mais do que um AppID

Um ID de aplicação (cliente) pode ser vinculado a mais do que um AppID Web IQ, por exemplo, um AppID por recurso Web IQ ou por carga de trabalho. Quando estiver, adicione o APPID parâmetro de consulta a cada pedido para escolher qual AppID a chamada utiliza. Os limites de pedidos 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 aceita o teu Web IQ AppID, não o ID da tua aplicação (cliente). O seu contacto da Microsoft fornece os seus AppIDs Web IQ.

O ID da sua aplicação (cliente) está vinculado a APPID no pedido Result
Um AppID Em falta, ou esse AppID O pedido foi bem-sucedido
Um AppID Um AppID diferente HTTP 403 AuthUnauthorizedAppId
Vários AppIDs Ausente ou vazio HTTP 400 AuthAppIdSelectionRequired
Vários AppIDs Um dos seus AppIDs associados O pedido foi bem-sucedido
Vários AppIDs Qualquer outro AppID HTTP 403 AuthUnauthorizedAppId
Sem AppID Qualquer HTTP 401 AuthUnauthorizedEntryId

Warning

As chaves API não suportam APPID. Cada chave API pertence a um AppID. Um pedido autenticado por chave que inclui o APPID parâmetro, mesmo vazio, devolve HTTP 401 AuthUnauthorizedEntryId.

Cabeçalhos da requisição

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

Passos seguintes

Suporte e comentários

Envie questões técnicas ou feedback para o Suporte Web IQ.

  • Última atualização a