reCAPTCHA Enterprise Assessment API: الشرح والتعامل معه في الأتمتة

من منظور مطوّر الأتمتة، الخبر الجيد بسيط: رمز reCAPTCHA Enterprise يُحَلّ مثل reCAPTCHA v2/v3 القياسي — تُرسل الطلب بالطريقة userrecaptcha وتضيف علامة واحدة هي enterprise=1. أمّا «تحليل المخاطر التفصيلي» و«أسباب النتيجة» و«Account Defender» فتحدث على خادم صاحب الموقع، لا في جانب العميل.

يجيب هذا الدليل عن أربعة أسئلة عملية:

• ما الذي تضيفه Enterprise فوق reCAPTCHA v3؟
• كيف تبدو استجابة Assessment API وما معنى حقولها؟
• كيف تكتشف أنّ الصفحة تستخدم Enterprise؟
• كيف تحلّ رموزها في الأتمتة عبر CaptchaAI؟

الأساسيات: ما هي Enterprise ولماذا تختلف

reCAPTCHA Enterprise مقابل الإصدار القياسي

الفرق الجوهري ليس في شكل الرمز بل في كمّ المعلومات التي يحصل عليها صاحب الموقع بعد التحقق:

انتبه إلى تقسيم الأدوار:

• مالك الموقع يستفيد من كل الميزات أعلاه عند التحقق من الرموز.
• مطوّر الأتمتة الذي يحلّ الرمز على صفحة طرف ثالث لا يرى هذا التحليل.

كيف يعمل Assessment API خطوة بخطوة

تنقسم دورة حياة التقييم إلى شقّين: شقّ في المتصفح يولّد الرمز، وشقّ على الخادم يحوّله إلى قرار وصول مدعوم بتحليل المخاطر.

Client-side:

  1. Load reCAPTCHA Enterprise script
  2. Call grecaptcha.enterprise.execute(SITE_KEY, {action: 'LOGIN'})
  3. Receive token
  4. Send token to your backend

Server-side:

  1. Create assessment via Enterprise API
  2. Receive detailed risk analysis
  3. Make access decision based on score + reasons
  4. Optionally annotate the assessment (report fraud/legitimate)

التكامل التقني: من العميل إلى الخادم

من جهة العميل عبر JavaScript SDK

الفرق الظاهر عن reCAPTCHA v3 هو اسم السكربت وكائن الـ API:

<script src="https://www.google.com/recaptcha/enterprise.js?render=SITE_KEY"></script>
<script>
    grecaptcha.enterprise.ready(function() {
        grecaptcha.enterprise.execute('SITE_KEY', { action: 'LOGIN' })
            .then(function(token) {
                // Send token to backend
                fetch('/api/verify', {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({ token: token })
                });
            });
    });
</script>

الفروق الأساسية محصورة في ثلاث نقاط:

• عنوان السكربت يستخدم .../recaptcha/enterprise.js بدلاً من .../recaptcha/api.js
• كائن الـ API هو grecaptcha.enterprise بدلاً من grecaptcha
• الدالة execute() تُرجِع الرمز المميز بالتنسيق نفسه

اكتشاف Enterprise من كود الصفحة

قبل اختيار طريقة الحل، حدّد إصدار صفحة الهدف. الدالة التالية تفحص مصدر HTML وتستخرج sitekey وأسماء الإجراءات:

import requests
import re

def detect_recaptcha_enterprise(url):
    """Detect if a page uses reCAPTCHA Enterprise."""
    html = requests.get(url, timeout=10).text

    indicators = {
        "is_enterprise": False,
        "is_standard": False,
        "site_key": None,
        "actions": [],
    }

    # Enterprise detection
    if "recaptcha/enterprise.js" in html:
        indicators["is_enterprise"] = True
        match = re.search(r"render=([A-Za-z0-9_-]+)", html)
        if match:
            indicators["site_key"] = match.group(1)

    # Standard v3 detection
    elif "recaptcha/api.js?render=" in html:
        indicators["is_standard"] = True
        match = re.search(r"render=([A-Za-z0-9_-]+)", html)
        if match:
            indicators["site_key"] = match.group(1)

    # Extract action names
    actions = re.findall(r"action:\s*['\"](\w+)['\"]", html)
    indicators["actions"] = list(set(actions))

    return indicators

print(detect_recaptcha_enterprise("https://example.com/login"))

إنشاء التقييم من جهة الخادم

هذا الجزء يخصّ مالك الموقع: بعد استلام الرمز، ينشئ الخادم تقييماً عبر مكتبة Google Cloud.

from google.cloud import recaptchaenterprise_v1
from google.cloud.recaptchaenterprise_v1 import Assessment

