集成购买保护 API

重要

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

本文介绍如何在 Microsoft Dynamics 365 欺诈保护中集成实时应用程序编程接口（API）。

若要利用完整的欺诈防护功能，必须将交易数据发送到实时欺诈防护 API。 在评估体验中，发送交易数据使你能够分析使用欺诈保护的结果。 在保护体验中，还可以根据您配置的规则尊重并执行决策。

根据使用欺诈保护的方式，可以使用以下购买保护 API 的不同集：

• 购买
• 购买状态
• 银行活动
• 退款
• 退款
• 更新账户
• 标签

API 集成阶段

购买保护 API 的集成分三个阶段进行：

1. 通过使用欺诈保护创建 Microsoft Entra 应用程序。
2. 生成访问令牌。
3. 调用 API。

登录

重要

必须是 Azure 租户中的全局管理员才能完成初始登录。

访问要使用的每个环境的以下门户。 如果系统提示你登录，请接受条款和条件。

• 沙盒环境
• 生产环境 （在初始注册期间，你可能已在生产中完成了此步骤。

创建Microsoft Entra 应用程序

重要

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

若要获取调用 API 所需的令牌，必须配置和使用 Microsoft Entra 应用程序，如本部分所述。

配置 Microsoft Entra 应用程序

若要配置 Microsoft Entra 应用程序，请执行以下步骤。

1. 在欺诈保护门户的左侧导航窗格中，选择集成>创建 Microsoft Entra 应用程序>立即设置。

2. 完成页面以创建应用。 建议为要与欺诈保护集成的每个环境创建一个Microsoft Entra 应用程序。

3. 输入或选择以下必填字段的值：

   • 应用程序显示名称 – 为应用程序提供描述性名称。 最大长度为 93 个字符。
   • 身份验证方法 – 选择是要通过证书还是机密（密码）进行身份验证。

4. 如果选择了证书身份验证方法，请执行以下步骤：

   1. 选择选择文件 上传公钥。 （获取令牌时需要匹配的私钥。
   2. 选择 “机密 ”以在创建应用程序后自动生成密码。

5. 完成设置必填字段后，选择“ 创建应用程序”。 确认页根据所选的身份验证方法汇总了应用的名称、ID 和证书指纹或机密。

重要

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

创建另一个应用程序

若要创建另一个应用程序，请选择“ 创建另一个应用程序”。 可以根据需要创建任意数量的应用，以在每个环境中运行 API 调用。

管理现有Microsoft Entra 应用程序

创建Microsoft Entra 应用后，可以通过 [Azure 门户]（https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps）管理它们。 有关详细信息，请参阅 如何将应用程序添加到 Microsoft Entra ID 和原因。

生成访问令牌

若要安全地将系统与欺诈保护集成，请获取Microsoft Entra 令牌，并在每个 API 调用的标头中提供它。

注释

访问令牌的有效期限制为 60 分钟。 建议缓存并重复使用令牌，直到令牌即将过期。 然后，可以获取新的访问令牌。

获取令牌需要以下信息。

所需的 ID 和信息

• 环境 URI – 沙盒或生产环境的 URI 显示在欺诈保护门户中 API 管理页的“配置”选项卡上。
• 目录（租户）ID – 此 ID 是 Azure 中租户域的全局唯一标识符（GUID）。 它显示在 Azure 门户和欺诈保护门户的 API 管理页的“配置”选项卡上。
• 应用程序（客户端）ID – 此 ID 标识已创建的用于调用 API 的 Microsoft Entra 应用。 从 实时 API 确认页获取 ID，或稍后在 Azure 门户中 的应用注册 下找到 ID。 将为每个创建的应用提供一个 ID。
• 证书指纹或机密 – 从实时 API 确认页获取指纹或机密。
• 实例 ID – 此 ID 是欺诈保护中环境的 GUID。 它将显示在欺诈保护仪表板上的 “集成 ”磁贴中。

示例：演示如何使用证书或机密获取令牌的代码示例

以下 C# 代码示例提供了使用证书或机密获取令牌的示例。 用您的具体信息替换占位符。 对于这两个 C# 示例，需要导入 Microsoft.Identity.Client NuGet 包。

有关其他语言的示例，请参阅 https://aka.ms/aaddev。

使用应用 ID 和私钥获取访问令牌

