Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

在网页上安装通用密钥

Fraud Defense Universal 密钥有助于保护您的 Web 应用和 API 端点免受自动机器人攻击、凭证滥用和欺诈。通过使用通用密钥，您可以使用自动网络请求拦截 (AutoExecute)、手动 JavaScript 执行或这两种方法的组合，在整个网站中部署保护措施。

准备工作

为 Google Cloud Fraud Defense 准备好环境。
创建通用密钥。
为您的通用密钥配置网域。
如需在Google Cloud 控制台中查看受保护端点的状态列，请确保您拥有 Cloud Monitoring monitoring.timeSeries.list 权限。此权限包含在预定义的 Fraud Defense 角色中：reCAPTCHA Enterprise Admin、reCAPTCHA Enterprise Editor 和 reCAPTCHA Enterprise Viewer。

在您的网站上安装通用密钥

如需安装通用密钥并帮助保护您的网页，您可以使用 AutoExecute 配置、手动 JavaScript 安装，或在不同端点上同时使用这两种方法，并使用相同的通用密钥：

AutoExecute 配置（推荐）：自动拦截指向已配置网址路径的异步网络请求，并将 reCAPTCHA 令牌附加到请求标头。
手动安装：使用手动 grecaptcha.enterprise.execute() 调用或 HTML 按钮属性。您可以单独使用此方法，也可以将其与 AutoExecute 搭配使用，以处理 AutoExecute 不支持的网络请求、需要在载荷中自定义令牌放置位置的请求，或在逐步迁移到 AutoExecute 的过程中使用。

配置 AutoExecute

AutoExecute 可以拦截网页上的网络请求，并消除针对每个前端操作的手动 grecaptcha.enterprise.execute() 调用，从而帮助简化前端 JavaScript 集成。

AutoExecute 的运作方式

Fraud Defense 脚本会自动与通用密钥的政策配置中定义的网络操作集成。当脚本检测到对已配置路径的异步网络请求时，它会拦截该请求，触发风险评估，并可能在原始请求继续之前向用户显示 CAPTCHA 验证。生成的响应令牌会自动附加到请求中的 X-Recaptcha-Token 标头。

支持的网络 API

AutoExecute 仅拦截由以下 API（包括依赖于这些 API 的 AJAX 等框架）发起的异步网络请求：

API 名称	超时配置	实现示例
Fetch API	使用 `AbortSignal` 控制器设置超时。	`AbortSignal.timeout(n)`
XMLHttpRequest	使用原生 `.timeout` 属性设置超时。	`xhr.timeout = n`

集成最佳做法

仅限用户触发的操作：AutoExecute 不支持在网页加载期间自动加载的资源。为避免集成失败，请仅对由明确的用户互动（例如点击登录或提交按钮）触发的请求应用 AutoExecute。
防止延迟超时：Fraud Defense 验证流程有时可能会导致网络延迟。为防止客户端超时，请始终使用表中列出的机制直接配置显式请求超时。
仅保护敏感路径：仅为敏感路径指定 protectedEndpoints，并在 action 参数中为用户互动使用有意义的名称。避免保护每个端点，因为在每个后端请求上触发 Fraud Defense 可能会对性能产生负面影响。如需更多指导，请参阅操作。

将脚本标记添加到您的网页

如需在网页上加载 Fraud Defense，请在网页的 <head></head> 元素中添加带有通用密钥的 JavaScript API：

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

Fraud Defense 默认使用浏览器的语言。如果您想指定其他语言，请在脚本中使用 hl=LANG 属性。例如，如需使用法语，请指定以下内容：

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

如需了解支持的语言，请参阅 Fraud Defense 的语言代码。

配置受保护的端点

如需为通用密钥配置受保护的端点，请选择一个标签页：

控制台

在 Google Cloud 控制台中，前往 Fraud Defense 页面。

前往 Fraud Defense
在控制台工具栏中，检查您的项目是否显示在资源选择器中。如果未显示，请点击资源选择器，然后选择您的项目。
选择密钥标签页。

