从 reCAPTCHA Classic 迁移

本文档介绍了如何将有效网站密钥从 reCAPTCHA Classic 迁移到项目中的 reCAPTCHA。Google Cloud 您可以使用 reCAPTCHA 管理控制台（推荐） 或 使用 控制台 Google Cloud 迁移网站密钥。迁移过程需要 5-10 分钟才能完成，并且无需更改代码。

如果您在 reCAPTCHA 管理控制台 中管理密钥， 则您使用的是 reCAPTCHA Classic。 最新的 reCAPTCHA 功能仅适用于在 项目中管理的网站密钥 Google Cloud 。如需详细了解 可用功能，请参阅比较 reCAPTCHA 方案。

完成迁移过程后，会发生以下变化：

  • 您的网站密钥在 Google Cloud 项目中可用，无需进行任何更改。
  • 您现有的 reCAPTCHA 集成将继续有效，无需更改代码。您可以保留相同的网页插桩和后端调用。但是，如需使用账号保护程序或 Password Defense 等功能，您必须修改网页插桩和后端调用。如需了解详情，请参阅迁移后使用 reCAPTCHA 功能。
  • 当您超出 reCAPTCHA 的每月免费配额（每月 10,000 次评估）时，系统会向您收费。如需了解详情，请参阅结算信息。

使用 reCAPTCHA 管理控制台进行迁移

  1. 前往 reCAPTCHA 管理控制台。

    前往 reCAPTCHA 管理控制台

  2. 选择要将密钥迁移到的项目。

  3. 选择要迁移的密钥。

  4. 点击提交 。

控制台会打开，其中包含您的项目和您迁移的密钥。 Google Cloud

使用 Google Cloud 控制台进行迁移

准备工作

  1. 在 Google Cloud 控制台的项目选择器页面上， 选择或创建 Google Cloud 项目。

    选择或创建项目所需的角色

    • 选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
    • 创建项目：如需创建项目，您需要 Project Creator 角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 权限。了解如何授予 角色。

    转到“项目选择器”

  2. 验证是否已为您的 Google Cloud 项目启用结算功能。

    reCAPTCHA 要求在项目中关联并启用结算功能 以便进行迁移。您可以使用信用卡或现有项目结算 ID 来启用结算功能。 Google Cloud 如果您需要结算方面的帮助， 请与 Cloud Billing 支持团队联系。

  3. 如果您要在 Google Cloud 控制台外部运行 gcloud CLI， 请安装并初始化 gcloud CLI。如需相关说明，请参阅

    安装 Google Cloud CLI。 安装后， 初始化 Google Cloud CLI，方法是运行以下命令： 

    gcloud init

    如果您使用的是外部身份提供方 (IdP)，则必须先 使用联合身份登录 gcloud CLI。

启用 reCAPTCHA Enterprise API

所有 reCAPTCHA 方案（Essentials、Premium 和 Enterprise）都在 reCAPTCHA Enterprise API 上运行。

控制台

  1. 在 Google Cloud 控制台中，前往 reCAPTCHA Enterprise API 页面。

    转到 reCAPTCHA Enterprise API

  2. 验证项目名称是否显示在页面顶部的项目选择器中。

    如果您没有看到项目名称，请点击项目选择器，然后选择您的项目。

  3. 点击启用 。

gcloud

  1. 在 Google Cloud 控制台中，激活 Cloud Shell。

    激活 Cloud Shell

    Cloud Shell 会话随即会在控制台的底部启动，并显示命令行提示符。 Google Cloud Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

  2. 如需在 gcloud 会话中设置项目，请运行 gcloud config set project 命令。 Google Cloud 将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。 
           gcloud config set project PROJECT_ID
  3. 如需启用 reCAPTCHA Enterprise API，请运行 gcloud services enable 命令： 
             gcloud services enable recaptchaenterprise.googleapis.com
  4. 如需验证 reCAPTCHA Enterprise API 是否已启用，请运行 gcloud services list 命令：
             gcloud services list --enabled

    验证 reCAPTCHA Enterprise API 是否在已启用的 API 列表中列出。

迁移到 reCAPTCHA

如需将 reCAPTCHA Classic 迁移到 reCAPTCHA，请从 reCAPTCHA 管理控制台中选择有效的网站密钥，然后迁移该网站密钥。您可以迁移一个或多个有效网站密钥。但是，一次只能迁移一个网站密钥。