/// <summary>
/// Gets an access token using an app ID and private certificate key.
/// </summary>
/// <param name="tenantId">Directory (tenant) ID, in GUID format</param>
/// <param name="clientId">Application (client) ID</param>
/// <param name="certPath">File path to the certificate file (pfx) used to authenticate your application to Microsoft Entra ID</param>
/// <param name="certPassword">Password to access to the certificate file's private key</param>
public async Task<string> AcquireTokenWithCertificate(string tenantId, string clientId, string certPath, string certPassword)
{
    var certificate = new X509Certificate2(certPath, certPassword);

    var app = ConfidentialClientApplicationBuilder.Create(clientId)
            .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
            .WithCertificate(certificate)
            .Build();

    var scopes = new string[] { "<API endpoint for INT or PROD>; should be https://api.dfp.microsoft-int.com/.default or https://api.dfp.microsoft.com/.default" };

    try
    {
        var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
        return result.AccessToken;
    }
    catch (MsalServiceException ex)
    {
        //Handle authentication exceptions
        throw ex;
    }
}

使用应用 ID 和机密获取访问令牌

/// <summary>
/// Gets an access token using an app ID and secret.
/// </summary>
/// <param name="tenantId">Directory (tenant) ID, in GUID format</param>
/// <param name="clientId">Application (client) ID</param>
/// <param name="clientSecret">The secret (password) used to authenticate the client (application) ID</param>
public async Task<string> AcquireTokenWithSecret(string tenantId, string clientId, string clientSecret)

{
    var app = ConfidentialClientApplicationBuilder.Create(clientId)
            .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
            .WithClientSecret(clientSecret)
            .Build();

    var scopes = new string[] { "<API endpoint for INT or PROD>; should be https://api.dfp.microsoft-int.com/.default or https://api.dfp.microsoft.com/.default" };

    try
    {
        var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
        return result.AccessToken;
    }
    catch (MsalServiceException ex)
    {
        //Handle authentication exceptions
        throw ex;
    }
}

每个情况下的 AuthenticationResult 对象都包含 AccessToken 值和 一个 ExpiresOn 属性，该属性指示令牌何时失效。

• POST 请求到：

  • https://login.microsoftonline.com/<Microsoft Entra tenant ID>/oauth2/token

• 标头：

  • 内容类型：application/x-www-form-urlencoded（应用/x-www-form-urlencoded格式）

• 正文（键值）：

  • grant_type：client_credentials
  • client_id：{上一步骤中的客户端 ID}
  • client_secret: {上一步的密钥}
  • 资源： https://api.dfp.microsoft.com （对于 int， https://api.dfp.microsoft-int.com）

• 响应：

  • 使用响应中 access_token 的值作为下一步。

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

• Microsoft身份验证库（MSAL）概述
• 使用 Microsoft 身份验证库(MSAL)获取和缓存令牌

调用 API

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

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

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

2. 生成基于事件的有效负载。 使用系统中的相关信息填写事件数据。 有关所有受支持的事件的文档，请参阅 Dynamics 365 欺诈防护 API。

3. 将头部（包括访问令牌）与负载合并，然后发送到您的欺诈保护终结点。

   • POST 请求到：

     • <Base URL>/v1.0/merchantservices/events/purchase

   • 标头：

     • x-ms-correlation-id： {一个GUID（全局唯一标识符），每个请求必须唯一}
     • content-type：application/json
     • 授权：{上一步骤中的令牌}
     • x-ms-dfpenvid： {目标环境的环境 ID}

   • 身体：

     • 从共享 Swagger 页获取示例帐户保护请求正文。

注释

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

API 调用中的 x-ms-dfpenvid 可以接受以下选项，并且行为相同。

• 对要调用的环境使用环境 ID。 ID 列在集成页面的环境 ID字段中。
• 使用完整的客户 API ID路径，从根目录到您正在调用的子环境，并使用正斜杠（/）作为分隔符。 例如 /primary/XYZ。
• 使用完整路径，通过正斜杠 (/) 作为分隔符，从根目录连接到您要调用的子环境的环境 ID 或客户 API ID。 例如7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ。

若要在创建环境时指定客户 API ID，请参阅文章“ 管理环境”。

最佳做法

• 每个Microsoft Entra 令牌的有效期为 60 分钟。 建议将其缓存较短时间，并重复使用。
• 确保 HttpClient 具有保持连接。
• 始终传递 x-ms-dfpenvid 标头，并确保它指向您要代为处理交易的商家的环境。
• 将机密存储在秘密储存库中。
• 始终传递 x-ms-correlation-id 标头，以便将来进行反欺诈保护的调试会话。
• 确保 x-ms-correlation-id 标头对于每个发送到欺诈防护系统的事务都是唯一的。 

查看示例应用

有关其他参考，可以查看 示例商家应用 和随附的开发人员文档。 示例应用提供了如何调用欺诈保护 API 的示例，包括实时发送客户帐户更新、退款和退款等 API 事件。 每当可能提供此类链接时，示例应用的文档都链接到实际示例代码。 否则，代码示例直接存在于文档中。

有关如何配置示例站点以供使用的指导，请参阅 “配置示例站点”。