使用舊版 SiteVerify 驗證使用者回應權杖

本頁說明如何透過應用程式的後端，使用舊版 SiteVerify API 端點 (https://www.google.com/recaptcha/api/siteverify) 驗證使用者對 reCAPTCHA 驗證問題做出的回應。只有在維護無法使用 CreateAssessment 的舊版整合項目或第三方外掛程式時，才應使用這個端點。

事前準備

如要呼叫 SiteVerify 端點，您需要金鑰的舊版密鑰。如要在 Google Cloud 控制台中尋找密鑰，請參閱「在 Google Cloud 控制台中擷取密鑰」。請在後端伺服器上妥善保管密鑰，絕不要在用戶端程式碼中公開密鑰。

擷取使用者的回應權杖

舊版網頁整合功能會載入非企業版 JavaScript API (https://www.google.com/recaptcha/api.js)，並在 grecaptcha 物件上提供方法，而非 grecaptcha.enterprise。您可以在前端透過下列任一方式擷取使用者的回應權杖：

  • 使用者在網站上提交表單時，透過 g-recaptcha-response POST 參數取得。
  • 在使用者完成 reCAPTCHA v2 驗證問題後呼叫 grecaptcha.getResponse(opt_widget_id)。這個方法會以字串形式傳回回應權杖，如果未完成驗證，則會傳回空字串。選用的 opt_widget_id 參數會指定 grecaptcha.render() 傳回的小工具 ID；如果省略，則預設為建立的第一個小工具。
  • 如果使用者完成挑戰，系統會將字串引數傳遞至回呼函式。如要啟用這項功能，請在 g-recaptcha HTML 元素的 data-callback 屬性或 grecaptcha.render(container, parameters) 方法的 callback 參數中，指定回呼函式名稱。
  • 從 grecaptcha.execute(site_key, {action: action_name}) 為以分數為依據 (v3) 的鍵傳回的 Promise 解析值。

舊版 grecaptcha 方法 (render、getResponse、execute、ready 和 reset) 和 g-recaptcha 標記屬性使用的參數，與 grecaptcha.enterprise 對應項目相同。如需參數詳細資料，請參閱 reCAPTCHA 的 JavaScript API 參考資料。

如要遷移至更新後的 reCAPTCHA JavaScript API，請參閱「遷移 reCAPTCHA JavaScript API」。

權杖限制

每個 reCAPTCHA 使用者回應權杖的效期為 2 分鐘，而且每個權杖只能驗證「一次」，以防範重複驗證攻擊。收到回應權杖後，請在兩分鐘內透過 reCAPTCHA 驗證權杖。如需新權杖，請重新執行 reCAPTCHA 驗證。

API 要求

使用下列端點和方法傳送要求：

  • 網址：https://www.google.com/recaptcha/api/siteverify (如果無法存取 www.google.com，請使用 https://www.recaptcha.net/recaptcha/api/siteverify；請參閱「在全球使用 reCAPTCHA」一文)
  • 方法：POST

請在要求中加入下列 POST 參數：

POST 參數 說明
secret 這是必要旗標，網站與 reCAPTCHA 共用的密鑰。
response 這是必要旗標，網站上 reCAPTCHA 用戶端整合功能提供的使用者回應權杖。
remoteip 選用。使用者的 IP 位址。

API 回應

SiteVerify 端點會傳回 JSON 物件。

如果是網頁整合 (以分數為準的 v3、核取方塊 v2 或隱形 v2 金鑰)，回應格式如下：

{
  "success": true|false,      // whether this request was a valid reCAPTCHA token for your site
  "score": number,            // the score for this request (0.0 - 1.0) for score-based (v3) keys
  "action": string,           // the action name for this request (important to verify)
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}

錯誤代碼參考資料

下表說明 error-codes 陣列中可能出現的錯誤碼：

錯誤代碼 說明
missing-input-secret 缺少 secret 參數。
invalid-input-secret secret 參數無效或格式錯誤。
missing-input-response 缺少 response 參數。
invalid-input-response response 參數無效或格式錯誤。
bad-request 要求無效或格式錯誤。
timeout-or-duplicate 回覆已失效，因為已過期或先前已使用過。

後續步驟