Delen via

Werken met Customer Insights - Data-API's

  • Artikel

Dynamics 365 Customer Insights - Data biedt API's om uw eigen toepassingen te bouwen op basis van uw gegevens in Customer Insights. Details van deze API's staan vermeld in de API-verwijzing. Ze bevatten aanvullende informatie over bewerkingen, parameters en reacties.

Notitie

Customer Insights - Data-tabellen zijn ook toegankelijk via Dataverse-API's. We raden u aan Dataverse-API's te gebruiken om Customer Insights-gegevens op te vragen, omdat deze uitgebreidere filters, een grotere doorvoer en een lagere latentie bieden. Zie Dataverse-API's voor Customer Insights voor meer informatie.

Aan de slag met het uitproberen van de API's

Een beheerder moet API-toegang tot uw gegevens inschakelen. Zodra toegang is ingeschakeld, kan elke gebruiker de API gebruiken met de abonnementssleutel.

  1. Meld u aan bij Customer Insights - Data of registreer u voor een proefversie van Customer Insights.

  2. Ga naar Instellingen>Machtigingen en selecteer het tabblad API's.

  3. Als er geen API-toegang tot de omgeving is ingesteld, selecteert u Inschakelen.

    Als u de API's inschakelt, wordt een primaire en secundaire abonnementssleutel voor uw omgeving gemaakt die wordt gebruikt in de API-aanvragen. Selecteer Primaire opnieuw genereren of Secundaire opnieuw genereren op het tabblad API′s om sleutels opnieuw te genereren.

  4. Selecteer Onze API's verkennen om de API's uit te proberen.

  5. Zoek en selecteer een API-bewerking en selecteer Uitproberen.

    Procedure voor het testen van de API's.

  6. Stel in het zijvenster de waarde in het vervolgkeuzemenu Autorisatie in op impliciet. De header Authorization wordt toegevoegd met een bearer-token. Uw abonnementssleutel wordt automatisch ingevuld.

  7. Voeg eventueel alle benodigde queryparameters toe.

  8. Scrol naar de onderkant van het deelvenster aan de zijkant en selecteer Verzenden.

    De HTTP-respons verschijnt onder aan het deelvenster.

Een nieuwe app-registratie in Azure Portal maken

Maak een nieuwe app-registratie om de API's in een Azure-toepassing te gebruiken met gedelegeerde machtigingen.

  1. Voltooi de sectie Aan de slag.

  2. Meld u aan op de Azure-portal met het account dat toegang heeft tot de Customer Insights-gegevens.

  3. Zoek naar en selecteer vervolgens App-registraties.

  4. Selecteer Nieuwe registratie, geef een toepassingsnaam op en kies het accounttype.

    Voeg eventueel een omleidings-URL toe. http://localhost is voldoende om een toepassing op uw lokale computer te ontwikkelen.

  5. Selecteer Registreren.

  6. Ga bij uw nieuwe app-registratie naar API-machtigingen.

  7. Selecteer Een machtiging toevoegen en selecteer Dynamics 365 AI voor Customer Insights in het zijpaneel.

  8. Selecteer voor Type machtiging de optie Gedelegeerde machtigingen en selecteer vervolgens de machtiging user_impersonation.

  9. Selecteer Machtigingen toevoegen.

  10. Selecteer Beheerders toestemming verlenen voor... om de app-registratie te voltooien.

  11. Als u toegang tot de API nodig hebt zonder dat een gebruiker zich aanmeldt, gaat u naar Machtigingen voor server-naar-server-toepassingen instellen.

U kunt de toepassings-/client-id voor deze app-registratie gebruiken bij de Microsoft Authentication Library (MSAL) om een bearer-token te verkrijgen om met uw verzoek naar de API te verzenden.

Zie Customer Insights-clientbibliotheken voor informatie over het gebruik van de API's in onze clientbibliotheken.

Machtigingen voor server-naar-server-toepassingen instellen

