راهنمای API سرور CPU و S3

۱. کلید و مجوزها

در پروفایل کلید مستقل بسازید و فقط مجوزهای لازم را انتخاب کنید. کلید فقط یک بار نمایش داده می‌شود؛ حداکثر ۵ کلید فعال، انقضای ۹۰ روز و سقف ۱۲۰ درخواست در دقیقه برای هر کلید. کلید را در مرورگر، Git، URL یا لاگ قرار ندهید. پیش از خرید، قرارداد عمومی را در سایت بپذیرید و کیف پول را شارژ کنید.

۲. ساخت سرور CPU

انتخاب‌ها را از Catalog دریافت کنید؛ GPU پذیرفته نمی‌شود. ابتدا قیمت بگیرید؛ مبلغ نهایی شامل ۱۰٪ مالیات است و فقط هنگام ساخت از کیف پول کسر می‌شود، نه هنگام شارژ. درخواست ساخت به نام، انتخاب‌ها و expected_total_toman نیاز دارد. شناسه درخواست یکتا را قبل از ارسال بسازید و در Retry تغییر ندهید.

برای حساب‌هایی که مالک سایت دستی پس‌پرداخت کرده، purchase_hours عدد صحیح ۱ تا ۷۲۰ در درخواست قیمت و ساخت قابل ارسال است؛ حداقل مشتری عادی یک ماه می‌ماند. حذف این فیلد برای سازگاری همان خرید ماهانه است. مبلغ مدت انتخاب‌شده با مالیات در بدهی ثبت می‌شود، نه کیف پول. این خرید مدت‌دار است، نه Pay-as-you-go یا تمدید خودکار؛ خاموشی مدت خرید را تغییر نمی‌دهد. قیمت از تعرفه ماهانه تقسیم بر ۷۲۰ به دست می‌آید؛ مبلغ و مالیات هر کدام به نزدیک‌ترین تومان گرد می‌شوند. تغییر وضعیت پس‌پرداخت از سایت یا API مشتری ممکن نیست.

# Configure CLOUDYDREAM_API_KEY securely, outside shell history.
curl --fail-with-body https://cloudydream.ir/api/customer/v1/cpu/catalog/ \
  -H "Authorization: Bearer $CLOUDYDREAM_API_KEY"

# Copy current public selection IDs from the catalog into selection.json:
# {"flavor_id":"plan-1","image_id":"os-ubuntu-24",
#  "network_id":"private-network","volume_size_gb":20}
curl --fail-with-body https://cloudydream.ir/api/customer/v1/cpu/quote/ \
  -H "Authorization: Bearer $CLOUDYDREAM_API_KEY" \
  -H "Content-Type: application/json" --data-binary @selection.json

# request.json: the same selection + name + expected_total_toman
# expected_total_toman must equal pricing.total_toman from your quote.
# Optional: ssh_key_source="provided", ssh_public_key="<YOUR PUBLIC KEY>"
curl --fail-with-body https://cloudydream.ir/api/customer/v1/cpu/servers/create/ \
  -H "Authorization: Bearer $CLOUDYDREAM_API_KEY" \
  -H "Idempotency-Key: $REQUEST_UUID" \
  -H "Content-Type: application/json" --data-binary @request.json

curl --fail-with-body "https://cloudydream.ir/api/customer/v1/cpu/servers/$SERVER_ID/" \
  -H "Authorization: Bearer $CLOUDYDREAM_API_KEY"

پاسخ 202 یعنی درخواست پذیرفته شده، نه اینکه سرور آماده است. وضعیت را با شناسه عمومی برگشتی هر ۱۰ ثانیه بررسی کنید. فهرست فعلی حداکثر ۱۰۰ سرور ساخته‌شده با این API را نشان می‌دهد؛ سرورهای قدیمی سایت در آن نیستند. کنسول، رمز ورود، حذف و کنترل روشن/خاموش از میزکار سایت انجام می‌شوند و در این نسخه API ارائه نمی‌شوند.

۳. اتصال استاندارد S3

فضای ذخیره‌سازی را در سایت ایجاد و کلید آن را یک‌بار از میزکار دریافت کنید. S3 از AWS Signature V4 و کلید مستقل Access Key/Secret Key استفاده می‌کند؛ Bearer سایت جایگزین آن نیست. اتصال HTTPS و path-style را نگه دارید و بررسی TLS را خاموش نکنید. پاسخ /s3/ فقط وضعیت و سهمیهٔ حساب خودتان است.

AWS CLI

# Use a dedicated AWS profile, or securely inject AWS_ACCESS_KEY_ID
# and AWS_SECRET_ACCESS_KEY. Do not use your CloudyDream Bearer API key.
aws configure set default.region us-east-1
aws configure set default.s3.addressing_style path

