رفتن به محتوا
آونداز هوش مصنوعی شکوفا
همه مستندات

راهنمای API

احراز هویت، ذخیره‌سازی، تحویل CDN، تبدیل تصویر و ویدیو — با درخواست‌های آماده برای کپی.

چگونه از سرویس فایل آوند در سمت سرور برنامه خودتان استفاده کنید: ذخیره‌سازی اشیا، تحویل CDN، تبدیل تصویر در لحظه و پخش ویدئو، همه از راه API سرویس Avand. هر نمونه یک دستور curl آماده رونوشت است و بخش ۱۳ همان مسیر را در Node و C#‎ نشان می‌دهد.

مرجع تعاملی: مسیر /scalar/ روی نمونه در حال اجرا. قرارداد ماشین‌خوان: به‌صورت زنده در /openapi/v1.json سرو می‌شود (برای مجموعه https://avandapi.shokoofa.ai/openapi/v1.json، و درون شبکه http://bee-api:8080/openapi/v1.json)، و همان قرارداد در docs/openapi/avand-v1.json هم در مخزن نگهداری و بازتولید می‌شود، هرگز دستی ویرایش نمی‌شود.

فهرست

  1. آوند چیست، و چهار سطح API
  2. حساب‌ها، نقش‌ها و مجوزها
  3. نشست یا کلید API: کدام اعتبارنامه
  4. کلیدهای API
  5. نشست‌ها: ورود و تازه‌سازی
  6. قراردادهایی که همه‌جا برقرارند
  7. ناحیه‌های ذخیره‌سازی و کلیدهای دسترسی ناحیه
  8. سطح داده ذخیره‌سازی: بارگذاری، دریافت، فهرست، حذف
  9. بارگذاری ازسرگیری‌پذیر
  10. CDN: ناحیه‌های pull، حافظه نهان، پاک‌سازی، قواعد لبه، URLهای امضاشده
  11. تصویر و ویدئو
  12. مدیریت، گزارش ممیزی و آمار
  13. سر تا ته: بارگذاری یک فایل و گرفتن نشانی CDN آن، در Node و C#‎
  14. عیب‌یابی
  15. مرجع سریع

۱. آوند چیست، و چهار سطح API

آوند برنامه وب است؛ Avand همان API پشت آن. هر کاری که در آوند می‌شود کرد، مستقیم با Avand هم می‌شود کرد، و این راهنما درباره همین است.

نحوه اجرای Avandنشانی پایه
docker compose uphttp://localhost:20331 (پورت منتشرشده AVAND_API_HOST_PORT است)
اجرای مستقیم با dotnet runhttp://localhost:20331
یک استقرار واقعیهمان مبدأیی که آوند آن را PUBLIC_AVAND_ORIGIN می‌نامد (برای مجموعه https://avandapi.shokoofa.ai)
استقرار مجموعه، از یک بک‌اند دیگر روی همان سرورhttp://bee-api:8080 روی شبکه Docker‏ shokoofa-shared-net

بک‌اندی که روی سرور مجموعه است آوند و Keycloak را درون شبکه صدا می‌زند، هرگز از راه میزبان‌های عمومی: آن‌ها پشت Cloudflare هستند، که به User-Agentهای پیش‌فرض کلاینت‌های سروری یک 403 به‌صورت HTML می‌دهد (هرگز از آوند نیست) و هر درخواست را به حدود ۱۰۰ MB و حدود ۱۰۰ ثانیه محدود می‌کند. قواعد در integrating-apps.md بخش ۱.۵ آمده است.

نمونه‌ها از یک متغیر شل استفاده می‌کنند تا همه‌جا کار کنند:

AVAND=http://localhost:20331

نقاط پایانی Avand به چهار سطح با احراز هویت متفاوت تقسیم می‌شوند. دانستن اینکه در کدام سطح هستید، پاسخ بیشتر پرسش‌های «چرا 401 می‌گیرم؟» است.

سطحمسیرهااعتبارنامهکاربرد
کنترل/api/v1/**توکن دسترسی از IdP مرکزی: مبادله‌شده از یک کلید API، یا توکن یک نشستساخت و پیکربندی همه‌چیز
داده ذخیره‌سازی/storage/{zone}/**کلید دسترسی ناحیهبارگذاری، دریافت، فهرست و حذف اشیای خام
نشست‌های بارگذاری/upload/sessions/**همان توکن دسترسیبارگذاری ازسرگیری‌پذیر
تحویل/cdn/**، /img/**هیچارائه محتوا به کاربران نهایی

سطح تحویل هیچ سربرگ احراز هویتی ندارد: دسترسی را تنظیمات امنیتی خودِ هر ناحیه pull کنترل می‌کند (URLهای امضاشده و قواعد ارجاع‌دهنده، IP و کشور).

۲. حساب‌ها، نقش‌ها و مجوزها

در آوند نه ساخت حساب هست، نه گذرواژه و نه ورود: افراد از راه Keycloak مرکزی (realm identity-service) وارد می‌شوند، و نخستین درخواستی که توکن آن‌ها را دارد حساب محلی را، با کلید sub توکن، همراه با فضای شخصی‌اش می‌سازد. نقش‌ها در مرکز حساب داده می‌شوند، نه اینجا.

Avand بر پایه مجوزها اجازه می‌دهد، که آن‌ها را از نقش‌های شخص به دست می‌آورد: نقش‌های realm فعلی او، که از Keycloak خوانده می‌شوند و حداکثر یک دقیقه نگه داشته می‌شوند. نقش‌ها و آنچه هر کدام می‌دهد یک جدول است، کاتالوگ نقش‌های آوند، در API_GUIDE بخش ۱ › نقش‌ها و مجوزها: avand.viewer، avand.member، avand.operator و avand.admin برای کار روزمره و مدیریت، و نقش‌های platform.* برای کارهای سطح استقرار و توقیف قانونی. نقش‌ها در مرکز حساب داده می‌شوند، نه اینجا. شخصی که هیچ استحقاقی ندارد فقط‌فضای‌خود است: می‌تواند در ناحیه‌هایی که صاحبشان است فهرست کند، بخواند، دانلود کند و حذف کند، /api/v1/me/space و /api/v1/auth/me را ببیند و از خدمت‌رسانی حساب خودش استفاده کند؛ بارگذاری، اشتراک، پیوند و تغییر فهرست دسترسی 403 access.own_space_read_only می‌دهند، و هر سطح دیگر 403 access.no_app_access.

مجوزها سلسله‌مراتبی‌اند، نه یک مجموعه تخت. مستندات هر عملیات مجوز لازم را نام می‌برد و مجوزهای بالاتر پایین‌تر را برآورده می‌کنند:

عملیات نیاز دارد بهبرآورده می‌شود با
bee:readbee:read، bee:write، bee:admin
bee:writebee:write، bee:admin
bee:purgebee:purge، bee:write، bee:admin
bee:streambee:stream، bee:write، bee:admin
bee:adminbee:admin
bee:platformفقط bee:platform
bee:legal-holdفقط bee:legal-hold

پس نقشی که bee:write می‌دهد بی‌آنکه bee:read را نام ببرد می‌تواند بخواند: bee:write آن را در بر دارد.

۳. نشست یا کلید API: کدام اعتبارنامه

اشخاص از نشست استفاده می‌کنند. کلیدهای API فقط برای مدیران و فراخوان‌های سیستمی (کارهایی که شخص نیستند) هستند. شخص در آوند کلید شخصی ندارد. اعتبارنامه‌هایی که به سطح کنترل می‌رسند به یک توکن دسترسی از IdP مرکزی ختم می‌شوند، یا برای کلید سیستمی به خودِ کلید، که به شکل Authorization: Bearer فرستاده می‌شود؛ Avand خودش هیچ توکنی صادر نمی‌کند.

توکن نشستکلید API مدیر (shk_…)
گرفتنشIdP مرکزی، از راه برنامه وب آوند (که آن را روی سرور خودش نگه می‌دارد)مرکز حساب ← کلیدهای API، برای برنامه avand، یک بار؛ فقط کسی می‌تواند از آن استفاده کند که اکنون avand.admin دارد
فرستادنشAuthorization: Bearer <token>در نقطه پایانی توکن IdP با یک توکن دسترسی مبادله می‌شود که به شکل Authorization: Bearer <token> فرستاده می‌شود
عمرشعمر توکن دسترسی در IdP؛ برنامه وب آن را با Keycloak تازه می‌کندخودِ کلید: تا ابطال، انقضا یا ۹۰ روز بی‌استفادگی. هر توکن مبادله‌شده: ۵ دقیقه
حملشهمه مجوزهای حسابمجوزهایی که برگزیده‌اید (bee:read، bee:write، bee:purge، bee:stream و bee:admin)، محدود به آنچه مدیر اکنون دارد
ابطال‌پذیرنه از سوی Avand: توکن دسترسی تا انقضا معتبر است. پایان دادن به نشست کار Keycloak استبله، در مرکز حساب: مبادله بعدی شکست می‌خورد، توکنی که از قبل مبادله شده ۵ دقیقه‌اش را تمام می‌کند
عملیات فقط‌نشست (حساب‌ها و کلیدهای سیستمی، نمایه، خروجی)بلهخیر
برایانسان‌ها، و خودِ برنامه آونداسکریپت‌های خودِ یک مدیر

کلید سیستمی (avand_ak_…، بخش ۴) اعتبارنامه سوم است: به یک حساب سیستمی تعلق دارد، مستقیم به آوند فرستاده می‌شود، همیشه انقضا دارد، و هرگز نمی‌تواند از طرف یک شخص عمل کند.

برای هر چیز بی‌سرپرست از کلید استفاده کنید. سمت سرور کاری با نگه داشتن نشست یک شخص ندارد: آن نشست هر کاری حساب می‌تواند بکند را حمل می‌کند و Avand نمی‌تواند باطلش کند. کلید فقط آنچه به آن داده‌اید دارد و هر توکنِ کلید مدیر پنج دقیقه زنده است. برنامه‌ای که از طرف شخص واردشده عمل می‌کند اصلاً کلید به کار نمی‌برد: توکن آن شخص را مبادله می‌کند (docs/integrating-apps.md). نمونه‌های این راهنما $AVAND_TOKEN را می‌فرستند: توکن دسترسی مبادله‌شده از یک کلید مدیر، یا برای عملیاتی که شخص واردشده می‌خواهند (کلیدهای ناحیه، حساب‌های سیستمی، گزارش ممیزی)، توکن نشست یک مدیر.

۴. کلیدهای API

کلیدهای مدیر

کلیدهای API مدیران برای آوند را IdP مرکزی صادر، نگهداری و تأیید می‌کند. فقط کسی که اکنون avand.admin دارد می‌تواند از یکی استفاده کند: به محض از دست دادنش، توکن کلید روی هر مسیر 403 access.api_keys_admin_only می‌دهد.

  1. یکی بسازید در مرکز حساب برای برنامه avand، و فقط مجوزهای لازم را تیک بزنید: bee:read، bee:write، bee:purge، bee:stream، و برای مدیریت bee:admin. کلید (shk_…) یک بار نمایش داده می‌شود؛ آن را در مخزن رازهایتان رونوشت کنید.
  2. مبادله‌اش کنید در نقطه پایانی توکن IdP با یک توکن دسترسی:
AVAND_TOKEN=$(curl -s \
  -d grant_type=urn:shokoofa:params:oauth:grant-type:api-key \
  -d client_id=administration-keys \
  -d api_key=$AVAND_API_KEY \
  https://auth.shokoofa.ai/realms/identity-service/protocol/openid-connect/token | jq -r .access_token)

پاسخ فقط یک access_token دارد که ۵ دقیقه معتبر است: پس از انقضا یا با یک 401 دوباره مبادله کنید. مبادله ردشده invalid_grant است: کلید باطل یا منقضی شده، ۹۰ روز بی‌استفاده مانده، یا شخصش غیرفعال است. 3. توکن را بفرستید به شکل Authorization: Bearer $AVAND_TOKEN، درست مثل توکن نشست. همه نمونه‌های این راهنما همین کار را می‌کنند.

توکن اشتراکِ مجوزهای کلید و مجوزهای فعلی مدیر را دارد، که در هر درخواست دوباره حساب می‌شود، پس تنزل نقش کلید را ظرف یک دقیقه محدود می‌کند. هرگز نشست تعاملی به شمار نمی‌آید: مدیریت حساب‌ها و کلیدهای سیستمی، نمایه و خروجی 403 می‌دهند؛ از step-up معاف است. GET /api/v1/auth/me مقدار "authMethod": "apiKey" را گزارش می‌دهد، و ردّ ممیزی آن را via = api-key:<key_id> می‌نامد. جزئیات: API_GUIDE بخش ۱ › کلیدهای مدیر.

حساب‌های سیستمی و کلیدهای سیستمی (avand_ak_)

حساب سیستمی صاحب فایل‌های کار یا اسکریپتی است که ورود ندارد: ارسال‌کننده لاگ، گرافیک رابط کاربری، محتوای تولیدشده. هرگز شخص نیست و هیچ کاری از آن به شخصی نسبت داده نمی‌شود. مدیر حساب‌های سیستمی و کلیدهایشان را در یک نشست تعاملی مدیریت می‌کند (bee:admin لازم است)، در داشبورد یا با API زیر. حساب غیرفعال و فعال می‌شود، و در این انتشار هرگز حذف نمی‌شود؛ غیرفعال کردن همه کلیدهایش را بی‌درنگ متوقف می‌کند و داده‌اش را نگه می‌دارد.

ساختن حساب سیستمی

curl -s -X POST $AVAND/api/v1/system-accounts \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-media-service" \
  -d '{"name":"media-service","purpose":"Generated thumbnails","quotaBytes":10737418240}'
{
  "id": "0198c0de-…",
  "name": "media-service",
  "purpose": "Generated thumbnails",
  "quotaBytes": 10737418240,
  "defaultZoneId": "0198c0df-…",
  "createdAt": "2026-10-06T12:00:00+00:00",
  "disabledAt": null
}

نام یکتاست (409 bee.system_account_name_taken) و از حروف کوچک، ارقام و خط تیره ساخته می‌شود (400 bee.system_account_name_invalid). quotaBytes سهمیه است؛ null یعنی نامحدود، و باید صریح گفته شود. حساب یک ناحیه خصوصی s- به‌علاوه شناسه‌اش بدون خط تیره می‌گیرد، و با یک کلید bee:write می‌تواند ناحیه‌های بیشتر بسازد. همچنین GET /api/v1/system-accounts، GET /api/v1/system-accounts/{id}، POST …/disable، POST …/enable و PUT …/quota با {"quotaBytes": …}.

ساختن کلید

curl -s -X POST $AVAND/api/v1/system-accounts/$ACCOUNT_ID/keys \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mint-media-service-key-1" \
  -d '{"name":"thumbnailer","permissions":["bee:write"],"expiresAt":"2027-08-24T00:00:00Z"}'
{
  "id": "0198c0de-…",
  "name": "thumbnailer",
  "keyPrefix": "avand_ak_0198c0de…",
  "permissions": ["bee:write"],
  "zoneIds": [],
  "plaintextKey": "avand_ak_0198c0de00007000800000000000abcd_Kj3…43 characters…",
  "createdAt": "2026-10-06T12:00:00+00:00",
  "expiresAt": "2027-08-24T00:00:00+00:00"
}

کلید یک بار نمایش داده می‌شود؛ Avand فقط درهم‌سازی آن را نگه می‌دارد. expiresAt الزامی است (400 bee.api_key_expiry_required) و حداکثر ۳۶۵ روز بعد (400 bee.api_key_expiry_too_far؛ حد آن AvandApiKeys:MaxLifetime است). permissions برخی از bee:read، bee:write، bee:purge، bee:stream است، هرگز admin. برای حساب غیرفعال کلید صادر نمی‌شود (409 bee.system_account_disabled).

قالب

avand_ak_<32 hex characters: the key id>_<43 characters: the secret>

شناسه داخل خودِ کلید است، پس Avand آن را مستقیم پیدا می‌کند و یک درهم‌سازی را مقایسه می‌کند. بخش پیش از آخرین _ همان keyPrefix است که آوند فهرست می‌کند، و با آن می‌توان کلیدی را که در یک فایل پیکربندی پیدا می‌کنید به ردیفش رساند. پویشگرهای راز می‌توانند کلید نشت‌کرده را با avand_(ak|zk)_[0-9a-f]{32}_[A-Za-z0-9_-]{43} بیابند.

فرستادن

هر کدام از این دو روی هر مسیری که کلید سیستمی به آن می‌رسد کار می‌کند، هر جا که مستندات می‌گوید «توکن bearer یا کلید API» ($AVAND_API_KEY کلید avand_ak_ را نگه می‌دارد):

# Standard: the same header a session token uses
curl -s "$AVAND/api/v1/files?storageZoneId=$ZONE_ID" -H "Authorization: Bearer $AVAND_API_KEY"

# bunny.net-style alias, for code written against bunny's APIs
curl -s "$AVAND/api/v1/files?storageZoneId=$ZONE_ID" -H "AccessKey: $AVAND_API_KEY"

مرجع تعاملی در /scalar/ کلید را همان‌طور که هست در فیلد bearer می‌پذیرد.

کلید چه می‌تواند و چه نمی‌تواند

  • به‌عنوان حساب سیستمی احراز می‌شود، هرگز شخص، و نمی‌تواند از طرف شخصی عمل کند. مجوزهایی را دارد که با آن ساخته شده، و فقط روی ناحیه‌های خودِ حساب کار می‌کند.
  • با zoneIds می‌تواند به برخی ناحیه‌های حساب محدود شود. کلید محدود به ناحیه بسته‌پیش‌فرض است: فقط روی درخواست‌های ناحیه‌آگاه همان ناحیه‌ها کار می‌کند (API فایل‌ها، مسیرهای شیء و بارگذاری ناحیه ذخیره‌سازی، نشست‌های بارگذاری، /api/v1/me/space، /api/v1/auth/me و فهرست ناحیه‌های ذخیره‌سازی که به ناحیه‌هایش فیلتر شده). هر چیز دیگر (ناحیه‌های کشش، ویدیو، وب‌هوک‌ها، تبدیل‌های ذخیره‌شده، کلیدهای فایل، مدیریت ناحیه) 403 bee.api_key_zone_not_owned می‌دهد.
  • پس از ابطال، پس از expiresAt و در مدت غیرفعال بودن حسابش، با همان 401 کلید اشتباه رد می‌شود. اینکه کدام‌یک بوده در سرور ثبت می‌شود و هرگز به فراخوان گفته نمی‌شود.
  • نمی‌تواند حساب‌ها یا کلیدهای سیستمی را مدیریت کند، نمایه را تغییر دهد یا خروجی را دانلود کند. آن‌ها به کلید 403 می‌دهند.
  • روی سطح تحویل، کلیدی با bee:read که حسابش صاحب ناحیه است جای URL امضاشده می‌نشیند.
  • GET /api/v1/auth/me مقدار "authMethod": "apiKey" و مجوزهای مؤثر کلید را گزارش می‌دهد.
  • هر حساب حداکثر ۲۵ کلید فعال دارد.

چرخش، ابطال، ممیزی

# A new secret under the same name, permissions and expiry. The old one dies in the same write.
curl -s -X POST $AVAND/api/v1/system-accounts/$ACCOUNT_ID/keys/$KEY_ID/rotate -H "Authorization: Bearer $SESSION_TOKEN"

# Dead on the next request. Irreversible.
curl -s -X DELETE $AVAND/api/v1/system-accounts/$ACCOUNT_ID/keys/$KEY_ID -H "Authorization: Bearer $SESSION_TOKEN"

# Everything the account has had, active first. Never the secret.
curl -s $AVAND/api/v1/system-accounts/$ACCOUNT_ID/keys -H "Authorization: Bearer $SESSION_TOKEN"

چرخش بازه هم‌پوشانی ندارد: کلید سیستمی پیکربندی یک فرایند است، پس راز تازه را همان لحظه مستقر کنید. هر ساخت، چرخش و ابطال در گزارش ممیزی (بخش ۱۲) نوشته می‌شود، و همچنین هر استفاده از کلید: یک ردیف apiKey.use با via = api-key:<id>، قالب مسیر (یا (unmatched)) و وضعیت. استفاده‌های محدودشده (429) حداکثر دقیقه‌ای یک بار برای هر کلید و مسیر خلاصه می‌شوند، با suppressed429=N. مدیران ورودی‌های حساب‌های سیستمی را در گزارش ممیزی می‌بینند.

راز نگهش دارید

با هر دو نوع کلید مانند گذرواژه رفتار کنید: متغیر محیطی یا مدیر رازها، هرگز در کنترل نسخه، هرگز در بسته سمت کاربر، هرگز در یک خط لاگ. اگر نشت کرد، باطلش کنید: کلید مدیر را در مرکز حساب (مبادله بعدی شکست می‌خورد)، کلید سیستمی را در آوند (درخواست بعدی با آن 401 می‌گیرد).

۵. نشست‌ها: ورود و تازه‌سازی

برنامه وب آوند شما را از راه IdP مرکزی وارد می‌کند و توکن را روی سرور خودش نگه می‌دارد؛ خودِ Avand هیچ نقطه پایانی‌ای برای ورود، تازه‌سازی یا گذرواژه ندارد. اسکریپت توکن را از Keycloak می‌گیرد (برای یک شخص، از راه برنامه‌ای که برایش کار می‌کند؛ برای یک سرویس، با client credentials) و آن را به شکل Authorization: Bearer <token> می‌فرستد. تازه‌سازی و پایان دادن به نشست‌ها کار Keycloak است. Avand توکن را در تمام عمرش به‌صورت آفلاین تأیید می‌کند و نمی‌تواند باطلش کند؛ وقتی منقضی شد پاسخ 401 invalid_token است و چاره‌اش توکن تازه است، نه تکرار درخواست.

۶. قراردادهایی که همه‌جا برقرارند

  • ساخت‌ها 201 با سربرگ Location و {"id":"<guid>"} برمی‌گردانند، نه خودِ منبع را. اگر لازمش دارید جداگانه بگیرید. به‌روزرسانی و حذف 204 بی‌بدنه برمی‌گردانند.
  • خطاها سند مشکل RFC 9457 هستند (application/problem+json) با type، title، status، detail، یک traceId که هنگام گزارش اشکال نقل می‌کنید، و یک code پایدار و نقطه‌دار (bee.storage_zone_not_found) که روی آن شاخه می‌زنید و ترجمه‌اش می‌کنید؛ title و detail توضیح انگلیسی برای توسعه‌دهنده‌اند. خطاهای اعتبارسنجی errors را می‌افزایند که هر خطا را به شکل { code, field, params? } فهرست می‌کند: [{"code":"validation.required","field":"name"}]. راهنمای API همه کدها را فهرست می‌کند. با هر درخواست Accept-Language: fa یا en بفرستید. استثنا: سطح تحویل (/cdn/**، /img/**) کد وضعیت خالی بی‌بدنه برمی‌گرداند، چون مصرف‌کننده‌هایش برچسب <img> و پخش‌کننده‌های ویدئو هستند؛ فقط 429 آن، مثل هر 429 دیگر، سند مشکل است.
  • فهرست‌ها با نشانگر صفحه‌بندی می‌شوند، قدیمی‌ترین اول. limit (پیش‌فرض ۵۰، محدود به ۱..۲۰۰) و nextCursor صفحه قبل را بفرستید. وقتی hasMore برابر false شد بایستید. نشانگرها مبهم‌اند؛ هرگز نسازید یا تجزیه نکنید. صفحه‌ای که پشت سرش صفحه دیگری هست سربرگ Link: <…>; rel="next" هم دارد که می‌توانید به جای ساختن درخواست بعدی دنبالش کنید.
  • هم‌توانی: نقاط پایانی‌ای که می‌گویند، سربرگ Idempotency-Key می‌پذیرند (هر رشته تا ۱۲۸ نویسه). تکرار همان کلید پاسخ اصلی را بی‌تکرار کار برمی‌گرداند؛ تکرار در حالی که درخواست نخست هنوز در حال اجراست 409 می‌دهد؛ استفاده دوباره از یک کلید برای درخواستی متفاوت 422 می‌دهد نه اینکه چیزی را که نفرستاده‌اید تکرار کند. یک کلید ۲۴ ساعت معتبر است و بعد از آن کلیدی تازه است. برای هر قصد کاربر یک کلید و در تلاش‌های مجدد شبکه همان را به کار ببرید.
  • شمارشی‌ها رشته‌های camelCase هستند ("ignoreAll")، زمان‌ها RFC 3339 به وقت UTC، شناسه‌ها UUID، و هر فیلدی که به Bytes، Seconds، Kbps یا Percent ختم شود در همان یکاست.
  • ناحیه‌ها و کتابخانه‌ها نسخه‌دارند. خواندن یک ناحیه pull، ناحیه ذخیره‌سازی یا کتابخانه ویدئو یک ETag برمی‌گرداند. هنگام تغییر ناحیه آن را به عنوان If-Match برگردانید؛ اگر کس دیگری زودتر تغییرش داده باشد نوشتن با 412 رد می‌شود تا ویرایش هیچ‌کس بی‌صدا گم نشود؛ برای خواندن دوباره بدون بدنه وقتی چیزی عوض نشده، آن را به عنوان If-None-Match بفرستید (304). اختیاری است مگر اپراتور شما الزامی‌اش کند (428).
  • هر پاسخ سربرگ X-Bee-Request-Id دارد، روی هر سطح، حتی 304، تغییر مسیر یا 429. همان مقداری است که traceId سند مشکل دارد. هنگام گزارش مشکل نقلش کنید؛ پاسخ را به رد سمت سرور پیوند می‌دهد. Avand خودش آن را می‌سازد و مقداری را که شما بفرستید نادیده می‌گیرد؛ برای پیوند دادن رد خودتان، به جای آن سربرگ W3C traceparent بفرستید.
  • پاسخ‌ها در صورت درخواست فشرده می‌شوند. Accept-Encoding: br یا gzip بفرستید تا متن، JSON (از جمله اسناد مشکل)، فهرست‌های پخش و SVG فشرده و با Vary: Accept-Encoding برگردند. محدوده‌های بایت (206)، تصاویر، قطعه‌های ویدئو و پاسخ‌های اعتبارنامه (صدور کلید API، کلید ناحیه یا راز وب‌هوک، و خروجی حساب) همیشه بدون فشرده‌سازی‌اند. کلاینت‌های HTTP خودشان باز می‌کنند؛ curl به --compressed نیاز دارد.
  • سربرگ‌های امنیتی. X-Content-Type-Options: nosniff روی همه چیز هست؛ سطح کنترل X-Frame-Options: DENY، Referrer-Policy: no-referrer و یک Content-Security-Policy هم می‌افزاید. سطح‌های تحویل، تصویر، ذخیره‌سازی و بارگذاری هیچ‌کدام از این سه را ندارند، تا رسانه میزبانی‌شده در Avand در صفحه‌های شما قابل جاسازی بماند.

۷. ناحیه‌های ذخیره‌سازی و کلیدهای دسترسی ناحیه

ساخت ناحیه

curl -s -X POST $AVAND/api/v1/storage-zones \
  -H "Authorization: Bearer $AVAND_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-assets-zone-1" \
  -d '{
    "name": "my-assets",
    "primaryRegion": "eu",
    "tier": "standard",
    "quotaBytes": 10737418240,
    "replicationRegions": []
  }'
# 201 → {"id":"<storageZoneId>"}

tier یکی از standard یا performance است. کد منطقه جغرافیایی رشته‌ای کوتاه با حروف کوچک است (۲ تا ۸ نویسه، مثلاً eu، us، apac). آماده‌سازی ناهمگام است: ناحیه را بپرسید تا state به ready برسد. quotaBytes: 0 یعنی بدون سهمیه، و سهمیه خودِ حساب روی آن اعمال می‌شود.

مرورگری که مستقیماً از ناحیه می‌خواند به CORS نیاز دارد. به‌طور پیش‌فرض فهرست سراسری AvandCors:AllowedOrigins اعمال می‌شود؛ یک ناحیه می‌تواند به جای آن فهرست خودش را داشته باشد:

curl -s -X PATCH $AVAND/api/v1/storage-zones/$ZONE_ID \
  -H "Authorization: Bearer $AVAND_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{ "cors": { "enabled": true, "allowedOrigins": ["https://app.example.com"], "allowedExtensions": [] } }'

وقتی enabled باشد، origin‌های ناحیه برای /storage/my-assets/… (از جمله preflight) جای فهرست سراسری را می‌گیرند؛ allowedExtensions تعیین می‌کند کدام اشیا اصلاً سربرگ CORS بگیرند (خالی یعنی همه). این سیاست روی ناحیه خوانده می‌شود.

همان PATCH مقادیر name، quotaBytes و replicationRegions را تغییر می‌دهد. منطقه‌های تکثیر به‌صورت مجموعه کامل مطلوب فرستاده می‌شوند: منطقه‌هایی که در آن نیستند حذف و تازه‌ها اضافه می‌شوند، [] تکثیر را متوقف می‌کند و منطقه اصلی نباید در فهرست باشد. tier پس از ایجاد قابل تغییر نیست.

صدور کلید دسترسی ناحیه

سطح داده با کلیدی محدود به یک ناحیه احراز هویت می‌کند، نه با اعتبارنامه حساب شما. صدور آن bee:admin می‌خواهد، که کلید صادرشده توسط IdP هرگز ندارد: آن را از آوند، یا با توکن نشست یک مدیر، صادر کنید.

curl -s -X POST $AVAND/api/v1/storage-zones/$ZONE_ID/keys \
  -H "Authorization: Bearer $AVAND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"backup-script","scope":"readOnly"}'
{
  "id": "…",
  "name": "backup-script",
  "scope": "readOnly",
  "keyPrefix": "avand_zk_…",
  "plaintextKey": "avand_zk_<32 hex>_<43 characters>",
  "issuedAt": "…"
}

هم name و هم scope لازم‌اند: نام است که کلیدهای چرخانده‌شده را از هم جدا می‌کند، و دامنه حذف‌شده رد می‌شود نه اینکه به خواندن‌ونوشتن پیش‌فرض شود. plaintextKey دقیقاً یک بار نمایش داده می‌شود. هر جا فقط دریافت لازم است readOnly را ترجیح دهید؛ کلید رازی حامل برای کل ناحیه است. با POST .../keys/{id}/rotate بچرخانید (کلید قدیمی بی‌درنگ از کار می‌افتد) و با DELETE .../keys/{id} باطل کنید. صدور، چرخش و ابطال ممیزی می‌شوند.

کلیدی که پیش از آنکه کلیدها شناسه‌شان را حمل کنند صادر شده keyPrefix ندارد و بی‌تغییر کار می‌کند.

۸. سطح داده ذخیره‌سازی: بارگذاری، دریافت، فهرست، حذف

کلید ناحیه را در X-Bee-Access-Key بفرستید، یا اگر کدتان برای API ذخیره‌سازی bunny.net نوشته شده، در AccessKey. درخواستی بدون کلید معتبر 401 با WWW-Authenticate: AccessKey realm="bee-storage" می‌گیرد. درخواست‌ها برای هر کلید محدود می‌شوند (۴٬۰۰۰ درخواست انفجاری، با پرشدن ۲٬۰۰۰ در ثانیه) و، روی همه کلیدها با هم، برای هر ناحیه (۲۰٬۰۰۰ انفجاری، ۱۰٬۰۰۰ در ثانیه)؛ مازاد 429 می‌گیرد که سهمیه پرشده را نام می‌برد.

بارگذاری

بایت‌های خام در بدنه، نه چندبخشی. مسیر پس از نام ناحیه می‌تواند / داشته باشد. اگر Content-Type نفرستید، شیء نوعی را می‌گیرد که پسوندش می‌گوید (.jpg → image/jpeg) و در غیر این صورت application/octet-stream:

curl -s -X PUT "$AVAND/storage/my-assets/photos/111.jpg" \
  -H "X-Bee-Access-Key: $ZONE_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @111.jpg
# 201 with a Location header and the stored object's metadata

می‌توانید SHA-256 مورد انتظار را بفرستید تا Avand آنچه ذخیره کرده را تأیید کند: به‌صورت Content-Digest: sha-256=:<base64>: طبق RFC 9530، در سربرگ Checksum به سبک bunny.net (هگز، با هر حالت حروف)، یا هگز در X-Bee-Content-Sha256. ناهم‌خوانی بارگذاری را رد می‌کند (422) به جای ذخیره بایت‌های خراب؛ الگوریتمی که Avand نمی‌تواند محاسبه کند، digest بدشکل، یا سربرگ‌هایی که با هم نمی‌خوانند پیش از خواندن بدنه با 400 رد می‌شوند. هر بارگذاری موفق با Repr-Digest: sha-256=:<base64>: بایت‌های ذخیره‌شده پاسخ می‌دهد. فراتر از سهمیه حساب 507 است؛ فراتر از حد اندازه درخواست 413. کلید readWrite لازم است.

نخستین بارگذاری در یک مسیر 201 می‌دهد؛ بازنویسی شیء موجود 200. هر دو فراداده شیء (created می‌گوید کدام بوده) و ETag آن را برمی‌گردانند. آن tag را در PUT یا DELETE بعدی به‌عنوان If-Match بفرستید تا اگر کسی پیش از شما شیء را تغییر داده باشد، نوشتن با 412 رد شود؛ If-None-Match: * یک PUT را فقط-ایجاد می‌کند (412 وقتی مسیر از قبل شیئی دارد)؛ If-Unmodified-Since همین کار را با تاریخ می‌کند. 412 چیزی نمی‌نویسد.

نام‌ها به Unicode NFC نرمال می‌شوند (هر دو املای یک نویسه لهجه‌دار یک شیء هستند)؛ یک بخش نمی‌تواند با فاصله شروع یا تمام شود، . یا .. باشد، نویسه کنترلی داشته باشد یا از ۲۵۵ بایت UTF-8 بیشتر شود، و اسلش کدشده (%2F) به جای جداکننده شمرده شدن با 400 رد می‌شود.

دریافت

curl -s "$AVAND/storage/my-assets/photos/111.jpg" -H "X-Bee-Access-Key: $ZONE_KEY" -o 111.jpg

Range پشتیبانی می‌شود (206، Content-Range، 416 فراتر از انتها)، If-None-Match (قوی یا ضعیف، فهرست، یا *) و If-Modified-Since پاسخ 304 همراه ETag و Last-Modified می‌دهند، Accept-Ranges: bytes همیشه فرستاده می‌شود، و هر پاسخ شیء Repr-Digest: sha-256=:<base64>: (RFC 9530) دارد مگر آنکه Want-Repr-Digest: sha-256=0 آن را نخواهد. ?download را اضافه کنید تا Content-Disposition: attachment با نام شیء بگیرید، یا با ?response-content-disposition=inline / attachment; filename="x" خودتان آن را تعیین کنید. HEAD همان وضعیت و سربرگ‌ها (Content-Length، ETag، Last-Modified، Content-Type) را بدون بدنه برمی‌گرداند. با کلید readOnly کار می‌کند.

فهرست

مسیری که به / ختم شود، یا ریشه ناحیه، به جای دریافت فهرست می‌دهد. همان نمای پوشه‌ای است که سطح کنترل ارائه می‌کند، فقط با کلید ناحیه، پس اسکریپتی که بارگذاری می‌کند می‌تواند بدون اعتبارنامه حساب ببیند چه بارگذاری کرده:

# The zone root
curl -s "$AVAND/storage/my-assets/" -H "X-Bee-Access-Key: $ZONE_KEY"

# One level down, paged
curl -s "$AVAND/storage/my-assets/photos/?limit=50" -H "X-Bee-Access-Key: $ZONE_KEY"
{
  "items": [
    { "path": "photos/2026/", "name": "2026", "isDirectory": true, "object": null },
    { "path": "photos/111.jpg", "name": "111.jpg", "isDirectory": false, "object": { "sizeInBytes": 48213, "contentType": "image/jpeg", "…": "…" } }
  ],
  "nextCursor": null,
  "hasMore": false
}

هر object این فیلدها را دارد: sizeInBytes، contentType، contentHash (SHA-256 با هگز کوچک)، checksum (همان SHA-256 با هگز بزرگ، همان‌طور که bunny.net فهرست می‌کند)، eTag، lastModifiedAt، createdAt و storageZoneName. پوشه‌ها از / در مسیر اشیا استنتاج می‌شوند و object ندارند؛ با درخواست path پوشه پایین‌تر بروید. با cursor صفحه بزنید تا hasMore برابر false شود. شکل سطح کنترل، GET /api/v1/storage-zones/{id}/objects?prefix=photos/، همین ساختار را با اعتبارنامه حساب برمی‌گرداند.

حذف

# One object
curl -s -X DELETE "$AVAND/storage/my-assets/photos/111.jpg" -H "X-Bee-Access-Key: $ZONE_KEY"

# Everything under a prefix, recursively
curl -s -X DELETE "$AVAND/storage/my-assets/photos/" -H "X-Bee-Access-Key: $ZONE_KEY"

اسلش پایانی تمامِ قرارداد است. هر دو 204 برمی‌گردانند، پس یک اسلش اضافی بسیار بیش از آنچه می‌خواستید حذف می‌کند و پاسخ متفاوتی هم نمی‌دهد. حذف دائمی است. If-Match و If-Unmodified-Since حذف تک‌شیء را محافظت می‌کنند (412 وقتی شیء تغییر کرده باشد)؛ حذف پیشوندی آن‌ها را نادیده می‌گیرد.

۹. بارگذاری ازسرگیری‌پذیر

سطح بارگذاری به پروتکل tus 1.0.0 صحبت می‌کند (OPTIONS $AVAND/upload/sessions افزونه‌ها را فهرست می‌کند: creation، creation-with-upload، creation-defer-length، expiration، checksum، termination)، پس هر کلاینت tus کار می‌کند؛ نمونه‌ها با curl است. نشست باز کنید، قطعه‌ها را در آفستی که سرور گزارش می‌دهد PATCH کنید، و قطعه‌ای که به طول اعلام‌شده می‌رسد بارگذاری را نهایی می‌کند. قطع اتصال فقط قطعه جاری را از بین می‌برد. نشست‌ها ۲۴ ساعت پس از ساخت منقضی می‌شوند (Upload-Expires روی هر پاسخ). هر پاسخ Tus-Resumable: 1.0.0 دارد؛ درخواستی که نسخه دیگری بگوید با 412 و Tus-Version رد می‌شود. همه فراخوان‌ها اعتبارنامه حساب می‌گیرند.

# 0. Discover the protocol (no credential needed)
curl -s -i -X OPTIONS $AVAND/upload/sessions
# Tus-Version: 1.0.0, Tus-Extension: creation,creation-with-upload,creation-defer-length,expiration,checksum,termination
# Tus-Max-Size: <bytes>, Tus-Checksum-Algorithm: sha256

# 1. Open a session, tus style: Upload-Length plus base64 Upload-Metadata naming the target
#    (storageZoneId + path or filename, optional filetype and contentSha256;
#     for a video source: videoLibraryId + videoId)
ZONE_B64=$(printf '%s' "<storageZoneId>" | base64 -w0)
PATH_B64=$(printf '%s' "backups/big.zip" | base64 -w0)
TYPE_B64=$(printf '%s' "application/zip" | base64 -w0)
curl -s -i -X POST $AVAND/upload/sessions \
  -H "Authorization: Bearer $AVAND_TOKEN" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Length: 104857600" \
  -H "Upload-Metadata: storageZoneId $ZONE_B64,path $PATH_B64,filetype $TYPE_B64"
# 201 + Location: /upload/sessions/<sessionId>, Upload-Offset: 0, Upload-Expires: <HTTP date>
# Upload-Defer-Length: 1 instead of Upload-Length opens a session of unknown size (send
# Upload-Length once, on a later PATCH); a body of application/offset+octet-stream on the
# POST is taken as the first chunk.

# 1b. The JSON body Avand accepted before tus still works
curl -s -i -X POST $AVAND/upload/sessions \
  -H "Authorization: Bearer $AVAND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"storageZoneId":"<storageZoneId>","path":"backups/big.zip","totalLength":104857600,"contentType":"application/zip"}'

# 2. Send chunks at the current offset; Upload-Checksum has each one verified as it streams
curl -s -i -X PATCH $AVAND/upload/sessions/$SESSION \
  -H "Authorization: Bearer $AVAND_TOKEN" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Offset: 0" \
  -H "Upload-Checksum: sha256 $(openssl dgst -sha256 -binary chunk-0 | base64 -w0)" \
  -H "Content-Type: application/offset+octet-stream" \
  --data-binary @chunk-0
# 204 + the new Upload-Offset; a mismatched checksum is 460 and the offset does not move

# 3. After an interruption, ask where to resume
curl -s -I $AVAND/upload/sessions/$SESSION -H "Authorization: Bearer $AVAND_TOKEN" -H "Tus-Resumable: 1.0.0"
# Upload-Offset: <bytes received so far>, Upload-Length (or Upload-Defer-Length: 1), Upload-Metadata

# 4. The chunk that brings Upload-Offset to Upload-Length finalises the upload: the object (or
#    the video source) exists when that PATCH answers 204. DELETE cancels and discards the bytes.
#    POST .../complete is deprecated; it still answers 204 for a finished session.

۱۰. CDN: ناحیه‌های pull، حافظه نهان، پاک‌سازی، قواعد لبه، URLهای امضاشده

قرار دادن ناحیه pull جلوی ناحیه ذخیره‌سازی

curl -s -X POST $AVAND/api/v1/pull-zones \
  -H "Authorization: Bearer $AVAND_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-assets-cdn-1" \
  -d '{
    "name": "my-assets-cdn",
    "originType": "storageZone",
    "originStorageZoneId": "<storageZoneId>"
  }'

originType فیلد همراه لازم را تعیین می‌کند: http به originUrl نیاز دارد؛ storageZone و videoLibrary هر دو شناسه پشتیبان را در originStorageZoneId می‌فرستند. آماده‌سازی ناهمگام است؛ ناحیه را بپرسید تا state به ready برسد. سپس هر کسی بی‌سربرگ احراز هویت می‌تواند بگیرد:

curl -s "$AVAND/cdn/my-assets-cdn/photos/111.jpg" -o photo.jpg
# X-Bee-Cache: MISS | HIT | STALE | BYPASS | REVALIDATED
# Cache-Status: bee;fwd=uri-miss;fwd-status=200;ttl=3600;stored   (RFC 9211; a hit is `bee;hit;ttl=3599`)
# Server-Timing: cache;desc=MISS, origin;dur=41.2, edge;dur=43.0
# Proxy-Status: bee;error=connection_refused;details="..."       (only on a 502/503/504/508)
# ETag / Last-Modified: validators. If-None-Match or If-Modified-Since -> 304; If-Range guards a Range

سیاست حافظه نهان

curl -s -X PUT $AVAND/api/v1/pull-zones/$PZ/cache \
  -H "Authorization: Bearer $AVAND_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "edgeTtlSeconds": 3600,
    "browserTtlSeconds": 300,
    "respectOriginCacheControl": true,
    "queryStringMode": "ignoreAll",
    "queryStringParameters": [],
    "vary": "none",
    "cacheErrorResponses": false,
    "enableRequestCoalescing": true,
    "staleWhileRevalidateSeconds": 60,
    "staleIfErrorSeconds": 300
  }'

# The same settings, sparsely: PATCH applies only the members you send
curl -s -X PATCH $AVAND/api/v1/pull-zones/$PZ/cache \
  -H "Authorization: Bearer $AVAND_TOKEN" -H "Content-Type: application/merge-patch+json" \
  -d '{"edgeTtlSeconds": 7200}'

PATCH …/cache و PATCH …/security همان اعضای PUTها را می‌گیرند، همه اختیاری؛ آرایه خالی فهرست را پاک می‌کند و 0 محدودیت نرخ را برمی‌دارد. queryStringMode یکی از includeAll، ignoreAll یا includeListed است (با queryStringParameters برای نام بردن فهرست). vary رشته‌ای جداشده با ویرگول از ابعاد است ("cookie, acceptEncoding" یا "none"). acceptEncoding برای سازگاری پذیرفته می‌شود و کاری نمی‌کند: Avand هنگام خروج فشرده می‌کند، پس حافظه نهان هرگز بر اساس رمزگذاری تقسیم نمی‌شود. browserTtlSeconds همان چیزی است که به حافظه نهان خودِ کلاینت گفته می‌شود: هر پاسخ قابل‌کش Cache-Control: public, max-age=<browserTtlSeconds> دارد (به‌علاوه immutable اگر مبدأ گفته باشد). با روشن بودن respectOriginCacheControl، به‌جای آن private، no-cache یا no-store مبدأ منتقل می‌شود؛ درخواست ردشده یا خطایی که لبه کش نکرده همیشه no-store است.

سه فیلد آخر اختیاری و افزودنی‌اند. staleWhileRevalidateSeconds (RFC 5861) می‌گوید تا چند ثانیه پس از TTL لبه، ورودی منقضی همچنان بی‌درنگ ارائه می‌شود (X-Bee-Cache: STALE) در حالی که نسخه تازه در پس‌زمینه گرفته می‌شود؛ staleIfErrorSeconds می‌گوید تا چند ثانیه هنگام دسترس‌ناپذیری یا پاسخ 5xx مبدأ ارائه می‌شود. بعد از هر دو پنجره، لبه با اعتبارسنج‌های خودش در همان درخواست اعتبارسنجی دوباره می‌کند و بدنه بی‌تغییر فقط یک 304 هزینه دارد (X-Bee-Cache: REVALIDATED). enableRequestCoalescing رگباری از missها روی یک کلید را به یک واکشی از مبدأ تبدیل می‌کند؛ بقیه کمی منتظر می‌مانند و Cache-Status: bee;hit;…;collapsed گزارش می‌دهند.

Vary مبدأ. با روشن بودن respectOriginCacheControl، سربرگ Vary مبدأ کش لبه را به‌ازای مقدار Accept، Accept-Language و Origin تقسیم می‌کند و پاسخ همان Vary را برای کلاینت تکرار می‌کند. Accept-Encoding نادیده گرفته می‌شود (لبه هنگام خروج فشرده می‌کند). Vary: * یا هر سربرگ دیگری که لبه نتواند بر اساسش کلید بسازد، پاسخ را به‌جای کش نادرست، غیرقابل‌کش می‌کند.

پاک‌سازی

# One URL, a prefix, or the whole zone
curl -s -X POST $AVAND/api/v1/pull-zones/$PZ/purge \
  -H "Authorization: Bearer $AVAND_TOKEN" -H "Content-Type: application/json" \
  -d '{"scope":"prefix","target":"photos/"}'

# Everything the origin tagged (Cache-Tag / CDN-Tag / Cache-Groups) with one surrogate key
curl -s -X POST $AVAND/api/v1/pull-zones/$PZ/purge \
  -H "Authorization: Bearer $AVAND_TOKEN" -H "Content-Type: application/json" \
  -d '{"scope":"tag","target":"product-42"}'

بودجه‌ها به‌ازای هر ناحیه‌اند: پاک‌سازی دقیق url ۱۲۰ انفجاری و ۳۰۰ در دقیقه، پاک‌سازی prefix/tag/zone ۲۰ انفجاری و ۳۰ در دقیقه؛ مازاد یک 429 با Retry-After و RateLimit-Policy: "bee-purge-broad";q=30;w=60 است.

به bee:purge نیاز دارد. پاک‌سازی ناهمگام است و در نسخه‌های تکراری منتشر می‌شود؛ لبه‌ها ممکن است کمی نسخه قدیمی را بدهند.

نام‌های میزبان سفارشی

هر ناحیه با یک نام میزبان سیستمی زیر دامنه تحویل Avand متولد می‌شود تا بی‌درنگ سرویس بدهد. نام خودتان را این‌گونه بیفزایید:

curl -s -X POST $AVAND/api/v1/pull-zones/$PZ/hostnames \
  -H "Authorization: Bearer $AVAND_TOKEN" -H "Content-Type: application/json" \
  -d '{"hostname":"cdn.example.com"}'

هر نام میزبان پرچم forceHttps خودش را دارد (برای نام تازه روشن است): درخواست HTTP ساده روی آن، وقتی استقرار بتواند روی HTTPS پاسخ دهد، با 308 هدایت می‌شود، مستقل از پرچم خود ناحیه. با PATCH …/hostnames/cdn.example.com و بدنه {"forceHttps": false} خاموشش کنید؛ مقادیر فعلی در hostnameSettings ناحیه خوانده می‌شود.

گرفتن گواهی برای آن. وقتی cdn.example.com به Avand اشاره کند، یک کلاینت ACME روی مبدأ شما (certbot، acme.sh، Caddy) همچنان می‌تواند اعتبارسنجی HTTP-01 را برای آن نام بگذراند: /.well-known/acme-challenge/<token> روی هر ناحیه pull بی‌کم‌وکاست به مبدأ سپرده می‌شود و از حافظه نهان، قواعد لبه، سیاست دسترسی و URLهای امضاشده رد می‌شود. ناحیه‌هایی که مبدأشان ناحیه ذخیره‌سازی یا کتابخانه ویدئوست سروری برای پرسیدن ندارند و آنجا 404 می‌دهند؛ برای آن نام‌ها از DNS-01 استفاده کنید.

قواعد لبه

قواعد برای هر درخواست به ترتیب اجرا می‌شوند؛ مسدودسازی یا تغییر مسیر ارزیابی را پایان می‌دهد. کنش‌ها: forceHttps، redirect، block، setRequestHeader، setResponseHeader، overrideCacheTime، overrideOrigin، bypassCache، disableTokenAuthentication، enableTokenAuthentication. راه‌اندازها روی url، requestHeader، responseHeader، fileExtension، countryCode، remoteIp، queryString، httpMethod یا hostname منطبق می‌شوند.

# Block hotlinking of zip files: create (edgeRuleId: null) or replace (edgeRuleId set)
curl -s -X PUT $AVAND/api/v1/pull-zones/$PZ/edge-rules \
  -H "Authorization: Bearer $AVAND_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "edgeRuleId": null,
    "description": "No zip downloads",
    "actionKind": "block",
    "actionParameter1": null, "actionParameter2": null, "actionParameter3": null,
    "triggerMatchMode": "all",
    "triggers": [
      { "kind": "fileExtension", "matchMode": "any", "patterns": ["zip"], "parameter": null }
    ]
  }'

با PUT .../edge-rules/order بازچینی کنید، با PATCH .../edge-rules/{id} ({"isEnabled":false}) خاموش و روشن کنید، با DELETE بردارید.

کنش‌ها روی سیم چه می‌کنند: setRequestHeader به مبدأ می‌رسد، setResponseHeader بعد از همه سربرگ‌هایی که خودِ لبه می‌گذارد نوشته می‌شود، و هر دو سربرگ‌های hop-by-hop و framing، Host و CDN-Loop، Via، Forwarded و X-Forwarded-* خودِ لبه را رد می‌کنند (هنگام ذخیره قاعده 400). forceDownload با Content-Disposition: attachment (RFC 6266/8187) پاسخ می‌دهد و نام فایل را از actionParameter1 یا آخرین بخش مسیر می‌گیرد. redirect یکی از 301، 302، 307 یا 308 را می‌پذیرد. forceHttps با 308 به همان URL روی HTTPS پاسخ می‌دهد؛ پرچم امنیتی forceHttps خودِ ناحیه فقط وقتی همین کار را می‌کند که استقرار بتواند HTTPS بدهد (نقطه پایانی TLS، AvandHost:EnforceHttps یا پراکسی مورداعتماد تنظیم شده باشد)، پس استقرار HTTP ساده هرگز در حلقه تغییر مسیر نمی‌افتد. قاعده‌ای با راه‌انداز responseHeader بعد از پاسخ مبدأ (یا کش) اجرا می‌شود و فقط می‌تواند سربرگ پاسخ بگذارد، زمان کش را بازنویسی کند، کش را دور بزند یا دانلود را اجباری کند. matchMode هر راه‌انداز الگوهای خودش را ترکیب می‌کند.

URLهای امضاشده

روی ناحیه توکن را لازم کنید (PUT .../security با "signedUrlsRequired": true)، سپس URLها را سمت سرور بسازید:

curl -s -X POST $AVAND/api/v1/signed-urls \
  -H "Authorization: Bearer $AVAND_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "pullZoneId": "<pullZoneId>",
    "path": "photos/111.jpg",
    "expiresAt": "2026-08-14T00:00:00+00:00",
    "isPrefixToken": false,
    "clientIpAddress": null,
    "allowedCountryCodes": [],
    "blockedCountryCodes": [],
    "maxBytesPerSecond": null
  }'
# → { "url": "https://<zone-hostname>/photos/111.jpg?expires=1786665600&token=...", "expiresAt": "..." }

اگر ناحیه نام میزبان سفارشی داشته باشد URL روی همان ساخته می‌شود، وگرنه روی مبدأ عمومی تحویلِ استقرار (PUBLIC_AVAND_ORIGIN) به شکل {origin}/cdn/<zoneName>/<path>، همان شکل هر URL تحویل دیگر، پس بدون DNS برای نام سیستمی کار می‌کند. maxBytesPerSecond بر حسب بایت است (1000 یعنی ۱ کیلوبایت بر ثانیه). توکن مسیر را امضا می‌کند (یا با isPrefixToken پیشوند را، که پخش HLS به آن نیاز دارد)، پس مسیر باید همان‌طور که برگشته به کار رود. از رشته پرس‌وجو فقط expires و پارامترهای محدودیتی که همراه دارد (ca، cb، rt، و برای URL یک شیء bi) امضا می‌شوند، پس تغییر یکی از آن‌ها URL را باطل می‌کند اما افزودن یک پارامتر نامربوط نه؛ پارامترهای خودِ URL امضاشده (token، expires، ca، cb، rt) را می‌توان زیر یک توکن پیشوندی روی مسیرهای هم‌سطح رونوشت کرد. کلید امضای ناحیه را با POST .../signing-key/rotate بچرخانید؛ URLهای موجود بی‌درنگ می‌میرند.

برای سپردن یک فایل خصوصی به کسی که حساب ندارد، برای چند روز به‌جای چند دقیقه، به‌جای آن یک پیوند اشتراک بسازید: POST /api/v1/files/{zoneId}/links یک بار توکنی برمی‌گرداند، و هر کس آن را داشته باشد تا انقضای پیوند (به‌طور پیش‌فرض حداکثر ۳۰ روز) یا ابطالش، از POST /api/v1/links/{token}/download-url یک URL دانلود تازه ۱۵ دقیقه‌ای می‌گیرد. به API_GUIDE.md بخش ۲ب نگاه کنید.

توکن‌ها به شکل HS256-<base64url> هستند؛ توکن پیشوندی token_path=<prefix> هم دارد که لبه برای هر مسیر زیر آن می‌پذیرد. توکن پیشوندی یک پوشه را پوشش می‌دهد: مسیری که به / ختم شود همان پوشه را (photos/2026/)، و هر مسیر دیگر پوشه والدش را ({videoId}/playlist.m3u8 پوشه {videoId}/ را)؛ مسیری که پوشه‌ای از خودش ندارد (یک نام تنها در سطح بالا مثل u123، ریشه، . یا x/..) کل ناحیه را می‌پوشاند و با 400 bee.signed_url_prefix_too_broad رد می‌شود. لبه همان پارامترها را با نام‌های Bunny (bcdn_token، token_countries، token_countries_blocked، limit بر حسب kB/s، token_ignore_params) و شکل پوشه‌ای /bcdn_token=…&expires=…&token_path=…/path هم می‌پذیرد، پس پخش‌کننده‌ای که برای آن طرح نوشته شده تغییری نمی‌خواهد. توکن بسته به IP کل /64 نسخه ۶ کلاینت را پوشش می‌دهد. maxBytesPerSecond (rt) اعمال می‌شود: بدنه با همان نرخ آهسته ارسال می‌شود.

قواعد ارجاع‌دهنده، IP و کشور

PUT /api/v1/pull-zones/{id}/security کل پیکربندی امنیتی را جایگزین می‌کند: signedUrlsRequired، forceHttps، blockRootPathAccess، allowedReferrers، blockedReferrers، blockedIpAddresses، allowedCountryCodes، blockedCountryCodes، و فیلدهای اختیاری allowedIpAddresses، rateLimitRequestsPerSecondPerIp، rateLimitBurstSize و rateLimitBytesPerSecondPerConnection. ورودی‌های IP یا نشانی تکی‌اند یا شبکه CIDR (203.0.113.0/24، 2001:db8::/32)؛ فهرست مجاز ناخالی بقیه را رد می‌کند و ورودی مسدود برنده است. بودجه درخواست به‌ازای هر نشانی کلاینت است و با 429، Retry-After و RateLimit-Policy: "bee-zone";q=<rate>;w=1 پاسخ می‌دهد؛ نرخ بایت هر بدنه پاسخ را آهسته می‌کند. همه این‌ها در لبه اعمال می‌شوند؛ درخواست مسدودشده یک 403 خالی است.

۱۱. تصویر و ویدئو

تبدیل تصویر

تبدیل‌ها فقط روی سطح /img/ رخ می‌دهند. نشانی تحویل /cdn/ تصویر را بگیرید، از Avand بخواهید نشانی تبدیل را بسازد، و آنچه برمی‌گردد به کار ببرید:

curl -s -X POST $AVAND/api/v1/images/url \
  -H "Authorization: Bearer $AVAND_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "'"$AVAND"'/cdn/my-assets-cdn/photos/111.jpg",
    "transformation": { "width": 300, "height": 200, "fit": "contain" }
  }'
# → "http://localhost:20331/img/my-assets-cdn/photos/111.jpg?width=300&height=200&fit=contain"

سازنده ترتیب پارامترها را استاندارد می‌کند، پس تبدیل‌های یکسان یک ورودی حافظه نهان دارند؛ آن را به ساخت دستی نشانی ترجیح دهید. POST /api/v1/images/srcset همین کار را در چند عرض می‌کند و مواردی آماده برای <img srcset> برمی‌گرداند.

پارامترمقادیریادداشت
width، heightپیکسلهرگز بزرگ‌نمایی نمی‌کند مگر با upscale=1
fitcontain، cover، fillپیش‌فرض cover
aspect_ratioمثلاً 16:9ارتفاع از روی عرض حساب می‌شود (اگر width نباشد، عرض منبع)؛ height نادیده گرفته می‌شود
cropw,hgravity (نام دیگر: crop_gravity) ناحیه را برمی‌گزیند: center، north، southEast، …
crop_offsetx,yگوشه بالا-چپ صریح، فقط همراه crop خوانده می‌شود؛ جایگزین gravity
formatjpeg، png، webp، avif، gifاگر حذف کنید از روی Accept انتخاب می‌شود: AVIF، بعد WebP، وگرنه قالب منبع (منبع GIF همان GIF می‌ماند)
quality۱ تا ۱۰۰
brightness، contrast، saturation، hue، gammaعددتنظیم رنگ
blur، sharpenعدد
sepia، flip، flop1flip عمودی، flop افقی
tintرنگ hex، مثل ff8800روشنایی ضرب در رنگ: تک‌رنگ با همان ته‌رنگ
rotate90، 180، 270درجه، ساعت‌گرد

پاسخ X-Bee-Image-Size: <width>x<height> را همراه دارد.

اگر format را حذف کنید، Avand آن را از سربرگ Accept درخواست انتخاب می‌کند (RFC 9110 §12.5.1): کلاینتی که image/avif را فهرست کند AVIF می‌گیرد، کلاینتی که image/webp را فهرست کند WebP می‌گیرد و بقیه قالب خود منبع را. این پاسخ‌ها Vary: Accept دارند. الگوهای عام مثل image/* قالب مدرنی انتخاب نمی‌کنند و منبع GIF هرگز تنها با مذاکره تبدیل نمی‌شود. format صریح وقتی به کار می‌رود که این میزبان بتواند آن را بسازد و مجازش بداند (AvandImaging:AllowedOutputFormats)؛ وگرنه قالب خود منبع به کار می‌رود. در هر دو حالت به Accept نگاه نمی‌شود.

ناحیه‌ای که در سیاست کش آن imageClientHints روشن باشد، client hint‌های RFC 8942 را هم می‌خواند: Sec-CH-DPR عرض درخواستی را در نسبت پیکسل دستگاه (۱ تا ۴) ضرب می‌کند و Sec-CH-Width وقتی URL عرضی ندارد آن را تأمین می‌کند. چنین پاسخ‌هایی hint‌ها را با Accept-CH اعلام می‌کنند و موارد استفاده‌شده را در Vary می‌آورند. این گزینه به‌طور پیش‌فرض خاموش است، چون پاسخ‌های مبتنی بر hint بر سربرگ‌هایی تنوع دارند که بیشتر کش‌های میانی نادیده می‌گیرند.

نسخه تبدیل‌شده در لبه کش می‌شود و از آن پس از همان‌جا ارائه می‌شود؛ حداکثر به مدت AvandImaging:VariantCacheTtl (پیش‌فرض ۷ روز) و هرگز بیش از تازگی خود منبع. پاک‌سازی منبع (با URL، پیشوند، tag یا ناحیه) نسخه‌های آن را هم حذف می‌کند. پاسخ همان سربرگ‌های /cdn را دارد: ETag قوی، Last-Modified و Cache-Control منبع، Cache-Status (در نخستین درخواست bee;fwd=uri-miss;fwd-status=200;ttl=N;stored و پس از آن bee;hit;ttl=N) و پاسخ 304 برای If-None-Match منطبق. HEAD فقط سربرگ‌ها را برمی‌گرداند؛ Range نادیده گرفته می‌شود چون نسخه تبدیل‌شده همیشه کامل تحویل می‌شود.

ذخیره یک فایل تبدیل‌شده

URL تبدیل در هر درخواست کارش را انجام می‌دهد. وقتی یک رندر را برای همیشه می‌خواهید، آن را از صفحه تصاویر (یا POST /api/v1/images/saved) ذخیره کنید: Avand یک بار رندر می‌کند و نتیجه را به‌عنوان یک شیء معمولی، transforms/{slug}.{ext}، در ناحیه ذخیره‌سازیِ مبدأ ناحیه pull می‌نویسد که در /cdn/{zone}/transforms/{slug}.{ext} بدون پارامتر ارائه می‌شود.

  • نامی به آن بدهید؛ slug (نام فایل) از آن ساخته می‌شود مگر خودتان انتخاب کنید. slug از حروف کوچک لاتین، ارقام و خط تیره تکی تشکیل می‌شود و در هر ناحیه pull یکتاست. اگر slug از قبل گرفته شده باشد، پس از نوشتن واژه replace (با حروف لاتین) می‌توانید همان فایل را جایگزین کنید.
  • فقط ناحیه pullای که جلوی ناحیه ذخیره‌سازی است می‌تواند چنین فایلی نگه دارد؛ ناحیه با مبدأ HTTP جایی برای فایل ندارد.
  • فایل در مرورگر فایل ناحیه زیر transforms/ دیده می‌شود و در سهمیه حساب می‌شود. آن را از صفحه تصاویر یا از مرورگر حذف کنید؛ در هر دو حالت فایل و رکوردش می‌روند.
  • اگر URL مبدأیی که از آن ذخیره کردید امضاشده بود، فایل ذخیره‌شده انقضا، فهرست کشورها و محدودیت نرخ آن امضا را به ارث می‌برد: صفحه تا پایان انقضای اصلی یک URL امضاشده با همان شرایط پیشنهاد می‌دهد و در هر زمان می‌توان یکی تازه ساخت.

ویدئو

# A library needs a storage zone to hold sources and renditions
curl -s -X POST $AVAND/api/v1/video-libraries \
  -H "Authorization: Bearer $AVAND_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "tutorials",
    "storageZoneId": "<storageZoneId>",
    "encodingTier": "standard",
    "encodingLadder": ["p360", "p720", "p1080"]
  }'

curl -s -X POST $AVAND/api/v1/video-libraries/$LIB/videos \
  -H "Authorization: Bearer $AVAND_TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Getting started","videoCollectionId":null}'
# → {"id":"<videoId>"}

# encodingTier: standard = H.264 (plays everywhere); premium = H.265/HEVC, ~1/3 fewer bytes, needs HEVC-capable players
# Upload the source: raw body in one request for small files
curl -s -X PUT $AVAND/api/v1/video-libraries/$LIB/videos/$VID/source \
  -H "Authorization: Bearer $AVAND_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H "X-Bee-File-Name: intro.mp4" \
  --data-binary @intro.mp4
# 202 Accepted: encoding runs in the background

فایل‌های بزرگ از نشست بارگذاری (بخش ۹) با videoLibraryId + videoId استفاده می‌کنند، یا بگذارید Avand آن را با POST .../videos/{id}/fetch و {"sourceUrl":"https://..."} بکشد؛ Avand منبع را درون همان درخواست دانلود می‌کند، پس اگر منبع در دسترس نباشد یا پاسخی جز 2xx بدهد خودِ درخواست شکست می‌خورد. از راه میزبان عمومی مجموعه، Cloudflare بدنه بزرگ‌تر از حدود ۱۰۰ MB را رد می‌کند و پس از حدود ۱۰۰ ثانیه دیگر منتظر نمی‌ماند: PUT خامِ بزرگ‌تر را با نشست بارگذاری بفرستید و fetch طولانی را درون شبکه صدا بزنید. GET .../videos/{id} را بپرسید: state مسیر created → uploading → queued → processing → ready | failed را می‌رود، encodeProgressPercent پیش می‌رود، و در حالت آماده playbackPath تنظیم و isPlayable برابر true می‌شود.

پخش و دانلود فایل کامل. دو تنظیم کتابخانه (PATCH .../video-libraries/{id}): enableMp4Fallback رمزگذار را وادار می‌کند برای هر پله یک MP4 پیش‌رونده faststart هم بنویسد که در {videoId}/play_{height}p.mp4 ارائه می‌شود (به‌صورت mp4Path روی هر rendition فهرست می‌شود و به‌عنوان downloadPath در embed.json به کار می‌رود)، برای دکمه دانلود و پخش‌کننده‌های بدون HLS؛ exposeOriginal منبع بارگذاری‌شده را در {videoId}/original ارائه می‌کند (به‌طور پیش‌فرض خاموش، تا فعال نشود 404). enableMp4Fallback روی ویدئوهایی اثر می‌گذارد که پس از تغییر کدگذاری شوند (برای ویدئوهای قبلی POST .../reencode)؛ exposeOriginal در هر درخواست خوانده می‌شود، پس بی‌درنگ اثر می‌کند.

تله‌متری پخش‌کننده (CMCD/CMSD). پخش‌کننده‌ای که CTA-5004 Common Media Client Data را (hls.js و dash.js با CMCD فعال) به‌صورت پارامتر CMCD در رشته پرس‌وجو یا سربرگ‌های CMCD-Request/-Object/-Status/-Session می‌فرستد فهمیده می‌شود: این پارامتر روی حافظه نهان اثری ندارد و d (مدت شیء) هر درخواست قطعه ویدئویی (ot=v یا ot=av) به watchTimeSeconds در آمار ویدئو تبدیل می‌شود؛ پخش‌کننده‌های بدون CMCD زمان تماشایی ثبت نمی‌کنند. هر پاسخ rendition و صدا CMSD-Static (CTA-5006) دارد که نوع شیء، قالب و نرخ بیت را می‌گوید.

از مرورگر. سرور شما اعتبارنامه را نگه می‌دارد و برای همان یک ویدئو یک مجوز بارگذاری (grant) می‌سازد؛ مرورگر به‌جای توکن، سربرگ‌های برگشتی را می‌فرستد، روی PUT …/source یا روی هر فراخوان /upload/sessions برای آن ویدئو (کلاینت‌های tus: به‌عنوان سربرگ اضافه بدهید). مجوز به هیچ چیز دیگری نمی‌رسد و به کلید امضای خودِ کتابخانه گره خورده است.

curl -s -X POST $AVAND/api/v1/video-libraries/$LIB/videos/$VID/upload-grant \
  -H "Authorization: Bearer $AVAND_TOKEN" -H "Content-Type: application/json" \
  -d '{"lifetimeSeconds": 3600}'
# {"signature":"…","expiresAt":"…","headers":{"X-Bee-Upload-Signature":"…","X-Bee-Upload-Expire":"<unix>",
#   "X-Bee-Upload-Library":"<libraryId>","X-Bee-Upload-Video":"<videoId>"}}
# The bunny.net names AuthorizationSignature / AuthorizationExpire / LibraryId / VideoId are aliases.

فایل‌های فقط صوتی. کتابخانه فایلی را هم که جریان ویدیویی ندارد می‌پذیرد: MP3، WAV، FLAC، Ogg (Vorbis یا Opus)، AAC خام، M4A یا هر کانتینر پذیرفته‌شده‌ای که فقط صدا دارد. تصویری که به‌عنوان جلد در فایل جاسازی شده باشد آن را ویدیو نمی‌کند. این فایل از همان endpointها و همان وضعیت‌ها می‌گذرد و به‌صورت موردی با mediaKind: "audio" بیرون می‌آید: بدون width، height، renditions و storyboard، و با نرخ‌های بیت در audioVariants. خروجی AAC-LC با حداکثر ۶۴، ۱۲۸ و ۱۹۲ کیلوبیت بر ثانیه روی همان CMAF HLS است (برای منبع مونو نصف این مقدار) و هرگز از منبع بالاتر نمی‌رود، بنابراین playbackPath، پخش امضاشده و خصوصی، زیرنویس و embed.json مانند ویدیو کار می‌کنند. پوستر همان جلد فایل است، اگر داشته باشد. با روشن بودن MP4 fallback کتابخانه، بالاترین نرخ بیت به‌صورت یک فایل کامل در {videoId}/play_audio.m4a هم در دسترس است؛ نسخه اصلی برای منبع بدون افت از گزینه «expose original» در دسترس می‌ماند.

چه چیزی پذیرفته می‌شود. کانتینرهای MP4/M4V، MOV، MKV، WebM، AVI، FLV، WMV/ASF، MPEG-TS، MPEG-PS/VOB؛ ویدئوی H.264، H.265/HEVC، VP8، VP9، AV1، MPEG-2، ProRes (و نیز MPEG-4 Part 2، MJPEG، WMV، VC-1 و Theora وقتی درون کانتینر پذیرفته‌شده بیایند)؛ صدای AAC، MP3، LPCM، FLAC، ALAC، WMA، Opus، Vorbis، AC-3. حداکثر ۷۲ ساعت، 2160p و ۶۰ فریم بر ثانیه (در سرور قابل تنظیم). این بررسی همان لحظه‌ای که منبع ماندگار می‌شود و در هر مسیری اجرا می‌شود: منبع ردشده با 422 و نوع مشکل video-source-unsupported و دلیلش پاسخ می‌گیرد، بایت‌ها دور ریخته می‌شوند و ویدئو با failureReason تنظیم‌شده به created برمی‌گردد تا فایل اصلاح‌شده روی همان ویدئو بارگذاری شود. روی میزبانی بدون ffprobe این بررسی انجام نمی‌شود.

پخش از راه ناحیه pullای می‌گذرد که مبدأش کتابخانه است ("originType": "videoLibrary"، "originStorageZoneId": "<videoLibraryId>"). playbackPath ({videoId}/playlist.m3u8) نسبت به ریشه آن ناحیه است و یک master استاندارد HLS است، با زیرنویس‌ها به صورت گروه subtitle، {videoId}/thumbnail.jpg، {videoId}/storyboard.vtt برای پیش‌نمایش نوار پیمایش و {videoId}/embed.json برای فراداده پخش‌کننده. پاسخ‌های تحویل ویدئو همیشه Access-Control-Allow-Origin: * دارند، به preflight OPTIONS مرورگر پاسخ می‌دهند (204 با سربرگ‌های مجوز و Access-Control-Max-Age: 86400) و سربرگ‌های اعتبارسنج، بازه، کش و زمان‌بندی را برای اسکریپت آشکار می‌کنند. ساده‌ترین راه پخش، پخش‌کننده جاسازی‌شدنی خودِ آوند است: کد جاسازی را از صفحه ویدئو رونوشت کنید.

زیرنویس: PUT .../videos/{id}/captions/{lang} با {"label","format":"webVtt","content"} ({lang} برچسب BCP 47 خوش‌ساخت مانند en یا pt-BR است؛ غیر از آن 422 می‌گیرد) ترک آن زبان را جایگزین می‌کند؛ DELETE آن را برمی‌دارد. POST .../reencode کدگذاری را از منبع ذخیره‌شده دوباره اجرا می‌کند. ویدئویی که منتشر شده، نسخه فعلی‌اش را تا آماده (ready) شدن کدگذاری تازه پخش می‌کند (isPlayable آن همچنان true می‌ماند) و سپس پخش، با زیرنویس‌ها، به نسخه تازه می‌رود؛ ویدئویی که هرگز منتشر نشده تا پایان نخستین کدگذاری‌اش پخش‌شدنی نیست. اگر کدگذاری دوباره شکست بخورد، نسخه فعلی همچنان پخش می‌شود و دلیل در failureReason ثبت می‌شود. playlistها و embed.json با Cache-Control: no-cache سرو می‌شوند، پس پخش‌کننده‌ای که پس از جابه‌جایی شروع کند playlistهای تازه را می‌گیرد. قطعه‌ها TTL مرورگرِ zone را نگه می‌دارند، پس مرورگری که در این بازه پیش از جابه‌جایی ویدئو را پخش کرده ممکن است تا همین مدت قطعه‌های کهنه را از حافظه نهان بخواند؛ پاک کردن حافظه نهان یا گذشتن این TTL پخش را درست می‌کند. بیننده‌ای که هنگام جابه‌جایی در میانه ویدئو است شاید لازم باشد صفحه را دوباره بارگذاری کند.

۱۲. مدیریت، گزارش ممیزی و آمار

مدیران (bee:admin) حساب‌ها را با GET /api/v1/users فهرست می‌کنند. استحقاق‌ها و قفل کردن در مرکز حساب‌اند: PUT /api/v1/users/{id}/roles و POST /api/v1/users/{id}/lock / unlock پاسخ 409 managed_in_idp می‌دهند، و قفل کردن یک شخص یعنی غیرفعال کردن حسابش در آنجا.

گزارش ممیزی فقط‌افزودنی است و ثبت می‌کند چه کسی، چه کاری، کِی و از کجا کرده:

curl -s "$AVAND/api/v1/admin/audit-log?limit=50" -H "Authorization: Bearer $AVAND_TOKEN"

هر ساخت، چرخش و ابطال کلید API (apiKey.*، با نام، شناسه و مجوزهای کلید)، هر صدور، چرخش و ابطال کلید ناحیه (zoneKey.*، با ناحیه و دامنه) و پاک‌سازی‌های مدیریتی را دارد. پس از گمان به نشت، نخستین جایی است که باید نگاه کرد. ورودی‌ها به‌طور پیش‌فرض ۴۰۰ روز نگه داشته می‌شوند (AvandAnalytics:AuditLogRetentionDays) و سپس پاک می‌شوند.

فضای ذخیره‌سازی سازمان

اگر سازمان شما فضای ذخیره‌سازی خریده باشد، فضای شخصی همه اعضایش از همین یک مجموع برداشته می‌شود. مالکان و مدیران سازمان آن را با /api/v1/tenant-storage مدیریت می‌کنند (با ورود به‌عنوان یک شخص؛ کلید API رد می‌شود):

# The organizations you administer, with what each has used (empty if you administer none)
curl -s $AVAND/api/v1/tenant-storage -H "Authorization: Bearer $AVAND_TOKEN"

# Who is charged to "acme", what each stores and their share
curl -s "$AVAND/api/v1/tenant-storage/acme/members?limit=50" -H "Authorization: Bearer $AVAND_TOKEN"

# Give a member 5 GiB; send {"shareBytes": null} to remove the share
curl -s -X PUT $AVAND/api/v1/tenant-storage/acme/members/$USER_ID/share \
  -H "Authorization: Bearer $AVAND_TOKEN" -H "Content-Type: application/json" \
  -d '{"shareBytes": 5368709120}'
  • جمع سهم‌ها می‌تواند از کل فضای خریداری‌شده بیشتر باشد؛ سقف همچنان همان کل فضاست، پس وقتی همه با هم آن را پر کنند آپلودهای آخر رد می‌شوند.
  • سهم را نمی‌توان کمتر از مصرف فعلی عضو گذاشت (409 bee.tenant_storage_share_below_usage). کم کردن سهم یا کل فضا چیزی را پاک نمی‌کند و فقط بایت‌های تازه را رد می‌کند.
  • سهم و سقفی که مدیر آوند روی حساب گذاشته هر دو اعمال می‌شوند و هر کدام کوچک‌تر باشد ملاک است.
  • سازمانی که شما مدیرش نیستید 404 bee.tenant_storage_not_found می‌دهد، دقیقاً مثل سازمانی که وجود ندارد.
  • در صفحه حساب، GET /api/v1/auth/me برای کسانی که از فضای یک سازمان برداشت می‌کنند فیلد organization را برمی‌گرداند: کل فضا و مصرف سازمان، سهم خودشان، و personalLimitBytes که بیشترین مقدار قابل ذخیره‌سازی‌شان در حال حاضر است.

حریم خصوصی: خروجی، حذف کامل، محل نگهداری داده

  • خروجی. شخصِ واردشده هر آنچه Avand درباره او دارد را با GET /api/v1/users/me/export دانلود می‌کند: نمایه، ناحیه‌ها با فهرست اشیا و فراداده کلیدها، ناحیه‌های pull، کتابخانه‌های ویدئو با ویدئوها و زیرنویس‌ها، فراداده کلیدهای API و وب‌هوک‌ها و ورودی‌های ممیزی که خودش نوشته. یک پیوست JSON است؛ هیچ رازی در آن نیست و با کلید API قابل دریافت نیست.
  • حذف کامل همان چرخه حذف حساب است: حذف حساب در مرکز حساب (یا POST /api/v1/users/{id}/deletion) یک دوره نگهداری ۳۰ روزه را آغاز می‌کند، که پس از آن مخزنش پاک می‌شود مگر یک توقیف قانونی (legal hold) نگهش دارد (API_GUIDE بخش ۱۴ › حذف حساب و توقیف قانونی). حذف فوری با POST /api/v1/users/{id}/erase پاسخ 409 account-deletion-lifecycle می‌دهد. گزارش ممیزی یک ورودی با مدیرِ عامل و شمارش‌ها نگه می‌دارد، نه شخص حذف‌شده را؛ ورودی‌هایی که خود حساب نوشته می‌مانند، چون گزارشی که عاملانش را فراموش کند گزارش نیست.
  • نشانی کلاینت پیش از نوشتن هر رکورد دسترسی یا ورودی ممیزی کوتاه می‌شود (IPv4 تا /24، IPv6 تا /48)؛ اپراتور می‌تواند آن را کاملاً حذف کند یا، با مبنای قانونی خودش، کامل نگه دارد (AvandAnalytics:IpAnonymization).
  • محل نگهداری. یک استقرار Avand همان‌جایی است که اپراتور اجرایش می‌کند: یک پایگاه داده، یک ذخیره‌گاه اشیا، یک منطقه. هیچ تکثیر بین‌منطقه‌ای داده شخصی وجود ندارد مگر اپراتور آن را بسازد؛ primaryRegion و replicationRegions ناحیه ذخیره‌سازی برچسبی است که اپراتور برای محل بایت‌ها وعده می‌دهد و Avand چیزی فراتر از آن برچسب اعمال نمی‌کند.

آمار:

# Delivery traffic, all zones or one; granularity is hourly, daily or monthly
curl -s "$AVAND/api/v1/statistics/delivery?from=2026-08-01T00:00:00Z&to=2026-08-13T00:00:00Z&granularity=daily&pullZoneId=$PZ" \
  -H "Authorization: Bearer $AVAND_TOKEN"

# Storage consumption and transfer for a zone. Every authenticated data-plane request is
# recorded: a download counts as egress, an upload as ingress, in the zone's daily bucket.
curl -s $AVAND/api/v1/storage-zones/$ZONE_ID/usage -H "Authorization: Bearer $AVAND_TOKEN"

# Per-video playback: views, watch time (from players that send CMCD) and bytes sent
curl -s "$AVAND/api/v1/video-libraries/$LIB/videos/$VID/statistics?from=...&to=..." \
  -H "Authorization: Bearer $AVAND_TOKEN"

۱۳. سر تا ته: بارگذاری یک فایل و گرفتن نشانی CDN آن، در Node و C#‎

مسیر: با توکن دسترسیِ مبادله‌شده از یک کلید صادرشده توسط IdP (بخش ۴)، ناحیه ذخیره‌سازی را پیدا کنید، فایلی را با کلید ناحیه‌اش روی سطح داده بارگذاری کنید، پوشه را فهرست کنید و نشانی عمومی را چاپ کنید. هر دو نمونه AVAND_TOKEN، AVAND_ZONE_KEY (یک کلید ناحیه readWrite که یک بار در آوند صادر شده، چون صدورش bee:admin می‌خواهد) و AVAND را در محیط، و ناحیه‌ای به نام my-assets با ناحیه pull به نام my-assets-cdn جلوی آن را فرض می‌کنند.

Node (بدون وابستگی)

// upload.mjs — node upload.mjs ./photo.jpg photos/photo.jpg
import { readFile } from "node:fs/promises";

const AVAND = process.env.AVAND ?? "http://localhost:20331";
const headers = { Authorization: `Bearer ${process.env.AVAND_TOKEN}` };
const zoneKey = process.env.AVAND_ZONE_KEY;
if (!zoneKey) throw new Error("Set AVAND_ZONE_KEY to a readWrite key of my-assets.");

async function api(path, init = {}) {
  const response = await fetch(`${AVAND}${path}`, { ...init, headers: { ...headers, ...init.headers } });
  if (!response.ok) {
    // Every control-plane failure is a problem document with a traceId worth logging.
    throw new Error(`${init.method ?? "GET"} ${path} → ${response.status}: ${await response.text()}`);
  }
  return response.status === 204 ? null : response.json();
}

const [file, objectPath] = process.argv.slice(2);

// 1. The zone, by name.
const zones = await api("/api/v1/storage-zones?limit=200");
const zone = zones.items.find((candidate) => candidate.name === "my-assets");
if (!zone) throw new Error("Create the my-assets zone in Avand first.");

// 2. The zone key for the data plane comes from AVAND_ZONE_KEY. Issuing one needs bee:admin,
//    which an IdP-issued key never carries, so it is issued once, in Avand (section 7).

// 3. Upload: raw bytes, PUT, on the data plane with the zone key.
const bytes = await readFile(file);
const upload = await fetch(`${AVAND}/storage/${zone.name}/${objectPath}`, {
  method: "PUT",
  headers: { "X-Bee-Access-Key": zoneKey, "Content-Type": "image/jpeg" },
  body: bytes,
});
if (upload.status !== 201) throw new Error(`upload → ${upload.status}`);

// 4. See it listed, with the same key.
const folder = objectPath.slice(0, objectPath.lastIndexOf("/") + 1);
const listing = await fetch(`${AVAND}/storage/${zone.name}/${folder}`, {
  headers: { "X-Bee-Access-Key": zoneKey },
}).then((response) => response.json());
console.log(listing.items.map((entry) => entry.path));

// 5. The public URL through the pull zone.
console.log(`${AVAND}/cdn/my-assets-cdn/${objectPath}`);

C#‎ (HttpClient، ‏.NET 8 به بالا)

// dotnet run -- ./photo.jpg photos/photo.jpg
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

string avand = Environment.GetEnvironmentVariable("AVAND") ?? "http://localhost:20331";
string token = Environment.GetEnvironmentVariable("AVAND_TOKEN")
    ?? throw new InvalidOperationException("Set AVAND_TOKEN.");
string zoneKey = Environment.GetEnvironmentVariable("AVAND_ZONE_KEY")
    ?? throw new InvalidOperationException("Set AVAND_ZONE_KEY to a readWrite key of my-assets.");
string file = args[0];
string objectPath = args[1];

using HttpClient control = new() { BaseAddress = new Uri(avand) };
control.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

// 1. The zone, by name.
JsonElement zones = await control.GetFromJsonAsync<JsonElement>("/api/v1/storage-zones?limit=200");
JsonElement zone = zones.GetProperty("items").EnumerateArray()
    .First(candidate => candidate.GetProperty("name").GetString() == "my-assets");
string zoneName = zone.GetProperty("name").GetString()!;

// 2. The zone key for the data plane comes from AVAND_ZONE_KEY. Issuing one needs bee:admin,
//    which an IdP-issued key never carries, so it is issued once, in Avand (section 7).

// 3. Upload: raw bytes, PUT, on the data plane with the zone key.
using HttpClient data = new() { BaseAddress = new Uri(avand) };
data.DefaultRequestHeaders.Add("X-Bee-Access-Key", zoneKey);

using ByteArrayContent body = new(await File.ReadAllBytesAsync(file));
body.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
HttpResponseMessage upload = await data.PutAsync($"/storage/{zoneName}/{objectPath}", body);
if (upload.StatusCode != System.Net.HttpStatusCode.Created)
{
    // The body is an RFC 9457 problem document; its traceId links to the server-side trace.
    throw new InvalidOperationException($"Upload failed: {(int)upload.StatusCode} {await upload.Content.ReadAsStringAsync()}");
}

// 4. See it listed, with the same key.
string folder = objectPath[..(objectPath.LastIndexOf('/') + 1)];
JsonElement listing = await data.GetFromJsonAsync<JsonElement>($"/storage/{zoneName}/{folder}");
foreach (JsonElement entry in listing.GetProperty("items").EnumerateArray())
{
    Console.WriteLine(entry.GetProperty("path").GetString());
}

// 5. The public URL through the pull zone.
Console.WriteLine($"{bee}/cdn/my-assets-cdn/{objectPath}");

۱۴. عیب‌یابی

وضعیتمعناچه کنید
400 + errorsخطای اعتبارسنجیفیلدهای نام‌برده را درست کنید؛ هر قلم code و field خودش را دارد. bee.api_key_expiry_required و bee.api_key_expiry_too_far روی expiresAt، و bee.system_account_name_invalid روی name همان را می‌گویند که نامشان می‌گوید؛ bee.api_key_zone_not_owned روی zoneIds همان ۴۰۰ هنگام ساختن کلید با ناحیه‌ای است که حساب صاحبش نیست.
401، چالش خالی Bearerاعتبارنامه‌ای نیستتوکن بفرستید: کلیدتان را مبادله کنید، یا وارد شوید
401، invalid_tokenتوکن دسترسی منقضی یا نامعتبر است؛ یا یک کلید avand_ak_ اشتباه، باطل یا منقضی است، یا حساب سیستمی‌اش غیرفعال استتوکن تازه بگیرید: کلید مدیر را دوباره مبادله کنید (مبادله ردشده، invalid_grant، یعنی کلید باطل، منقضی یا بی‌استفاده مانده یا شخصش غیرفعال است: در مرکز حساب کلید تازه بسازید)؛ نشست را برنامه وب تازه می‌کند. کلید سیستمیِ ردشده: کلید تازه بسازید (بخش ۴)
403اعتبارنامه معتبر است، مجوز نیست؛ access.no_app_access (هیچ استحقاقی برای آوند نیست، روی سطحی که شخص فقط‌فضای‌خود به آن نمی‌رسد)؛ access.own_space_read_only (بدون استحقاق: بارگذاری، اشتراک و پیوند خاموش‌اند، خواندن و حذف در فضای خودتان کار می‌کند)؛ access.api_keys_admin_only (کلید مدیری که شخصش مدیر نیست)؛ bee.api_key_zone_not_owned (کلید سیستمی محدود به ناحیه که روی چیزی جز ناحیه‌هایش به کار رفته)؛ یا کلید روی عملیاتی که فقط نشست می‌پذیردتکرار کمکی نمی‌کند. به کلید مجوز درست بدهید یا استحقاق را درخواست کنید؛ برای حساب‌های سیستمی، نمایه و خروجی از نشست استفاده کنید
404پیدا نشد؛ منبع حساب دیگری؛ یا روی /cdn هر محتوای ردشده یا غایبسطح تحویل هرگز خودش را توضیح نمی‌دهد
409نام تکراری، کلید هم‌توانی هنوز در اجرا، ۲۵ کلید فعال روی یک حساب سیستمی، چرخش کلید مرده، bee.system_account_name_taken، bee.system_account_disabled، یا managed_in_idp (نقش‌ها یا قفل)نام دیگری بگذارید، صبر کنید و همان کلید را تکرار کنید، نخست کلیدی را باطل کنید؛ کار managed_in_idp را در مرکز حساب انجام دهید
413 / 422 / 507بارگذاری خیلی بزرگ / ناهم‌خوانی checksum / فراتر از سهمیه حساببارگذاری ازسرگیری‌پذیر؛ دوباره بفرستید؛ از مدیر سهمیه بخواهید
502 / 504 / 508 در /cdnمبدأ اتصال را رد یا قطع کرد یا در آن شکست خورد، یا پاسخ غیرقابل‌تجزیه فرستاد / در مهلت پاسخ نداد / درخواست از قبل CDN-Loop: bee داشتنشانی مبدأ و سربرگ host ناحیه را بررسی کنید؛ 504 یعنی AvandEdge:OriginResponseTimeout را بالا ببرید یا مبدأ را سریع‌تر کنید؛ 508 یعنی چیزی جلوی مبدأ به Avand برمی‌گردد. 5xx خودِ مبدأ بدون تغییر عبور داده می‌شود
429محدودیت نرخبه اندازه Retry-After ثانیه صبر کنید؛ همه سطح‌ها آن را می‌فرستند. RateLimit-Policy می‌گوید کدام سهمیه پر شده ("bee-delivery";q=30000;w=1) و RateLimit می‌گوید کی بازنشانی می‌شود

هر خطای سطح کنترل و سطح ذخیره‌سازی یک سند مشکل با traceId است: هنگام گزارش مشکل آن را نقل کنید، پاسخ را به رد سمت سرور پیوند می‌دهد. خواندن WWW-Authenticate به کلاینت می‌گوید گرفتن توکن تازه می‌ارزد یا نه؛ کلید avand_ak_ِ ردشده هرگز ارزش تکرار ندارد: کلید تازه بسازید.

محدودیت نرخ. تحویل: ۳۰٬۰۰۰ درخواست در ثانیه برای هر نشانی کلاینت، انفجاری تا ۶۰٬۰۰۰. سطح کنترل: ۱۲٬۰۰۰ در دقیقه برای هر حساب. سطح داده ذخیره‌سازی: ۲٬۰۰۰ در ثانیه برای هر کلید ناحیه، انفجاری تا ۴٬۰۰۰، و ۱۰٬۰۰۰ در ثانیه برای هر ناحیه روی همه کلیدها، انفجاری تا ۲۰٬۰۰۰. پیوندهای اشتراک (/api/v1/links/**): ۶۰۰ در دقیقه برای هر نشانی. پاک‌سازی‌ها: برای هر ناحیه pull، ۳۰۰ در دقیقه (انفجاری تا ۱۲۰) برای URLهای دقیق و ۳۰ در دقیقه (انفجاری تا ۲۰) برای پاک‌سازی پیشوند، برچسب و کل ناحیه. این‌ها پیش‌فرض‌اند؛ اپراتور آن‌ها را زیر AvandRateLimits تنظیم می‌کند (به docs/host-configuration.md نگاه کنید)، و یک 429 همیشه می‌گوید کدام سهمیه و چقدر باید صبر کرد.

زمان انتظار و تلاش مجدد. GET، HEAD، PUT و DELETE را می‌توان بی‌خطر تکرار کرد. POST را فقط با Idempotency-Key تکرار کنید. از راه میزبان عمومی مجموعه، Cloudflare پس از حدود ۱۰۰ ثانیه دیگر منتظر پاسخ نمی‌ماند و بدنه بزرگ‌تر از حدود ۱۰۰ MB را رد می‌کند (nginx مبدأ پشت آن ۱ ساعت و ۴ GiB اجازه می‌دهد)، با یک صفحه خطا به جای problem document؛ درون شبکه فقط محدودیت‌های خودِ Avand اعمال می‌شوند.

۱۵. مرجع سریع

اعتبارنامهسربرگقالبکجا کار می‌کند
کلید API مدیر (فقط مدیران)در نقطه پایانی توکن IdP مبادله می‌شود؛ توکن در Authorization: Bearer <jwt> می‌رودshk_…؛ توکن مبادله‌شده JWT است، ۵ دقیقه/api/v1/**، /upload/sessions/**، جز حساب‌ها و کلیدهای سیستمی، نمایه و خروجی
توکن نشستAuthorization: Bearer <jwt>JWT از IdP مرکزی؛ عمرش را IdP تعیین می‌کندهمه‌چیز روی سطح کنترل
کلید سیستمی (فقط حساب‌های سیستمی)Authorization: Bearer <key> یا AccessKey: <key>avand_ak_<32 hex>_<43 chars>ناحیه‌های خودِ حساب از راه سطح کنترل، ذخیره‌سازی و بارگذاری (کلید محدود به ناحیه: فقط مسیرهای ناحیه‌آگاه)؛ /cdn و /img برای ناحیه‌ای که حسابش صاحبش است
کلید دسترسی ناحیهX-Bee-Access-Key: <key> یا AccessKey: <key>avand_zk_<32 hex>_<43 chars>فقط /storage/{zone}/**
URL امضاشدهرشته پرس‌وجو?token=…&expires=…/cdn/**، /img/** روی ناحیه‌هایی که لازمش دارند
پیوند اشتراکبخشی از مسیر۴۳ نویسه base64url/api/v1/links/{token}، ناشناس (API_GUIDE.md بخش ۲ب)
مجوزبه اعتبارنامه اجازه می‌دهد…
bee:readخواندن هر منبعی که حساب دارد
bee:writeساخت و تغییر ناحیه‌ها، ناحیه‌های pull، قواعد، کتابخانه‌ها، ویدئوها؛ خواندن، پاک‌سازی و ویدئو را در بر دارد
bee:purgeپاک‌سازی حافظه نهان CDN
bee:streamمدیریت کتابخانه‌ها و ویدئوها
bee:adminهمه‌چیز، از جمله کلیدهای ناحیه، کاربران و گزارش ممیزی؛ هرگز روی کلید صادرشده توسط IdP
فعل سطح دادهشکل مسیراثر
PUT/storage/{zone}/{path}بارگذاری بایت‌های خام (readWrite)
GET/storage/{zone}/{path}دریافت، با پشتیبانی Range
GET/storage/{zone}/{prefix}/ یا /storage/{zone}/فهرست یک سطح، JSON، صفحه‌بندی‌شده
DELETE/storage/{zone}/{path}حذف یک شیء (readWrite)
DELETE/storage/{zone}/{prefix}/حذف همه‌چیز زیر پیشوند (readWrite)