集成购买保护 API

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

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

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

• 购买
• PurchaseStatus
• BankEvent
• 回充
• 退款
• UpdateAccount
• Label

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_MicrosoftEntra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps）管理它们。 有关详细信息，请参阅如何以及为何将应用程序添加到 Microsoft Entra ID。

生成访问令牌

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

注意

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

获取令牌需要以下信息。

所需的 ID 和信息

• 环境 URI – 沙盒或生产环境的 URI 显示在欺诈保护门户中API 管理页的“配置”选项卡上。
• 目录（租户）ID – 此 ID 是 Azure 中租户域的全局唯一标识符（GUID）。 它显示在“欺诈保护”门户的“API 管理”页的“Azure 门户”和“配置”选项卡上。
• 应用程序（客户端）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

• 标头：

  • Content-type：application/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： {A GUID，每个请求必须唯一}
     • content-type: application/json
     • 授权：{上一步骤中的令牌}
     • x-ms-dfpenvid： {目标环境的环境 ID}

   • 正文：

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

注意

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

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

• 对要调用的环境使用环境 ID。 ID 列在“环境 ID”字段中的“集成”页上。
• 使用从根目录到所调用的子环境（使用正斜杠（/）作为分隔符，使用客户 API ID 的完整 pat。 例如 /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 事件。 每当可能提供此类链接时，示例应用的文档都链接到实际示例代码。 否则，代码示例直接存在于文档中。

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