aws --endpoint-url https://s3.cloudydream.ir s3api list-buckets
aws --endpoint-url https://s3.cloudydream.ir s3api create-bucket --bucket YOUR-UNIQUE-BUCKET
aws --endpoint-url https://s3.cloudydream.ir s3 cp ./example.txt s3://YOUR-UNIQUE-BUCKET/example.txt
aws --endpoint-url https://s3.cloudydream.ir s3 ls s3://YOUR-UNIQUE-BUCKET/
aws --endpoint-url https://s3.cloudydream.ir s3 cp s3://YOUR-UNIQUE-BUCKET/example.txt ./download.txt

# Only when you intentionally want to delete this test object:
aws --endpoint-url https://s3.cloudydream.ir s3 rm s3://YOUR-UNIQUE-BUCKET/example.txt
# Empty bucket only; no recursive/force deletion:
aws --endpoint-url https://s3.cloudydream.ir s3api delete-bucket --bucket YOUR-UNIQUE-BUCKET

Python / boto3

import boto3
from botocore.config import Config

# Credentials come from the standard secure AWS credential chain.
s3 = boto3.client("s3", endpoint_url="https://s3.cloudydream.ir",
    region_name="us-east-1",
    config=Config(signature_version="s3v4", s3={"addressing_style": "path"}))
s3.upload_file("example.txt", "YOUR-UNIQUE-BUCKET", "example.txt")
s3.download_file("YOUR-UNIQUE-BUCKET", "example.txt", "download.txt")
for page in s3.get_paginator("list_objects_v2").paginate(Bucket="YOUR-UNIQUE-BUCKET"):
    for obj in page.get("Contents", []):
        print(obj["Key"], obj["Size"])
# This URL grants temporary access: do not log, commit or publicly share it.
url = s3.generate_presigned_url("get_object",
    Params={"Bucket":"YOUR-UNIQUE-BUCKET", "Key":"example.txt"}, ExpiresIn=300)

upload_file انتقال چندبخشی فایل‌های بزرگ را مدیریت می‌کند. Multipart ناتمام فضا مصرف می‌کند؛ فقط انتقال متعلق به خودتان را لغو کنید. فایل‌ها و Bucket را خصوصی نگه دارید. لینک امضاشده دسترسی موقت می‌دهد و نباید عمومی یا لاگ شود. خطای 403 به معنی اشتباه بودن کلید، امضا یا مجوز است؛ 409 هنگام حذف Bucket معمولاً یعنی خالی نیست.

S3 SDK reference · boto3 examples

۴. خطا و تکرار درخواست

401: احراز هویت · 403: مجوز · 400: ورودی نامعتبر یا GPU · 402: اعتبار ناکافی · 409: اختلاف قیمت یا تکرار درخواست · 428: پذیرش قرارداد · 429: محدودیت درخواست · 503: عدم دسترسی موقت

برای خطای موقت با فاصلهٔ افزایشی و همان Idempotency-Key تلاش کنید. یک کلید با بدنه متفاوت رد می‌شود. برای پشتیبانی فقط X-Request-ID را بفرستید، نه کلید و اطلاعات محرمانه. تغییر قیمت نیازمند قیمت‌گیری و تأیید مجدد مبلغ است.

۵. شبکهٔ خصوصی و روتر

مسیرها نصب شده‌اند؛ ساخت شبکه فعلاً خاموش است و تا تکمیل آمادگی پروژه و Policy زیرساخت پاسخ 503 می‌دهد. کلید جدید با networks:read و networks:write بسازید؛ کلیدهای قبلی ارتقا نمی‌یابند.

CIDR باید IPv4 خصوصی با پیشوند /16 تا /29 و بدون هم‌پوشانی در همان پروژه باشد. DHCP و Port Security فعال می‌مانند. روتر داخلی gateway خارجی، SNAT یا Floating IP ندارد و به اینترنت وصل نمی‌شود. سهمیه افزایش نمی‌یابد و برداشت کیف پول انجام نمی‌شود.

POST /api/customer/v1/networks/create/
{"name":"app-network","cidr":"192.168.42.0/24"}

POST /api/customer/v1/routers/create/
{"name":"app-router"}

POST /api/customer/v1/routers/attach/
{"network":"<network response data.id>","router":"<router response data.id>"}

GET /api/customer/v1/networks/
GET /api/customer/v1/networks/<operation-id>/

هدر Authorization: Bearer برای همه درخواست‌ها لازم است. هر POST هدر Idempotency-Key مستقل با ۱۶ تا ۱۲۸ نویسه دارد. برای تکرار همان درخواست، همان کلید و بدنه را نگه دارید. network و router فقط شناسهٔ عمومی پاسخ همین API هستند؛ Project ID، Provider ID یا تنظیم gateway ارسال نکنید.

200: کامل؛ 202: در حال اجرا؛ 409 recovery_required: نتیجه نامشخص و نیازمند پشتیبانی—با کلید جدید تلاش نکنید. منابع احتمالی حفظ می‌شوند. 404: مرجع نامعتبر یا متعلق به مشتری دیگر؛ 428: پذیرش قرارداد؛ 503: قابلیت خاموش یا پروژه آماده نیست. این نسخه حذف منابع یا اتصال روترهای قدیمی را ارائه نمی‌کند.