واجهة برمجة التطبيقات للتعرف على بروتوكول Recaptcha3

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

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

لاستخدام واجهة برمجة التطبيقات للتعرف على بروتوكول Recaptcha3، يجب أولاً الذهاب إلى لوحة تحكم Ace Data Cloud للحصول على رمز API الخاص بك، للاحتفاظ به كنسخة احتياطية.

إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم العودة تلقائيًا إلى الصفحة الحالية. يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة. ستتلقى رصيدًا مجانيًا عند التقديم لأول مرة، يمكنك تجربته مجانًا؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في لوحة التحكم.

📘 الوثائق الكاملة: واجهة برمجة التطبيقات للتعرف على بروتوكول Recaptcha3 →

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

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، مقارنةً بـ Recaptcha2، نحتاج إلى تمرير معلمة إضافية page_action، والتي يجب الحصول عليها من الكود، عنوان URL لعرض سرعة الشبكة هو: https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php، وفيما يلي طريقة للحصول عليها:

الطريقة السريعة:

افتح f12، ثم ابحث في صفحة العناصر عن .execute(، في منطقة الإطار الأحمر يمكننا رؤية معلمة action، بينما تتبع execute سلسلة من الأحرف، وهذا هو المحتوى المطلوب في الأسفل، كما هو موضح في الصورة أدناه.

بعد ذلك، تحتاج أيضًا إلى إدخال عنوان URL للموقع الذي يحتاج إلى معالجة رمز التحقق، للحصول على النتيجة المعالجة، يجب أولاً تمرير حقل website_url ببساطة، وأخيرًا تحتاج إلى إدخال معلمة website_key، والتي يمكن الحصول عليها من النص السابق، وهي أيضًا سلسلة من الأحرف بعد execute. يمكننا بعد ذلك ملء المحتويات المقابلة في الواجهة، كما هو موضح في الصورة:

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:

accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
authorization: مفتاح استدعاء واجهة برمجة التطبيقات، يمكن اختياره مباشرة بعد التقديم.

بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:

page_action: يجب الحصول عليها من كود الموقع الذي يحتوي على رمز التحقق.
website_url: عنوان URL للموقع الذي يحتاج إلى معالجة رمز التحقق.
website_key: معرف مفتاح الموقع في Recaptcha3.

بعد الاختيار، يمكن ملاحظة أنه تم أيضًا إنشاء كود مطابق على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، وهنا حصلنا على النتيجة التالية:

{
  "token": "03AFcWeA5mfdNlQD0RGX9PTWPs0l65QukjwbYObCue5hygRuA6jJmBtwR98S2bmmZOjbLh7ogEMDd8NzJdq8DoHOD_LHIUWmdEL3HJS0pP2nmTTSoU_ltxORWA4sVsrWiXDgkARA4wAhJCegD6PftkRuu0KKbqRsJ7KVKukUbLU1ThBu7P3r0fybwpS11yQmF7xpbEZeFzRm_osERk9tQzs1lEYORZSVA5dimbWi42TqUC87mJHCKO0HMiU404LOyER84It7ne51V5YXEHR_o6-ORr2CmBOawdTDTsqWUwT8vyEvzy-ov-pZdl0B0A_U59_uZd7vbIwv937-iXyzkVWbakUXNMdXlHffpFYd7OLTSBhJu6nasV3IhrbnxO8eGIbPDoHIyGpA74D882ALwTnXMgkcmGeGM9YuqCrf7F06cNKY7yKiisZIU-7v3ZnHV3JUkODGpXQ6dwq2fuP5o6kgeUQVdkv4fAZ_Tx_TB_R6gPSgwulr8Q5hH34bs-v1oUl2S9mLhXT9SWvgYizU_4FN2Ou23ETXTAVD_uI9fWaDgKaLOKI1i-xHCF_LKU3wKjyYJfQhFSCSyoeGL4o1j9lZ27cEHL5AlCm_jcCiXhe2_LT_dI-r5ozuyOGv-iDZ_1XTSSnCGdmroXX56XsZAytU52zBAlYVe_aRAojruc9KdkhK4kdeBESBbDLVe3-jNFwYspe0R93SORxXXIqR9CtZrIjI_2U8XjCHFz_euChdU_wkH5BjvONVbUT1DQNuoo0ugJL5kUkFrubHppOKvoZMwIKjjK_ZX1NBeCvQvYm6IpwBWfvM4hjGI7UVXH3iZkrX9PLATIIIkA8PxTeN45k8DulzOhKLSFKK196fRlH83S8UAaM-vjBxf32Vg83C1gWzKB5sYhxqEtZeB7DNpmAkozFfubljURr7YTjtq8Bgnj0PkfzbgKk8FRl-hMUb9BUjNNuSuFC7GZVim6xQnIV9ZPaAcuzJTYcOizFJePbVEXlc9A5Vq2rDh3D7Ld5o5oqc2kK4eCrO_38le6EVTs_fRY2nXy6RMyjjaJN12lOKYwYzGKhm52gTZTrJXqeTAW8o2KfwZ9iek-tr5qxj5b40iY4V2PY6SflMQvmKLAgFhB-yo-o5PEkikQ98T-bE-wG2-3kd5NRMiD132kIhf48zhVJUGeJqdV_3m8ukyqTk26KisM12kN-h9uYefvUCxzd_mBuWlHzH9rFMlJSe8Z6lcZIVcqNF4fcEM-ukNnwMUK5H_SC48U7O_xfOaEqEpAHDC7CCyVwlGCFh0uAT8KSpaNFfxBmMPXeYrGYn83PCgMg1NZA-7PrpeidXmWdBZ2yY8MA__7uCe8clCmINseBTCIbNmAHPlI_zJKqQfhXaDbaELeD62P0Pquu_SBtdEtqPeB9Esn_yjbK3IFvAaGSnFhwhHHK8dpOI7v-rJvTigPu8MMrEUTvug_zog81kCG8HY3xorTj2OdTwdEYpeMJ1VIHSjdTcnepLB0Cffx5wAdk-gf1TGEnEyTiwII4A4vtq8r0LFK4YObOzNmBTl3IoTNheYYKpheTKH3KShMK6hXDKxDRGEUhdsW4TRtVT-dwJDqY_F7J1RwKP-xDuN98VgwQmQuhJteQUALevgI2jAGFCFfSeFbQ8BOT6ekEI0m30zDX0kh83mkE7-u9qKljYifjqbLarMNPP51QRbvAS3mHlP17PMhIKzjuIka4T2Y9XdRwDgRRdEkYiJgDvkcABTknGBMezraon8JNDRhIJMUIKpidWTdhEQ79qAEfZkowdbnTdKeWeayi1OmV_W4aox-aC62H-VIn70McXXB6zRyYlA2NvTUWgNhHWkSO1SW7uflNEyUeWFRLBZV_firMEVfIGirHOAbQqsn83BirDNPHl4xevf4nRu4gWpgOGBrzeUXQeuMWO4ZFsdWxJ2VsT19t0H5DJtxtHYXFtPZ8tFDFY-r8JKFab4S6e5v8PCrfjCWkPmDaRJal_vLFa1V1dF1l0ARu9NLW4mEuT600azFms8cMlvuCTvWI2VWyn4Wk05UvcR8FYO2-ke4E-ZFRl0jSxjlEutzbOwm2ik4eF0Wh2DBliaSr1obHaxkmLJDUIzGQ3wi49Nyn0SSOdz_BGaxuRrrxCZ4ci0e2b5cxLtkv64Njy7IYJURaBuQk99ijdw7rg3pssAa_uJSMQeZe_kLtgEWF73uT4ceSOFPVuxMGLrJRQTBYxAHVKq7kloS5wtphUr2Sp-b4kezKnCV9HNfC5NRk2KqDT-bkJ6cUYN_0yauyZK1_F4BVTk36IOCe1Cqfe3K-wAZBzvrI_Vz8Li1uEWe0b5KOQ"
}

توجد عدة حقول في النتيجة، كما هو موضح أدناه:

token، نتيجة التحقق من مهمة Recaptcha3.

يمكننا أن نرى أننا حصلنا على نتيجة معالجة Recaptcha3، ثم يمكننا استخدامها في POST أو GET لمحاكاة الإرسال إلى الموقع المستهدف، وهي صالحة للاستخدام مرة واحدة لمدة 120 ثانية، يُنصح باستخدامها خلال 60 ثانية. فيما يلي سنقدم باختصار طريقة لتقديم الـ token المولد إلى الموقع المستهدف: استدعاء كود Python للتحقق من الـ token:

import requests

url = "https://recaptcha-demo.appspot.c/recaptcha-v3-verify.php?action=examples/v3scores&token='{token}'"

r = requests.get(url)
if r.status_code == 200:
    return r.text

لذا يمكننا الحصول على النتيجة:

{
  "success": true,
  "hostname": "recaptcha-demo.appspot.com",
  "challenge_ts": "2024-09-14T08:52:26Z",
  "apk_package_name": null,
  "score": 0.9,
  "action": "examples/v3scores",
  "error-codes": []
}

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

curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha3' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php",
  "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9",
  "page_action": "examples/v3scores"
}'

