DEV Community

Cover image for Apidog CLI: عميل API الطرفي
Yusuf Khalidd
Yusuf Khalidd

Posted on Originally published at apidog.com

Apidog CLI: عميل API الطرفي

مساحة عمل واجهة برمجة التطبيقات (API) الخاصة بك تعيش في واجهة مستخدم رسومية (GUI)، بينما يوم عملك يعيش في الطرفية (terminal). كل تبديل سياق بينهما يستهلك وقتًا وتركيزًا، وفي مسارات التكامل المستمر (CI) أو جلسات عوامل الذكاء الاصطناعي (AI agents)، قد لا تكون الواجهة الرسومية خيارًا أصلًا. يسد Apidog CLI هذه الفجوة عبر جلب منصة Apidog — الاختبارات، ونقاط النهاية، والمخططات، والبيئات، وتوقعات المحاكاة، والوثائق — إلى موجه الأوامر المفتوح لديك بالفعل.

جرّب Apidog اليوم

توضيح مهم: Apidog CLI ليس أداة curl أخرى. إذا كنت تريد إرسال طلب GET لمرة واحدة وفحص JSON، فإن curl وHTTPie يؤديان هذه المهمة جيدًا، كما يغطي دليل عملاء REST للطرفية وTUI الاستخدام التفاعلي. Apidog CLI هو عميل لمساحة عمل API نفسها: يشغّل سيناريوهات الاختبار التي أنشأتها، ويقرأ عقد API ويحدّثه، وينقل المواصفات إلى المشروع ومنه، وكل ذلك عبر أوامر يمكن لبرنامج نصي أو عامل تشغيلها.

ماذا يعني أن «يعيش في الطرفية»؟

تتعامل أدوات HTTP الطرفية عادةً مع طلب واحد في كل مرة. أما Apidog CLI فيعمل على مستوى المشروع، ويضم أكثر من أربعين مجموعة أوامر تتوزع على خمس مهام رئيسية:

الوظيفة الأوامر
تشغيل الاختبارات run، test-scenario، test-suite، test-case، test-data، test-report
إدارة العقد endpoint، schema، folder، common-parameter، response-component، security-scheme
نشر الوثائق والمحاكاة doc، docs-site، shared-doc، mock
الإعداد والاتصال environment، variables، vault، database-connection، websocket، socketio
العمل الجماعي branch، merge-request، runner، scheduled-task، audit-log، import، export

ابدأ دائمًا بمساعدة الأمر الذي تستخدمه:

apidog --help
apidog run --help
Enter fullscreen mode Exit fullscreen mode

يدعم كل أمر الخيار --help، ويكون الإخراج JSON منظمًا. تتضمن معظم الاستجابات أيضًا agentHints.nextSteps التي تقترح ما يجب تشغيله لاحقًا لك أو لعامل الذكاء الاصطناعي. عمليًا، هذا يحول CLI من مجموعة أوامر منفصلة إلى سير عمل موجّه.

ثبّته وسجّل الدخول

يُوزّع CLI كحزمة npm باسم apidog-cli، ويعمل على macOS وLinux وWindows. يتطلب Node.js بالإصدار 16 أو أحدث.

npm install -g apidog-cli
apidog --version
Enter fullscreen mode Exit fullscreen mode

سجّل الدخول باستخدام رمز وصول API. من تطبيق Apidog، انقر على صورتك الرمزية، ثم افتح إعدادات الحساب وانسخ الرمز من قسم API Access Token.

apidog login --with-token <YOUR_TOKEN>
Enter fullscreen mode Exit fullscreen mode

يتم تخزين الرمز في:

~/.apidog/config.toml
Enter fullscreen mode Exit fullscreen mode

لا تضف هذا الملف إلى المستودع أو سجلات البناء. في CI، مرّر الرمز من أسرار المنصة في كل تنفيذ باستخدام --access-token.

هذه الخيارات العامة تغطي أغلب الاستخدامات:

apidog run \
  --project <project_id> \
  --branch <branch_name> \
  --access-token "$APIDOG_TOKEN" \
  --api-base-url <self_hosted_url>
Enter fullscreen mode Exit fullscreen mode
  • --project: يحدد المشروع.
  • --branch: يحدد الفرع.
  • --access-token: يتجاوز بيانات تسجيل الدخول المحلية.
  • --api-base-url: يوجّه CLI إلى نشر Apidog مستضاف ذاتيًا.

راجع دليل مصادقة Apidog CLI لتفاصيل استخدام الرموز في CI.

شغّل الاختبارات التي أنشأتها بصريًا

سير العمل الأساسي بسيط:

  1. أنشئ سيناريو اختبار في محرر Apidog المرئي.
  2. أضف الطلبات المتسلسلة والمتغيرات والتأكيدات.
  3. انسخ أمر التشغيل من تبويب CI/CD في السيناريو.
  4. شغّله محليًا أو داخل CI. 
# انسخ هذا الأمر، بما في ذلك المعرّفات، من تبويب CI/CD للسيناريو
apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

