Loading documentation…
شروع سریع API ابران با curl
با API token، هدر پروژه و curl به API ابران متصل شوید، Appها را بخوانید و خطاها را درست مدیریت کنید.
آخرین بازبینی:
این صفحه مفید بود؟
بازخورد شما به بهترشدن مستندات کمک می‌کند.
با API token، هدر پروژه و curl به API ابران متصل شوید، Appها را بخوانید و خطاها را درست مدیریت کنید.
آخرین بازبینی:
Loading documentation…
این صفحه مفید بود؟
بازخورد شما به بهترشدن مستندات کمک می‌کند.
این راهنما یک درخواست واقعی و امن به API ابران می‌فرستد. در پایان می‌توانید هویت فعلی را بررسی کنید، شناسه پروژه را پیدا کنید و resourceهای همان پروژه را بخوانید.
curl و یک ابزار خواندن JSON مانند jqtoken را از Console بسازید و فقط در secret store نگه دارید. آن را در repository، تصویر Docker، فایل قابل اشتراک یا خروجی CI قرار ندهید. جزئیات ساخت و rotation در راهنمای API token و امنیت حساب آمده است.
آدرس production API برابر https://api.abr.run است. متغیرها را برای session فعلی shell تنظیم کنید:
export ABRUN_API_URL='https://api.abr.run'
export ABRUN_TOKEN='<your-api-token>'قرار دادن token پس از export ممکن است آن را در history شل ذخیره کند. در محیط واقعی، مقدار را از secret manager یا ورودی امن shell بخوانید و پس از پایان session پاک کنید.
درخواست زیر کاربر متناظر با token را برمی‌گرداند:
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $ABRUN_TOKEN" \
"$ABRUN_API_URL/v1/auth/me" | jqاگر پاسخ 401 Unauthorized است، token وجود ندارد، نامعتبر است یا منقضی شده است. اگر 403 Forbidden می‌گیرید، هویت معتبر است اما مجوز عملیات را ندارد.
فهرست پروژه‌های حساب را دریافت کنید:
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $ABRUN_TOKEN" \
"$ABRUN_API_URL/v1/projects" | jqپاسخ این endpoint یک آرایه از پروژه‌ها است. مقدار عددی id پروژه موردنظر را انتخاب کنید:
export ABRUN_PROJECT_ID='<project-id>'endpointهای collection پروژه‌ای مانند فهرست Appها به هدر X-Project-ID نیاز دارند:
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $ABRUN_TOKEN" \
--header "X-Project-ID: $ABRUN_PROJECT_ID" \
"$ABRUN_API_URL/v1/apps" | jqاین فهرست یک پاسخ صفحه‌بندی‌شده دارد:
{
"items": [],
"total": 0,
"limit": 20,
"offset": 0
}برای endpointهای item مانند /v1/apps/{appID} معمولاً هدر پروژه لازم نیست؛ API مالکیت resource و دسترسی شما را از خود شناسه بررسی می‌کند. وجود یک شناسه به معنی دسترسی به آن نیست.
برای درخواست‌هایی که body دارند، Content-Type را صریح بفرستید. این نمونه فقط الگوی صحیح ارسال JSON را نشان می‌دهد؛ پیش از استفاده، فیلدهای endpoint موردنظر را در مرجع API بررسی کنید.
curl --fail-with-body --silent --show-error \
--request POST \
--header "Authorization: Bearer $ABRUN_TOKEN" \
--header "X-Project-ID: $ABRUN_PROJECT_ID" \
--header 'Content-Type: application/json' \
--data '{"name":"example"}' \
"$ABRUN_API_URL/v1/apps" | jqیک resource به‌صورت object مستقیم برمی‌گردد. فهرست‌های صفحه‌بندی‌شده شامل items، total، limit و offset هستند و عملیات بدون body می‌توانند 204 No Content برگردانند.
خطای API این envelope پایدار را دارد:
{
"error": {
"code": "error_code",
"message": "A readable explanation"
}
}automation باید ابتدا HTTP status و سپس error.code را بررسی کند. روی متن message یا جزئیات داخلی provider، Kubernetes و دیتابیس شرط نگذارید. --fail-with-body باعث می‌شود curl در statusهای ناموفق exit code غیرصفر بدهد و در عین حال body خطا را برای عیب‌یابی حفظ کند.
بعد از پایان کار، token را از محیط shell حذف کنید:
unset ABRUN_TOKEN ABRUN_PROJECT_IDبرای قواعد کامل پاسخ‌ها و تغییر قرارداد، مرجع API ابران را بخوانید. اگر commandهای آماده و خروجی table، JSON یا YAML می‌خواهید، به مرجع CLI ابران بروید.