Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

在網頁中安裝通用金鑰

本文說明如何安裝通用金鑰，並將其整合至網頁。

事前準備

在網站中安裝通用金鑰

如要安裝通用金鑰並保護網頁，您可以使用 AutoExecute 設定、手動安裝 JavaScript，或在不同端點上同時使用這兩種方法，並搭配相同的通用金鑰：

AutoExecute 設定 (建議)：自動攔截傳送至指定網址路徑的非同步網路要求，並將 reCAPTCHA 權杖附加至要求標頭。
手動安裝：使用手動 grecaptcha.enterprise.execute() 呼叫或 HTML 按鈕屬性。您可以單獨使用這個方法，也可以搭配 AutoExecute 使用，用於 AutoExecute 不支援的網路要求、需要在酬載中自訂權杖位置的要求，或在逐步遷移至 AutoExecute 時使用。

請根據整合方式選擇合適的選項：

AutoExecute 設定

AutoExecute 會攔截網頁上的網路要求，並免除每個前端動作的手動 grecaptcha.enterprise.execute() 呼叫，有助於簡化前端 JavaScript 整合。

AutoExecute 只會攔截透過 Fetch API 或 XMLHttpRequest 啟動的非同步網路要求，包括來自 AJAX 等架構 (使用這些 API) 的要求。
AutoExecute 不支援在網頁載入時自動載入的資源。請改為將 AutoExecute 套用至使用者在網頁上執行動作 (例如點選登入按鈕) 時觸發的網路要求。
為避免 Fraud Defense 驗證導致網路逾時，請直接對要求套用逾時設定。請使用 AbortSignal.timeout(n) 處理 Fetch API，並使用 XMLHttpRequest.timeout 屬性處理 XMLHttpRequest。

在網頁中加入指令碼標記

如要在網頁上載入 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 指令碼偵測到對應路徑的非同步網路要求，就會攔截要求、觸發風險評估，並可能在原始要求繼續執行前，向使用者顯示 CAPTCHA 驗證。產生的回應權杖會自動附加至要求中的 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 也會攔截這些要求。這可能會導致額外的網路延遲、指標偏差或非預期的 CAPTCHA 驗證。為避免衝突，請確保受保護的路徑不重複 (例如 /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。如果不相符，則代表有攻擊者企圖假冒正常操作。

後續步驟

如要根據自訂規則觸發 CAPTCHA 驗證問題，請設定驗證政策。
如要評估 reCAPTCHA 回應權杖，請建立評估。