برمجة FlipLink: مرّر مخرجات الـ CLI إلى jq

تطبع أداة FlipLink CLI افتراضياً جداول ودودة سهلة القراءة للبشر. وهذا رائع حين تعمل من الطرفية (terminal) — لكن في اللحظة التي تريد فيها برمجة شيء ما، ستحتاج إلى بيانات خام يفهمها الحاسوب بدلاً من ذلك. وهذا تحديداً ما يمنحك إياه الخيار --json، وبمجرد أن تقرنه بأداة jq يصبح بوسعك استخراج المعرّفات وسحب روابط المشاركة والتصفية حسب الحالة وربط الأوامر معاً في أتمتة حقيقية.

يدور هذا الدليل حول برمجة أداة FlipLink CLI: تحويل بضعة أوامر إلى خط معالجة صغير وموثوق. وإن كنت جديداً تماماً على الأداة، فابدأ بـالبدء مع واجهة سطر الأوامر FlipLink CLI ثم عُد إلى هنا. أمّا للاطّلاع على مجموعة الأوامر الكاملة، فإن توثيق الـ CLI هو المرجع.

الخيار الوحيد الذي يجعل البرمجة ممكنة: --json

يقبل كل أمر قراءة أو كتابة تقريباً الخيار --json. أضِفه، فتُخرج الأداة بيانات JSON خام إلى المخرج القياسي (standard output) بدلاً من جدول منسّق:

fliplink flipbook list --json

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

# See the full shape of a single item — keys, casing, everything
fliplink flipbook list --json | jq '.[0]'

تستخدم الأمثلة أدناه أسماء حقول معقولة مثل .ID و.URL، لكن لا ينبغي أن تفترضها أبداً — فحالة الأحرف في أسماء الحقول قد تختلف. شغّل الأمر أعلاه مرة واحدة واقرأ المفاتيح، ثم عدّل مسارات jq لتطابق ما تراه فعلياً.

استخرج المعرّفات فقط

الخطوة الأولى الكلاسيكية: احصل على قائمة مسطّحة بمعرّفات الكتب المتحركة يمكنك المرور عليها في حلقة.

fliplink flipbook list --json | jq '.[].ID'

تمشي jq عبر المصفوفة (.[]) وتسحب حقل ID من كل عنصر. غلّف الحقل بالخيار -r (مخرجات خام) حين تريد سلاسل نظيفة دون علامات اقتباس محيطة — وهذا ما تحتاجه عند تمرير القيم إلى أمر آخر:

fliplink flipbook list --json | jq -r '.[].ID'

اسحب روابط المشاركة في قائمة نظيفة

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

fliplink flipbook list --json | jq -r '.[].URL'

تريد تقريراً من عمودين بالعنوان والرابط؟ ابنِ صفاً مفصولاً بعلامات جدولة (tab) لكل عنصر باستخدام استيفاء السلاسل في jq:

fliplink flipbook list --json \
  | jq -r '.[] | "\(.Title)\t\(.URL)"'

ومرة أخرى — تأكّد من .Title و.URL مقابل مخرجات --json الخاصة بك قبل الوثوق بها. وإن اختلفت المفاتيح، فاستبدلها.

صفِّ قبل أن تتصرّف

تتيح لك دالة select() في jq الإبقاء على العناصر التي تطابق شرطاً معيناً فقط. لنفترض أن كل عنصر يحمل علامة نشر وأنك تريد معرّفات الكتب المتحركة المنشورة فقط:

fliplink flipbook list --json \
  | jq -r '.[] | select(.IsPublished == true) | .ID'

افحص مخرجاتك لتعرف الاسم الحقيقي للعلامة ونوعها — فقد تكون قيمة منطقية (boolean) أو سلسلة نصية أو حقل حالة. عدّل تعبير select() تبعاً لذلك. ويبقى النمط كما هو: صفِّ المصفوفة، ثم استخرج الحقل الذي تحتاجه.

اربط الأوامر: اسرد، ثم صفِّ، ثم تصرّف

هنا يصبح الأمر مفيداً. مرّر المعرّفات المصفّاة إلى حلقة في الصدفة (shell) وشغّل أمراً ثانياً على كل واحد منها. يجد هذا المثال كل كتاب متحرك لم يُنشر بعد ويقوم بنشره:

fliplink flipbook list --json \
  | jq -r '.[] | select(.IsPublished == false) | .ID' \
  | while read -r id; do
      echo "Publishing $id..."
      fliplink flipbook publish "$id"
    done

تستهلك حلقة while read -r id معرّفاً واحداً لكل سطر وتستدعي fliplink flipbook publish على كل منها. ولأن jq -r يزيل علامات الاقتباس، فإن $id قيمة نظيفة جاهزة للتمرير مباشرةً. والشكل نفسه يصلح لأي أمر إجرائي — استبدله بـ set-expiry أو share-link أو delete.

