📄 شروع استفاده از API محصول CDN - نسخه جدید

نسخه جدید API محصول CDN در قالب Restful ارائه می‌شود و به سادگی در فرآیندهای اتوماسیون سمت خودتان قابل استفاده است.

پیش‌نیازها

• دسترسی به پنل اوشن و مجوز مدیریت CDN/DNS
• داشتن توکن کاربری فعال برای احراز هویت درخواست‌ها

ساخت توکن کاربری

۱- وارد بخش توکن‌ها در پروفایل کاربری خود در پنل اوشن شوید.

۲- در بخش «توکن‌های کاربر» روی دکمه «افزودن توکن کاربر» کلیک کنید. سپس یک نام دلخواه برای توکن انتخاب کرده و توکن جدید را اضافه کنید.

۳- توکن ساخته‌شده را کپی کنید. این توکن بعدا نمایش داده نمی‌شود، پس آن را در محل امن نگه دارید. دارنده این توکن می‌تواند از طرف شما تغییراتی در تنظیمات محصولات اعمال کند.

۴- از بخش فضاهای کاری در پروفایل کاربری شناسه فضای کاری که قصد دارید روی آن کار کنید را کپی کرده و در ادامه جایگزین workspaceUUID بکنید.

اصول احراز هویت و هدرها

طبق مستندات، تمامی درخواست‌ها باید با توکن ارسال شوند. احراز هویت از نوع Bearer Token است و باید در هدر Authorization ارسال شود:

• Authorization: Bearer <TOKEN>

الگوی عمومی درخواست‌ها

هر عملیات در API به یک مسیر (Endpoint) و متد HTTP مشخص متکی است. نمونه زیر یک الگوی کلی است؛ مقدار مسیر و بدنه را از مستندات بردارید:

curl -X <METHOD> \
  "<BASE_URL>/<ENDPOINT>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '<JSON_BODY>'

نمونه‌های عملی (قابل استفاده با جایگزینی مقادیر)

در نمونه‌های زیر، مقادیر داخل <> را مطابق مستندات مرجع جایگزین کنید.

مثال ۱: دریافت لیست (GET) با پارامترهای Query

curl -X GET \
  "https://api.sotoon.ir/delivery/v2.1/global/workspaces/{workspaceUUID}/cdns" \
  -H "Authorization: Bearer <TOKEN>"

مثال ۲: دریافت (GET) با پارامتر مسیر

curl -X GET \
  "https://api.sotoon.ir/delivery/v2.1/global/workspaces/<workspaceUUID>/cdns/<resourceId>" \
  -H "Authorization: Bearer <TOKEN>"

نکته: در اینجا و ادامه resourceId اشاره می کند به uid مربوط به آبجکتی که قصد تغییر آن را دارید.

مثال ۳: ایجاد (POST) با بدنه JSON

