שימוש בשירות פתרון CAPTCHA ב-Express

השתמשו ב-Node.js 22 ומעלה וב-Express 5. התקינו את ה-SDK הרשמי של JavaScript באמצעות התקנת tarball המתוארת בתיעוד, במקום להניח שהוא פורסם במאגר npm. הדוגמה יוצרת לקוח Solvethree אחד מחוץ לפונקציות הטיפול.

• SOLVETHREE_API_KEY: מפתח ה-API של סביבת העבודה שלכם. שמרו אותו בשרת.
• INTEGRATION_KEY: סוד נפרד לגורמים קוראים פנימיים מהימנים. הדוגמה דורשת אותו בכותרת x-integration-key; אל תפיצו אותו ללקוחות דפדפן. אם כבר יש לכם שכבת ביניים לאימות, השתמשו בה במקום מנגנון ההגנה באמצעות מפתח משותף שבדוגמה.
• CAPTCHA_SITE: שם המארח של היעד, ולא כתובת URL מלאה. הגדירו פרופיל אתר פעיל לסביבת העבודה שלכם לפני יצירת משימות; שליחת שם מארח אינה יוצרת פרופיל.
• SOLVETHREE_PROXY: הפרוקסי עבור היעד הזה. הדוגמה מספקת פרוקסי יחיד ומקבעת את הפעולה ל-login. שנו את הפעולה בצד השרת אם היעד שלכם משתמש בפעולה אחרת.

הבקשה הזו משתמשת בתצורת ברירת המחדל של reCAPTCHA Enterprise. היא דורשת site,‏ action ופרוקסי — לא type או url. ראו הגדרת פרופיל אתר אם היעד עדיין אינו מוגדר.

// npm install express and the official solvethree SDK tarball.
import express from 'express';
import { Solvethree, SolvethreeError } from '@solvethree/sdk';
const app = express();
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const secret = process.env.INTEGRATION_KEY;
if (!secret) throw new Error('Set INTEGRATION_KEY');
app.use((request, response, next) => {
  if (request.get('x-integration-key') !== secret) return response.sendStatus(401);
  next();
});
app.post('/captcha/tasks', async (request, response) => {
  const task = await client.createTask({
    site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
    requestId: request.get('x-request-id'),
  }, { waitMs: 0, signal: AbortSignal.timeout(20000) });
  response.json(task);
});
app.get('/captcha/tasks/:id', async (request, response) => {
  response.json(await client.getTask(request.params.id, { waitMs: 15000, signal: AbortSignal.timeout(25000) }));
});
app.use((error, request, response, next) => {
  if (error instanceof SolvethreeError) return response.status(502).json({ requestId: error.requestId, taskId: error.taskId });
  response.status(400).json({ error: 'Invalid task input or ID' });
});
app.listen(3000);

שני הנתיבים מוגנים באמצעות מנגנון האימות. פונקציית הטיפול ב-POST לוקחת את שם המארח, הפעולה והפרוקסי מתצורת השרת, ולא מגוף הבקשה. רק מזהה היצירה האופציונלי מגיע מהגורם הקורא.

1. 1.

   הקצו מזהה בקשה לפני היצירה

   שלחו x-request-id עם 1–64 אותיות ASCII, ספרות, קווים תחתונים או מקפים. שמרו אותו עם הבקשה הלוגית כדי שתוכלו לשחזר את היצירה אם הזמן הקצוב לחיבור יפוג.

2. 2.

   שלחו POST אל /captcha/tasks פעם אחת

   פונקציית הטיפול קוראת ל-createTask עם waitMs: 0 ומחזירה את המשימה. שמרו את המזהה שלה. תגובה מוצלחת פירושה שיש לכם משימה, ולא בהכרח פתרון.

3. 3.

   אחזרו את הסטטוס באמצעות GET

   קראו ל-/captcha/tasks/:id. המשיכו לאחזר כל עוד הסטטוס הוא pending או solving; אל תחזרו על POST כדי לבדוק התקדמות. עצרו במצב ready או failed.

4. 4.

   השתמשו רק בפתרון מוכן

   שלחו את הטוקן עם userAgent ו-secChUa שהוחזרו, באמצעות אותו פרוקסי מוגדר ולאותו יעד מיועד. ה-SDK אינו שולח אותו עבורכם. משימה מוכנה פירושה שנוצר פתרון, ולא שהיעד קיבל את בקשת האפליקציה שלכם.

לקריאת ה-SDK של POST יש מגבלת זמן של 20 שניות באמצעות AbortSignal. קריאת GET מאפשרת המתנה של 15 שניות למשימה, במסגרת מגבלת זמן של 25 שניות לקריאת ה-SDK. תגובת GET עדיין עשויה להיות במצב שאינו סופי; בדקו את הסטטוס שלה במקום לראות בסיום ההמתנה כישלון של הפתרון.

חריגה מהזמן הקצוב ליצירה אינה מוכיחה ש-solvethree דחה את הבקשה. אם קיבלתם מזהה משימה, אחזרו אותה. אחרת, חזרו על היצירה עם אותו מזהה בקשה ועם קלטי משימה ללא שינוי כדי לשחזר את המשימה הקיימת. שימוש חוזר במזהה הזה עם קלטים שונים יוצר התנגשות. אם לא שמרתם מזהה בקשה, POST חדש עלול ליצור עבודה נפרדת.

Express 5 מעביר דחיות של פונקציות טיפול אסינכרוניות לשכבת הביניים לטיפול בשגיאות. הדוגמה מחזירה HTTP 502 עבור SolvethreeError, וחושפת רק את מזהי הבקשה והמשימה שלו — לא את השגיאה הגולמית, פרטי הגישה או הפתרון. תגובת ה-HTTP 400 החלופית שלה כללית; היא אינה מסווגת במדויק כל שגיאה שאינה שגיאת SDK, כולל שגיאות של חריגה ממגבלת זמן.

טפלו בשגיאות HTTP לפני קריאת נתוני תגובה מוצלחת. בנפרד מכך, משימה שאוחזרה יכולה להיות בסטטוס failed: בדקו את errorCode ואת error שלה, ואז הפסיקו את התשאול. ניתן החזר כספי על פתרונות שנכשלו, אך ניסיון חוזר עם קלטים לא תקינים שלא שונו לא יתקן אותם. השתמשו במדריך שגיאות ה-API כדי לאבחן את הכשל שדווח.