Mit Customer Insights - Data-APIs arbeiten

  • Artikel

Dynamics 365 Customer Insights - Data stellt APIs bereit, um Ihre eigenen Anwendungen basierend auf Ihren Daten in Customer Insights zu erstellen. Details zu diesen APIs finden Sie in der API-Referenz. Sie enthalten zusätzliche Informationen über Operationen, Parameter und Antworten.

Anmerkung

Auf Customer Insights - Data-Tabellen kann auch über die Dataverse APIs zugegriffen werden. Wir empfehlen Ihnen, Dataverse APIs zum Abfragen von Customer Insights-Daten zu verwenden, da diese eine umfassendere Filterung, einen höheren Durchsatz und eine geringere Latenz bieten. Weitere Informationen finden Sie unter Dataverse APIs für Customer Insights.

Erste Schritte mit den APIs

Ein Administrierender muss den API-Zugriff auf Ihre Daten aktivieren. Sobald der Zugriff aktiviert ist, kann jeder Benutzer die API mit dem Abonnementschlüssel verwenden.

  1. Melden Sie sich in Customer Insights - Data an oder registrieren Sie sich für eine Testversion von Customer Insights.

  2. Gehen Sie zu Einstellungen>Berechtigungen und wählen Sie die Registerkarte APIs.

  3. Wenn kein API-Zugriff auf die Umgebung eingerichtet wurde, wählen Sie Aktivieren.

    Das Aktivieren der APIs erstellt einen primären und sekundären Abonnementschlüssel für Ihre Umgebung, die in den API-Anfragen verwendet wird. Sie können die Schlüssel regenerieren, indem Sie die Registerkarte Primär neu generieren oder Sekundär neu generieren auf der Registerkarte API auswählen.

  4. Wählen Sie Unsere APIs erkunden um die APIs zu testen.

  5. Suchen Sie nach einem API-Vorgang und wählen Sie Testen.

    So testen Sie die APIs.

  6. Legen Sie im Seitenbereich den Wert im Dropdown-Menü Genehmigung auf implizit fest. Der Authorization Header wird mit einem Bearertoken hinzugefügt. Ihr Abonnementschlüssel wird automatisch ausgefüllt.

  7. Fügen Sie optional alle erforderlichen Abfrageparameter hinzu.

  8. Scrollen Sie zum unteren Rand des Seitenfensters und wählen Sie Senden.

    Die HTTP-Antwort wird unten im Bereich angezeigt.

Erstellen Sie eine neue App-Registrierung im Azure-Portal

Erstellen Sie eine neue App-Registrierung, um die APIs in einer Azure-Anwendung mithilfe delegierter Berechtigungen zu verwenden.

  1. Vervollständigen Sie den Abschnitt Erste Schritte.

  2. Melden Sie sich beim Azure-Portal mit dem Konto an, das auf die Customer Insights-Daten zugreifen kann.

  3. Suchen Sie sie und wählen App-Anmeldungen aus.

  4. Wählen Sie Neuregistrierung geben Sie einen Anwendungsnamen an und wählen Sie den Kontotyp.

    Fügen Sie optional eine Umleitungs-URL hinzu. http://localhost ist ausreichend für die Entwicklung einer Anwendung auf Ihrem lokalen Computer.

  5. Wählen Sie Registrieren aus.

  6. Gehen Sie bei Ihrer neuen App-Registrierung zu API-Berechtigungen.

  7. Wählen Sie Berechtigung hinzufügen und dann Dynamics 365 AI für Customer Insights im Seitenbereich.

  8. Für den Berechtigungstyp wählen Sie Delegierte Berechtigungen aus und wählen Sie dann die Berechtigung user_impersonation.

  9. Wählen Sie Zugriffsrechte hinzufügen.

  10. Wählen Sie Admin-Zustimmung erteilen für..., um die Registrierung der App abzuschließen.

  11. Um ohne Anmeldung auf die API zuzugreifen, lesen Sie den Abschnitt Berechtigungen für Server-zu-Server-Anwendungen.

Sie können die Anwendungs-/Client-ID für diese App-Registrierung mit der Microsoft Authentication Library (MSAL) verwenden, um ein Träger-Token zu erhalten, das Sie mit Ihrer Anfrage an die API senden.

Informationen zur Verwendung der APIs in unseren Clientbibliotheken finden Sie unter Customer Insights-Clientbibliotheken.

Server-zu-Server-Anwendungsberechtigungen festlegen