密钥标签页有两个视图：卡片和表格。如果您的项目有许多密钥，则只有表格视图可用。
在 reCAPTCHA 密钥部分中，找到要配置的通用密钥：
- 在卡片视图中，点击密钥卡片上的密钥详情。
- 在表视图中，点击密钥的名称。
在密钥详情页面上，点击集成标签页。
在为您的网站添加 reCAPTCHA 步骤中，选择 AutoExecute（推荐）标签页。

可选：如需手动保护特定端点，请点击手动标签页以查看 grecaptcha.enterprise.execute() 代码段。
在受保护的端点部分中，点击添加端点，以配置要保护的每个端点：
1. 在操作字段中，输入用户互动的名称。例如 login、register 或 add_to_cart。如需更多指导，请参阅操作。
2. 在路径字段中，输入要拦截的唯一网址路径或 glob 模式。例如 /login_api、/register_api 或 /cart_api/add/*。
3. 可选：如需添加其他端点，请点击添加端点。
点击保存，保存受保护的端点。

保存配置后，受保护的端点表中的状态列会指示 Fraud Defense 在过去 24 小时内是否收到了每项操作的流量。端点首次收到流量后，流量状态可能需要 10 分钟才能更新。

gcloud

如需检查通用密钥的当前政策配置，请使用 gcloud alpha recaptcha policies describe 命令：

gcloud alpha recaptcha policies describe --key=KEY_ID

如需使用受保护的端点更新政策配置，请创建一个 YAML 文件（例如 POLICY.yaml），用于定义受保护的路径和操作：

clientSettings:
  allowedDomains:
    - example.com
  protectedEndpointGroup:
    protectedEndpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

使用 gcloud alpha recaptcha policies update 命令通过 YAML 文件更新密钥配置：

gcloud alpha recaptcha policies update \
    --key=KEY_ID \
    --policy=POLICY.yaml

REST API

如需使用 REST API 更新政策配置以定义受保护的端点，请使用 projects.keys.updatePolicy 方法。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的 Google Cloud 项目 ID
KEY_ID：通用密钥的 ID

HTTP 方法和网址：

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings

请求 JSON 正文：

{
"clientSettings": {
  "allowedDomains": [
    "example.com"
  ],
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings" | Select-Object -Expand Content

如果成功，请求将返回更新后的政策配置。

受保护的端点语法和限制

每个通用密钥最多可以配置 25 个受保护的端点。每个端点都必须满足以下要求：

action：操作名称必须包含 1 到 100 个字符，并且只能使用字母、数字、斜杠 (/) 和下划线 (_)。
path（区分大小写）：路径必须满足以下条件：
- 是唯一的，以 / 开头，包含 1 到 200 个字符，不含连续斜杠 (//)。
- 请至少包含一个非通配符层级。例如，不能是 /、/*、/** 或 /*/。
- 通配符必须独占整个段：* 与单个段匹配。例如，/api/*/login 或 /api/* 有效；/api/login* 无效，** 仅作为最终片段匹配多个片段。例如，/api/** 有效，/api/**/login 无效。

路径匹配行为

AutoExecute 会从上到下依次根据网址路径评估受保护的端点。它会忽略目标网域、协议和查询参数。此行为具有以下实际影响：

