Skip to main content
ستقدم هذه الوثيقة شرحًا حول واجهة برمجة التطبيقات للتعرف على بروتوكول Recaptcha2، والتي تتيح للمستخدمين التحقق من الصور الخاصة برمز التحقق Recaptcha2 دون الحاجة إلى التعرف عليها أو النقر عليها، بل يكفي تقديم مفتاح الموقع لتحقيق فك التشفير التلقائي في الخلفية وإكمال التحقق.

​
عملية التقديم

لاستخدام واجهة برمجة التطبيقات للتعرف على بروتوكول Recaptcha2، يجب أولاً الذهاب إلى لوحة تحكم Ace Data Cloud للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا. إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم العودة تلقائيًا إلى الصفحة الحالية. يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة. عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في لوحة التحكم.
📘 الوثائق الكاملة: واجهة برمجة التطبيقات للتعرف على بروتوكول Recaptcha2 →

​
الاستخدام الأساسي

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال عنوان URL للموقع الذي يحتاج إلى معالجة رمز التحقق، للحصول على النتيجة المعالجة. يجب أولاً تمرير حقل website_url ببساطة، وموقعنا التجريبي هو: https://www.google.com/recaptcha/api2/demo، نحتاج إلى الحصول على website_key من صفحة website_url، يجب أولاً فتح هذه الصفحة، ثم الضغط على F12 للدخول إلى وحدة التحكم، وأخيرًا البحث عالميًا في صفحة العناصر عن recaptcha-demo، وسنحصل على النتيجة التالية:

حيث أن السلسلة المرتبطة بـ data-sitekey هي قيمة website_key، وفيما يلي النتائج المحددة للمعلمات:

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء واجهة برمجة التطبيقات، يمكن اختياره مباشرة بعد التقديم.
كما تم تعيين جسم الطلب، بما في ذلك:
  • website_url: عنوان URL للموقع الذي يحتاج إلى معالجة رمز التحقق.
  • website_key: معرف مفتاح الموقع في Recaptcha2.
  • proxy: اختياري، استخدم وكيل خاص بك (Bring Your Own Proxy). بعد التعيين، ستقوم الخدمة باستخدام IP الوكيل الذي تقدمه لفك تشفير رمز التحقق، للتحكم في جودة IP الخارجي (على سبيل المثال، لتجنب حظر IP الوكيل العام من قبل الموقع المستهدف مما يؤدي إلى إرجاع 410 Gone). التنسيق هو scheme://[user:pass@]host:port، حيث يدعم scheme http/https/socks4/socks5، مثل http://user:pass@1.2.3.4:8080. إذا لم يتم ملؤه، سيتم استخدام الوكيل الافتراضي للمنصة.
بعد الاختيار، يمكنك أن تلاحظ أنه تم إنشاء كود مطابق على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، وهنا حصلنا على النتيجة التالية:
تحتوي النتيجة على عدة حقول، كما هو موضح أدناه:
  • token، نتيجة التحقق من مهمة Recaptcha2 بعد المعالجة.
  • started_at، finished_at: الوقت الذي بدأ فيه الطلب ومعالجة النتيجة، طابع زمني Unix (ثوانٍ، عائم).
  • elapsed: إجمالي الوقت المستغرق في المعالجة (ثوانٍ).
يمكننا أن نرى أننا حصلنا على نتيجة التحقق من Recaptcha2، ثم يمكننا استخدامها في POST أو محاكاة تقديمها إلى الموقع المستهدف، للاستخدام لمرة واحدة، صلاحيتها 120 ثانية، يُنصح باستخدامها خلال 60 ثانية، بعد ذلك سنقدم جزءًا من كود Python لتقديم الـ token المعالج إلى الموقع المستهدف لتجاوز Recaptcha2. أولاً، نحتاج إلى معرفة كيفية إرسال الموقع لطلبات POST، حتى نتمكن من تمرير الـ token الذي تم إنشاؤه. نحتاج أولاً إلى فتح وحدة التحكم F12، ثم نقوم بالتحقق يدويًا، وأخيرًا يمكننا رؤية أن الموقع أرسل طلب POST، كل ما علينا هو مراجعة بناء هذا الطلب، العملية المحددة كما يلي:
  • أولاً، تحقق يدويًا، كما هو موضح في الصورة أدناه:

  • ثم انقر على submit، وراقب تغييرات الشبكة في وحدة التحكم، كما هو موضح في الصورة أدناه:

  • تحليل بناء طلب POST المقدم، يمكننا في النهاية النقر بزر الماوس الأيمن على هذا الطلب لنسخ كود CURL، كما هو موضح في الصورة أدناه:

