Mit Microsoft Web IQ authentifizieren

Es gibt zwei Möglichkeiten, sich mit den Microsoft Web IQ-Laufzeit-APIs zu authentifizieren. Verwenden Sie einen API-Schlüssel für den schnellsten Start und Microsoft Entra ID für Produktionsworkloads.

Important

Die Verwaltung von Bereichen verwendet die Kundenverwaltungs-API, die ein Nur-App-Entra-Bearertoken und eine separate CustomerApiAccess Berechtigung für das beabsichtigte Abrechnungskonto erfordert. Laufzeitprofilbindungen und Such-API-Schlüssel gewähren keinen Verwaltungszugriff. Informationen zu den Schritten für die Zugriffsgewährung durch den Kontoadministrator und zur Erstellung von Scopes finden Sie unter Filterergebnisse mit Scopes.

API-Schlüssel

Erstellen Sie einen API-Schlüssel im Microsoft Web IQ-Portal, um sich bei Microsoft Web IQ-APIs zu authentifizieren. Übergeben Sie ihn in der x-apikey Kopfzeile für jede Anfrage:

x-apikey: <YOUR_API_KEY>

Warning

API-Schlüssel gewähren Vollzugriff auf Ihr Konto. Speichern Sie sie in einem Secret-Manager, nicht in clientseitigem Code oder in der Quellcodeverwaltung.

Microsoft Entra ID

Verwenden Sie Microsoft Entra ID OAuth 2.0 Client Credentials (reines App-Token) für die Authentifizierung mit der Microsoft Web IQ-API.

Note

Microsoft Entra ID ist die Identitätsplattform. Eine App-Registrierung verfügt über eine Anwendungs-ID (Client-ID), die die Anwendung in Ihrem Mandanten identifiziert und der Wert ist, den Sie an Ihre Web IQ AppID binden. Zur Laufzeit tauscht Ihre App ihre Anmeldeinformationen gegen ein Microsoft Entra-Zugriffstoken aus, das mit jeder API-Anforderung gesendet werden soll.

Voraussetzungen

  1. Einrichten eines Mandanten: Um Ihre App zu registrieren, ist ein Azure Mandant erforderlich. Ein Azure-Abonnement ist nicht erforderlich, aber wenn Ihre Organisation bereits über ein oder mehrere Azure-Abonnements oder eine Microsoft 365-Organisation verfügt, hat sie bereits einen Azure-Mandanten. Stellen Sie andernfalls einen neuen Mandanten bereit.

  2. Eine App-Registrierung erstellen: Eine App-Registrierung stellt eine Vertrauensstellung zwischen Ihrer Anwendung und Microsoft Identity Platform her, sodass Ihre App sich sicher authentifizieren und auf Ressourcen zugreifen kann.

    Wenn Sie Ihre App registrieren, werden eine Client-ID, Objekt-ID und Verzeichnis-ID erstellt. Informationen zum Erstellen von Anmeldeinformationen für Ihre App-Registrierung finden Sie unter Eine Anwendung bei der Microsoft Identity Platform registrieren.

Entra ID Setupschritte

  1. App-Registrierung – Verwenden Sie eine vorhandene Microsoft Entra ID App-Registrierung, oder erstellen Sie eine. Notieren Sie die Anwendungs-ID (Client). Suchen Sie im Azure-Portal unter Microsoft Entra ID>App-Registrierungen>Ihre App>Übersicht.

  2. Binden Sie Ihre App-Registrierung – Wechseln Sie zur Profilverwaltung, wählen Sie die Registerkarte Anwendungs-IDs (Client-IDs) und dann bind Application (Client)-ID aus. Geben Sie Ihre Entra-Anwendungs-ID (Client)-ID ein. Profilaktualisierungen können bis zu einer Minute dauern, bis sie synchronisiert werden.

  3. Ein Token abrufen – Verwenden Sie den Client Credentials Grant mit Ihrer bevorzugten Microsoft Authentication Library (MSAL) (MSAL):

    • Autorität: https://login.microsoftonline.com/{your-tenant-id}
    • Geltungsbereich: https://api.microsoft.ai/.default

Übergeben Sie dann das Zugriffstoken für jede Web IQ-Anforderung:

Authorization: Bearer <access-token>

Aufrufen von mehr als einer AppID

Eine Entra-Anwendungs-ID (Client) kann an mehrere Web IQ AppID gebunden werden, z. B. eine AppID pro Web IQ-Ressource oder pro Workload. Wenn dies der Fall ist, fügen Sie den APPID Abfrageparameter jeder Anforderung hinzu, um auszuwählen, welche AppID der Aufruf verwendet. Ratenbegrenzungen werden auf diese AppID angerechnet.

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

APPID verwendet Ihre Web IQ AppID, nicht Ihre Entra-Anwendungs-ID (Client-ID). Das Entwicklerportal erstellt eine AppID, wenn Sie Ihre Web IQ-Ressource verbinden. kopieren Sie es aus der Profilverwaltung.

Ihre Entra-Anwendungs-ID (Client-ID) ist gebunden an APPID bei der Anforderung Result
One AppID Fehlt, oder jene AppID Anforderung erfolgreich ausgeführt
One AppID Eine andere AppID HTTP 403 AuthUnauthorizedAppId
Mehrere AppIDs Fehlende oder leere HTTP 400 AuthAppIdSelectionRequired
Mehrere AppIDs Eine Ihrer gebundenen AppIDs Anforderung erfolgreich ausgeführt
Mehrere AppIDs Beliebige andere AppID HTTP 403 AuthUnauthorizedAppId
Keine AppID Any HTTP 401 AuthUnauthorizedEntryId

Warning

API-Schlüssel akzeptieren keine APPID. Jeder API-Schlüssel gehört zu einer AppID. Eine schlüsselauthentifizierte Anforderung, die den APPID-Parameter enthält, auch wenn er leer ist, gibt HTTP 401 AuthUnauthorizedEntryId zurück.


Anfrage-Header

Header Wert Description
x-apikey oder Authorization <your-api-key> oder Bearer <access-token> Ihr API-Schlüssel oder Microsoft Entra ID Zugriffstoken für die Authentifizierung
Content-Type application/json Format des Anforderungstexts

Nächste Schritte

Support und Feedback

Senden Sie technische Probleme oder Feedback an den Web IQ Support.