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

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

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

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

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال صورة كود التحقق 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: مفتاح استدعاء API، يمكنك اختياره مباشرة بعد التقديم.
كما تم تعيين جسم الطلب، بما في ذلك:
  • queries: قائمة صور كود التحقق المشفرة بتنسيق Base64.
  • question: معلمة محتوى التعرف ذات الصلة بصورة كود التحقق، تدعم الإدخال المباشر باللغتين الصينية والإنجليزية.
بعد الاختيار، يمكنك أن تلاحظ أنه تم إنشاء كود مطابق على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، وهنا حصلنا على النتيجة التالية:
تتضمن النتيجة عدة حقول، كما هو موضح أدناه:
  • solution، نتيجة التحقق من معالجة مهمة صورة كود التحقق hCaptcha.
    • label، المحتوى الذي تم التعرف عليه من صورة كود التحقق hCaptcha.
    • box، معلومات موقع نتيجة التعرف على صورة كود التحقق hCaptcha، وهي تتكون من معلومات إحداثيات الصورة.
    • confidences، مستوى الثقة في التعرف على المحتوى بعد معالجة صورة كود التحقق hCaptcha.
  • started_at، finished_at: الوقت الذي بدأ فيه الطلب معالجة وإنتاج النتيجة، طابع زمني Unix (ثوانٍ، عائم).
  • elapsed: إجمالي الوقت المستغرق في المعالجة (ثوانٍ).
يمكننا أن نرى أننا حصلنا على نتيجة التحقق من معالجة صورة كود التحقق hCaptcha، كل ما علينا فعله هو محاكاة النقر على منطقة صورة كود التحقق بناءً على معلومات إحداثيات box في النتيجة. فيما يلي سنوضح كيفية النقر بناءً على معلومات موقع box، أولاً، يتم إنشاء نظام إحداثيات قائم الزاوية لصورة كود التحقق المرفوعة، حيث تكون نقطة الأصل في أسفل يسار الصورة، 360 هو الإحداثي الأفقي، و276 هو الإحداثي العمودي، كل ما علينا فعله هو محاكاة النقر على الإحداثيات المقابلة لكود التحقق، كما هو موضح في معلومات الصورة أدناه:

إذا كنت ترغب في إنشاء كود التكامل المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود 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 ونتيجة التعرف solution (هيكل الحقول متطابق تمامًا مع وضع التزامن):
شرح الفوترة: في وضع غير المتزامن، لا يتم احتساب رسوم لإنشاء المهام وقراءة حالة “قيد المعالجة”؛ يتم احتساب الرسوم مرة واحدة عند قراءة العميل للنتيجة الناجحة لأول مرة (متوافقة مع السلوك الحالي وأسعار وضع التزامن). سيقوم الخادم بدفع المهمة بشكل تلقائي، لكنه لن يقوم بخصم الرسوم مسبقًا بسبب الانتهاء في الخلفية. إذا لم تنجح المهمة خلال 120 ثانية، ستنتهي إلى HTTP 504 timeout، ولن يتم احتساب الرسوم. /captcha/tasks ليست مسؤولة عن دفع المهمة.

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

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

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

​
الخاتمة

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