通过

外部调用

  • 项目

本文介绍如何使用外部调用从 Microsoft Dynamics 365 欺诈保护中的 API 引入数据。

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

注意

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

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

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

  • 欺诈保护目前仅支持以下身份验证方法：匿名、基本、证书、OAuth（Microsoft Entra ID）、OAuth（泛型）和 OAuth（自定义令牌）。
  • 欺诈保护目前仅支持以下 HTTP 方法： GET 和 POST。

注意

若要详细了解 Microsoft 的外部数据实践，请参阅 外部数据实践。

创建外部调用

若要创建外部调用，请执行以下步骤。

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

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

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

      注意

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

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

    • 添加参数 – 可以使用参数将数据从欺诈保护传递到 API 终结点。 根据所选的 HTTP 方法，这些参数将发送到查询字符串中的终结点或作为请求正文的一部分。 可以使用格式 {parameter.\<parameter name\>}将此步骤中定义的参数手动添加到请求 URL、标头和/或正文。 所有参数值都解释为字符串。 可以为欺诈保护用于在创建前或选择“ 测试连接”时对终结点进行示例调用的每个参数添加示例值。

      注意

      可以使用 Request.CorrelationId() 规则中的函数提取传入事件的关联 ID，并将其作为外部调用的参数值传递。

    • 添加配置 – 可以在外部调用设置页上提供固定的配置数据。 对于敏感信息，可以将配置标记为机密，并提供来自 Azure 密钥库而不是实际值的机密标识符 URL。 有关如何在 Azure 密钥库中存储机密并提供对欺诈保护的访问权限的信息，请参阅 Azure 密钥库中的存储密码。

    与参数一样，此步骤中定义的配置可以使用 {配置格式 手动添加到请求 URL、标头和/或正文中。<配置名称>}。 但是，与从规则传递实际值的参数不同，在进行示例或实际调用时，将使用外部调用设置页上提供的配置值。

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

      注意

      仅支持 HTTPS 终结点。

    • 身份验证 – 选择要用于对传入请求进行身份验证的方法。 有关身份验证、身份验证特定字段、授权和 Microsoft Entra 令牌的详细信息，请参阅 “了解身份验证和授权”。

    • 标头 - 可以根据需要提供标头。 Content-Type 的默认值为“application/json”。 目前，欺诈保护仅支持“application/json”和“application/x-www-form-urlencoded”内容类型。

    • 示例请求 – 发送到外部调用的请求示例。 请求应反映指定的参数名称和值，并且无法对其进行编辑。 还可以向请求 URL 或正文添加配置。

      注意

      对于 GET 方法，不包含任何请求正文。

      对于 POST 方法，将显示请求正文。 可以通过选择 +高级生成自己的请求来构造 POST 调用的自定义请求正文。 示例请求用于在创建之前或选择“ 测试连接”时对终结点进行示例调用。

    • 示例响应 – API 终结点成功响应中返回的数据示例。 此数据必须采用 JavaScript 对象表示法（JSON）格式，并且可以在规则中引用。 你提供的示例响应显示在规则编辑器中，还对响应字段启用自动完成。 选择“ {} 获取 API 响应 ”，在此字段中自动输入来自 API 的实际响应。

      注意

      必须弹出示例响应才能成功完成外部调用设置。

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

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

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

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

测试外部调用

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

  • 若要在创建新的外部调用或编辑现有外部调用时测试连接，请设置所有必填字段，然后选择“ 测试连接”。 欺诈防护使用提供的终结点和参数将请求发送到外部调用。 还可以在 URL、标头或请求正文中手动添加配置。
  • 如果欺诈保护成功到达目标终结点，面板顶部会显示一条绿色消息栏，告知连接成功。 若要查看完整响应，请选择“ 查看详细信息”。
  • 如果欺诈保护无法访问目标终结点，或者如果在指定的超时之前未收到响应，则会在面板顶部显示一条红色消息栏，并显示生成的错误。 若要查看有关错误的详细信息，请选择“ 查看详细信息”。

监视外部调用

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

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

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

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

注意

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

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

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

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

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

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

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

还可以在规则中访问 Diagnostics 对象，以便从外部调用响应中发现重要的诊断和调试信息。 Diagnostics 对象包含请求有效负载、终结点、HttpStatus 代码、错误消息和延迟。 可以在规则体验中访问这些字段中的任何一个，并可用于观察输出方法创建自定义属性。 在规则中使用对象字段之前，必须使用相应的扩展方法 .GetDiagnostics()创建 Diagnostics 对象。