يُرجع الأمر رمز خروج 0 عندما تمر كل التأكيدات، ورمزًا غير صفري عند فشل أي اختبار. لذلك يمكنك ربطه مباشرة بخط أنابيب CI:

apidog run -t <scenario_id> -e <env_id> -r cli,junit

if [ $? -ne 0 ]; then
  exit 1
fi
Enter fullscreen mode Exit fullscreen mode

بدّل قيمة -e لتشغيل السيناريو نفسه على بيئات التطوير أو الاختبار أو الإنتاج.

تشغيل اختبار موجه بالبيانات

بدل تكرار خطوات السيناريو، زوّده بملف CSV أو JSON لتشغيله على كل صف بيانات. هذا هو نمط الاختبار الموجه بالبيانات.

إذا كنت تبدأ من الصفر، فاتبع التجول خطوة بخطوة لاختبار REST API من التثبيت حتى أول تشغيل ناجح.

اختر صيغة التقرير المناسبة

يدعم Apidog CLI أربع صيغ للتقارير:

  • cli: نتائج خطوة بخطوة في الطرفية.
  • html: تقرير قابل للعرض في المتصفح.
  • json: مخرجات منظمة للاستهلاك البرمجي.
  • junit: مناسب للوحات CI وأدوات التقارير.

تُحفَظ تقارير html وjson وjunit في apidog-reports/.

apidog run -t <scenario_id> -e <env_id> -r cli,junit
Enter fullscreen mode Exit fullscreen mode

راجع دليل تقارير الاختبار لمعرفة شكل كل صيغة.

للتشغيلات التي لا تريد ربطها بجهاز المطور، استخدم runner وscheduled-task لإدارة المشغلات المستضافة ذاتيًا والاختبارات المجدولة. هذه هي الآلية المستخدمة في اختبارات API المجدولة في Apidog.

أدر عقد API دون فتح التطبيق

لا يقتصر CLI على تشغيل الاختبارات؛ يمكنه أيضًا قراءة تعريف API وإدارته:

apidog endpoint list --project <project_id>
apidog schema get <schema_id>
apidog environment list
apidog mock list
Enter fullscreen mode Exit fullscreen mode

يمكنك الاستعلام عن العناصر التالية وتعديلها:

  • نقاط النهاية
  • مخططات البيانات
  • المجلدات
  • البيئات والمتغيرات
  • مخططات الأمان
  • المكونات القابلة لإعادة الاستخدام
  • توقعات المحاكاة

يدير أمر mock توقعات المحاكاة، وهي أزواج طلب/استجابة ثابتة يعيدها الخادم الوهمي. وتتفاعل أوامر doc وdocs-site مع الوثائق المنشورة.

توجد أيضًا مجموعات أوامر مخصصة لنقاط نهاية WebSocket وSocket.IO، بينما يغطي database-connection إعدادات اتصال قاعدة البيانات التي قد تقرؤها سيناريوهات الاختبار.

استورد وصدّر المواصفات

يدعم الاستيراد والتصدير:

  • OpenAPI 3.x
  • Swagger 2.0
  • مجموعات Postman

وهذا يجعل CLI مناسبًا لنصوص الترحيل والدمج بين الأدوات. على سبيل المثال:

apidog import openapi.json --project <project_id>
apidog export --format openapi
Enter fullscreen mode Exit fullscreen mode

تستند OpenAPI وSwagger إلى المواصفات التي تتكامل معها معظم سلاسل أدوات API.

استخدمه مع عوامل الذكاء الاصطناعي بشكل منضبط

تعتمد إصدارات CLI لعام 2026 على مبدأ واضح: يجب أن يتمكن عامل ذكاء اصطناعي برمجي من تشغيل مساحة عمل API بأمان كما يفعل الإنسان. يدعم ذلك أربع آليات.

1. الإخراج المنظم

يعيد كل أمر JSON قابلًا للتحليل، وتوضح agentHints.nextSteps الخطوات التالية، بما فيها مسارات التعافي من الأخطاء.

2. مخططات إدخال منشورة

اعرض مخطط JSON المتوقع لأي أمر كتابة قبل تنفيذه:

apidog cli-schema list
apidog cli-schema get <command_name>
Enter fullscreen mode Exit fullscreen mode

تحقق من الحمولة قبل تعديل المشروع:

apidog cli-schema validate <payload.json>
Enter fullscreen mode Exit fullscreen mode

اتبع هذا التسلسل عند إنشاء أو تحديث مورد:

  1. احصل على المخطط.
  2. أنشئ JSON مطابقًا له.
  3. تحقق من الحمولة.
  4. شغّل create أو update.

3. مهارة CLI مدمجة

يوفر الأمر skill معرفة تشغيلية بالـ CLI بصيغة يمكن للعوامل تحميلها مباشرة. يوضح مقال لماذا بُنيت مهارة Apidog CLI الهدف من هذه الآلية.

وفق القياسات المذكورة في هذا التحليل، استخدمت العوامل التي تعمل عبر مخطط CLI نحو 30% استدعاءات أدوات أقل و25% رموزًا أقل من العوامل التي تخمّن الحمولات.

