外部调用

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

注意

如果所有事件需要此附加数据，还可以将其作为评估架构的一部分发送。 有关如何在 API 请求中发送自定义数据的详细信息，请参阅 自定义数据示例。

可在外部调用中使用的 API 类型

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

• 欺诈保护目前仅支持以下身份验证方法： 匿名 和 AAD。
• 欺诈保护目前仅支持以下 HTTP 方法： GET 和 POST。

创建外部调用

1. 在 欺诈保护门户的左侧导航中，选择 “外部呼叫”，然后选择“ 新建外部呼叫”。

2. 根据需要查看并设置以下字段。

   • 名称 – 输入用于从规则引用外部调用的名称。 名称只能包含数字、字母和下划线。 它不能以数字开头。

     注意

     在规则中使用外部调用后，无法更改其名称。

   • 说明 – 添加说明，帮助团队快速识别外部呼叫。

   • Web 请求 – 选择适当的 HTTP 方法（GET 或 POST），然后输入 API 终结点。

     注意

     仅支持 HTTPS 终结点。

   • 启用定期预热调用 - 如果发往外部调用终结点的流量太低，则连接可能会冷，并可能会增加来自外部服务的响应延迟。 若要缓解此问题，请从 外部调用设置 页启用预热呼叫。 使用切换开关启用预热呼叫。 需要提供有效的 GET Keep-alive URL。 与主终结点一样，保持连接终结点还必须通过 测试连接。 如果将外部调用配置为启用了预热呼叫，则当流量下降过低时，欺诈保护会自动使用 GET 方法对保持连接终结点进行匿名预热调用。

     注意

     热身调用中不能使用任何参数、配置或可配置标头。

   • 身份验证 – 选择用于对传入请求进行身份验证的方法。

     • 如果选择“匿名”，则不会发送授权标头。
     • 如果选择 AAD，则会在租户中生成 Azure Active Directory（Azure AD）令牌，持有者<令牌>用作授权标头。

     有关身份验证、授权和 Azure AD 令牌的详细信息，请参阅 本文后面的“了解身份验证和授权 ”部分。

   • 访问群体 - 如果选择 AAD 作为身份验证方法，系统会要求提供访问群体。 可以使用现有的 Azure 应用程序作为受众，或通过欺诈保护门户中的集成体验创建新的应用程序。 确保访问群体有权访问外部调用/服务。 若要详细了解如何配置 Azure Active Directory （Azure AD） 身份验证，请参阅 配置 Azure AD 身份验证。

   • 应用程序 ID – 还需要在欺诈保护订阅租户中提供新的或现有的 Azure AD 应用程序的应用程序 ID。 在 Azure 密钥库中生成证书。 欺诈保护应用应具有对此 Azure 密钥库的读取访问权限。 将证书加载到此 Azure AD 应用程序。 有关如何创建和管理 Azure AD 应用程序的详细信息，请参阅 “创建 Azure Active Directory 应用程序”。

   • 证书 URL – 提供来自 Azure 密钥库的证书标识符 URL。 这是在上一步中加载到 Azure AD 应用的相同证书。 有关如何在 Azure 密钥库中生成证书的详细信息，请参阅在 Azure 中创建和合并证书签名请求密钥库

   • 添加参数 – 可以使用参数将数据从欺诈保护传递到 API 终结点。 根据所选的 HTTP 方法，这些参数将发送到查询字符串中的终结点或作为请求正文的一部分。

     可以为每个参数添加示例值。 欺诈保护使用这些参数值在创建之前或选择“ 测试”时对终结点进行示例调用。

     注意

     所有参数值都解释为字符串。

   • 示例请求 – 提供发送到外部调用的请求示例。 请求应反映指定的参数名称和值，并且无法对其进行编辑。

     对于 GET 方法，将显示请求 URL。 对于 POST 方法，将显示请求正文。

     示例请求用于在创建之前或选择“ 测试”时对终结点进行示例调用。

   • 示例响应 – 提供 API 终结点成功响应中返回的数据示例。 此数据应采用 JavaScript 对象表示法（JSON）格式，可在规则中引用。 在此处提供的示例显示在创建规则时。

     选择“测试”可在此字段中自动输入来自 API 的实际响应。

   • 超时 – 指定请求在超时之前应等待多长时间（以毫秒为单位）。必须指定介于 1 到 1000 之间的数字。

   • 默认响应 – 指定在请求失败或超过指定超时时应返回的默认响应。该值必须是有效的 JSON 对象或 JSON 元素。