以下示例演示了使用 Diagnostics 对象的示例规则：

LET $extResponse = External. myCall(@"device.ipAddress")
LET $extResponseDiagnostics = $extResponse.GetDiagnostics()
OBSERVE Output(Diagnostics = $extResponseDiagnostics ) 
WHEN $extResponseDiagnostics.HttpStatusCode != 200

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

注意

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

还可以从 Functions 调用外部调用。 有关详细信息，请参阅函数。

了解身份验证和授权

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

  • 匿名
  • 基本
  • 证书
  • OAuth （Microsoft Entra ID） （前 Azure Active Directory）
  • OAuth （泛型）
  • OAuth （自定义令牌）

注意

目前，欺诈保护仅支持以下 HTTP 方法：

  • GET
  • POST

匿名

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

基本

如果选择 “基本 ”作为身份验证方法，请提供以下信息来设置外部调用：

  • 用户名 - 提供尝试连接到的 URL 的用户名。
  • 密码 URL – 提供来自 Azure 密钥库的密码标识符 URL 进行基本身份验证。 有关如何在 Azure 密钥库中存储密码并提供对欺诈保护的访问权限的信息，请参阅在 Azure 密钥库中存储密码。

证书

如果选择“证书”作为身份验证方法，请提供以下信息来设置外部调用：

  • 证书 URL – 提供来自 Azure 密钥库的证书标识符 URL。 有关如何在 Azure 密钥库中生成证书并提供对欺诈保护的访问权限的信息，请参阅在 Azure 密钥库中创建证书。

OAuth （Microsoft Entra ID）

如果选择 OAuth（Microsoft Entra ID） （前 Azure Active Directory）作为身份验证方法，请提供以下附加信息来设置外部调用：

  • 受众 - 如果选择了 OAuth（Microsoft Entra ID）作为身份验证方法，系统会提示提供受众。 可以使用现有的 Azure 应用程序作为受众，或通过欺诈保护门户中的集成体验创建新应用程序。 确保访问群体有权访问外部调用/服务。 有关如何配置 Microsoft Entra 身份验证的详细信息，请参阅 配置 Microsoft Entra 身份验证。
  • 应用程序 ID – 必须在欺诈保护订阅租户中提供新的或现有的 Microsoft Entra 应用程序的应用程序 ID。 在 Azure 密钥库中生成证书。 欺诈保护应用应具有对此 Azure 密钥库的读取访问权限。 有关如何在 Azure 密钥库中生成证书并提供对欺诈保护的访问权限的信息，请参阅在 Azure 密钥库中创建证书。 将证书加载到此 Microsoft Entra 应用程序。 有关如何创建和管理 Microsoft Entra 应用程序的详细信息，请参阅 “创建 Microsoft Entra 应用程序”。
  • 证书 URL – 提供来自 Azure 密钥库的证书标识符 URL，该 URL 与之前上传到 Microsoft Entra 应用的证书相同。

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

<持有者令牌>

令牌声明

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

名称 声明 说明
租户 ID tid 此声明标识与欺诈保护帐户关联的订阅的 Azure 租户 ID。 有关如何在欺诈保护门户中查找租户 ID 的信息，请参阅 所需的 ID 和信息。 有关如何在Azure 门户中查找租户 ID 的信息，请参阅“如何查找 Microsoft Entra 租户 ID”。
受众 aud 此声明标识有权访问要调用的外部服务的 Azure 应用程序。 有关如何配置 Microsoft Entra 身份验证的信息，请参阅 配置 Microsoft Entra 身份验证。
应用程序 ID appid 此声明标识谁正在请求令牌。 有关如何配置 Microsoft Entra 身份验证的详细信息，请参阅 配置 Microsoft Entra 身份验证。

当 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 audience>" || appid != "<my application id>")
{
    throw new Exception("the token is not authorized.");
}

OAuth （泛型）