Maak een app-registratie waarvoor geen gebruikersinteractie nodig is en die op een server kan worden uitgevoerd.

  1. Ga bij uw app-registratie in de Azure-portal naar API-machtigingen.

  2. Selecteer Een machtiging toevoegen.

  3. Selecteer het tabblad API's die mijn organisatie gebruikt en kies Dynamics 365 AI voor Customer Insights in de lijst.

  4. Selecteer voor Type machtiging de optie Toepassingsmachtigingen en selecteer vervolgens de machtiging api.access.

  5. Selecteer Machtigingen toevoegen.

  6. Ga terug naar API-machtigingen voor uw app-registratie.

  7. Selecteer Beheerders toestemming verlenen voor... om de app-registratie te voltooien.

  8. Voeg de naam van de app-registratie als gebruiker toe in Customer Insights - Data.

    1. Open Customer Insights - Data, ga naar Instellingen>Machtigingen en selecteer Gebruikers toevoegen.

    2. Zoek naar de naam van uw app-registratie, selecteer deze in de zoekresultaten en selecteer Opslaan.

Voorbeeldquery's

Een korte lijst met OData-voorbeeldquery's om met de API's te werken, vindt u hier: Voorbeelden van OData-query's.

Customer Insights-clientbibliotheken

Ga aan de slag met het gebruik van de clientbibliotheken die beschikbaar zijn voor de Customer Insights - Data-API's. Alle broncode en voorbeeldtoepassingen van de bibliotheek zijn te vinden in een GitHub-repo​.

C# NuGet

Gebruik de C#clientbibliotheken van NuGet.org. Momenteel richt het pakket zich op de frameworks netstandard2.0 en netcoreapp2.0. Meer informatie over het NuGet-pakket, vindt u hier: Microsoft.Dynamics.CustomerInsights.Api.

De C#-clientbibliotheek toevoegen aan een C#-project

  1. Open in Visual Studio de NuGet Package Manager voor uw project.

  2. Zoek Microsoft.Dynamics.CustomerInsights.Api.

  3. Selecteer Installeren om het pakket aan het project toe te voegen.

    U kunt deze opdracht ook uitvoeren in de NuGet Package Manager-console: Install-Package -Id Microsoft.Dynamics.CustomerInsights.Api -Source nuget.org -ProjectName <project name> [-Version <version>]

De C#-clientbibliotheek gebruiken

  1. Gebruik de Microsoft Authentication Library (MSAL) om een AccessToken op te halen met uw bestaande Azure app-registratie.

  2. Nadat u een token hebt geverifieerd en verkregen, maakt u een nieuwe of gebruikt u een bestaande HttpClient met de DefaultRequestHeaders "Autorisatie" ingesteld op Bearer "toegangstoken" en met Ocp-Apim-Subscription-Key ingesteld op de abonnementssleutel van uw Customer Insights - Data-omgeving.

    Reset de Autorisatie-koptekst indien van toepassing. Bijvoorbeeld wanneer het token is verlopen.

  3. Geef deze HttpClient door aan de constructie van de CustomerInsights-cliënt.

  4. Oproepen doen met de client naar de 'extensiemethoden', bijvoorbeeld GetAllInstancesAsync. Als toegang tot het onderliggende Microsoft.Rest.HttpOperationResponse de voorkeur heeft, gebruik dan de 'http-berichtmethoden', bijvoorbeeld GetAllInstancesWithHttpMessagesAsync.

  5. De respons is waarschijnlijk het type object omdat de methode meerdere typen kan retourneren (bijvoorbeeld IList<InstanceInfo> en ApiErrorResult). Gebruik om het retourtype te controleren, de objecten in de responstypen die zijn opgegeven op de API-detailspagina voor die bewerking.

    Als er meer informatie over de aanvraag nodig is, gebruik dan de http-berichtmethoden om toegang te krijgen tot het onbewerkte responsobject.

NodeJS-pakket

Gebruik de NodeJS-clientbibliotheken die beschikbaar zijn via NPM: https://www.npmjs.com/package/@microsoft/customerinsights

Python-pakket

Gebruik de Python-clientbibliotheken die beschikbaar zijn via PyPi: https://pypi.org/project/customerinsights/