def create_assessment(project_id, site_key, token, action):
    """Create a reCAPTCHA Enterprise assessment."""
    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()

    event = recaptchaenterprise_v1.Event()
    event.site_key = site_key
    event.token = token
    event.expected_action = action

    assessment = recaptchaenterprise_v1.Assessment()
    assessment.event = event

    request = recaptchaenterprise_v1.CreateAssessmentRequest()
    request.assessment = assessment
    request.parent = f"projects/{project_id}"

    response = client.create_assessment(request)
    return response

بنية استجابة التقييم

تجمع الاستجابة النتيجة وأسبابها وخصائص الرمز وتقييم Account Defender في كائن JSON:

{
    "name": "projects/123456/assessments/abcdef123",
    "event": {
        "token": "...",
        "siteKey": "6Le...",
        "expectedAction": "LOGIN",
        "hashedAccountId": "abc123..."
    },
    "riskAnalysis": {
        "score": 0.9,
        "reasons": [
            "AUTOMATION",
            "TOO_MUCH_TRAFFIC"
        ],
        "extendedVerdictReasons": [
            "BROWSER_ERROR"
        ]
    },
    "tokenProperties": {
        "valid": true,
        "hostname": "example.com",
        "action": "LOGIN",
        "createTime": "2025-01-15T10:30:00Z",
        "invalidReason": ""
    },
    "accountDefenderAssessment": {
        "labels": ["PROFILE_MATCH"]
    }
}

قراءة التقييم: النتيجة ودفاع الحساب

أسباب النتيجة (Score Reasons)

لا تكتفي Enterprise برقم بل تشرح سبب انخفاضه. تأتي الإشارات في مجموعتين:

• أسباب رئيسية تؤثر مباشرة في النتيجة.
• أسباب موسّعة تضيف تفاصيل تقنية دون أثر رقمي.

ويوضّح الجدول التالي أشهر الأسباب الرئيسية وتأثيرها التقريبي:

أسباب الحكم الموسّعة

Account Defender وتتبّع دورة حياة الحساب

يتتبّع Account Defender سلوك الحساب عبر الزمن ويضع عليه تسميات (labels) تصف اعتياديته:

{
    "accountDefenderAssessment": {
        "labels": [
            "PROFILE_MATCH",
            "SUSPICIOUS_LOGIN_ACTIVITY",
            "SUSPICIOUS_ACCOUNT_CREATION",
            "RELATED_ACCOUNTS_NUMBER_HIGH"
        ]
    }
}

طبقة الشبكة: تكامل reCAPTCHA Enterprise مع WAF

تفرض Enterprise تحديات CAPTCHA على حافة الشبكة قبل وصول الطلب إلى الخادم الأصلي، عبر التكامل مع أبرز مزوّدي WAF:

• Cloudflare
• Fastly
• F5 BIG-IP

التكامل مع Cloudflare WAF

Request arrives at Cloudflare edge
    ↓
Cloudflare WAF rule evaluates request
    ↓
Rule triggers reCAPTCHA Enterprise challenge
    ↓
Client solves CAPTCHA → token returned
    ↓
Cloudflare validates token via Enterprise API
    ↓
If valid + score above threshold → request forwarded to origin

تكامل F5 BIG-IP

F5 iRule or policy evaluates request
    ↓
Triggers reCAPTCHA Enterprise challenge page
    ↓
Client solves → token validated server-side
    ↓
F5 forwards or blocks based on assessment score

حلّ reCAPTCHA Enterprise في سير عمل الأتمتة

الخطوات الأربع

المسار مطابق لـ reCAPTCHA القياسي مع علامة واحدة إضافية:

1. أرسِل sitekey وpageurl بالطريقة userrecaptcha مع enterprise=1.
2. احفظ معرّف المهمة العائد.
3. استطلِع النتيجة دورياً عبر res.php حتى الاكتمال.
4. احقن الرمز في النموذج المستهدف.

مثال: فريق ضمان جودة في الخليج

تخيّل فريق ضمان جودة في متجر إلكتروني خليجي يختبر تسجيل الدخول المحمي بـ reCAPTCHA Enterprise قبل موسم التخفيضات. لا يحتاج مساراً مختلفاً: يرسل sitekey مع enterprise=1 عبر userrecaptcha نفسها.

import requests
import time

API_KEY = "YOUR_API_KEY"

# Enterprise is solved with the same method
# The solver handles the Enterprise variant automatically
submit = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": "6LcR_RsTAAAAAN_r0GEkGBfq3L7KmU5JbPHJtwNp",
    "pageurl": "https://enterprise-site.com/login",
    "enterprise": 1,  # Flag for Enterprise variant
    "json": 1,
})

