📄 راهنمای استفاده از API Purge

زمانی که نیاز دارید یک آدرس cache شده را ابطال (invalidate) کنید تا cache مورد نظر حذف شود و محتوای جدید از سرور origin مجددا دریافت شود، می‌توانید از API محصول CDN استفاده کنید.

API قدیمی Purge منسوخ شده است

آدرس https://purge.edge.sotoon.ir منسوخ شده و به‌زودی حذف می‌شود. اسکریپت‌ها و سرویس‌هایی که هنوز به این آدرس درخواست می‌فرستند باید به API نسخه ۲.۱ مهاجرت کنند. Purge از پنل اوشن تغییری نمی‌کند.

برای آشنایی کلی با API نسخه ۲.۱ به شروع استفاده از API محصول CDN و مستندات مرجع OpenAPI مراجعه کنید.

ارسال درخواست HTTP

یک درخواست با متد POST به آدرس زیر ارسال کنید:

https://api.sotoon.ir/delivery/v2.1/global/workspaces/<workspaceUUID>/purges

هدرهای زیر را برای این درخواست تنظیم کنید:

Authorization: Bearer <TOKEN>
Content-Type: application/json

برای دریافت <TOKEN> به بخش ساخت توکن کاربری مراجعه کنید. مقدار <workspaceUUID> هم در همان بخش توضیح داده شده است.

بدنه درخواست باید یک منبع Purge با فرمت JSON باشد:

{
  "apiVersion": "delivery/v2.1",
  "kind": "Purge",
  "metadata": {
    "name": "purge-scripts"
  },
  "spec": {
    "hostname": "<hostname-of-cdn>",
    "subdomains": ["list", "of", "extra", "subdomains"],
    "paths": ["list", "of", "paths"]
  }
}

در اینجا:

• مقدار metadata.name یک نام یکتا برای این درخواست Purge در فضای کاری شماست.
• مقدار hostname برابر با نام دامنه‌ای است که برای آن CDN ساخته‌اید و باید با hostname همان CDN یکی باشد.
• مقدار subdomains لیستی اختیاری از زیردامنه‌هایی است که باید همراه دامنه اصلی Purge شوند. هر زیردامنه به ابتدای hostname اضافه می‌شود. نباید خود hostname را دوباره در این لیست بیاورید.
• مقدار paths لیستی از مسیرهایی است که باید Purge شوند. حداقل یک مسیر لازم است. مسیری که با * تمام شود به‌عنوان پیشوند در نظر گرفته می‌شود.

نکته مهم

این درخواست فقط باید توسط کاربری ارسال شود که نقش cdn-purger دارد. فهرست نقش‌ها در نقش‌های CDN و نحوه تخصیص نقش در مدیریت نقش‌ها آمده است.

مثال

فرض کنید برای دامنه domain.ir یک CDN ساخته‌اید و درخواست‌های www.domain.ir هم از همین CDN پاسخ داده می‌شوند. نمونه درخواست به شکل زیر است:

curl -X POST \
  "https://api.sotoon.ir/delivery/v2.1/global/workspaces/<workspaceUUID>/purges" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "delivery/v2.1",
    "kind": "Purge",
    "metadata": {
      "name": "purge-scripts"
    },
    "spec": {
      "hostname": "domain.ir",
      "subdomains": ["www"],
      "paths": ["/scripts/*", "/data/image.png"]
    }
  }'

در اینجا:

• عملیات Purge برای دو دامنه domain.ir و www.domain.ir اجرا می‌شود.
• همه فایل‌هایی که مسیرشان با /scripts/ شروع می‌شود Purge می‌شوند. کاراکتر * فقط باید آخرین کاراکتر مسیر باشد.
• تک فایل /data/image.png حذف می‌شود.

فیلدهای spec

مقدار	نوع	فیلد	الزامی
نام دامنه CDN	string	hostname	بله
زیردامنه‌هایی که باید همراه دامنه اصلی Purge شوند	array of strings	subdomains	خیر
مسیرهای مطلق یا پیشوندی برای Purge	array of strings	paths	بله

محدودیت‌ها در مجموع برای همه درخواست‌های فعال Purge یک hostname:

• حداکثر ۱۰۰ درخواست Purge
• حداکثر ۲۰ هزار مسیر مطلق (بدون * در انتها)
• حداکثر ۱ هزار مسیر پیشوندی (خاتمه‌یافته به *)

ثبت درخواست به معنی انجام فوری Purge نیست. فرایند Purge زمان‌بر است و منابع Purge پس از حدود ۲۴ ساعت به‌صورت خودکار حذف می‌شوند.

استفاده با kubectl

راه‌اندازی kubectl، kubeconfig و توکن بپا در شروع استفاده از API با kubectl آمده است. پس از آن می‌توانید منبع Purge را اعمال کنید:

apiVersion: delivery.cafebazaar.cloud/v1beta1
kind: Purge
metadata:
  name: purge-scripts
  namespace: <your-namespace>
spec:
  hostname: domain.ir
  subdomains:
    - www
  paths:
    - /scripts/*
    - /data/image.png

kubectl --context sotoon --namespace <your-namespace> apply -f purge.yaml

پیوست۱: دریافت توکن IAM کاربر

مراحل ساخت توکن در ساخت توکن کاربری و کلیدها و توکن‌ها آمده است.

پیوست۲: دریافت شناسه فضای کاری

شناسه فضای کاری (workspaceUUID) را از بخش فضاهای کاری کپی کنید. توضیح آن در ساخت توکن کاربری آمده است.

پیوست۳: تخصیص مجوز Purge به یک کاربر

نقش مورد نیاز cdn-purger است. تعریف نقش‌های CDN در نقش‌های CDN و نحوه تخصیص نقش در مدیریت نقش‌ها آمده است.