3. 可选：若要向 API 终结点发送示例请求并查看响应，请选择“ 测试”。 有关详细信息，请参阅下一部分： 测试外部调用。

4. 完成设置必填字段后，选择“ 创建”。

测试外部调用

若要确保欺诈保护可以连接到终结点，请随时测试连接。

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

  欺诈防护使用提供的终结点和参数将请求发送到外部调用。

  • 如果欺诈保护成功到达目标终结点，面板顶部会显示一条绿色消息栏，告知连接成功。 若要查看完整的响应，请选择“ 查看响应详细信息”。
  • 如果欺诈保护无法访问目标终结点，或者如果在指定的超时之前未收到响应，则会在面板顶部显示红色消息栏，并显示遇到的错误。 若要查看有关错误的详细信息，请选择“ 查看错误详细信息”。

监视外部调用

在欺诈保护门户中监视外部调用

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

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

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

注意

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

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

   欺诈保护显示一个新页面，其中包含更详细的指标视图。

2. 若要查看过去三个月中任何时间范围的指标，请调整 页面顶部的“日期”范围 设置。

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

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

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

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

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

• FraudProtection.Monitoring.ExternalCalls
• FraudProtection.Errors.ExternalCalls

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

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

有关事件跟踪、如何订阅事件以及事件可以执行的操作的详细信息，请参阅 事件跟踪。

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

管理外部调用

• 若要编辑现有的外部调用，请选择 卡片头上的“编辑 ”。

  注意

  在规则中使用外部调用后，无法更改其名称和参数。

• 若要删除现有的外部调用，请选择省略号 （...），然后选择“ 删除”。

  注意

  在规则中引用外部调用后，无法将其删除。

• 若要查看外部调用的详细性能指标，请选择“ 性能”。

• 若要测试欺诈保护仍可以连接到外部呼叫，请选择省略号 （...），然后选择“ 测试连接”。

在规则中使用外部调用

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

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

External.myCall（）

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

External.myCall（@“device.ipAddress”）

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

注意

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

了解身份验证和授权

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

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

如果选择 AAD，则指向目标终结点的 HTTP 请求中的授权标头包括持有者令牌。 持有者令牌是由 Azure AD 颁发的 JSON Web 令牌（JWT）。 有关 JWT 的信息，请参阅Microsoft 标识平台访问令牌。 欺诈保护将令牌值追加到请求授权标头中所需格式的文本“Bearer”，如下所示：

<持有者令牌>

令牌声明

下表列出了在欺诈保护颁发的持有者令牌中可以期望的声明。

名称	声明	说明
租户 ID	tid	此声明标识与欺诈保护帐户关联的订阅的 Azure 租户 ID。 有关如何在欺诈保护门户中查找租户 ID 的信息，请参阅 所需的 ID 和信息。 有关如何在Azure 门户中查找租户 ID 的信息，请参阅如何查找 Azure Active Directory 租户 ID。
受众	aud	此声明标识令牌的目标收件人。 该值完全反映你在欺诈保护门户中配置外部调用时提供的应用程序 ID。
应用程序 ID	appid	此声明是欺诈保护的应用程序 ID：* bf04bdab-e06f-44f3-9821-d3af64fc93a9*。 此 ID 仅由欺诈保护拥有，只有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.");
}

外部数据实践

你承认你有责任遵守所有适用的法律和法规，包括不受数据保护法律、合同限制和/或与你通过欺诈保护的外部呼叫功能提供给Microsoft的数据集相关的数据保护法律、合同限制和/或策略。 此外，你确认你使用欺诈保护受到Microsoft 客户协议中详述的限制，该限制规定你不得使用欺诈保护（i）作为确定是否继续付款交易的唯一因素：（二）确定任何人的财务状况、财务史、信用状况或保险、住房或就业资格的一个因素：或（三）作出产生法律影响或严重影响某人的决定。 还禁止你提供或使用敏感或高度管控数据类型，以使用欺诈保护的外部调用功能。 在将数据集或数据类型与欺诈保护的外部调用功能一起使用之前，请花时间查看这些数据集或数据类型，以确保你符合此预配。 Microsoft还保留验证是否符合此规定的权利。

其他资源

• 视频： 了解Dynamics 365欺诈保护中的新外部呼叫功能
• 博客： 使用Dynamics 365欺诈保护预览版中的新功能自定义保护：使用外部呼叫实时做出明智的决策