集成帐户保护 API

2025-05-07

重要

自 2025 年 2 月 3 日起，Dynamics 365 欺诈保护不再可供购买。对欺诈保护的支持将于 2026 年 2 月 3 日结束。有关详细信息，请参阅终止支持 Dynamics 365 欺诈保护文章。

若要利用 Microsoft Dynamics 365 欺诈防护中的完整功能套件，请将事务数据发送到实时应用程序编程接口（API）。在评估体验阶段中，您可以分析使用Fraud Protection的结果。在保护体验中，还可以尊重基于已有配置的规则的决策。

根据选择使用欺诈保护的方式，可以使用不同的 帐户保护 API。例如 ，AccountCreation、 AccountLogin、 AccountCreationStatus、 AccountLoginStatus、 AccountUpdate 和 Label。

有关所有受支持的事件的信息，请参阅 Dynamics 365 欺诈保护 API。

设置

重要

若要完成初始 API 载入，你必须是 Azure 租户Microsoft中的全局管理员。

如果系统提示你接受这些条款和条件，请转到欺诈保护门户，登录并接受条款和条件。

此步骤可确保在 Azure 租户中正确配置欺诈保护。（在初始注册期间，你可能已经完成了此步骤。

创建Microsoft Entra 应用程序

重要

若要完成此步骤，你必须是 Azure 租户中的应用程序管理员、云应用程序管理员或全局管理员。

若要获取调用 API 所需的令牌，必须使用 Microsoft Entra 应用程序。可以使用欺诈保护中的 “实时 API ”页来配置这些应用。

配置 Microsoft Entra 应用：

在左侧导航窗格中，选择“ 配置”，然后选择 “实时 API”。
填写字段以创建应用。以下字段是必填字段：
- 应用程序显示名称 – 输入应用的描述性名称。最大长度为 93 个字符。
- 环境 – 选择生产终结点。
- 身份验证方法 – 选择证书还是密码（密码）用于身份验证。如果选择 “证书”，请选择 “选择文件 ”以上传公钥。获取令牌时，需要匹配的私钥。如果选择 “机密”，则会在创建应用后为你生成密码。
填写完字段后，选择“ 创建应用程序”。

确认页汇总了应用的名称和 ID，以及证书指纹或机密，具体取决于所选的身份验证方法。

重要

保存有关证书指纹或机密的信息以供将来参考。机密只显示一次。

可以根据需要创建任意数量的应用，以在生产环境中运行 API 调用。

若要创建另一个应用，请执行以下作：

选择“ 创建另一个应用程序”。
填写字段以创建应用，然后选择“ 创建应用程序”。

管理现有Microsoft Entra 应用程序

创建Microsoft Entra 应用后，可以通过 [Azure 门户]（https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps）管理它们。有关详细信息，请参阅 Azure 文档站点。

调用欺诈防护实时 API

使用本节中的信息将系统与欺诈保护集成。

所需的 ID 和信息

API 终结点 – 环境的 URI 显示在欺诈保护仪表板上的 “帐户信息 ”磁贴上。
目录（租户）ID – 目录 ID 是 Azure 中租户域的全局唯一标识符（GUID）。它显示在 Azure 门户和欺诈保护仪表板上的 “帐户信息 ”磁贴上。
应用程序（客户端）ID – 应用程序 ID 标识为调用 API 而创建的 Microsoft Entra 应用。可以在选择“实时 API”页上的“创建应用程序”后显示的确认页上找到此 ID。稍后还可以在 Azure 门户中 的应用注册 下找到它。将为每个创建的应用提供一个 ID。
证书指纹或机密 – 可以在选择“实时 API”页上的“创建应用程序”后显示的确认页上找到证书指纹或机密。
实例 ID - 实例 ID 是欺诈保护中环境的全局唯一标识符（GUID）。它将显示在欺诈保护仪表板上的 “集成 ”磁贴中。

生成访问令牌

必须生成此令牌，并为每个 API 调用提供该令牌。请注意，访问令牌的有效期有限。建议缓存并重复使用每个访问令牌，直到获取新的访问令牌。

以下 C# 代码示例提供了演示如何使用证书或机密获取令牌的示例。请使用您自己的信息替换占位符。

证书指纹

public async Task<string> AcquireTokenWithCertificateAsync()
{
    var x509Cert = CertificateUtility.GetByThumbprint("<Certificate thumbprint>");
    var clientAssertion = new ClientAssertionCertificate("<Client ID>", x509Cert);
    var context = new AuthenticationContext("<Authority URL. Typically https://login.microsoftonline.com/[Directory_ID]>");
    var authenticationResult = await context.AcquireTokenAsync("<API endpoint>", clientAssertion);

    return authenticationResult.AccessToken;
}

机密

public async Task<string> AcquireTokenWithSecretAsync()
{
    var clientAssertion = new ClientCredential("<Client ID>", "<Client secret>");
    var context = new AuthenticationContext("<Authority URL. Typically https://login.microsoftonline.com/[Directory_ID]>");
    var authenticationResult = await context.AcquireTokenAsync("<API endpoint>", clientAssertion);

    return authenticationResult.AccessToken;
}

响应

在后台，上述代码生成 HTTP 请求，并接收类似于以下示例的响应。

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: <date>
Content-Length: <content length>

{
    "token_type":"Bearer",
    "expires_in":"3599",
    "ext_expires_in":"3599",
    "expires_on":"<date timestamp>",
    "not_before":"<date timestamp>",
    "resource":"https://api.dfp.dynamics.com",
    "access_token":"<your access token; e.g.: eyJ0eXA...NFLCQ>"
}

有关详细信息，请参阅 Azure 文档：

调用 API

若要调用 API，请执行以下步骤。

在每个请求上传递以下所需的 HTTP 标头。

标题名称	标头值
授权	将此标头使用以下格式：Bearer accesstoken，其中 accesstoken 是 Microsoft Entra ID 返回的令牌。
x-ms-correlation-id	在每个共同进行的 API 调用集上发送一个新的 GUID 值。
x-ms-dfpenvid	发送实例 ID 的 GUID 值。

生成基于事件的有效负载。使用系统中的相关信息填写事件数据。有关所有受支持的事件的信息，请参阅 Dynamics 365 欺诈保护 API。
将头部（包括访问令牌）与负载合并，然后发送到您的欺诈保护终结点。

注释

如果创建新环境，请在集成期间在 API 标头中包含环境 ID，以便正确路由事务。

查看示例应用

有关其他参考，请查看示例商家应用，并查看随附的开发人员文档。示例应用提供了一个示例，演示如何实时调用欺诈保护 API。只要有可能链接，示例应用的文档将链接到实际示例代码。否则，代码示例将直接包含在文档中。

有关如何配置示例站点以便使用它的信息，请参阅 “配置示例站点”。