外部调用

项目
02/27/2025

重要

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

通过外部调用，可以从 Microsoft Dynamics 365 Fraud Protection 外部的 API 引入数据，然后使用这些数据实时做出明智的决策。例如，第三方地址和电话验证服务，或你自己的自定义评分模型，可能会提供关键输入，帮助确定某些事件的风险水平。通过使用外部调用，可以连接到任何 API 终结点，根据需要从规则内向该终结点发出请求，并使用来自该终结点的响应做出决策。

注意

如果所有事件都需要这些额外的数据，你也可以将其作为评估架构的一部分发送。有关如何将自定义数据作为 API 请求的一部分发送的详细信息，请参阅自定义数据示例。

可用于外部调用的 API 类型

在创建外部调用之前，应了解以下限制：

Fraud Protection 目前仅支持以下身份验证方法：匿名和 AAD。
Fraud Protection 目前仅支持以下 HTTP 方法：GET 和 POST。

创建外部调用

在 Fraud Protection 门户的左侧导航中，选择外部调用，然后选择新建外部调用。
根据需要查看并设置以下字段。
- 名称 – 输入你将用于从规则中引用外部调用的名称。名称只能包含数字、字母和下划线。不能以数字开头。
  
  注意
  
  在规则中使用外部调用后，无法更改其名称。
- 说明 – 添加说明，帮助团队快速识别外部调用。
- Web 请求 – 选择适当的 HTTP 方法（GET 或 POST），然后输入 API 终结点。
  
  注意
  
  仅支持 HTTPS 终结点。
- 启用定期预热调用 - 如果发往外部调用终结点的流量太低，则连接可能会冷，并可能会增加来自外部服务的响应延迟。若要缓解此问题，请从外部调用设置页启用预热调用。使用切换开关启用预热调用。需要提供有效的 GET 保持连接 URL。与主终结点一样，保持连接终结点还必须通过测试连接。如果将外部调用配置为启用了预热调用，则当流量降至过低时，Fraud Protection 将仅使用 GET 方法自动对保持连接终结点进行匿名预热调用。
  
  注意
  
  预热调用中不能使用任何参数、配置或可配置标头。
- 身份验证 – 选择用于对传入请求进行身份验证的方法。
  - 如果选择匿名，则不会发送授权标头。
  - 如果选择 AAD，则会在租户中生成 Azure Active Directory (Azure AD) 令牌，并将持有者 <令牌>用作授权标头。
  有关身份验证、授权和 Azure AD 令牌的详细信息，请参阅本文后面的了解身份验证和授权部分。
- 访问群体 - 如果选择 AAD 作为身份验证方法，系统会要求提供访问群体。可以使用现有的 Azure 应用程序作为访问群体，也可以通过 Fraud Protection 门户中的集成体验创建新的访问群体。确保访问群体有权访问外部调用/服务。若要了解有关如何配置 Azure Active Directory (Azure AD) 身份验证的详细信息，请参阅配置 Azure AD 身份验证。
- 应用程序 ID – 还需要提供 Fraud Protection 订阅租户中新的或现有的 Azure AD 应用程序的应用程序 ID。在 Azure 密钥保管库中生成证书。 Fraud Protection 应用应具有对此 Azure 密钥保管库的读取访问权限。将证书加载到此 Azure AD 应用程序。有关如何创建和管理 Azure AD 应用程序的详细信息，请参阅创建 Azure Active Directory 应用程序。
- 证书 URL – 提供来自 Azure 密钥保管库的证书标识符 URL。这与你在上一步中加载到 Azure AD 应用的证书相同。有关如何在 Azure 密钥保管库中生成证书的详细信息，请参阅在 Azure 密钥保管库中创建和合并证书签名请求
- 添加参数 – 可以使用参数将数据从 Fraud Protection 传递到 API 终结点。根据所选的 HTTP 方法，这些参数将在查询字符串中或作为请求正文的一部分发送到终结点。
  
  可以为每个参数添加示例值。 Fraud Protection 使用这些参数值在创建之前或选择测试时对终结点进行示例调用。
  
  注意
  
  所有参数值都解释为字符串。
- 示例请求 – 提供一个发送到外部调用的请求示例。请求应反映指定的参数名称和值，并且不能编辑。
  
  对于 GET 方法，将显示请求 URL。对于 POST 方法，将显示请求正文。
  
  示例请求用于在创建之前或选择测试时对终结点进行示例调用。
