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

在网页上安装通用密钥

本文档介绍了如何安装 Universal 密钥并将其与网页集成。

准备工作

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

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

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

根据您的集成方法，选择适当的选项：

AutoExecute 配置

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

AutoExecute 仅拦截使用 Fetch API 或 XMLHttpRequest 发起的异步网络请求，包括来自使用这些 API 的框架（如 AJAX）的请求。
对于在网页加载时自动加载的资源，不支持 AutoExecute。而应将 AutoExecute 应用于由用户在网页上执行的操作（例如点击登录按钮）触发的网络请求。
为防止 Fraud Defense 验证导致网络超时，请直接对请求应用超时。对 Fetch API 使用 AbortSignal.timeout(n)，对 XMLHttpRequest 使用 XMLHttpRequest.timeout 属性。

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

如需在网页上加载 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 的语言代码。

配置受保护的端点

Fraud Defense 脚本会自动与通用密钥的政策配置中定义的网络操作集成。此部分定义了网址路径 (path) 到操作名称 (action) 的映射。

如果 Fraud Defense 脚本检测到对映射路径的异步网络请求，它会拦截该请求，触发风险评估，并可能在原始请求继续之前向用户显示人机识别系统验证。生成的响应令牌会自动附加到请求中的 X-Recaptcha-Token 标头。

gcloud

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

gcloud alpha recaptcha policies describe --key=KEY_ID

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

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - 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.protectedEndpointGroup

请求 JSON 正文：

{
"clientSettings": {
  "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.protectedEndpointGroup"

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.protectedEndpointGroup" | Select-Object -Expand Content

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

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

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

第三方请求：如果您的网页上运行的第三方工具（例如分析或合作伙伴脚本）向与受保护端点匹配的路径（例如，https://analytics.example.net/login 与 /login 匹配）发送请求，AutoExecute 也会拦截这些请求。这可能会导致额外的网络延迟、指标偏差或意外的人机识别系统验证。为避免冲突，请确保您的受保护路径具有独特性（例如 /auth/v1/login），或者在发生路径冲突时使用手动安装。
跨网域 API：如果您的后端 API 托管在与您的网站不同的网域（例如 examplecdn.net 与 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() 方法。
1. 为 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。
1. 当用户使用此按钮在您的网站上提交表单时，g-recaptcha-response POST 参数会包含响应令牌。
注意：如果您将 g-recaptcha 按钮设置为 disabled，则该按钮会在 Fraud Defense 加载后启用。
生成令牌后，将 reCAPTCHA 令牌发送到后端，并在两分钟内创建评估。

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

后续步骤

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