אימות טוקנים של תשובות משתמשים באמצעות SiteVerify מדור קודם

בדף הזה מוסבר איך לאמת את התשובה של משתמש לאתגר reCAPTCHA מהבק-אנד של האפליקציה באמצעות נקודת הקצה של SiteVerify API מדור קודם (https://www.google.com/recaptcha/api/siteverify). כדאי להשתמש בנקודת הקצה הזו רק אם אתם מתחזקים שילוב מדור קודם או פלאגין של צד שלישי שלא יכול להשתמש ב-CreateAssessment.

לפני שמתחילים

כדי להתקשר לנקודת הקצה SiteVerify, צריך את המפתח הסודי מדור קודם של המפתח. כדי למצוא את המפתח הסודי במסוף Google Cloud , אפשר לעיין במאמר אחזור המפתח הסודי במסוף Google Cloud . חשוב לשמור על המפתח הסודי בשרת העורפי ולא לחשוף אותו אף פעם בקוד בצד הלקוח.

אחזור טוקן התשובה של המשתמש

שילובים קודמים של אתרים טוענים את JavaScript API שאינו מיועד לארגונים (https://www.google.com/recaptcha/api.js), שמספק שיטות באובייקט grecaptcha במקום grecaptcha.enterprise. אפשר לאחזר את טוקן התשובה של המשתמש בחלק הקדמי של האתר באחת מהדרכים הבאות:

  • מפרמטר POST מסוג g-recaptcha-response כשמשתמש שולח טופס באתר.
  • על ידי קריאה ל-grecaptcha.getResponse(opt_widget_id) אחרי שהמשתמש מסיים אתגר reCAPTCHA גרסה 2. הפונקציה הזו מחזירה את טוקן התגובה כמחרוזת, או מחרוזת ריקה אם האתגר לא הושלם. הפרמטר האופציונלי opt_widget_id מציין את מזהה הווידג'ט שמוחזר על ידי grecaptcha.render(). אם לא מציינים אותו, ברירת המחדל היא הווידג'ט הראשון שנוצר.
  • כארגומנט מחרוזת שמועבר לפונקציית הקריאה החוזרת כשמשתמש משלים אתגר, אם מציינים את שם פונקציית הקריאה החוזרת במאפיין data-callback של רכיב ה-HTML‏ g-recaptcha או בפרמטר callback של method‏ grecaptcha.render(container, parameters).
  • מהערך שמתקבל של Promise שמוחזר על ידי grecaptcha.execute(site_key, {action: action_name}) עבור מפתחות מבוססי-ציון (גרסה 3).

השיטות מדור קודם grecaptcha (‏render,‏ getResponse,‏ execute,‏ ready ו-reset) ומאפייני התג g-recaptcha משתמשים באותם פרמטרים כמו המקבילים שלהם grecaptcha.enterprise. לפרטים על הפרמטרים, ראו את מאמרי העזרה של ה-API של reCAPTCHA ב-JavaScript.

כדי לעבור לגרסה המעודכנת של reCAPTCHA JavaScript API, אפשר לעיין במאמר בנושא העברה של reCAPTCHA JavaScript API.

הגבלות על טוקנים

כל טוקן של תשובת משתמש ב-reCAPTCHA תקף למשך שתי דקות. וכדי למנוע מתקפות מסוג Replay, אפשר לאמת כל טוקן רק פעם אחת. צריך לאמת את טוקן התשובה באמצעות reCAPTCHA תוך שתי דקות מרגע קבלתו. אם אתם צריכים טוקן חדש, צריך להריץ שוב את האימות מסוג reCAPTCHA.

בקשת API

שולחים בקשה עם נקודת הקצה והשיטה הבאות:

  • כתובת URL: https://www.google.com/recaptcha/api/siteverify (או https://www.recaptcha.net/recaptcha/api/siteverify אם אין גישה אל www.google.com. מידע נוסף זמין במאמר שימוש ב-reCAPTCHA באופן גלובלי)
  • Method: ‏ 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 התגובה כבר לא תקפה כי תוקף שלה פג או שכבר נעשה בה שימוש.

המאמרים הבאים