كود الربط بلغة بايثون كما يلي:

import requests

url = "https://api.acedata.cloud/captcha/token/recaptcha3"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php",
    "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9",
    "page_action": "examples/v3scores"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

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

بشكل افتراضي، تكون واجهة برمجة التطبيقات متزامنة وتنتظر: ستنتظر الطلب حتى يتم معالجة الرمز. إذا كنت تقوم بتدوير حل متعدد (multi-solver rotation) وترغب في “تقديم المهمة والحصول على task_id على الفور، ثم جدولة حل آخر، والعودة لاحقًا للحصول على النتيجة”، يمكنك تمرير async: true في جسم الطلب. بعد تمرير async: true، ستعيد الواجهة على الفور task_id، دون الانتظار:

curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha3' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php",
  "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9",
  "page_action": "examples/v3scores",
  "async": true
}'

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab",
  "status": "processing"
}

بعد ذلك، استخدم task_id للاستعلام عن POST /captcha/tasks (يوصى كل 3~5 ثوانٍ مرة واحدة) للحصول على النتيجة:

curl -X POST 'https://api.acedata.cloud/captcha/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002"
}'

أثناء المعالجة، ستعيد status: processing:

{ "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "processing" }

عند الانتهاء من المعالجة، ستعيد status: ready والرمز:

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "token": "03AFcWeA5mfdNlQD0RGX9PTWPs0l65QukjwbYObCue5hygRuA6......"
}

شرح الفوترة: في الوضع غير المتزامن، لا يتم احتساب رسوم لإنشاء المهام أو الاستعلام عن “قيد المعالجة”; يتم احتساب الرسوم مرة واحدة فقط عند الحصول على النتيجة بنجاح (بأسعار متطابقة مع الوضع المتزامن). لذلك، فإن إلغاء المهام التي لم تكتمل بعد أثناء التدوير لن ينتج عنه أي رسوم. /captcha/tasks متاحة لجميع واجهات برمجة التطبيقات الخاصة بالتحقق من الرموز (token و recognition series) ويمكن استخدام نفس task_id للاستعلام.

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

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستعيد الواجهة رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال:

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

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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

الخاتمة

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

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

وكيل

متقدم

واجهة برمجة التطبيقات للتعرف على بروتوكول Recaptcha3

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

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

الطريقة السريعة:

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

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

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

الخاتمة

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

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

​الطريقة السريعة:

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

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

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

​الخاتمة

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

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

الطريقة السريعة:

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

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

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

الخاتمة