如果选择 OAuth（Generic） 作为身份验证方法，请提供以下附加信息来设置外部调用：

  • 令牌 URL – 令牌调用的 API 终结点。
  • 令牌身份验证 – 选择令牌调用的匿名或基本身份验证方法。
  • 客户端 ID/用户名 – 用于匿名身份验证的客户端 ID，或用于基本身份验证的用户名。
  • 客户端机密/密码 URL – Azure 密钥库 中用于匿名身份验证的客户端机密标识符 URL，或用于基本身份验证的密码标识符 URL。 有关如何在 Azure 密钥库中存储机密并提供对欺诈保护的访问权限的信息，请参阅 Azure 密钥库中存储密码。
  • 范围 – 范围 值。
  • 资源 – 资源 值（如果需要）。

OAuth （自定义令牌）

如果选择 OAuth（自定义令牌） 作为身份验证方法，可以通过选择 +创建令牌请求 并提供以下信息来配置自定义 OAuth 令牌调用：

  • 配置 – 要传入令牌调用的配置值。 有关配置的详细信息，请参阅 创建外部调用。
  • 令牌 URL – 令牌调用的 API 终结点。
  • 令牌身份验证 – 选择令牌调用的匿名或基本身份验证方法。
  • 用户名 - 基本身份验证的用户名。
  • 密码 URL – Azure 密钥库中用于基本身份验证的密码标识符 URL。 有关如何在 Azure 密钥库中存储密码并提供对欺诈保护的访问权限的信息，请参阅在 Azure 密钥库中存储密码。
  • 标头 – 标头值。
  • 示例请求 – 发送到令牌终结点的请求示例：
    • 示例请求 URL – 显示用于进行示例调用的请求 URL 的只读字段。
    • 示例请求正文 – 可以通过选择 +高级生成自己的请求来构造令牌调用的自定义请求正文。 示例请求 URL 和正文用于在创建之前或选择“ 测试连接”时对令牌终结点进行示例调用。
  • 超时 – 指定 1 到 5000 之间的超时持续时间。

使用 Azure Key Vault

根据 Microsoft 对数据安全的承诺，欺诈保护仅允许你在外部调用设置页中提供机密、密码和证书的 Azure 密钥库 URL。

在 Azure 密钥库中存储密码

若要将机密或密码上传到 Azure 密钥库并授予对欺诈保护的访问权限，请执行以下步骤。

  1. 使用租户凭据登录到Azure 门户。
  2. 可以使用现有密钥保管库，也可以按照快速入门中的说明创建新的密钥保管库：使用Azure 门户创建密钥保管库。 确保在 机密权限中选择“获取 ”和 “列表 ”。
  3. 在左侧导航窗格中，选择“机密”，然后选择“生成/导入”。
  4. 在 “创建机密 ”页上，输入机密的名称。 机密值应是想要使用外部调用连接到的 Web URL 的密码。
  5. 在必填字段中输入信息，然后选择“ 创建”。 在欺诈保护门户中设置外部调用时，复制并保存机密标识符以供以后使用。
  6. 在左侧导航窗格中的“设置”下，选择“访问策略”，然后选择“添加新访问策略”。
  7. 在“机密权限”部分中，选择“获取”和“列出”检查框。
  8. 在“主体”和“授权”应用程序字段中，搜索 Dynamics 365 欺诈防护，然后选择“选择”。
  9. 选择“添加”，然后选择“保存”。

在 Azure 密钥库中创建证书

若要在 Azure 密钥库中创建证书，请执行以下步骤。

  1. 使用租户凭据登录到Azure 门户。
  2. 可以使用现有密钥保管库，也可以按照快速入门中的说明创建新的密钥保管库：使用Azure 门户创建密钥保管库。 请确保 在机密权限中选择“获取 和 列出 ”。
  3. 在左窗格中，选择“证书”，然后单击“生成/导入”。
  4. 在 “创建证书 ”页上，输入证书的名称。 对于 使用者，请输入证书使用者。
  5. 在必填字段中输入信息，然后选择“ 创建”。
  6. 在左侧导航窗格中，选择“ 访问策略”，然后选择“ 创建”。
  7. 在“证书权限”部分中，选择“获取”和“列出”检查框。
  8. 在“主体”和“授权”应用程序字段中，搜索 Dynamics 365 欺诈防护，然后选择“选择”。
  9. 选择“添加”，然后选择“保存”。

有关如何在 Azure 密钥库中生成证书的详细信息，请参阅在 Azure 密钥库 中创建和合并证书签名请求。

外部数据实践

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

其他资源