> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Recaptcha2 واجهة برمجة التطبيقات للتعرف على الصور

> Recaptcha verification code recognition service API guide - Ace Data Cloud

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

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

لاستخدام واجهة برمجة التطبيقات للتعرف على الصور Recaptcha2، يجب أولاً الذهاب إلى [لوحة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على رمز API الخاص بك، للاحتفاظ به كنسخة احتياطية.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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

**يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة.** عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في [لوحة التحكم](https://platform.acedata.cloud/console/coin).

> 📘 الوثائق الكاملة: [واجهة برمجة التطبيقات للتعرف على الصور Recaptcha2 →](https://platform.acedata.cloud/documents/captcha-recognition-recaptcha2)

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

أولاً، دعنا نفهم طريقة الاستخدام الأساسية، نحتاج إلى التقاط صورة كود Recaptcha2 من الموقع، هنا مثال على عنوان URL للموقع: `https://www.google.com/recaptcha/api2/demo`، الصفحة المحددة كما هو موضح في الصورة أدناه:

<p>
  <img src="https://cdn.acedata.cloud/3mgkjk.png" width="500" className="m-auto" />
</p>

نحتاج إلى النقر على مربع الاختيار الخاص بكود التحقق حتى تظهر صورة كود Recaptcha، في الصورة أعلاه، تشير السهم الأصفر إلى نص معين، وهذا النص هو قيمة `question` المذكورة لاحقًا. أولاً، نحتاج إلى تمرير حقل `image`، وهو صورة كود Recaptcha2 المحددة، وهي الصورة المشار إليها بالسهم الأحمر في الصورة أعلاه، ويجب أيضًا ضبط الصورة على الحجم القياسي (100x100، 300x300، 450x450)، حتى تتمكن الخدمة من تحديد نوع الصورة، يجب عليك ضغط الصورة بنفسك، توصي هذه المقالة بموقع [ضغط الصور](https://www.photopea.com/) حيث يمكنك ضغط الصورة من حيث الحجم والأبعاد، والنتيجة المضغوطة كما هو موضح في الصورة:

![](https://cdn.acedata.cloud/l7aotl.png)

كما تحتاج إلى إدخال معلمات المحتوى ذات الصلة بصورة كود التحقق `question`، نقدم فقط الجدول أدناه كمراجع:

### جدول المحتويات باللغة الصينية

```json theme={null}
{
  "/m/0pg52": "出租车",
  "/m/01bjv": "巴士",
  "/m/02yvhj": "校车",
  "/m/04_sv": "摩托车",
  "/m/013xlm": "拖拉机",
  "/m/01jk_4": "烟囱",
  "/m/014xcs": "人行横道",
  "/m/015qff": "红绿灯",
  "/m/0199g": "自行车",
  "/m/015qbp": "停车计价表",
  "/m/0k4j": "汽车",
  "/m/015kr": "桥",
  "/m/019jd": "船",
  "/m/0cdl1": "棕榈树",
  "/m/09d_r": "山",
  "/m/01pns0": "消防栓",
  "/m/01lynh": "楼梯"
}
```

### جدول المحتويات باللغة الإنجليزية

```json theme={null}
{
  "/m/0pg52": "taxis",
  "/m/01bjv": "bus",
  "/m/02yvhj": "school bus",
  "/m/04_sv": "motorcycles",
  "/m/013xlm": "tractors",
  "/m/01jk_4": "chimneys",
  "/m/014xcs": "crosswalks", // pedestrian crossings 也是一样的
  "/m/015qff": "traffic lights",
  "/m/0199g": "bicycles",
  "/m/015qbp": "parking meters",
  "/m/0k4j": "cars",
  "/m/015kr": "bridges",
  "/m/019jd": "boats",
  "/m/0cdl1": "palm trees",
  "/m/09d_r": "mountains or hills",
  "/m/01pns0": "fire hydrant",
  "/m/01lynh": "stairs"
}
```

من النص أعلاه، يمكننا تعيين المعلمة `question` إلى `/m/01pns0` الخاصة بخزانة الإطفاء، والمحتوى المحدد كما يلي:

<p>
  <img src="https://cdn.acedata.cloud/d53oc3.png" width="500" className="m-auto" />
</p>

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

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

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

* `image`: صورة كود التحقق المشفرة بتنسيق Base64.
* `question`: معرف السؤال، يرجى الرجوع إلى الجدول، يبدأ بـ /m/.

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

<p>
  <img src="https://cdn.acedata.cloud/bsp8g9.png" width="500" className="m-auto" />
</p>

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

```json theme={null}
{
  "solution": {
    "size": 300,
    "label": "/m/01pns0",
    "confidences": [
      0,
      0.0007,
      1,
      0.0003,
      0.0046,
      1,
      0,
      1,
      0
    ],
    "objects": [
      2,
      5,
      7
    ],
    "type": "multi"
  }
}
```

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

* `solution`، نتيجة التحقق من معالجة صورة كود Recaptcha2.
  * `size`، حجم صورة كود Recaptcha2.
  * `label`، المحتوى الذي تم التعرف عليه في صورة كود Recaptcha2.
  * `confidences`، مستوى الثقة في منطقة التعرف على صورة كود Recaptcha2، حيث تبدأ المناطق من 0.
  * `objects`، المناطق التي تلبي محتوى التعرف على صورة كود Recaptcha2، تبدأ المناطق من 0.
  * `type`، نوع مهمة صورة كود Recaptcha2، إذا كانت هناك مناطق متعددة، تكون `multi`.

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

<p>
  <img src="https://cdn.acedata.cloud/2d6qhx.png" width="500" className="m-auto" />
</p>

يمكننا أن نرى أن المناطق تبدأ من 0، ومن النتيجة في `objects` حصلنا على 2، 5، 7، نحتاج فقط إلى محاكاة النقر على هذه المناطق الثلاثة في كود التحقق للمرور بالتحقق.

بالإضافة إلى ذلك، إذا كنت ترغب في إنشاء كود التكامل المقابل، يمكنك ببساطة نسخه، على سبيل المثال، كود CURL كما يلي:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/recognition/recaptcha2' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "/m/01pns0",
  "image": "iVBORw0KGgoAAAANSUhEUgAAASoAAAEsCAIAAAD7AWllAAAAAX..."
}'
```

كود التكامل بلغة Python كما يلي:

```python theme={null}
import requests

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

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

payload = {
    "question": "/m/01pns0",
    "image": "iVBORw0KGgoAAAANSUhEUgAAASoAAAEsCAIAAAD7AWllAAAAAX..."
}

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

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

بشكل افتراضي، تكون واجهة برمجة التطبيقات متزامنة ومعلقة: ستنتظر الطلب حتى يتم معالجة نتيجة التعرف قبل أن تعود. إذا كنت تقوم بتدوير عدة حلّات (multi-solver rotation) وترغب في "تقديم المهمة والحصول على task\_id على الفور، ثم جدولة حلّات أخرى، والعودة لاحقًا للحصول على النتيجة"، يمكنك تمرير `async: true` في جسم الطلب.

بعد تمرير `async: true`، ستعيد الواجهة على الفور `task_id`، دون الانتظار:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/recognition/recaptcha2' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "/m/01pns0",
  "image": "iVBORw0KGgoAAAANSUhEUgAAASoAAAEsCAIAAAD7AWllAAAAAX...",
  "async": true
}'
```

```json theme={null}
{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

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

```shell theme={null}
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`:

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

عند الانتهاء من المعالجة، ستعيد `status: ready` ونتيجة التعرف `solution` (هيكل الحقول متطابق تمامًا مع الوضع المتزامن):

```json theme={null}
{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "solution": {
    "size": 300,
    "label": "/m/01pns0",
    "objects": [2, 5, 7],
    "type": "multi"
  }
}
```

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

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

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

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

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

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

## الخاتمة

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