Eseguire l'autenticazione con Microsoft Web IQ

Esistono due modi per autenticarsi e ottenere l'accesso alle API Microsoft Web IQ. Usare una chiave API per iniziare più rapidamente e Microsoft Entra ID per i carichi di lavoro di produzione.

API key

Creare una chiave API nel portale Microsoft Web IQ per l'autenticazione con le API Microsoft Web IQ. Passarlo nell'intestazione x-apikey per ogni richiesta:

x-apikey: <YOUR_API_KEY>

Warning

Le chiavi API concedono l'accesso completo all'account. Archiviarli in un gestore dei segreti, non nel codice lato client o nel controllo versione.

Microsoft Entra ID

Usare Microsoft Entra ID credenziali client OAuth 2.0 (token solo app) per l'autenticazione con l'API IQ Web Microsoft.

Note

Microsoft Entra ID è la piattaforma di gestione delle identità. Una registrazione dell'app ha un ID applicazione (client), che identifica l'applicazione nel tenant ed è il valore associato all'account Web IQ. In fase di esecuzione, l'app scambia le proprie credenziali per un token di accesso Microsoft Entra da inviare con ogni richiesta API.

Prerequisites

  1. Configurare un tenant: Per registrare l'app, è necessario un tenant Azure. Non è necessaria una sottoscrizione Azure, ma se l'organizzazione ha già una o più sottoscrizioni Azure o un'organizzazione Microsoft 365, allora dispone già di un tenant Azure. In caso contrario, effettuare il provisioning di un nuovo tenant.

  2. Creare una registrazione dell'app: Una registrazione dell'app stabilisce una relazione di trust tra l'applicazione e la piattaforma di identità Microsoft, consentendo all'app di autenticarsi e accedere in modo sicuro alle risorse.

    Quando si registra l'app, vengono creati un ID client, un ID oggetto e un ID directory. Per creare le credenziali per la registrazione dell'app, vedere Registrare un'applicazione con il Microsoft Identity Platform.

Entra ID procedura di configurazione

  1. Registrazione dell'app: usare una registrazione dell'app Microsoft Entra ID esistente o crearne una. Annotare l'ID applicazione (client). Nel portale di Azure trovarlo in Microsoft Entra ID>Registrazioni app>la tua app>Panoramica.

  2. Associa la registrazione dell'app : passare a Gestione profili, selezionare la scheda ID applicazione (client) e quindi selezionare Associa ID applicazione (client). Immettere l'ID dell'applicazione (client). La sincronizzazione degli aggiornamenti dei profili può richiedere fino a un minuto.

    Note

    Se la scheda ID applicazione (client) non è disponibile, l'autenticazione di Microsoft Entra ID potrebbe non essere abilitata per la versione di valutazione. Contattare il rappresentante Microsoft per richiedere l'accesso dedicato.

  3. Acquisisci un token: usare la concessione delle credenziali client con Libreria di Autenticazione Microsoft (MSAL) preferita:

    • Autorità: https://login.microsoftonline.com/{your-tenant-id}
    • Ambito: https://api.microsoft.ai/.default

Passare quindi il token di accesso a ogni richiesta Web IQ:

Authorization: Bearer <access-token>

Chiamata di più AppID

Un ID applicazione (client) può essere associato a più di un ID app Web IQ, ad esempio un ID app per ogni risorsa Web IQ o per carico di lavoro. In questo caso, aggiungere il APPID parametro di query a ogni richiesta per scegliere l'ID app usato dalla chiamata. I limiti di frequenza vengono conteggiati per quell'AppID.

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

APPID accetta Web IQ AppID, non l'ID applicazione (client). Il contatto Microsoft fornisce i tuoi AppID di Web IQ.

L'ID applicazione (client) è associato a APPID sulla richiesta Result
Un AppID Mancante o quell'AppID Richiesta riuscita
Un AppID Un AppID diverso HTTP 403 AuthUnauthorizedAppId
Diversi AppID Mancante o vuoto HTTP 400 AuthAppIdSelectionRequired
Diversi AppIDs Uno dei tuoi AppIDs collegati Richiesta riuscita
Diversi AppIDs Qualsiasi altro AppID HTTP 403 AuthUnauthorizedAppId
Nessun AppID Any HTTP 401 AuthUnauthorizedEntryId

Warning

Le chiavi API non accettano APPID. Ogni chiave API appartiene a un AppID. Una richiesta autenticata tramite chiave che include il APPID parametro, anche vuoto, restituisce HTTP 401 AuthUnauthorizedEntryId.

Intestazioni della richiesta

Header Value Description
x-apikey oppure Authorization <your-api-key> oppure Bearer <access-token> La chiave API o Microsoft Entra ID token di accesso per l'autenticazione
Content-Type application/json Formato del corpo della richiesta

Passaggi successivi

Supporto e feedback

Inviare problemi tecnici o commenti al Web IQ Support.

  • Ultimo aggiornamento: