OData 查詢範例

注意

也可以使用 Dataverse API 存取 Customer Insights - Data 資料表。 由於 Dataverse API 提供更廣泛的篩選、更高的輸送量和更低的延遲，因此建議您用來查詢 Customer Insights 資料。 如需詳細資訊，請參閱 Customer Insights 的 Dataverse API。

開放式資料通訊協定 (OData) 是建立在核心通訊協定 (例如 HTTP) 的資料存取通訊協定。 它使用普遍接受的方法 (例如網站的 REST)。 有多種可用來使用 OData 服務的程式庫和工具。

為了協助您根據 Dynamics 365 Customer Insights - Data API 建置自己的實作，請檢閱一些經常要求的範例查詢。

修改查詢範例，使其在目標環境中運作：

• {serviceRoot}：https://api.ci.ai.dynamics.com/v1/instances/{instanceId}，其中 {instanceId} 是您要查詢的 Customer Insights - Data 環境的 GUID。 ListAllInstances 作業可尋找您有權存取的 {InstanceId}。
• {CID}：整合客戶記錄的 GUID。 範例：ce759201f786d590bf2134bff576c369。
• {AlternateKey}：資料來源中，客戶記錄的主索引鍵識別碼。 範例: CNTID_1002
• {DSname}：包含資料來源的資料表名稱的字串，該資料來源已內嵌至 Customer Insights - Data。 範例：Website_contacts。
• {SegmentName}：包含 Customer Insights - Data 的客戶細分輸出資料表名稱的字串。 範例：Male_under_40。

客戶

對客戶資料表的範例查詢。

查詢類型	範例	注意
單一客戶識別碼	{serviceRoot}/data/Customer?$filter=CustomerId eq '{CID}'
其他索引鍵	{serviceRoot}/data/Customer?$filter={DSname_TableName_PrimaryKeyColumnName} eq '{AlternateKey}'	其他索引鍵會保留在統一客戶資料表中
選擇	{serviceRoot}/data/Customer?$select=CustomerId,FullName&$filter=customerid eq '1'
於	{serviceRoot}/data/Customer?$filter=CustomerId in ('{CID1}',’{CID2}’)
其他索引鍵 + In	{serviceRoot}/data/Customer?$filter={DSname_TableName_PrimaryKeyColumnName} in ('{AlternateKey}','{AlternateKey}')
搜尋	{serviceRoot}/data/Customer?$top=10&$skip=0&$search="string"	回傳搜尋字串的前 10 個結果
客戶細分成員資格	{serviceRoot}/data/Customer?select=*&$filter=IsMemberOfSegment('{SegmentName}')&$top=10	從客戶細分資料表中回傳預設的列數。
客戶的客戶細分成員資格	{serviceRoot}/data/Customer?$filter=CustomerId eq '{CID}'&IsMemberOfSegment('{SegmentName}')	如果使用者是指定客戶細分的成員，則傳回客戶設定檔

整合活動

對 UnifiedActivity 資料表的範例查詢：

查詢類型	範例	注意
CID 活動	{serviceRoot}/data/UnifiedActivity?$filter=CustomerId eq '{CID}'	列出特定客戶個人資料的活動
活動時間範圍	{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	時間範圍中的客戶個人資料活動
活動類型	{serviceRoot}/data/UnifiedActivity?$filter=CustomerId eq '{CID}' and ActivityType eq '{ActivityName}'
活動 (依顯示名稱)	{serviceRoot}/data/UnifiedActivity$filter=CustomerId eq ‘{CID}’ and ActivityTypeDisplay eq ‘{ActivityDisplayName}’
活動排序	{serviceRoot}/data/UnifiedActivity?$filter=CustomerId eq ‘{CID}’ & $orderby=ActivityTime asc	以遞增或遞減排序活動
客戶的所有活動與量值	{serviceRoot}/data/Customer?$expand=UnifiedActivity,Customer_Measure&$filter=CustomerId eq '{CID}'	活動和量值是回傳的客戶設定檔的額外索引鍵/值組

管理工作流程

與 Customer Insights - Data 中程序相關的範例查詢，例如重新整理資料來源、統整資料或取得統整工作狀態。

查詢類型	範例	注意
取得資料來源識別碼	{serviceRoot}/manage/datasources/v2	傳回環境中的所有資料來源。 在回應中，您可以檢查特定資料來源的 'friendlyName'，然後使用其 'dataSourceId'。
重新整理資料來源	{serviceRoot}/manage/workflows/main/jobs?operationType=Ingestion&identifiers='{dataSourceId}'&forceRunRequested=true	使用上述回應中的 'dataSourceId' 來重新整理資料來源。 這是 POST 要求。
執行完整重新整理	{serviceRoot}/manage/workflows/main/jobs?operationType=all&forceRunRequested=true	重新整理環境中的所有程序。 這是 POST 要求。
取得程序的狀態	{serviceRoot}/manage/workflows/main/jobs

其他範例

對其他資料表的範例查詢：

查詢類型	範例	注意
CID 的量值	{serviceRoot}/data/Customer_Measure?$filter=CustomerId eq '{CID}'
CID 擴充品牌	{serviceRoot}/data/BrandShareOfVoiceFromMicrosoft?$filter=CustomerId eq '{CID}'
CID 的興趣擴充	{serviceRoot}/data/InterestShareOfVoiceFromMicrosoft?$filter=CustomerId eq '{CID}'
In-子句 + 展開	{serviceRoot}/data/Customer?$expand=UnifiedActivity,Customer_Measure&$filter=CustomerId in ('{CID}', '{CID}')

限制

• 根據預設，Customer Insights API 最多會回傳 100 個物件。 您可以使用標準分頁技術，解析回傳的 100 個以上的物件。 或者，您也可以匯出資料 。

• 不支援下列查詢：

  • 在已擷取的來源資料表上進行 $filter。 您只能對 Customer Insights - Data 建立的系統資料表執行 $filter 查詢。
  • 從 $search 查詢進行 $expand。 例如：Customer?$expand=UnifiedActivity$top=10&$skip=0&$search="corey"。
  • 選取了屬性的子集時才能從 $select 進行 $expand。 例如：Customer?$select=CustomerId,FullName&$expand=UnifiedActivity&$filter=CustomerId eq '{CID}'。
  • 對指定客戶 $expand 擴充品牌或興趣相似性。 例如：Customer?$expand=BrandShareOfVoiceFromMicrosoft&$filter=CustomerId eq '518291faaa12f6d853c417835d40eb10'。
  • 透過其他索引鍵查詢預測模型輸出資料表。 例如：OOBModelOutputTable?$filter=HotelCustomerID eq '{AK}'。