- 示例响应 – 提供 API 终结点成功响应中返回的数据示例。此数据应采用 JavaScript 对象表示法 (JSON) 格式，并可在规则中引用。在此处提供的示例将在创建规则时显示。
  
  选择测试可在此字段中自动输入来自 API 的实际响应。
- 超时 – 指定请求在超时之前应等待多长时间（以毫秒为单位）。必须指定介于 1 到 5000 之间的数字。
- 默认响应 – 指定在请求失败或超过指定超时时应返回的默认响应。该值必须是有效的 JSON 对象或 JSON 元素。
可选：若要向 API 终结点发送示例请求并查看响应，请选择测试。有关详细信息，请参阅下一部分：测试外部调用。
设置完必填字段后，选择创建。

测试外部调用

为确保 Fraud Protection 可以连接到终结点，请随时测试连接。

若要在创建新的外部调用或编辑现有外部调用时测试连接，请设置所有必填字段，然后选择测试。

Fraud Protection 使用你提供的终结点和参数将请求发送到外部调用。
- 如果 Fraud Protection 成功到达目标终结点，面板顶部会出现一个绿色消息栏，通知你连接成功。若要查看完整响应，请选择查看响应详细信息。
- 如果 Fraud Protection 无法访问目标终结点，或者在指定的超时之前没有收到响应，面板顶部会出现一个红色消息栏，显示遇到的错误。若要查看有关错误的详细信息，请选择查看错误详细信息。

监视外部调用

在 Fraud Protection 门户中监视外部调用

Fraud Protection 显示一个磁贴，其中包含你定义的每个外部调用的三个指标：

每秒请求数 – 所选时间范围内的请求总数除以总分钟数。
平均延迟 – 请求延迟总数除以所选时间范围内的总分钟数。
成功率 – 成功请求的总数除以发出的请求总数。

此磁贴上显示的数字和图表仅包括你在页面右上角的下拉列表中选择的时间范围的数据。

注意

仅当外部调用在活动规则中使用时，才会显示指标。

若要深入了解有关外部调用的数据，请选择磁贴右侧的性能。

Fraud Protection 显示一个新页面，其中包含更详细的指标视图。
若要查看过去三个月中任何时间范围的指标，请调整页面顶部的日期范围设置。

除了前面所述的三个指标外，还会显示一个错误图表。此图表按错误类型和代码显示错误数。若要查看一段时间内的错误计数，或查看错误分布，请选择饼图。

除了 HTTP 客户端错误（400、401 和 403），你可能还会看到以下错误：

无效的应用程序 ID – 提供的应用程序 ID 在租户中不存在，或者无效。
AAD 故障 - 无法检索 Azure AD 令牌。
未找到定义 – 外部调用已被删除，但它仍在规则中被引用。
超时 – 对目标的请求花费的时间超过了指定的超时时间。
通信失败 – 由于网络问题或目标不可用，无法连接到目标。
断路器 – 如果外部调用连续失败并超过某个阈值，则所有后续调用将暂停一段时间。
未知失败 - 发生了内部 Dynamics 365 失败。

使用事件跟踪来监视外部调用

可以使用 Fraud Protection 的事件跟踪功能将与外部调用相关的事件转发到你自己的 Azure 事件中心或 Azure Blob 存储实例。在 Fraud Protection 门户的事件跟踪上，你可以订阅以下两个与外部调用相关的事件：

FraudProtection.Monitoring.ExternalCalls
FraudProtection.Errors.ExternalCalls

每当向外部调用发出请求时，都会将事件发送到 FraudProtection.Monitoring.ExternalCalls 命名空间。事件有效负载包括有关调用延迟、请求状态以及触发请求的规则和子句的信息。

当外部调用失败时，事件将发送到 FraudProtection.Errors.ExternalCalls 命名空间。事件有效负载包括发送到外部调用的 URI 请求和正文，以及收到的响应。

有关事件跟踪、如何订阅事件以及如何处理事件的详细信息，请参阅事件跟踪。

有关如何将此数据与你自己的组织的工作流集成，以及设置自定义监视、警报和报告的信息，请参阅通过事件中心的扩展性。

管理外部调用

若要编辑现有的外部调用，请选择卡标头上的编辑。

注意

在规则中使用外部调用后，无法更改其名称和参数。
若要删除现有的外部调用，请选择省略号 (...)，然后选择删除。

注意