Erstellen Sie eine App-Registrierung erstellen, die keine Benutzerinteraktion erfordert und auf einem Server ausgeführt werden kann.

  1. Gehen Sie bei Ihrer App-Registrierung im Azure-Portal zu API-Berechtigungen.

  2. Wählen Sie Berechtigung hinzufügen aus.

  3. Wählen Sie die Registerkarte APIs, die meine Organisation verwendet und wählen Sie Dynamics 365 KI für Customer Insights aus der Liste.

  4. Für den Berechtigungstyp wählen Sie Anwendungsberechtigungen und dann die Berechtigung api.access aus.

  5. Wählen Sie Berechtigungen hinzufügen aus.

  6. Gehen Sie zurück zu API-Berechtigungen für Ihre App-Registrierung.

  7. Wählen Sie Admin-Zustimmung erteilen für..., um die Registrierung der App abzuschließen.

  8. Fügen Sie den Namen der App-Registrierung als Benutzender in Customer Insights - Data hinzu.

    1. Öffnen Sie Customer Insights - Data, gehen Sie zu Einstellungen>Berechtigungen und wählen Sie Benutzenden hinzufügen aus.

    2. Suchen Sie nach dem Namen Ihrer App-Registrierung, wählen Sie ihn aus den Suchergebnissen und wählen Sie Speichern.

Beispielabfragen

Wir haben eine kurze Liste von OData-Beispielabfragen zusammengestellt, um mit den APIs zu arbeiten. Mehr unter Beispiele für OData-Abfragen.

Customer Insights Client-Bibliotheken

Beginnen Sie mit der Verwendung der für die Clientbibliotheken verfügbaren Customer Insights - Data-APIs. Alle Quellcodes und Beispielanwendungen der Bibliothek finden Sie in einem GitHub-Repository.

C# NuGet

Nutzen Sie die C# Client-Bibliotheken von NuGet.org. Zurzeit zielt dieses Paket auf die Frameworks netstandard2.0 und netcoreapp2.0 ab. Für weitere Informationen über die NuGet Pakete gehen Sie zu Microsoft.Dynamics.CustomerInsights.Api.

Fügen Sie die C#-Client-Bibliothek zu einem C#-Projekt hinzu

  1. Öffnen Sie in Visual Studio den NuGet Paketmanager für Ihr Projekt.

  2. Suchen Sie nach Microsoft.Dynamics.CustomerInsights.Api.

  3. Wählen Sie Installieren, um das Paket zum Projekt hinzuzufügen.

    Führen Sie alternativ diesen Befehl in der NuGet Paketmanager-Konsole aus: Install-Package -Id Microsoft.Dynamics.CustomerInsights.Api -Source nuget.org -ProjectName <project name> [-Version <version>]

Verwenden Sie die C# Client-Bibliothek

  1. Verwenden Sie die Microsoft Authentication Library (MSAL), um eine AccessToken mit Ihrer bestehenden Azure-App-Registrierung zu erhalten.

  2. Erstellen Sie nach erfolgreicher Authentifizierung und dem Erwerb eines Tokens einen neuen oder verwenden Sie einen bestehenden HttpClient mit dem Zusatz DefaultRequestHeaders „Authorization“, der auf Bearer „access token“ festgelegt ist, und Ocp-Apim-Subscription-Key, der auf den Abonnementschlüssel aus Ihrer Customer Insights - Data-Umgebung festgelegt ist.

    Setzen Sie gegebenenfalls den Autorisierung-Header zurück. Zum Beispiel, wann der Token abgelaufen ist.

  3. Übergeben Sie diese HttpClient in die Konstruktion des CustomerInsights Clients.

  4. Rufen Sie mit dem Client die „Erweiterungsmethoden“ auf, zum Beispiel GetAllInstancesAsync. Wenn der Zugriff auf die zugrundeliegende Microsoft.Rest.HttpOperationResponse bevorzugt wird, verwenden Sie die http-Message-Methoden, z. B. GetAllInstancesWithHttpMessagesAsync.

  5. Die Antwort wird wahrscheinlich vom Typ object sein, da die Methode mehrere Typen zurückgeben kann (zum Beispiel IList<InstanceInfo> und ApiErrorResult). Um den Rückgabetyp zu überprüfen, verwenden Sie die Objekte in den Antworttypen, die auf der API-Detailseite für diesen Vorgang angegeben sind.

    Wenn mehr Informationen über die Anfrage benötigt werden, verwenden Sie die http-Message-Methoden für den Zugriff auf das raw response-Objekt.

NodeJS-Paket

Verwenden Sie die über NPM verfügbaren NodeJS-Clientbibliotheken: https://www.npmjs.com/package/@microsoft/customerinsights

Python-Paket

Verwenden Sie die über PyPi verfügbaren Python-Clientbibliotheken: https://pypi.org/project/customerinsights/