Erste Schritte mit den Dataverse Ask-APIs (Vorschau)

[Dieser Artikel ist eine Vorabdokumentation und kann geändert werden.]

Konfigurieren Sie vor dem Aufrufen der Dataverse Ask-APIs die Umgebung und eine Identität, und verstehen Sie die in diesem Artikel beschriebenen HTTP- und Wiederholungsanforderungen.

Wichtig

  • Dies ist eine Vorschauversion.
  • Vorschauangebote werden as-is bereitgestellt und können jederzeit geändert oder eingestellt werden. Bei nutzungsbasierten Diensten kann die Nutzung zugrunde liegender Anwendungsdienste während des Vorschauzeitraums weiterhin Lizenzgebühren verursachen.
  • Vorschaufeatures unterliegen ergänzenden Nutzungsbedingungen und stehen vor einer offiziellen Version zur Verfügung, damit Kunden frühzeitig Zugriff erhalten und Feedback geben können.

Voraussetzungen

Aktivieren Sie im Power Platform Admin Center Business Applications in Work IQ für diese Umgebung für jede Umgebung , in der Sie die Dataverse Ask-APIs verwenden möchten. Erfahren Sie, wie Sie Featureeinstellungen verwalten.

Wichtig

Wenn Sie ein semantisches Modell erstellen, indiziert Dataverse die von Ihnen ausgewählten Tabellen. Dieser Indizierungsprozess verwendet Dataverse-Datenbankspeicher.

Um anzuzeigen, wie viel Speicherindizierung in einer Umgebung verwendet, überprüfen Sie die DataverseSearch-Tabelle (vormals Relevanzsuche). Dieser Speicher wird auf den Registerkarten „Zusammenfassung“ und „Dataverse“ auf den Datenbankspeicherverbrauch angerechnet.

Authentication

Die Dataverse Ask-APIs verwenden dieselbe Microsoft Entra ID OAuth-Authentifizierung wie andere Dataverse-HTTP-Endpunkte.

  1. Registrieren Sie Ihre Anwendung in Microsoft Entra ID.
  2. Konfigurieren Sie delegierten Zugriff für eine interaktive Anwendung, oder erstellen Sie einen Dataverse-Anwendungsbenutzer für eine Server-zu-Server-Anwendung.
  3. Abrufen eines Zugriffstokens für die Dataverse-Umgebungs-URL.
  4. Senden Sie das Token im Authorization Header jeder Anforderung.

Fordern Sie für die delegierte Authentifizierung den <environment-url>/user_impersonation Bereich an. Für vertrauliche Kunden <environment-url>/.default anfordern.

Authorization: Bearer <access-token>

Informationen zu Registrierungsoptionen, Flüssen und Codebeispielen finden Sie unter Verwenden der OAuth-Authentifizierung mit Microsoft Dataverse.

Autorisierung und Privilegien

Die Authentifizierung identifiziert den Benutzer oder anwendungsbenutzer. Dataverse-Sicherheitsrollen bestimmen, was der Aufrufer tun kann.

Verwaltung des semantischen Modells

Weisen Sie im Power Platform Admin Center dem Aufrufer eine Sicherheitsrolle zu, die Berechtigungen zum Erstellen und Löschen von semantischen Modellen enthält. Zu den folgenden Sicherheitsrollen gehören die folgenden Berechtigungen:

  • Dataverse-Suchrolle
  • Umgebungsersteller
  • Systemadministrator
  • Systemanpasser

Wenn Sie eine benutzerdefinierte Sicherheitsrolle verwenden, kann ein Systemadministrator seine Berechtigungen im Power Platform Admin Center konfigurieren.

Vorgänge abfragen

Der Aufrufer muss über Lesezugriff auf die Dataverse-Tabellen und Spalten verfügen, die im semantischen Modell enthalten sind. Der Dienst verwendet nur Daten, die der Aufrufer zum Lesen autorisiert hat. Datensatzbesitz, Zugriff auf Geschäftseinheiten, Freigabe und Sicherheit auf Spaltenebene können sich auf die Ergebnisse auswirken.

Eine Anwendung, die die Server-zu-Server-Authentifizierung verwendet, wird mit den Berechtigungen ausgeführt, die dem Dataverse-Anwendungsbenutzer zugewiesen sind. Gewähren Sie nur die Berechtigungen, die die Anwendung benötigt.

Anfragen verfassen

Erstellen Sie die Basis-URL, indem Sie /api/iq/v1.0/ an die URI der Organisation anhängen:

Wenn der Organisations-URI lautet https://contoso.api.crm.dynamics.com/, lautet die vollständige Basis-URL:

https://contoso.api.crm.dynamics.com/api/iq/v1.0/

Verwenden Sie HTTPS, und schließen Sie diese Header ein:

Authorization: Bearer <access-token>
Accept: application/json

Für Anfragen mit einem JSON-Text fügen Sie außerdem Folgendes hinzu:

Content-Type: application/json

Die Dataverse Ask-APIs sind kein OData-Dienst. Schließen Sie keine OData-spezifischen Header oder Abfrageoptionen ein, es sei denn, ein anderer Artikel erfordert sie explizit.