task_id = submit.json()["request"]

for _ in range(60):
    time.sleep(5)
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": API_KEY,
        "action": "get",
        "id": task_id,
        "json": 1,
    }).json()

    if result.get("status") == 1:
        token = result["request"]
        print(f"Enterprise token: {token[:50]}...")
        break

التنفيذ في Node.js

النمط نفسه في Node.js:

const axios = require("axios");

async function solveEnterprise(sitekey, pageurl) {
    const API_KEY = "YOUR_API_KEY";

    const { data: submit } = await axios.post(
        "https://ocr.captchaai.com/in.php",
        new URLSearchParams({
            key: API_KEY,
            method: "userrecaptcha",
            googlekey: sitekey,
            pageurl: pageurl,
            enterprise: 1,
            json: 1,
        })
    );

    const taskId = submit.request;

    for (let i = 0; i < 60; i++) {
        await new Promise(r => setTimeout(r, 5000));
        const { data: result } = await axios.get(
            "https://ocr.captchaai.com/res.php",
            { params: { key: API_KEY, action: "get", id: taskId, json: 1 } }
        );

        if (result.status === 1) return result.request;
    }

    throw new Error("Timeout");
}

التمييز بين Enterprise والقياسي على صفحة الهدف

عند التعامل مع مواقع متعددة، حدّد الإصدار تلقائياً:

def identify_recaptcha_version(html):
    """Determine which reCAPTCHA version a page uses."""
    if "recaptcha/enterprise.js" in html:
        return "enterprise"
    elif "recaptcha/api.js?render=" in html:
        return "v3"
    elif "g-recaptcha" in html and 'data-size="invisible"' in html:
        return "v2_invisible"
    elif "g-recaptcha" in html:
        return "v2"
    else:
        return "none"

حلّ المشكلات الشائعة مع Enterprise

أغلب المشكلات ترجع إلى علامة enterprise مفقودة أو معلمة action غير مطابقة:

أسئلة شائعة

هل يزيد حلّ Enterprise من تكلفتك على CaptchaAI؟

لا يوجد رسم إضافي مرتبط بنوع الـ CAPTCHA. تعتمد باقات CaptchaAI على عدد الـ Threads المتزامنة مع حلول غير محدودة لكل Thread، بدءاً من BASIC بسعر 15 دولاراً شهرياً (5 threads). فرمز Enterprise يستهلك Thread مثل القياسي تماماً.

متى أحتاج تمرير enterprise=1 وماذا يحدث لو نسيته؟

تحتاجها فقط عندما تستخدم صفحة الهدف سكربت enterprise.js. إذا نسيتها على موقع Enterprise فقد يُرفض الرمز أو تنخفض النتيجة، وهو أول ما تفحصه عند فشل التحقق. أمّا مع reCAPTCHA v3 القياسي فلا تضِفها.

ماذا يعني ظهور "AUTOMATION" في أسباب النتيجة؟

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

كيف أميّز Enterprise عن الإصدار القياسي على صفحة الهدف؟

افحص عنوان السكربت وكائن الـ API: تستخدم Enterprise ملف recaptcha/enterprise.js والكائن grecaptcha.enterprise.execute()، بينما القياسي يستخدم recaptcha/api.js وgrecaptcha.execute().

هل أحتاج حساب Google Cloud لحلّ اختبارات Enterprise؟

لا. بصفتك مطوّر أتمتة، تكفيك قيمة sitekey وخدمة حلّ مثل CaptchaAI. حساب Google Cloud مطلوب فقط لمالك الموقع كي يتحقق من التقييمات.

الخلاصة

تمدّ reCAPTCHA Enterprise الإصدار القياسي بتحليل مخاطر وأسباب نتيجة وAccount Defender وتكامل WAF، لكن كل ذلك يجري على خادم مالك الموقع. من زاوية الأتمتة يبقى الأمر مباشراً: احلل الرمز عبر CaptchaAI بإضافة enterprise=1، واكتشف Enterprise عبر recaptcha/enterprise.js في مصدر الصفحة مع تطابق action.

مقالات ذات صلة

• حلّ استدعاء reCAPTCHA v2 من نوع Callback عبر الـ API
• التعامل مع reCAPTCHA v2 وTurnstile في الموقع نفسه
• حلّ reCAPTCHA v3 Enterprise عبر الـ API

أدلة ذات صلة

• البدء السريع مع CaptchaAI: حلّ أول كابتشا في 5 دقائق
• كيفية حلّ reCAPTCHA v2 عبر الـ API: دليل خطوة بخطوة