Mit Customer Insights - Data-APIs arbeiten

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.

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 bei 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.

   

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.

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 "Berechtigungen hinzufügen" aus.

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. Zum Abschluss müssen wir den Namen der App-Registrierung als Benutzer in Customer Insights - Data hinzufügen.

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

   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

Dieser Abschnitt hilft Ihnen bei den ersten Schritten mit den Client-Bibliotheken, die für die Customer Insights - Data APIs verfügbar sind. Alle Quellcodes und Beispielanwendungen der Bibliothek finden Sie in einem GitHub-Repository.

C# NuGet

Verwenden Sie die C#-Clientbibliotheken aus NuGet.org. Derzeit zielt das Paket auf die Frameworks netstandard2.0 und netcoreapp2.0 ab. Weitere Informationen zum NuGet-Paket finden Sie unter Microsoft.Dynamics.CustomerInsights.Api.

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

1. Öffnen Sie in Visual Studio den NuGet-Paket-Manager 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/