在规则中引用外部调用后，无法将其删除。
若要查看外部调用的详细性能指标，请选择性能。
若要测试 Fraud Protection 是否仍可以连接到外部调用，请选择省略号 (...)，然后选择测试连接。

在规则中使用外部调用

若要使用外部调用做出决策，请从规则中引用它们。

例如，若要在规则中引用名为 myCall 的外部调用，请使用以下语法：

External.myCall()

如果 myCall 需要参数（如 IPaddress），请使用以下语法：

External.myCall(@"device.ipAddress")

有关规则语言以及如何在规则中使用外部调用的信息，请参阅语言参考指南。

注意

如果在规则中使用外部调用，则规则的延迟可能会增加。

了解身份验证和授权

为了确保安全访问数据，API 通常会对请求的发送方进行身份验证，以验证它们是否有权访问数据。 Fraud Protection 中的外部调用支持两种身份验证方法：匿名和 AAD。

如果选择匿名，则指向目标终结点的 HTTP 请求中的授权标头将留空。当目标终结点不需要授权标头时，请使用此选项。例如，如果终结点使用 API 密钥，请将键值对配置为在 Web 请求字段中输入的请求 URL 的一部分。然后，目标终结点可以验证是否允许来自请求 URL 的 API 密钥，然后决定是否应该授予权限。

如果选择 AAD，则发送到目标终结点的 HTTP 请求中的授权标头将包含持有者令牌。持有者令牌是由 Azure AD 颁发的 JSON Web 令牌 (JWT)。有关 JWT 的详细信息，请参阅 Microsoft 标识平台访问令牌。 Fraud Protection 将令牌值追加到请求授权标头中所需格式的文本“Bearer”，如下所示：

持有者<令牌>

令牌声明

下表列出了 Fraud Protection 颁发的持有者令牌中可能出现的声明。

名称	声明	说明
租户 ID	tid	此声明标识与你的 Fraud Protection 帐户关联的订阅的 Azure 租户 ID。有关如何在 Fraud Protection 门户中查找租户 ID 的信息，请参阅所需的 ID 和信息。有关如何在 Azure 门户中查找租户 ID 的信息，请参阅如何查找 Azure Active Directory 租户 ID。
读者	aud	此声明标识令牌的目标接收方。该值准确反映了你在 Fraud Protection 门户中配置外部调用时提供的应用程序 ID。
应用程序 ID	appid	此声明是 Fraud Protection 的应用程序 ID：* bf04bdab-e06f-44f3-9821-d3af64fc93a9*。此 ID 仅由 Fraud Protection 拥有，只有 Microsoft 可以代表其请求令牌。

当 API 收到令牌时，它会打开令牌，并验证上述每个声明是否与其说明匹配。

下面是一个示例，显示了如何使用 JwtSecurityTokenHandler 对传入请求进行身份验证。

string authHeader = "Bearer <token>"; // the Authorization header value
var jwt = new JwtSecurityTokenHandler().ReadJwtToken(token);
string tid = jwt.Claims.Where(c => c.Type == "tid").FirstOrDefault()?.Value;
string aud = jwt.Claims.Where(c => c.Type == "aud").FirstOrDefault()?.Value;
string appid = jwt.Claims.Where(c => c.Type == "appid").FirstOrDefault()?.Value;
if(tid != "<my tenant id>" || aud != "<my application id>" || appid != "bf04bdab-e06f-44f3-9821-d3af64fc93a9")
{
    throw new Exception("the token is not authorized.");
}

外部数据做法

你承认，你有责任遵守所有适用的法律法规，包括但不限于数据保护法、合同限制和/或与你通过 Fraud Protection 的外部调用功能提供给 Microsoft 的数据集相关的政策。此外，你承认，你对 Fraud Protection 的使用受 Microsoft 客户协议中详细说明的使用限制的约束，该协议规定，你不得将 Fraud Protection (i) 作为决定是否继续进行支付交易的唯一因素；(ii) 作为决定任何人的财务状况、财务历史、信誉或保险、住房或就业资格的因素；或 (iii) 做出产生法律效力或对某人产生重大影响的决定。你还被禁止在使用 Fraud Protection 的外部调用功能时提供或以其他方式使用敏感或高度监管的数据类型。在将任何数据集或数据类型与 Fraud Protection 的外部调用功能一起使用之前，请花时间对其进行审查，以确保你符合此规定。 Microsoft 还保留核实你是否符合此规定的权利。

通过