Verwenden Sie UTF-8 für Anfrageinhalte. Verwenden Sie die Schreibweise in Groß- und Kleinbuchstaben für Eigenschaftsnamen und Auswahlwerte, die in den API-Artikeln verwendet wird.

Antworten verarbeiten

Überprüfen Sie den HTTP-Statuscode, bevor Sie eine erfolgreiche Antwort deserialisieren. Antwortinhalte verwenden JSON. Erfolgreiche Vorgänge geben diese Statuscodes zurück:

Operation Statuscode
Auflisten semantischer Modelle 200 OK
Erstellen eines semantischen Modells 201 Created
Semantikmodell löschen 200 OK
Fragen mithilfe des semantischen Modells 200 OK

Einige Eigenschaften der Antwort können den Wert null haben. Gehen Sie nicht davon aus, dass eine Zusammenfassung, Zitatlinks, unformatierte Zeilen oder ein Pagingtoken vorhanden ist.

Die Form der einzelnen Elemente in rawResult hängt von der Frage und den Daten ab, die zu ihrer Beantwortung verwendet werden. Verarbeiten Sie jedes Element als JSON-Objekt, anstatt jede Ask-Antwort in einen festen Zeilentyp zu deserialisieren.

Fehler behandeln

Für eine erfolglose Antwort:

  1. Überprüfen Sie den HTTP-Statuscode.
  2. Wenn die Antwort über einen JSON-Textkörper verfügt, protokollieren Sie den Fehlertyp und die Meldung für die Diagnose.
  3. Suchen Sie nach einem Retry-After Response-Header.
  4. Wiederholen Sie den Vorgang nur bei vorübergehenden Fehlern.
  5. Schreiben Sie keine Logik, die von nicht dokumentierten Fehlereigenschaften oder exakten Nachrichtentext abhängt.

Erwartete Statuscodes

Behandeln Sie diese Arten von Fehlern:

Statuscode Bedeutung Empfohlene Maßnahme
400 Bad Request Die Anforderung ist ungültig, eine erforderliche Umgebungsfunktion ist nicht aktiviert, oder es kann keine autorisierte Tabelle verwendet werden. Korrigieren Sie die Anforderungs- oder Umgebungskonfiguration. Wiederholen Sie nicht die gleiche Anforderung unverändert.
401 Unauthorized Das Zugriffstoken fehlt, ungültig, abgelaufen oder für eine andere Ressource. Erwerben Sie ein gültiges Token für die Umgebung, und versuchen Sie es erneut.
403 Forbidden Der Aufrufer verfügt über keine erforderlichen Berechtigungen. Weisen Sie eine geeignete Sicherheitsrolle zu, oder verwenden Sie eine andere Identität.
404 Not Found Das angeforderte Semantikmodell ist nicht vorhanden. Bestätigen Sie den Bezeichner oder den Namen des semantischen Modells.
429 Too Many Requests Der Aufrufer hat einen Dienstschutzgrenzwert überschritten. Warten Sie die Retry-After Dauer ab, bevor Sie es erneut versuchen.
500 Internal Server Error Ein unerwarteter Fehler ist aufgetreten. Wiederholen Sie den Vorgang mit "Backoff", wenn der Vorgang sicher wiederholt werden kann. Wenn der Fehler weiterhin auftritt, wenden Sie sich an Microsoft-Support.
503 Service Unavailable Der Dienst oder die erforderlichen Metadaten sind vorübergehend nicht verfügbar. Wiederholen Sie mit Backoff.

Bei vorübergehenden Fehlern wiederholen

Behandeln Sie 429, 500, 502, 503 und 504-Antworten als potenziell temporär. Versuchen Sie außerdem Netzwerkfehler erneut, bei denen bekannt ist, dass der Ausgang der Anfrage sicher ist.

Verwenden Sie diese Wiederholungsreihenfolge:

  1. Wenn die Antwort enthält Retry-After, warten Sie auf diese Dauer.
  2. Verwenden Sie andernfalls exponentielles Backoff mit zufälligem Jitter.
  3. Beschränken Sie die Wiederholungsanzahl und die gesamt verstrichene Zeit.
  4. Versuchen Sie nichttransiente Antworten nicht erneut.
  5. Protokollieren Sie den endgültigen Fehler und die Korrelationsinformationen, die vom Dienst zurückgegeben werden.

Vermeiden Sie das sofortige Wiederholen mehrerer Anforderungen parallel, da diese Aktion die Einschränkung erweitern kann.

Berücksichtigen der Betriebssicherheit

  • List- und Ask-Anfragen können nach einem vorübergehenden Fehler sicher erneut versucht werden.
  • Führen Sie vor dem Erneuten Erstellen die Semantikmodelle auf, um zu ermitteln, ob die erste Anforderung erfolgreich war. Semantikmodellnamen müssen eindeutig sein.
  • Führen Sie vor dem Erneuten Löschen die semantischen Modelle auf, um zu bestimmen, ob das Modell noch vorhanden ist. Ein fehlendes Modell nach einer unklaren Löschantwort als abgeschlossenen Löschvorgang behandeln.

Nächste Schritte

  • Zuletzt aktualisiert um