Praca z interfejsami API Customer Insights - Data

Dynamics 365 Customer Insights - Data oferuje interfejsy API do tworzenia własnych aplikacji na podstawie danych z aplikacji Customer Insights. Szczegółowe informacje o tych interfejsach API są podane w odwołaniach do interfejsów API. Zawierają one dodatkowe informacje na temat operacji i parametrów oraz odpowiedzi.

Uwaga

Tabele Customer Insights - Data są również dostępne za pomocą interfejsów Dataverse API. Zaleca się użycie interfejsów API Dataverse do przesyłania zapytań o dane Customer Insights, ponieważ oferują bardziej szczegółowe filtrowanie, większą wydajność i mniejsze opóźnienie. Więcej informacji można znaleźć w Dataverse API w Customer Insights.

Rozpoczynanie korzystania z interfejsów API

Administrator musi włączyć dostęp interfejsu API do danych. Po włączeniu dostępu każdy użytkownik może używać interfejsu API z kluczem subskrypcji.

1. Zaloguj się do Customer Insights - Data lub zaloguj się, aby uzyskać dostęp do próbnej wersji programu Customer Insights.

2. Przejdź do pozycji Ustawienia>Uprawnienia i wybierz kartę Interfejsy API.

3. Jeśli dostęp interfejsu API do środowiska nie został ustawiony, wybierz opcję Włącz.

   Włączenie interfejsów API powoduje utworzenie podstawowego i pomocniczego klucza subskrypcji dla środowiska używanego w żądaniach interfejsów API. Możesz ponownie wygenerować klucze, wybierając Regeneruj podstawową lub Regeneruj drugorzędną na karcie Interfejsy API.

4. Zaznacz opcję Poznaj nasze interfejsy API w celu wypróbowania interfejsów API.

5. Wyszukaj i wybierz operację interfejsu API i wybierz opcję Wypróbuj.

   

6. W okienku bocznym ustaw wartość w menu rozwijaną Autoryzacja na niejawna. Nagłówek Authorization jest dodawany z tokenem elementu nośnego. Klucz subskrypcji zostanie wypełniony automatycznie.

7. Można też dodać wszystkie wymagane parametry zapytania.

8. Przewiń w dół do końca okienka bocznego i wybierz opcję Wyślij.

   Odpowiedź HTTP zostanie wyświetlona u dołu okienka.

Utwórz nową rejestrację aplikacji w witrynie Azure Portal

Utwórz nową rejestrację aplikacji, aby używać interfejsów API w aplikacji Azure, używając uprawnień delegowanych.

1. Wykonaj czynności z sekcji Wprowadzenie.

2. Zaloguj się w witrynie Azure Portal, korzystając z konta, które może mieć dostęp do danych Customer Insights.

3. Wyszukaj i wybierz Rejestracje aplikacji.

4. Wybierz Nowa rejestracja, podaj nazwę aplikacji i wybierz typ konta.

   Opcjonalnie dodaj przekierowanie. http://localhost jest wystarczający do projektowania aplikacji na komputerze lokalnym.

5. Wybierz pozycję Zarejestruj.

6. W nowej rejestracji aplikacji przejdź do uprawnienia interfejsu API.

7. Wybierz opcję Dodaj uprawnienie i w okienku bocznym wybierz pozycję AI usługi Dynamics 365 for Customer Insights.

8. Dla Typu uprawnienia wybierz Uprawnienia delegowane, a następnie wybierz uprawnienie user_impersonation.

9. Wybierz Przyznaj uprawnienia.

10. Wybierz opcję Udziel administratorowi zgodę na..., aby zakończyć rejestrację aplikacji.

11. Aby uzyskać dostęp do interfejsu API bez logowania użytkownika, przejdź do Ustawianie uprawnień aplikacji serwer-serwer.

Możesz użyć identyfikatora aplikacji/klienta do rejestracji tej aplikacji z biblioteką uwierzytelniania firmy Microsoft (MSAL), aby uzyskać token okaziciela do wysłania z żądaniem do interfejsu API.

Aby uzyskać więcej informacji na temat korzystania z interfejsów API w naszych bibliotekach klienckich, zobacz biblioteki klienckie aplikacji Customer Insights.

Ustawianie uprawnień aplikacji między serwerami

Stwórz aplikację rejestracyjną, która nie wymaga interakcji z użytkownikiem i może być uruchomiona na serwerze.

