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.
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
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.
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
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.
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.
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
- Autoridade:
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
- Faça sua primeira chamada no início rápido.
- Explore a referência da API REST.
Suporte e comentários
Envie problemas técnicos ou comentários para o Suporte do Web IQ.