要执行迁移过程，您必须有满足以下要求的 reCAPTCHA 用户账号：

  • 在 reCAPTCHA 管理控制台中，用户账号被列为要迁移的网站密钥的所有者。
  • 对于启用了 reCAPTCHA Enterprise API 的 Google Cloud 项目，该用户账号具有以下 IAM 角色之一：
    • Project Owner (roles/owner)
    • Project Editor (roles/editor)
    • reCAPTCHA Admin (roles/recaptchaenterprise.admin)
    如果您的用户账号没有这些角色之一，请让您的管理员授予其中一个角色，或按照授予、更改和撤消访问权限中的说明操作。

  1. 使用 Google Cloud 控制台、Google Cloud CLI 或 reCAPTCHA Enterprise API 迁移网站密钥。

    迁移网站密钥不会影响密钥或 API 端点，而是将密钥添加到企业许可。

    Google Cloud 控制台

    1. 在 Google Cloud 控制台中，前往 reCAPTCHA 页面。

      前往 reCAPTCHA

    2. 验证项目名称是否显示在页面顶部的资源选择器中。 如果您没有看到项目名称，请点击资源选择器，然后选择您的项目。

    3. 在 Classic keys 部分中，找到要迁移的密钥，然后点击 Upgrade key 。

    4. 如需完成所选密钥的迁移，请点击确认 。

    gcloud CLI

    1. 如需配置身份验证，请运行以下 gcloud 命令：

      gcloud auth login

      使用拥有所选网站密钥且具有以下角色之一的 reCAPTCHA 用户账号登录：Project Owner、Project Editor 或 reCAPTCHA Enterprise Admin 角色。

    2. 选择并复制您用于将 reCAPTCHA 与网页集成的有效网站密钥：

      1. 转到 reCAPTCHA 管理控制台，然后点击 。

      2. 选择网站密钥。迁移支持以下 reCAPTCHA 网站密钥：reCAPTCHA v2 Checkbox、reCAPTCHA v2 Invisible 和 reCAPTCHA v3。

      3. 要复制网站密钥，请点击 Copy site key 。

    3. 迁移网站密钥。

      如以下示例所示运行 gcloud recaptcha keys migrate 命令：

       gcloud recaptcha keys migrate SITE_KEY --project PROJECT-ID

      请提供以下值：

      • SITE_KEY：您从 reCAPTCHA 管理控制台复制的有效网站密钥。
      • PROJECT-ID：启用了 reCAPTCHA Enterprise API 的 Google Cloud 项目的 ID。

    REST API

    1. 选择并复制您用于将 reCAPTCHA 与网页集成的有效网站密钥：

      1. 转到 reCAPTCHA 管理控制台，然后点击 。

      2. 选择网站密钥。迁移支持以下 reCAPTCHA 网站密钥：reCAPTCHA v2 Checkbox、reCAPTCHA v2 Invisible 和 reCAPTCHA v3。

      3. 要复制网站密钥，请点击 Copy site key 。

    2. 迁移网站密钥。

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

      • PROJECT_ID：启用了 reCAPTCHA API 的 Google Cloud 项目的 ID。
      • SITE_KEY：您从 reCAPTCHA 管理控制台复制的有效网站密钥。

      HTTP 方法和网址：

      POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/SITE_KEY:migrate

      如需发送请求，请选择以下方式之一：

      curl

      执行以下命令：

      curl -X POST \
           -H "Authorization: Bearer $(gcloud auth print-access-token)" \
           -H "Content-Type: application/json; charset=utf-8" \
           -d "" \
           "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/SITE_KEY:migrate"

      PowerShell

      执行以下命令：

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

      Invoke-WebRequest `
          -Method POST `
          -Headers $headers `
          -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/SITE_KEY:migrate" | Select-Object -Expand Content

      您应该收到类似以下内容的 JSON 响应：

      {
  "name": "projects/PROJECT-ID/keys/6Ldqgs0UAAAAAIn4k7YxEB-LwEh5S9-Gv6IIWB8m",
  "displayName": "My site key",
  "webSettings": {
    "allowAllDomains": false,
    "allowedDomains": [
      recaptcha.net
    ],
    "allowAmpTraffic": false,
    "integrationType": "SCORE",
    "challengeSecurityPreference": "CHALLENGE_SECURITY_PREFERENCE_UNSPECIFIED"
  }
}

  2. 如需验证网站密钥是否已迁移，请按如下所述操作：

    Google Cloud 控制台

    前往 reCAPTCHA 页面，然后在 reCAPTCHA keys 部分中找到迁移后的网站密钥。

    前往 reCAPTCHA

    gcloud CLI

    运行 gcloud recaptcha keys list 命令并在密钥列表中找到迁移后的网站密钥。

迁移到 reCAPTCHA 后，您可以继续使用 siteverify 方法评估用户的 reCAPTCHA 响应令牌。如需了解响应，请参阅 响应siteverify method。

网站密钥迁移到 reCAPTCHA 后，其用量会在 Google Cloud 控制台中开始记录，以便在一小时内显示，包括用量和分数相关的信息中心。迁移之前的用量 通常不会显示在 Google Cloud 控制台中。

您可以撤消 reCAPTCHA 用户账号中的 reCAPTCHA Enterprise Admin (roles/recaptchaenterprise.admin) IAM 角色。您可以要求管理员撤消访问权限，也可以按照授予、更改和撤消访问权限中的说明操作。

后续步骤