curl -X POST \
  "https://api.sotoon.ir/delivery/v2.1/global/workspaces/{workspaceUUID}/cdns" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "delivery/v2.1",
    "kind": "CDN",
    "metadata": {
      "name": "cdn-name",
      "namespace": "workspace-name"
    },
    "spec": {
      "hostname": "example.com",
      "firewall": {
        "enabled": true,
        "rules": [
          {
            "name": "ratelimit-1",
            "enabled": true,
            "constraints": [
              [
                {
                  "type": "known_bots",
                  "known_bots": {
                    "expected": "false",
                    "operator": "equals"
                  }
                }
              ]
            ],
            "action": {
              "type": "ratelimit",
              "ratelimit": {
                "algorithm": "sliding_window",
                "rate": 100,
                "period": 60,
                "penalty_period": 1,
                "identifier": {
                  "type": "ip"
                },
                "statusCode": "429",
                "validationStatusCode": "412"
              }
            }
          }
        ]
      },
      "locations": [
        {
          "path": "/path/to/static-assets/*",
          "host": "example.com",
          "action": "proxy_http",
          "upstream": "upstream-name",
          "cache": {
            "level": "standard",
            "edgeTTL": "120",
            "ttlTimeUnit": "second",
            "detectCountry": "true",
            "detectDevice": "true"
          },
          "cors": {
            "allowOrigins": "*",
            "allowMethods": "*",
            "allowHeaders": "*"
          },
          "imgsvc": {
            "enabled": "false",
            "forcedFilter": {
              "enabled": true
            }
          },
          "headers": {},
          "rewrite": {}
        },
        {
          "path": "/*",
          "host": "example.com",
          "action": "proxy_http",
          "upstream": "upstream-name",
          "cache": {
            "level": "standard",
            "edgeTTL": "3601",
            "browserTTL": "3601",
            "ttlTimeUnit": "second"
          },
          "cors": {
            "enabled": "true",
            "allowOrigins": "*",
            "allowMethods": "*",
            "allowHeaders": "*",
            "allowCredentials": "true",
            "exposeHeaders": "*"
          },
          "imgsvc": {
            "enabled": "false",
            "forcedFilter": {
              "enabled": false
            }
          },
          "headers": {},
          "rewrite": {}
        }
      ],
      "upstreams": [
        {
          "name": "foriegn_upstream_name",
          "scheme": "https",
          "preferredHealthCheckVersion": "2",
          "smartRouting": "true",
          "hc2": {
            "protocol": "tcp"
          },
          "servers": [
            {
              "host": "4.4.4.4",
              "port": "443",
              "weight": "1"
            }
          ]
        },
        {
          "name": "upstream-name",
          "scheme": "https",
          "smartRouting": "true",
          "preferredHealthCheckVersion": "2",
          "hc2": {
            "protocol": "tcp"
          },
          "servers": [
            {
              "host": "upstream-server-host",
              "port": "443",
              "weight": "1"
            }
          ]
        }
      ],
      "secureLink": {
        "tokenName": "token",
        "expireName": "expire"
      },
      "tls": {
        "enabled": "true",
        "auto": "true",
        "forced": "true"
      }
    }
  }'

مثال ۴: نمونه واقعی PATCH فقط برای به‌روزرسانی firewall

curl -X PATCH \
  "https://api.sotoon.ir/delivery/v2.1/global/workspaces/<workspaceUUID>/cdns/<resourceId>" \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "spec": {
      "firewall": {
        "enabled": true,
        "rules": [
          {
            "name": "ratelimit-1",
            "enabled": true,
            "constraints": [
              [
                {
                  "type": "known_bots",
                  "known_bots": {
                    "expected": "false",
                    "operator": "equals"
                  }
                }
              ]
            ],
            "action": {
              "type": "ratelimit",
              "ratelimit": {
                "algorithm": "sliding_window",
                "rate": 100,
                "period": 60,
                "penalty_period": 1,
                "identifier": {
                  "type": "ip"
                },
                "statusCode": "429",
                "validationStatusCode": "412"
              }
            }
          }
        ]
      }
    }
  }'

گام‌های پیشنهادی برای شروع

1. یک سناریوی ساده انتخاب کنید (مثلا مشاهده یا ایجاد تنظیمات CDN/DNS).
2. مسیر و پارامترها را از مستندات مرجع پیدا کنید.
3. درخواست را با توکن و هدرهای لازم ارسال کنید.
4. پاسخ دریافتی را بررسی کنید و در صورت نیاز، خطاها را مدیریت کنید.

مدیریت خطاها و نکات عملی

• کدهای پاسخ HTTP را بررسی کنید؛ خطاهای احراز هویت معمولا با کدهای 401/403 مشخص می‌شوند.
• اگر پارامترها معتبر نباشند، پاسخ شامل پیام خطا خواهد بود.
• برای اسکریپت‌های اتوماسیون، خطاها را لاگ و درخواست‌های ناموفق را بازپخش کنید.