ملاحظة: كل أمر معروض هنا هو أمر حقيقي من أوامر FlipLink CLI. وإن احتجت إلى إجراء لا تغطّيه الأوامر المنسّقة، فاستخدم منفذ الهروب fliplink api (على سبيل المثال fliplink api PUT /api/set-skin/<id> --data '{"SkinName":"Modern"}') — فالـواجهة REST API نفسها تعمل في الخلفية.

🚀

جرّب FlipLink مجاناً

حوّل ملف PDF خلال ثوانٍ. لا تسجيل ولا بطاقة ائتمان — ارفع ملفك وانطلق.

Drop your PDF here or click to browse

الحجم الأقصى 40MB

الباقات المدفوعة من $39 ترفع هذا الحد إلى 150 MB.

ابنِ تقريراً صغيراً

بمجرد أن تتمكن من الاستخراج والتصفية، يصبح تقرير الحالة السريع مجرد تعبير jq إضافي واحد. عُدّ إجمالي كتبك المتحركة وكم منها منشور:

fliplink flipbook list --json | jq '{
  total: length,
  published: ([.[] | select(.IsPublished == true)] | length)
}'

يطبع ذلك ملخص JSON مدمجاً يمكنك تسجيله أو إرساله بالبريد أو نشره في قناة. تفضّل سطراً يقرأه البشر بدلاً من ذلك؟

fliplink flipbook list --json \
  | jq -r '"Total: \(length) flipbooks"'

اكتب نصوصاً برمجية تعرف إن كانت قد نجحت

لا يكون خط المعالجة جديراً بالثقة إلا إذا تفاعل مع الإخفاق. تستخدم أداة FlipLink CLI رموز خروج (exit codes) ذات معنى، فيمكن لنصوصك البرمجية أن تتفرّع بناءً عليها:

• 0 — نجاح
• 1 — خطأ في الطلب أو في HTTP (شبكة، مفتاح خاطئ، خطأ 401)
• 2 — خطأ في التطبيق (أعادت الواجهة Result: ERROR)

تحقق من رمز الخروج بعد الأمر وعالِج كل حالة:

fliplink flipbook publish "$id"
status=$?

if [ "$status" -eq 0 ]; then
  echo "Published $id"
elif [ "$status" -eq 2 ]; then
  echo "Application error publishing $id (check the response)" >&2
else
  echo "Request failed for $id (exit $status)" >&2
fi

لنص برمجي يتوقف عند أول خطأ، أضف set -e في الأعلى كي يتوقف التشغيل كاملاً عند أول خروج غير صفري. أمّا لمهمة دفعية مرنة، فاستمر في العمل لكن سجّل حالات الإخفاق — فتفرّع رمز الخروج أعلاه هو ما يميّز بين “تمّ” و“تمّ مع أخطاء.”

وإن كنت تبرمج في بيئة CI بدلاً من حاسوبك المحمول، فاضبط مفتاحك عبر متغير البيئة FLIPLINK_API_KEY بدلاً من ملف الإعداد المحلي، واقرأ الشرح الأعمق في أتمتة نشر الكتب المتحركة في CI/CD.

جدوِله بـ cron

الخطوة الأخيرة في أي أتمتة: ضعه على جدول زمني. احفظ خط معالجتك كنص برمجي، واجعله قابلاً للتنفيذ، وأضِف مدخلة cron. يشغّل ما يلي عملية نشر وتقرير ليلية عند الساعة 02:00:

# crontab -e
0 2 * * * FLIPLINK_API_KEY=your_key /home/you/scripts/nightly-publish.sh >> /var/log/fliplink.log 2>&1

إن إعادة توجيه كلٍّ من stdout وstderr إلى ملف سجل (>> ... 2>&1) تعني أن تفرّعات رمز الخروج وتقارير jq تُلتقط في كل تشغيل — حتى إذا تعطّل شيء ما عند الساعة الثانية فجراً، فلديك سجل بما حدث بالضبط.

النمط، في سطر واحد

كل نص برمجي في هذا الدليل هو الفكرة نفسها: --json للحصول على بيانات خام → jq للاستخراج أو التصفية → حلقة للتصرّف → رموز الخروج للتحقق. ابدأ بفحص مخرجات --json الخاصة بك كي تكون أسماء الحقول صحيحة، وابنِ خط المعالجة مرحلة تلو الأخرى، وستحصل على أتمتة FlipLink موثوقة في دقائق.

قراءات ذات صلة

• توثيق FlipLink CLI
• البدء مع واجهة سطر الأوامر FlipLink CLI
• تحويل مجلد كامل من ملفات PDF إلى كتب متحركة دفعةً واحدة
• أتمتة نشر الكتب المتحركة في CI/CD
• مرجع FlipLink API
• ما هي واجهة API؟ (مسرد المصطلحات)