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

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

لاستخدام واجهة برمجة التطبيقات، يجب أولاً زيارة صفحة واجهة برمجة التطبيقات للتعرف على الصور من hCaptcha للتقدم للحصول على الخدمة المناسبة، بعد الدخول إلى الصفحة، انقر على زر “Acquire”، كما هو موضح في الصورة: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد تسجيل الدخول، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات هذه مجانًا.

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

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال صورة رمز التحقق من hCaptcha التي تحتاج إلى معالجتها، للحصول على النتيجة المعالجة، يجب أولاً تمرير حقل queries، وهو صورة رمز التحقق من hCaptcha المحددة، نحتاج إلى التقاط صورة لهذه الصورة من موقع يحتوي على رمز التحقق من hCaptcha، ورابط الموقع التجريبي هو: https://democaptcha.com/demo-form-eng/hcaptcha.html، انقر على مربع الاختيار لعرض صورة رمز التحقق الكاملة، كما هو موضح في الصورة أدناه:

حيث أن حقل queries هو لقطة الشاشة لصورة رمز التحقق المذكورة أعلاه، يُفضل ألا يتجاوز حجم الصورة 100 كيلوبايت، ويجب أيضًا التقاط صورة للمنطقة المشار إليها بالسهم الأحمر في الصورة أعلاه، ويجب عليك ضغط حجم الصورة بنفسك، ويجب أيضًا تحويلها إلى ترميز Base64، كما هو موضح في الصورة أدناه:

كما يجب إدخال معلمة محتوى التعرف ذات الصلة بصورة رمز التحقق question، والتي تدعم الترجمة بين اللغتين العربية والإنجليزية، يمكنك إدخال المحتوى ذي الصلة مباشرة، كما يتضح من المحتوى المنفذ بواسطة السهم الأصفر في الصورة أعلاه، يجب أن يكون إدخال question هو Please click on the UNIQUE object among the others.. المحتوى المحدد هو كما يلي:

يمكنك أن ترى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: الشكل الذي ترغب في تلقي استجابة به، هنا يتم ملؤه بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء واجهة برمجة التطبيقات، يمكنك اختياره مباشرة بعد التقديم.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • queries: قائمة صور رمز التحقق المشفرة بتنسيق Base64.
  • question: معلمة محتوى التعرف ذات الصلة بصورة رمز التحقق، تدعم الإدخال المباشر باللغتين.
بعد الاختيار، يمكنك أن تلاحظ أنه تم إنشاء كود مطابق على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء اختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية: 
{
  "solution": {
    "label": "Please click on the UNIQUE object among the others",
    "box": [
      "360",
      "276"
    ],
    "confidences": 0.6354503631591797
  }
}
تتضمن النتيجة عدة حقول، كما هو موضح أدناه:
  • solution، نتيجة التحقق من معالجة صورة رمز التحقق من hCaptcha.
    • label، المحتوى الذي تم التعرف عليه من صورة رمز التحقق من hCaptcha.
    • box، معلومات موقع نتيجة التعرف على صورة رمز التحقق من hCaptcha، وهي تتكون من معلومات إحداثيات الصورة.
    • confidences، مستوى الثقة في التعرف على المحتوى بعد معالجة صورة رمز التحقق من hCaptcha.
يمكنك أن ترى أننا حصلنا على نتيجة التحقق من معالجة صورة رمز التحقق من hCaptcha، كل ما علينا فعله هو محاكاة النقر على منطقة الصورة بناءً على معلومات إحداثيات box في النتيجة. سنستعرض الآن كيفية النقر بناءً على معلومات موقع box، أولاً، يتم إنشاء نظام إحداثيات قائم الزاوية للصورة المرفوعة، حيث تكون نقطة الأصل في الزاوية السفلية اليسرى للصورة، 360 هو الإحداثي الأفقي المقابل، و276 هو الإحداثي العمودي المقابل، كل ما علينا فعله هو محاكاة النقر على الإحداثيات المقابلة لرمز التحقق، كما هو موضح في الصورة أدناه:

إذا كنت ترغب في إنشاء كود التكامل المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/captcha/recognition/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "Please click on the UNIQUE object among the others.",
  "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}'
كود التكامل بلغة Python كما يلي: 
import requests

url = "https://api.acedata.cloud/captcha/recognition/hcaptcha"

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

payload = {
    "question": "Please click on the UNIQUE object among the others.",
    "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}

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

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

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال:
  • 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"
}

​
الخاتمة

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