路径匹配顺序：AutoExecute 会应用第一个匹配的端点。如果没有匹配的端点，AutoExecute 不会拦截请求。将特定路径放在通配符模式之前，以避免遮蔽更具体的路由。例如，将 /mysite/login 列在 /*/login 之前。
第三方请求：如果您的网页上运行的第三方工具（例如分析或合作伙伴脚本）向与受保护端点匹配的路径（例如，https://analytics.example.net/login 匹配 /login）发送请求，AutoExecute 也会拦截这些请求。这可能会导致额外的网络延迟、指标偏差或意外的人机识别系统验证。为避免冲突，请确保受保护的路径具有独特性（例如 /auth/v1/login），或者在发生路径冲突时使用手动安装。
跨网域 API：如果您的后端 API 托管在与您的网站不同的网域（例如 cdn.example.com 与 www.example.com）上，AutoExecute 会自动运行，无需额外的网域配置。

如果与特定目标网域匹配对您的集成很重要，请提交功能请求。

在后端验证令牌

在后端，从 X-Recaptcha-Token 请求标头中获取响应令牌，并在两分钟内创建评估。

手动安装

我们建议您在需要验证的用户互动中添加 Fraud Defense 验证。例如，如果您想验证表单的提交操作，则需要为提交操作添加 Fraud Defense 验证。

根据您希望添加 Fraud Defense 验证的位置，选择相应的选项：

在用户互动中添加验证
在 HTML 按钮上添加 Fraud Defense

在用户互动时添加验证

如需在网页上加载 reCAPTCHA，请在网页的 <head></head> 元素中添加包含通用密钥的 JavaScript API：
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense 默认使用浏览器的语言。如果您想指定其他语言，请在脚本中使用 hl=LANG 属性。例如，如需使用法语，请指定以下内容：

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

如需了解支持的语言，请参阅 Fraud Defense 的语言代码。

如果您想为徽章指定位置，请在脚本标记中使用 badge=LOCATION 作为查询参数。例如 https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft。默认情况下，位置设置为 bottomright。其他可能的值包括 inline 和 bottomleft。

如需在用户互动中添加 Fraud Defense 验证，请执行以下操作：

为确保 grecaptcha.enterprise.execute() 会在 Fraud Defense 库加载后运行，请使用 grecaptcha.enterprise.ready()。

针对您要使用通用密钥保护的每项互动调用 grecaptcha.enterprise.execute()。在 action 参数中为用户互动指定一个有意义的名称。如需更多指导，请参阅操作。

以下示例展示了如何在登录操作中调用 grecaptcha.enterprise.execute()：

<script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  function onClick(e) {
    e.preventDefault();
    grecaptcha.enterprise.ready(async () => {
      const token = await grecaptcha.enterprise.execute(
        'KEY_ID',
        {action: 'LOGIN'}
      );
      // IMPORTANT: The 'token' that results from execute is an
      // encrypted response sent by Fraud Defense to
      // the end user's browser.
      // This token must be validated by creating an assessment.
      // See https://cloud.google.com/recaptcha/docs/create-assessment
    });
  }
</script>

生成令牌后，将 reCAPTCHA 令牌发送到后端，并在两分钟内创建评估。

重要提示：您的后端必须在 CreateAssessmentRequest 中指定 assessment.event.expected_action（或 JSON 中的 expectedAction），并且该值必须与 execute() 调用中配置的操作一致。例如，如果您将前端操作配置为 LOGIN，则后端在为该请求创建评估时必须将 expected_action 设置为 LOGIN。如果存在不匹配，则表示攻击者正在尝试伪造操作。

在 HTML 按钮上添加 Fraud Defense

如需在网页上加载 reCAPTCHA，请在网页的 <head></head> 元素中添加包含通用密钥的 JavaScript API：
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense 默认使用浏览器的语言。如果您想指定其他语言，请在脚本中使用 hl=LANG 属性。例如，如需使用法语，请指定以下内容：

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

如需了解支持的语言，请参阅 Fraud Defense 的语言代码。
如需在 HTML 按钮上添加 Fraud Defense，请执行以下操作：
1. 定义用于处理令牌的回调函数。
```
<script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>
```
  如需了解详情，请参阅 requestSubmit() 方法。
2. 为 HTML 按钮添加属性。
```
<button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>
```
  如果您想为徽章指定位置，请在具有 class="g-recaptcha" 的元素上使用 data-badge="LOCATION" 属性。默认情况下，位置设置为 bottomright。其他可能的值包括 inline 和 bottomleft。
3. 使用此按钮在您的网站上提交表单时，g-recaptcha-response POST 参数会包含响应令牌。
  
  注意：如果您将 g-recaptcha 按钮设置为 disabled，则在加载 Fraud Defense 时，该按钮处于启用状态。
生成令牌后，将 reCAPTCHA 令牌发送到后端，并在两分钟内创建评估。

重要提示：您的后端必须在 CreateAssessmentRequest 中指定 assessment.event.expected_action（或 JSON 中的 expectedAction），并且该值必须与按钮上配置的操作一致。例如，如果您将按钮操作配置为 submit，则在为该请求创建评估时，您的后端必须将 expected_action 设置为 submit。如果存在不匹配，则表示攻击者正在尝试伪造操作。

后续步骤

如需根据自定义规则触发人机识别系统验证，请配置验证政策。
如需评估 reCAPTCHA 响应令牌，请创建评估。