OData 查询示例

备注

还可以使用 Dataverse API 访问 Customer Insights - Data 表。 我们建议您使用 Dataverse API 来查询 Customer Insights 数据，因为它们提供更大范围的筛选、更大的吞吐量和更低的延迟。 有关详细信息，请参阅 Customer Insights 的 Dataverse API。

Open Data Protocol (OData) 是一种基于 HTTP 等核心协议构建的数据访问协议。 它使用普遍接受的方法，例如适用于 Web 的 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。

客户

客户表的示例查询。

查询类型	示例	备注
单个客户 ID	{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 中的流程相关的示例查询，如刷新数据源、统一数据或获取统一作业的状态。

查询类型	示例	备注
获取数据源 ID	{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}'。