4. بوابات الأذونات وفروع الذكاء الاصطناعي

افتراضيًا، تُحظر عمليات الكتابة إلى فرع مصدرها الذكاء الاصطناعي حتى يفعّل إنسان خيار External AI Edit Permissions. يتوفر هذا في عميل Apidog 2.8.32 أو أحدث، ضمن:

إعدادات المشروع → إعدادات الميزات → إعدادات ميزات الذكاء الاصطناعي
Enter fullscreen mode Exit fullscreen mode

البديل هو استخدام فرع AI معزول:

  1. يستورد العامل الموارد التي يحتاجها.
  2. يجري التعديلات في الفرع.
  3. يعيد النتيجة كطلب دمج للمراجعة.
  4. يدمج الإنسان التغييرات بعد التحقق.

تُؤرشف فروع AI غير المستخدمة تلقائيًا بعد 24 ساعة، ما يمنع تراكم التجارب غير المراجعة ويحافظ على قابلية تدقيق عقد API.

ما لا يمثله Apidog CLI

ثلاثة حدود يجب معرفتها قبل اختياره.

واجهة توضيحية لـ Apidog CLI

ليس عميل طلبات تفاعليًا

لا يوجد أمر مخصص لكتابة طلب POST حر وتنسيق الاستجابة بشكل جميل. استخدم curl أو HTTPie أو عملاء TUI لهذه المهمة؛ فهي أفضل لهذا الاستخدام.

ليس مفتوح المصدر

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

ليس مستقلاً عن المنصة

تعيش السيناريوهات ونقاط النهاية والبيئات في مشروع Apidog، وليست في ملفات محلية. المقابل هو وجود مصدر واحد للحقيقة عبر التصميم والاختبار والمحاكاة والوثائق.

أين يناسب ضمن أدوات الطرفية؟

الفرق الأساسي بين أدوات التشغيل هو مكان تأليف الاختبارات:

الأداة مكان تأليف الاختبارات
Newman وPostman CLI مجموعات مؤلفة في Postman
Hurl وBruno ملفات نصية
Apidog CLI سيناريوهات مؤلفة في محرر مرئي يتضمن أيضًا العقد والمحاكاة والوثائق

اقرأ مقارنة Apidog CLI مقابل Newman للتفاصيل، أو راجع قائمة أفضل أدوات اختبار API المستندة إلى الطرفية.

إعداد عملي لمعظم الفرق:

  • استخدم curl أو xh للتحقق السريع.
  • استخدم apidog run لتشغيل السيناريوهات المحفوظة في CI.
  • استخدم تقارير junit لدمج النتائج مع لوحات البناء.
  • استخدم --access-token من أسرار CI بدلًا من تسجيل الدخول التفاعلي.

يتضمن دليل GitHub Actions مسار عمل جاهزًا للنسخ واللصق.

الأسئلة الشائعة

هل Apidog CLI مجاني للاستخدام؟

نعم. تُثبّت الحزمة مجانًا من npm، وتغطي الطبقة المجانية من Apidog إنشاء السيناريوهات وتشغيلها عبر CLI. تضيف الخطط المدفوعة ميزات على مستوى الفريق، لا الوصول الأساسي إلى CLI.

هل يحل محل curl أو HTTPie؟

لا. ترسل تلك الأدوات طلبات مخصصة، بينما يشغّل Apidog CLI سيناريوهات اختبار محفوظة ويدير موارد المشروع. ستحتاج غالبًا إلى النوعين.

هل يمكن تشغيله بالكامل دون واجهة رسومية في CI؟

نعم. مرّر --access-token من سر CI، ثم شغّل apidog run باستخدام معرف السيناريو، واجعل رمز الخروج يحدد نجاح البناء أو فشله. لا تحتاج إلى تطبيق سطح مكتب على المشغّل.

ما التنسيقات التي يمكن استيرادها وتصديرها؟

OpenAPI 3.x وSwagger 2.0 ومجموعات Postman، في الاتجاهين. وهذا يغطي سيناريوهات الترحيل والدمج.

كيف تستخدمه عوامل الذكاء الاصطناعي بأمان؟

استخدم تسلسل المخطط ثم التحقق ثم الكتابة، مع بوابات الأذونات. يكتشف cli-schema validate الحمولات غير الصحيحة قبل وصولها إلى المشروع، بينما تبقي فروع AI التعديلات معزولة حتى يراجعها إنسان ويدمجها. راجع كيفية استخدام Apidog CLI في Claude Code لمثال عملي.

الطرفية هي المكان الذي تعمل فيه اختباراتك وعوامل الذكاء الاصطناعي بالفعل. إضافة عميل API إليها تقلل تبديل السياق: نزّل Apidog، وثبّت CLI من npm، ثم شغّل سيناريو واحدًا من البداية إلى النهاية. عندما تصبح مستعدًا لتجاوز run، راجع مرجع Apidog CLI الكامل.

Top comments (0)