Automation با curl و jq
چرا curl و jq؟
در دنیای امروز بسیاری از سرویسها و ابزارها از طریق REST API با هم ارتباط برقرار میکنند. شما ممکن است بخواهید:
- وضعیت یک deployment را از CI/CD سیستم بگیرید
- یک notification به Slack بفرستید
- اطلاعات یک سرور را از Cloud Provider بخوانید
- یک webhook را trigger کنید
این کارها همه با HTTP request انجام میشوند و پاسخ معمولاً JSON است. دو ابزار کلیدی برای این کار:
curl— ارسال HTTP requestjq— خواندن و پردازش JSON
curl: ارسال HTTP Request
curl یکی از رایجترین ابزارهای خط فرمان برای کار با APIها است. در هفتهی سوم با آن آشنا شدید، اما اینجا روی استفاده در automation تمرکز میکنیم.
GET Request
سادهترین حالت، خواندن داده:
-s: silent mode — progress bar را نشان نمیدهد
خروجی یک JSON است. برای دیدن فقط status code:
POST Request با JSON
برای ارسال داده به API:
-X POST: متد HTTP-H: اضافه کردن header-d: بدنهٔ request (data)
Error Handling در curl
بهطور پیشفرض، curl حتی اگر سرور 404 یا 500 برگرداند، exit code 0 میدهد. برای automation باید این رفتار را تغییر دهید:
-f: fail on HTTP errors (4xx, 5xx)-S: در صورت خطا، پیام را نشان بده-L: redirect را دنبال کن
jq: پردازش JSON
وقتی یک API پاسخ JSON میدهد، نیاز دارید بخشهای خاصی از آن را استخراج کنید. jq دقیقاً برای این کار ساخته شده.
نصب jq
در هفتهی دوم احتمالاً آن را نصب کردید، اما اگر نه:
استخراج یک فیلد
فرض کنید این JSON را دارید:
برای گرفتن فقط version:
خروجی:
.version: مسیر فیلد در JSON-r: raw output (بدون quote)
کار با Array
فرض کنید لیست deploymentها را میخواهید:
گرفتن همهٔ idها:
خروجی:
فیلتر کردن فقط موفقها:
مثال عملی: چک کردن وضعیت CI
فرض کنید میخواهید وضعیت آخرین GitHub Actions workflow را بررسی کنید:
مثال عملی: ارسال Notification به Slack
Slack webhook را میتوان برای ارسال پیام استفاده کرد:
استفاده:
توجه کنید که payload را با jq -n ساختیم — این روش امنتر از string interpolation است چون jq خودش escape میکند.
ساختن JSON با jq
بهجای نوشتن JSON بهصورت دستی، میتوانید با jq بسازید:
خروجی:
این روش امنتر است چون نیازی به escape کردن دستی quote یا newline ندارید.
تمرین
- یک درخواست به
https://api.github.com/users/YOUR_USERNAMEبفرستید و باjqفقط فیلدهایnameوpublic_reposرا نمایش دهید - همان API را فراخوانی کنید و اگر
public_reposبیشتر از 10 بود، پیام موفقیت چاپ کنید، در غیر این صورت با exit code1خارج شوید - یک اسکریپت بنویسید که یک health check endpoint را فراخوانی کند و اگر status code چیزی غیر از
200بود، باcurlretry کند (حداکثر 3 بار)
منابع یادگیری
مستندات و مقالات
- Shell Script API Calls: Use curl in Scripts for Automation — استفاده از curl در اسکریپتهای automation
- Bash REST API with curl + jq — ترکیب curl و jq برای کار با APIها
- How to use jq with curl to explore an API’s JSON response — راهنمای عملی استفاده از jq با curl
ویدیو