CLI مع --json: معالجة مخرجات Same-QR داخل السكربتات

لماذا JSON للبرامج

تجيب برامج سطر الأوامر عادةً للبشر: جملة أو جدول. أما السكربت فسيضطر إلى تقطيع هذا النص والأمل في ألا يتغير شكله أبدًا. JSON صيغة نصية للبيانات المنظمة تستطيع قراءتها تقريبًا كل لغة. وأداة CLI ذات مخرجات JSON تعطي المعلومات نفسها بشكل ثابت.

الخيار --json

يعرف كل أمر في sameqr-CLI الخيار --json. وبدل الجدول يأتي رد API بصيغة JSON:

sameqr qr list --json
sameqr qr create --name "Plakat Nord" --url https://example.com/aktion --json
sameqr seite list --json

المعالجة بواسطة jq

في سكربتات الصدفة تستخرج الأداة الصغيرة jq قيمًا مفردة. هكذا تعرض اسم كل رمز QR وعدد عمليات مسحه، أو تحتفظ بمعرّف رمز QR جديد:

sameqr qr list --json | jq -r '.codes[] | "\(.name);\(.scanCount)"'

id=$(sameqr qr create --name "Plakat Süd" --url https://example.com/aktion --json | jq -r .id)
sameqr qr stats "$id"

اكتشاف الأخطاء في السكربت

مع --json تأتي الأخطاء أيضًا بصيغة JSON، وعلى مخرج الأخطاء حتى لا تختلط بالبيانات الفعلية. إضافة إلى ذلك تكشف قيمة الإرجاع نوع الخطأ:

• 0: كل شيء سليم.
• 2: إدخال خاطئ أو ناقص، مثل نسيان --name.
• 3: لم تسجّل الدخول أو المفتاح غير صالح.
• 4: لا توجد صلاحية، مثل مفتاح «للقراءة فقط» أو بلوغ حد الباقة.
• 1: خطأ آخر من API.

أوقف الحلقات عند أول خطأ بدل أن تنتج الخطأ نفسه مئة مرة، مثلًا بإضافة «|| break» بعد الأمر.

أمثلة على المهام

• قائمة مواقع تتحول إلى رموز QR، وتُحفظ ردود JSON في ملف للمطبعة.
• مهمة شهرية تحفظ «sameqr qr list --json» كلقطة لتقرير المسح.
• وكيل برمجة يستدعي CLI بنفسه ويقرأ ردود JSON ليخطط للخطوات التالية.

الخلاصة: لماذا Same-QR

صُممت sameqr-CLI للسكربتات: JSON عند الطلب، وأخطاء مفصولة بوضوح مع قيم إرجاع محددة، ومفتاح يأتي من البيئة لا من سطر الأوامر. بهذا تتحول الأوامر المفردة إلى مهام موثوقة، مع Same-QR في كل باقة.

ابدأ الآن: سجّل مجانًا على sameqr.com، فـ 20 رمز QR ديناميكيًا مجانية بشكل دائم. API وCLI وخادم MCP متاحة في كل باقة، والتوثيق على sameqr.com/entwickler.

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