使用 Customer Insights - Data API

  • 项目

Dynamics 365 Customer Insights - Data 提供 API 以基于 Customer Insights 中的数据生成您自己的应用程序。 这些 API 的详细信息将在 API 参考中列出。 其中包括有关操作、参数和响应的其他信息。

备注

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

开始试用 API

管理员必须启用对您的数据的 API 访问权限。 启用访问后，任何用户都可以通过订阅密钥使用 API。

  1. 登录到 Customer Insights - Data 或注册 Customer Insights 试用。

  2. 转到设置>权限，然后选择 API 选项卡。

  3. 如果尚未设置对环境的 API 访问，请选择启用。

    启用 API 可为在 API 请求中使用的环境创建主要和辅助订阅密钥。 要重新生成密钥，在 API 选项卡上选择重新生成主密钥或重新生成辅助密钥。

  4. 选择浏览我们的 API 试用 API。

  5. 搜索并选择一个 API 操作，然后选择试用。

    如何测试 API。

  6. 在侧边窗格中，将授权下拉菜单中的值设置为隐式。 Authorization 标头中将添加持有者令牌。 将自动填充您的订阅密钥。

  7. 可以选择添加所有必要的查询参数。

  8. 滚动到侧窗格底部并选择发送。

    HTTP 响应显示在窗格底部。

在 Azure 门户中创建新的应用注册

创建新的应用注册来使用委托的权限在 Azure 应用程序中使用 API。

  1. 完成“入门”一节。

  2. 使用可访问 Customer Insights 数据的帐户登录到 Azure 门户。

  3. 进行搜索，然后选择应用注册。

  4. 选择新注册，提供应用程序名称并选择帐户类型。

    可以选择添加重定向 URL。 http://localhost 足以在您的本地计算机上开发应用程序。

  5. 选择注册。

  6. 在您的新应用注册上，转到 API 权限。

  7. 选择添加权限，然后在侧窗格中选择 Dynamics 365 AI for Customer Insights。

  8. 对于权限类型，选择委托的权限，然后选择 user_impersonation 权限。

  9. 选择添加权限。

  10. 选择对其授予管理员同意以完成应用注册。

  11. 要在无需用户登录的情况下访问 API，请转到设置服务器到服务器应用程序权限。

您可以结合使用此应用注册的应用程序/客户端 ID 与 Microsoft 身份验证库 (MSAL)，获取持有者令牌以发送您的 API 请求。

有关在客户端库中使用 API 的信息，请参阅 Customer Insights 客户端库。

设置服务器到服务器应用程序权限

创建不需要用户交互并且可在服务器上运行的应用注册。

  1. 在 Azure 门户中的应用注册上，转到 API 权限。

  2. 选择添加权限。

  3. 选择我的组织使用的 API 选项卡，然后从列表中选择适用于 Customer Insights 的 Dynamics 365 KPI。

  4. 对于权限类型，选择应用程序权限，然后选择 api.access 权限。

  5. 选择添加权限。

  6. 对于您的应用注册，返回到 API 权限。

  7. 选择对其授予管理员同意以完成应用注册。

  8. 在 Customer Insights - Data 中作为用户添加应用注册的名称。

    1. 打开 Customer Insights - Data，转到设置>权限，选择添加用户。

    2. 搜索您的应用注册的名称，从搜索结果中选择它，然后选择保存。

示例查询

有关使用 API 的 OData 示例查询的简短列表，请参阅OData 查询示例。

Customer Insights 客户端库

开始使用可用于 Customer Insights - Data API 的客户端库。 所有库源代码和示例应用程序都可以在 GitHub 存储库上找到。

C# NuGet

使用 NuGet.org 中的 C# 客户端库。当前，此包针对的是 netstandard2.0 和 netcoreapp2.0 框架。 有关 NuGet 包的更多信息，请参阅 Microsoft.Dynamics.CustomerInsights.Api。

将 C# 客户端库添加到 C# 项目

  1. 在 Visual Studio 中，为您的项目打开 NuGet 包管理器。

  2. 搜索 Microsoft.Dynamics.CustomerInsights.Api。

  3. 选择安装以将包添加到项目。

    或者，在 NuGet 包管理器控制台中运行此命令：Install-Package -Id Microsoft.Dynamics.CustomerInsights.Api -Source nuget.org -ProjectName <project name> [-Version <version>]

使用 C# 客户端库

  1. 使用 Microsoft 身份验证库 (MSAL) 以使用现有的 Azure 应用注册获取 AccessToken。

  2. 成功验证并获取令牌后，构建一个新的或使用现有的 HttpClient，并将 DefaultRequestHeaders“授权”设置为持有者“访问令牌”，将 Ocp-Apim-Subscription-Key 设置为 Customer Insights - Data 环境中的订阅密钥。

    根据需要重置授权标头。 例如，当令牌到期时。

  3. 将此 HttpClient 传递到 CustomerInsights 客户端的构造中。

  4. 使用客户端调用“扩展方法”，例如 GetAllInstancesAsync。 如果首选访问基础 Microsoft.Rest.HttpOperationResponse，请使用“http 消息方法”，例如 GetAllInstancesWithHttpMessagesAsync。

  5. 响应可能是 object 类型，因为该方法可以返回多个类型（例如 IList<InstanceInfo> 和 ApiErrorResult）。 要检查返回类型，可以针对该操作使用 API 详细信息页上指定的响应类型中的对象。

    如果需要有关请求的详细信息，请使用 http 消息方法访问原始响应对象。

NodeJS 程序包

使用通过 NPM 提供的 NodeJS 客户端库：https://www.npmjs.com/package/@microsoft/customerinsights

Python 程序包

使用通过 PyPi 提供的 Python 客户端库：https://pypi.org/project/customerinsights/