本頁面由 Cloud Translation API 翻譯而成。

在應用程式伺服器上設定 reCAPTCHA Express

如果無法在用戶端整合 reCAPTCHA JavaScript 或行動裝置 SDK，例如要保護 API 端點，則可在應用程式伺服器上設定 reCAPTCHA Express。

reCAPTCHA Express 是一項功能，可讓您建立評估，不必整合用戶端或使用用戶端信號。reCAPTCHA Express 只會使用後端信號產生 reCAPTCHA 風險分數。您可以根據這項風險分數，決定是否要處理要求、重新導向至驗證頁面，或是記錄要求以供日後分析。

事前準備

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
- Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Go to project selector
請記下專案 ID，以供日後使用。 Google Cloud
Verify that billing is enabled for your Google Cloud project.
Enable the reCAPTCHA Enterprise API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API
建立用於驗證的 API 金鑰：
1. 前往 Google Cloud 控制台的「憑證」頁面。
  
  前往「憑證」
2. 按一下「建立憑證」，然後選取「API 金鑰」。
3. 請記下 API 金鑰，稍後會用到。

建立 reCAPTCHA Express 金鑰

如要導入 reCAPTCHA Express，請建立 reCAPTCHA Express 金鑰。

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell
gcloud

如要建立 reCAPTCHA 金鑰，請使用 gcloud recaptcha keys create 指令。

使用下列任何指令資料之前，請先替換以下項目：
- INTEGRATION_TYPE：整合類型。指定 score。
- DISPLAY_NAME：金鑰名稱。通常是網站名稱。
執行 gcloud recaptcha keys create 指令：
Linux、macOS 或 Cloud Shell

gcloud recaptcha keys create \ --express \ --display-name=DISPLAY_NAME
Windows (PowerShell)

gcloud recaptcha keys create ` --express ` --display-name=DISPLAY_NAME
Windows (cmd.exe)

gcloud recaptcha keys create ^ --express ^ --display-name=DISPLAY_NAME
回應包含新建立的 reCAPTCHA 金鑰。
REST
如要查看金鑰類型和整合類型的 API 參考資訊，請參閱「金鑰」和「整合類型」。
使用任何要求資料之前，請先替換以下項目：
- INTEGRATION_TYPE：整合類型。指定 score。
- DISPLAY_NAME：金鑰名稱。通常是網站名稱。
- DEFAULT_SCORE_THRESHOLD：如果是以政策為準的驗證問題金鑰，當未定義自訂分數門檻時，這會定義金鑰的通用驗證問題門檻。這項功能目前為預先發布版。
- ACTION_SCORE_THRESHOLDS：如果是以政策為準的驗證金鑰，這會指定動作和對應的門檻分數 (介於 0.0 和 1.0 之間)。例如，login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'。這項功能目前為預先發布版。
  注意：評估結果只會傳回在完成所有挑戰後計算出的最終分數。系統會將 reCAPTCHA 計算的初始分數與門檻進行比較。
HTTP 方法和網址：
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys
JSON 要求主體：
{ "displayName": "DISPLAY_NAME", "expressSettings": {} }
如要傳送要求，請選擇以下其中一個選項：
curl

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
-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"

PowerShell

注意： 下列指令假設您已執行 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 POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content
您應該會收到如下的 JSON 回應：
{ "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m", "displayName": "DISPLAY_NAME, "expressSettings": { } }

請記下快速鍵，稍後會用到。

建立評估

如要從應用程式伺服器向 reCAPTCHA 提出要求，請使用 projects.assessments.create 方法建立評估。

使用任何要求資料之前，請先替換以下項目：

API_KEY：您為驗證建立的 API 金鑰。
EXPRESS_KEY：您為應用程式建立的 reCAPTCHA Express 金鑰。
USER_IP_ADDRESS：使用者裝置在與此事件相關的請求中提供的 IP 位址。
HEADER_INFO：選用。用戶端傳送至應用程式伺服器的 HTTP 標頭。這是字串陣列，包含 `[key:value]` 格式的要求標頭。例如 `[key:value, key:value,...]`。建議您盡可能分享多個標題，並按照必要順序排列。請確保同一工作階段中所有要求的標頭順序一致。
JA3_FINGERPRINT：選用。JA3 是 TLS 用戶端問候封包特定欄位的 MD5 指紋。詳情請參閱「JA3 - A method for profiling SSL/TLS Clients」。
URI_NAME：選用。使用者存取的 URI。
USER_AGENT：選用。使用者裝置在與此事件相關的請求中提供的使用者代理程式。
ACCOUNT_ID：選用。使用者帳戶的專屬永久 ID，例如經過雜湊處理的帳戶名稱。

HTTP 方法和網址：

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

JSON 要求主體：


{
  "event": {
    "siteKey": "EXPRESS_KEY",
    "express": true,
    "userIpAddress": "USER_IP_ADDRESS",
    "headers": ["HEADER_INFO"],
    "ja3": "JA3_FINGERPRINT",
    "requestedUri": "URI_NAME",
    "userAgent": "USER_AGENT",
    "user_info": {
      "account_id": "ACCOUNT_ID"
    }
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

PowerShell

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "name": "projects/123456789/assessments/abcdef1234000000",
  "event": {
    "token": "",
    "siteKey": "6L...",
    "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 13816.55.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.86 Safari/537.36",
    "userIpAddress": "1.2.3.4",
    "express": true,
    "requestedUri": "https://example.com/",
    "user_info": {
      "account_id": "123456789"
    },
    "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

解讀分數

reCAPTCHA Express 只會傳回兩個分數：0.3 和 0.7。0.3 表示使用者互動的風險較高，可能是詐欺行為；0.7 表示使用者互動的風險較低，可能是正當活動。

如果信號不足，reCAPTCHA Express 預設會傳回 0.7。

在應用程式伺服器上設定 reCAPTCHA Express

事前準備

建立 reCAPTCHA Express 金鑰

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl

PowerShell

建立評估

curl

PowerShell

解讀分數

後續步驟