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

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

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

事前準備

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

    請記下專案 ID，以供日後使用。 Google Cloud

  2. Make sure that billing is enabled for your Google Cloud project.

  3. Enable the reCAPTCHA Enterprise API.

    Enable the API

  4. 建立用於驗證的 API 金鑰：

    1. 前往 Google Cloud 控制台的「憑證」頁面。

      前往「憑證」

    2. 按一下「建立憑證」，然後選取「API 金鑰」。

    3. 請記下 API 金鑰，稍後會用到。

建立 reCAPTCHA Express 金鑰

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

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. gcloud

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

    使用下方的任何指令資料之前，請先替換以下項目：

    • 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 參考資訊，請參閱「金鑰」和「整合類型」。

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

    • DISPLAY_NAME：金鑰名稱。通常是網站名稱。

    HTTP 方法和網址：

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

    JSON 要求主體：

    
{
  "displayName": "DISPLAY_NAME",
  "expressSettings": {}
}

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

    curl

    將要求主體儲存在名為 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

    將要求主體儲存在名為 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。

後續步驟