Przykłady zapytań OData

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.

Open Data Protocol (OData) jest protokołem dostępu do danych zbudowanym na podstawowych protokołach, takich jak HTTP. Wykorzystuje powszechnie akceptowane metodologie, takie jak REST dla sieci. Istnieją różne rodzaje bibliotek i narzędzi, które mogą być używane do korzystania z usług OData.

Aby pomóc w budowaniu własnych implementacji na podstawie interfejsów API Dynamics 365 Customer Insights - Data, należy przejrzeć często wymagane przykładowe zapytania.

Musisz zmodyfikować próbki zapytań, aby działały na docelowych środowiskach:

• {serviceRoot}: https://api.ci.ai.dynamics.com/v1/instances/{instanceId} gdzie {instanceId} to identyfikator GUID środowiska Customer Insights - Data, do którego ma być zapytanie. Operacja ListAllInstances pozwala ci znaleźć {InstanceId}, do których masz dostęp.
• {CID}: GUID zunifikowanego rekordu klienta. Przykład: ce759201f786d590bf2134bff576c369.
• {AlternateKey}: Identyfikator klucza głównego rekordu klienta w źródle danych. Przykład: CNTID_1002
• {DSname}: ciąg zawierający nazwę tabeli źródło danych, których jest pozyskiwany do Customer Insights - Data. Przykład: Website_contacts.
• {SegmentName}: ciąg zawierający nazwę tabeli wyjściowej segmentu w Customer Insights - Data. Przykład: Male_under_40.

kliencie

Przykładowe zapytania dotyczące tabeli Klient.

Typ zapytania	Przykład	Uwaga
Identyfikator pojedynczego klienta	{serviceRoot}/data/Customer?$filter=CustomerId eq '{CID}'
Klucz alternatywny	{serviceRoot}/data/Customer?$filter={DSname_TableName_PrimaryKeyColumnName} eq '{AlternateKey}'	Klucze alternatywne są przechowywane w ujednoliconej tabeli klientów
Zaznacz	{serviceRoot}/data/Customer?$select=CustomerId,FullName&$filter=customerid eq '1'
Za	{serviceRoot}/data/Customer?$filter=CustomerId in ('{CID1}',’{CID2}’)
Klucz alternatywny + In	{serviceRoot}/data/Customer?$filter={DSname_TableName_PrimaryKeyColumnName} in ('{AlternateKey}','{AlternateKey}')
Wyszukiwanie	{serviceRoot}/data/Customer?$top=10&$skip=0&$search="string"	Zwraca 10 najlepszych wyników dla wyszukiwanego ciągu znaków
Członkostwo segmentu	{serviceRoot}/data/Customer?select=*&$filter=IsMemberOfSegment('{SegmentName}')&$top=10	Zwraca zadaną liczbę wierszy z tabeli segmentacji.
Członkostwo w segmentach dla klienta	{serviceRoot}/data/Customer?$filter=CustomerId eq '{CID}'&IsMemberOfSegment('{SegmentName}')	Zwraca profil klienta, jeśli użytkownik należy do danego segmentu

Ujednolicona aktywność

Przykładowe zapytania dotyczące tabeli UnifiedActivity.

Typ zapytania	Przykład	Uwaga
Aktywność CID	{serviceRoot}/data/UnifiedActivity?$filter=CustomerId eq '{CID}'	Listy działań dla określonego profilu klienta
Ramy czasowe działania	{serviceRoot}/data/UnifiedActivity?$filter=CustomerId eq '{CID}' and ActivityTime gt 2017-01-01T00:00:00.000Z and ActivityTime lt 2020-01-01T00:00:00.000Z	Aktywność profilu klienta w określonym przedziale czasu
Typ działania	{serviceRoot}/data/UnifiedActivity?$filter=CustomerId eq '{CID}' and ActivityType eq '{ActivityName}'
Aktywność według nazwy wyświetlanej	{serviceRoot}/data/UnifiedActivity$filter=CustomerId eq ‘{CID}’ and ActivityTypeDisplay eq ‘{ActivityDisplayName}’
Sortowanie działań	{serviceRoot}/data/UnifiedActivity?$filter=CustomerId eq ‘{CID}’ & $orderby=ActivityTime asc	Sortuj aktywności rosnąco lub malejąco
Wszystkie działania i miary dla klienta	{serviceRoot}/data/Customer?$expand=UnifiedActivity,Customer_Measure&$filter=CustomerId eq '{CID}'	Działania i miary to dodatkowe pary kluczowe/wartości w zwróconym profilu klienta

Zarządzanie przepływami pracy

Przykładowe zapytania dotyczące procesów w Customer Insights - Data, takie jak odświeżanie źródło danych, ujednolicenie danych lub uzyskiwanie stanu zadania ujednolicania.

Typ zapytania	Przykład	Uwaga
Pobierz identyfikatory źródła danych	{serviceRoot}/manage/datasources/v2	Zwraca wszystkie źródła danych w środowisku użytkownika. W odpowiedzi można sprawdzić pole „friendlyName” dla określonej wartości źródło danych a następnie użyć jej wartości „dataSourceId”.
Odśwież źródło danych	{serviceRoot}/manage/workflows/main/jobs?operationType=Ingestion&identifiers='{dataSourceId}'&forceRunRequested=true	Użyj powyższej odpowiedzi „dataSourceId”, aby odświeżyć źródło danych. To jest żądanie POST.
Uruchom pełne odświeżanie	{serviceRoot}/manage/workflows/main/jobs?operationType=all&forceRunRequested=true	Odświeża wszystkie procesy w środowisku. To jest żądanie POST.
Pobierz proces stanu	{serviceRoot}/manage/workflows/main/jobs

Inne przykłady

Przykładowe zapytania dotyczące innych tabel.

Typ zapytania	Przykład	Uwaga
Miary CID	{serviceRoot}/data/Customer_Measure?$filter=CustomerId eq '{CID}'
Wzbogacone marki CID	{serviceRoot}/data/BrandShareOfVoiceFromMicrosoft?$filter=CustomerId eq '{CID}'
Wzbogacone interesy CID	{serviceRoot}/data/InterestShareOfVoiceFromMicrosoft?$filter=CustomerId eq '{CID}'
In-Clause + Rozwiń	{serviceRoot}/data/Customer?$expand=UnifiedActivity,Customer_Measure&$filter=CustomerId in ('{CID}', '{CID}')

Ograniczenia

• Interfejs API funkcji Customer Insights zwraca domyślnie maksymalnie 100 obiektów. Korzystając ze standardowych technik stronicowania, można przećwiczyć ponad 100 zwróconych obiektów. Alternatywnie można wyeksportować dane.

• Następujące zapytania nie są obsługiwane:

  • $filter dla pozyskanych tabel źródłowych. Kwerendy można uruchamiać tylko $filter tabel systemowych, które tworzy Customer Insights - Data.
  • $expand z zapytania $search. Na przykład: Customer?$expand=UnifiedActivity$top=10&$skip=0&$search="corey".
  • $expand z $select, tylko jeśli wybrano podzbiór atrybutów. Na przykład: Customer?$select=CustomerId,FullName&$expand=UnifiedActivity&$filter=CustomerId eq '{CID}'.
  • $expand wzbogacona marka lub powiązania zainteresowań dla danego klienta. Na przykład: Customer?$expand=BrandShareOfVoiceFromMicrosoft&$filter=CustomerId eq '518291faaa12f6d853c417835d40eb10'.
  • Model przewidywania zapytań określa tabele wyjściowe za pomocą klucza alternatywnego. Na przykład: OOBModelOutputTable?$filter=HotelCustomerID eq '{AK}'.