من خلال تحليل الصورة أعلاه، يمكننا أن نرى أن عنوان URL لطلب POST هذا هو: https://www.google.com/recaptcha/api2/demo، نحن بحاجة فقط لتقديم المعامل g-recaptcha-response، ثم نحتاج فقط إلى تمرير الرمز المعالج إلى البيانات أدناه، كود CURL المحدد لاستدعاء الرمز للتحقق هو كما يلي:
كود Python لاستدعاء التحقق من الرمز هو كما يلي:
ثم نقوم بتشغيل الكود ونلاحظ أن وحدة التحكم أصبحت بهذا الشكل:

وأخيرًا، نجحنا في اجتياز تحقق Recaptcha2. بالإضافة إلى ذلك، إذا كنت ترغب في توليد كود التكامل المقابل، يمكنك نسخه مباشرة، مثل كود CURL كما يلي:
كود التكامل بلغة Python هو كما يلي:

​
الوضع غير المتزامن (async)

بشكل افتراضي، تكون واجهة برمجة التطبيقات متزامنة وتنتظر: ستنتظر الطلب حتى يتم معالجة الرمز قبل أن تعود. إذا كنت تقوم بتدوير حل متعدد (multi-solver rotation) وترغب في “تقديم المهمة والحصول على task_id على الفور، ثم الانتقال إلى جدولة حل آخر، والعودة لاحقًا لقراءة النتيجة”، يمكنك تمرير async: true في جسم الطلب. بعد تمرير async: true، ستعيد الواجهة على الفور task_id، دون الانتظار:
إذا كنت ترغب في التحقق من التقدم، يمكنك استخدام task_id للاستعلام عن POST /captcha/tasks (يوصى بذلك كل 3~5 ثوان). هذه الواجهة لن تحفز أو تدفع معالجة المهمة؛ حتى لو لم يتم الاستعلام، أو انقطع الاتصال، أو خرجت من العميل، سيستمر الخادم في المعالجة:
أثناء المعالجة، ستعيد status: processing:
عند الانتهاء من المعالجة، ستعيد status: ready والرمز:
شرح الفوترة: في الوضع غير المتزامن، لا يتم احتساب رسوم لإنشاء المهمة وقراءة حالة “قيد المعالجة”؛ يتم احتساب الرسوم مرة واحدة عند قراءة العميل للنتيجة الناجحة لأول مرة (بما يتماشى مع السلوك الحالي وأسعار الوضع المتزامن). سيقوم الخادم بدفع المهمة بشكل مستقل، لكنه لن يخصم الرسوم مقدمًا لمجرد أن الخلفية قد اكتملت. إذا لم تنجح المهمة خلال 120 ثانية، ستنتهي إلى HTTP 504 timeout، دون احتساب رسوم. /captcha/tasks لا تتحمل مسؤولية دفع المهمة.

​
معالجة الأخطاء

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستعيد الواجهة رمز الخطأ والمعلومات المقابلة. على سبيل المثال:
  • 400 token_mismatched: طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 400 api_not_implemented: طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 401 invalid_token: غير مصرح به، رمز تفويض غير صالح أو مفقود.
  • 429 too_many_requests: عدد كبير جدًا من الطلبات، لقد تجاوزت الحد الأقصى لمعدل الطلبات.
  • 500 api_error: خطأ داخلي في الخادم، حدث خطأ ما على الخادم.

​
مثال على استجابة الخطأ

​
الخاتمة

من خلال هذه الوثيقة، أصبحت لديك فكرة عن كيفية استخدام واجهة برمجة التطبيقات الخاصة بـ Recaptcha2 للتعرف على المستخدمين دون الحاجة إلى التعرف على أو النقر على صور رمز التحقق Recaptcha2، يكفي تقديم Website Key لتحقيق فك التشفير التلقائي في الخلفية وإكمال التحقق. نأمل أن تساعدك هذه الوثيقة في التكامل واستخدام هذه الواجهة بشكل أفضل. إذا كان لديك أي استفسارات، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.