Utilizzare le API di Customer Insights - Data

  • Articolo

Dynamics 365 Customer Insights - Data fornisce API per creare le tue applicazioni in base ai tuoi dati in Customer Insights. I dettagli di queste API sono elencati nel Riferimento API. Includono informazioni aggiuntive su operazioni, parametri e risposte.

Nota

È possibile accedere alle tabelle Customer Insights - Data anche utilizzando le API Dataverse. Ti consigliamo di utilizzare le API Dataverse per eseguire query sui dati di Customer Insights poiché offrono filtri più estesi, maggiore velocità effettiva e minore latenza. Per altre informazioni, vedi API Dataverse per Customer Insights.

Iniziare a provare le API

Un amministratore deve abilitare l'accesso API ai tuoi dati. Una volta abilitato l'accesso, qualsiasi utente può utilizzare l'API con la chiave di abbonamento.

  1. Accedi a Customer Insights - Data o iscriviti per una versione di prova di Customer Insights.

  2. Vai a Impostazioni>Autorizzazioni e seleziona la scheda API.

  3. Se l'accesso API all'ambiente non è stato configurato, seleziona Abilita.

    L'abilitazione delle API crea una chiave di sottoscrizione primaria e secondaria per l'ambiente che viene utilizzato nelle richieste API. Per rigenerare le chiavi, seleziona Rigenera primaria o Rigenera secondaria nella scheda API.

  4. Seleziona Esplora le nostre API per provare le API.

  5. Cerca e seleziona un'operazione API e seleziona Prova.

    Come testare le API.

  6. Nel riquadro laterale imposta il valore nel menu a discesa Autorizzazione su implicito. L'intestazione Authorization viene aggiunta con un token di connessione. La chiave di sottoscrizione è popolata automaticamente.

  7. Se lo si desideri, aggiungi tutti i parametri di query necessari.

  8. Scorri fino alla fine del riquadro laterale e seleziona Invia.

    La risposta HTTP viene visualizzata nella parte inferiore del riquadro.

Creare una nuova registrazione di app nel portale di Azure

Crea una nuova registrazione app per usare le API in un'applicazione Azure utilizzando autorizzazioni delegate.

  1. Completa la sezione introduttiva.

  2. Accedi al portale di Azure con l'account che può accedere ai dati di Customer Insights.

  3. Cerca e seleziona Registrazioni app.

  4. Seleziona Nuova registrazione, immetti un nome per l'applicazione e scegli il tipo di account.

    Se lo desideri, aggiungi un URL di reindirizzamento. http://localhost è sufficiente per sviluppare un'applicazione nel computer locale.

  5. Selezionare Registrazione.

  6. Nella nuova registrazione, seleziona Autorizzazioni API.

  7. Seleziona Aggiungi un'autorizzazione e seleziona Dynamics 365 AI per Customer Insights nel riquadro laterale.

  8. Per Tipo di autorizzazione seleziona Autorizzazioni delegate, quindi l'autorizzazione user_impersonation.

  9. Selezionare Aggiungi autorizzazioni.

  10. Seleziona Concedi consenso amministratore per... per completare la registrazione.

  11. Per accedere all'API senza che un utente abbia effettuato l'accesso, vai a Imposta le autorizzazioni delle applicazioni da server a server.

Puoi utilizzare l'ID applicazione/client per questa registrazione con la libreria MSAL (Microsoft Authentication Library) per ottenere un token di connessione da inviare con la richiesta all'API.

Per informazioni sull'utilizzo delle API nelle librerie client, vedi Librerie client di Customer Insights.

Impostare le autorizzazioni delle applicazioni da server a server

Creare una registrazione di un'app che non richiede l'interazione dell'utente e che può essere eseguita su un server.

  1. Nella registrazione dell'app nel portale di Azure, seleziona Autorizzazioni API.

  2. Seleziona Aggiungi autorizzazione.

  3. Seleziona la scheda API utilizzate dall'organizzazione e scegli Dynamics 365 AI for Customer Insights dall'elenco.

  4. Per Tipo di autorizzazione seleziona Autorizzazione dell'applicazione, quindi l'autorizzazione api.access.

  5. Selezionare Aggiungi autorizzazioni.

  6. Torna a Autorizzazioni API per la registrazione dell'app.

  7. Seleziona Concedi consenso amministratore per... per completare la registrazione.

  8. Aggiungi il nome della registrazione app come utente in Customer Insights - Data.

    1. Apri Customer Insights - Data, vai a Impostazioni>Autorizzazioni e seleziona Aggiungi utenti.

    2. Cerca il nome della registrazione dell'app, selezionalo nei risultati della ricerca e seleziona Salva.

Query di esempio

Per un breve elenco di query di esempio OData per usare le API, vedi Esempi di query OData.

Librerie client di Customer Insights

Inizia a utilizzare le librerie client disponibili per le API Customer Insights - Data. Tutto il codice sorgente della libreria e le applicazioni di esempio sono disponibili nel repository GitHub.

C# NuGet

Usa le librerie del client C# da NuGet.org. Attualmente, il pacchetto è per i framework netstandard2.0 e netcoreapp2.0. Per ulteriori informazioni sul pacchetto NuGet, vedi Microsoft.Dynamics.CustomerInsights.Api.

Aggiungi la libreria client C# a un progetto C#

  1. In Visual Studio, apri la Gestione pacchetti NuGet per il progetto.

  2. Cerca Microsoft.Dynamics.CustomerInsights.Api.

  3. Seleziona Installa per aggiungere il pacchetto al progetto.

    In alternativa, esegui questo comando nella console di Gestione pacchetti NuGet: Install-Package -Id Microsoft.Dynamics.CustomerInsights.Api -Source nuget.org -ProjectName <project name> [-Version <version>]

Usare la libreria client C#

  1. Utilizza la libreria MSAL per ottenere un AccessToken usando la registrazione dell'app Azure esistente.

  2. Dopo aver eseguito correttamente l'autenticazione e l'acquisizione di un token, costruisci un nuovo HttpClient o utilizzane uno esistente con l'"Autorizzazione" DefaultRequestHeaders impostata su "Token di accesso" portante e Ocp-Apim-Subscription-Key impostato sulla chiave di sottoscrizione del tuo ambiente Customer Insights - Data.

    Reimposta l'intestazione Autorizzazione quando appropriato. Ad esempio, alla scadenza del token.

  3. Passa HttpClient nella costruzione del client CustomerInsights.

  4. Effettua chiamate con il client ai "metodi di estensione", ad esempio, GetAllInstancesAsync. Se l'accesso al Microsoft.Rest.HttpOperationResponse sottostante è preferibile, utilizza i "metodi di messaggio http", ad esempio GetAllInstancesWithHttpMessagesAsync.

  5. La risposta è probabilmente di tipo object poiché il metodo può restituire più tipi (ad esempio, IList<InstanceInfo> e ApiErrorResult). Per controllare il tipo restituito, utilizza gli oggetti nei tipi di risposta specificati in Pagina dei dettagli dell'API per quell'operazione.

    Se sono necessarie ulteriori informazioni sulla richiesta, utilizza i metodi di messaggio http per accedere all'oggetto risposta non elaborato.

Pacchetto NodeJS

Utilizza le librerie client NodeJS disponibili tramite NPM: https://www.npmjs.com/package/@microsoft/customerinsights

Pacchetto Python

Utilizza le librerie client Python disponibili tramite PyPi: https://pypi.org/project/customerinsights/