1. W rejestracji aplikacji w portalu Azure Portal wybierz opcję uprawnienia interfejsu API.

2. Wybierz Dodaj uprawnienie.

3. Wybierz z listy interfejsy API używane przez organizację i wybierz pozycję Dynamics 365 AI dla Customer Insights.

4. Dla Typu uprawnienia wybierz Uprawnienia aplikacji , a następnie wybierz uprawnienie api.access.

5. Wybierz Przyznaj uprawnienia.

6. Aby zobaczyć rejestrację aplikacji wróć do uprawnienia interfejsu API.

7. Wybierz opcję Udziel administratorowi zgodę na..., aby zakończyć rejestrację aplikacji.

8. Dodaj nazwę rejestracji aplikacji jako użytkownika w Customer Insights - Data.

   1. Otwórz Customer Insights - Data, przejdź do menu Ustawienia>Uprawnienia i wybierz opcję Dodaj użytkowników.

   2. Wyszukaj nazwę rejestracji swojej aplikacji, wybierz ją z listy wyników wyszukiwania i wybierz pozycję Zapisz.

Przykładowe zapytania

Zebraliśmy krótką listę przykładowych zapytań OData, które mogą współpracować z interfejsami API, zobacz Przykłady zapytań OData.

Biblioteki klientów Customer Insights

Wprowadzenie do bibliotek klientów dostępnych dla interfejsów API Customer Insights - Data. Cały kod źródłowy i przykładowe aplikacje z biblioteki można znaleźć na stronie repozytorium GitHub.

C# NuGet

Użyj bibliotek klienta C# z NuGet.org. Obecnie pakiet jest przeznaczony dla frameworków netstandard2.0 i netcoreapp2.0. Aby uzyskać więcej informacji na temat pakietu NuGet, zobacz Microsoft.Dynamics.CustomerInsights.Api.

Dodawanie biblioteki klienta C# do projektu C#

1. W Visual Studio otwórz Menedżera pakietów NuGet dla swojego projektu.

2. Wyszukaj Microsoft.Dynamics.CustomerInsights.Api.

3. Wybierz Zainstaluj, aby dodać pakiet do projektu.

   Można też uruchomić to polecenie w konsoli Menedżer pakietów NuGet: Install-Package -Id Microsoft.Dynamics.CustomerInsights.Api -Source nuget.org -ProjectName <project name> [-Version <version>]

Korzystanie z biblioteki klienta C#

1. Użyj biblioteki uwierzytelniania firmy Microsoft (MSAL), aby uzyskać możliwość AccessToken za pomocą istniejącej rejestracji aplikacji Azure.

2. Po pomyślnym uwierzytelnieniu i nabyciu tokenu stwórz nowy lub użyj istniejącego HttpClient z DefaultRequestHeaders "Autoryzacja" ustawionym na Nosiciel "tokenu dostępu" i Ocp-Apim-Subscription-Key ustawiony na klucz subskprycji ze środowiska Customer Insights - Data.

   Nagłówek Autoryzacji jest resetowany w zależności od potrzeb. Na przykład ważność tokenu wygasła.

3. Przekaż HttpClient do konstrukcji klienta CustomerInsights.

4. Wywołaj z klientem „metody rozszerzające”, na przykład GetAllInstancesAsync. Jeśli preferowany jest dostęp do bazowego Microsoft.Rest.HttpOperationResponse, użyj „metod wiadomości http”, na przykład GetAllInstancesWithHttpMessagesAsync.

5. Odpowiedź będzie prawdopodobnie typu object, ponieważ metoda może zwracać wiele typów (na przykład IList<InstanceInfo> i ApiErrorResult). Aby sprawdzić typ zwrotu, używasz obiektów w typach odpowiedzi określonych na stronie Szczegóły API dla tej operacji.

   Jeśli potrzeba więcej informacji na temat żądania, użyj metod wiadomości http, aby uzyskać dostęp do surowego obiektu odpowiedzi.

Pakiet NodeJS

Korzystaj z bibliotek klientów NodeJS dostępnych za pośrednictwem NPM: https://www.npmjs.com/package/@microsoft/customerinsights

Pakiet języka Python

Korzystaj z bibliotek klientów Python dostępnych za pośrednictwem PyPi: https://pypi.org/project/customerinsights/