آموزش ساخت کلید API در cPanel

۱. کلید API در cPanel چیست؟

وقتی می‌خواهید یک برنامه اطلاعات هاست را دریافت کند یا کاری را در حساب شما انجام دهد، API راه ارتباط برنامه با پنل است. «کلید API» در این آموزش همان API Token سی‌پنل است؛ برنامه آن را هنگام درخواست ارسال می‌کند و لازم نیست هر بار وارد محیط گرافیکی پنل شوید.

این راهنما برای حساب معمولی cPanel است. اگر صفحهٔ WHM را باز کرده‌اید، ابتدا وارد cPanel سرویس خود شوید؛ توکن این دو پنل را جای یکدیگر استفاده نکنید.

۲. ورود به پنل و پیدا کردن API Tokens

cPanel پنل مدیریت هاست شماست؛ فایل‌ها، دیتابیس و ترمینال را از همین صفحه مدیریت می‌کنید. برای ورود، اطلاعات سرویس فعال خود را آماده داشته باشید.

1. وارد ناحیهٔ کاربری هاست وردپرس شوید؛ از حسابی استفاده کنید که هاست را با آن تهیه کرده‌اید.
2. در بخش سرویس‌ها، هاست فعال خود را باز کنید و گزینهٔ ورود به cPanel را بزنید. اگر لینک ورود مستقیم ندارید، از آدرس و اطلاعات ورودِ پیام فعال‌سازی سرویس استفاده کنید.
3. پس از ورود، صفحهٔ اصلی cPanel را می‌بینید. نام ابزار موردنیاز، مثل File Manager یا Terminal را در کادر جست‌وجوی پنل بنویسید.

نام کاربری cPanel را از اطلاعات سرویس پیدا کنید. هر جا در فرمان‌ها USERNAME دیدید، همین نام را جایگزین کنید؛ این مقدار، ایمیل یا نام نمایشی حساب شما نیست.

در کادر جست‌وجوی پنل، API Tokens را بنویسید. سپس ابزار Manage API Tokens را از بخش Security باز کنید.

اگر این ابزار نمایش داده نمی‌شود، از پشتیبانی هاست دربارهٔ فعال‌بودن آن برای سرویس خود بپرسید. دسترسی این بخش را ارائه‌دهندهٔ هاست تنظیم می‌کند.

۳. ساخت توکن و تعیین تاریخ انقضا

1. روی Create بزنید.
2. در API Token Name نامی مشخص مانند pythonhost-monitor وارد کنید. نام باید یکتا، حداکثر ۵۰ کاراکتر و شامل حروف انگلیسی، عدد، خط تیره یا زیرخط باشد.
3. در Should the API Token Expire? گزینهٔ Specify an expiration date را انتخاب و تاریخ پایان استفاده را مشخص کنید. قالب ورود دستی تاریخ YYYY-MM-DD است.
4. با Create توکن را بسازید.

۴. کپی و نگهداری کلید

در صفحهٔ نتیجه، Copy را بزنید و مقدار توکن را در محل امن ذخیره کنید؛ سپس Yes, I Saved My Token را انتخاب کنید. با خروج از این صفحه، مقدار توکن دوباره قابل مشاهده نیست.

برای هر برنامه نام جداگانه‌ای انتخاب کنید تا بعداً بتوانید توکن همان برنامه را شناسایی و لغو کنید. پیش از بستن صفحه مطمئن شوید مقدار را کامل کپی کرده‌اید؛ نام توکن، خودِ کلید نیست.

۵. یک نمونهٔ استفاده با پایتون

برای یک آزمایش خواندنی می‌توانید فهرست دامنه‌های حساب را از DomainInfo/list_domains بگیرید. این درخواست دامنه‌ای ایجاد یا حذف نمی‌کند. آدرس باید مربوط به سرور cPanel باشد؛ آدرس پنل مشتریان یا یک صفحهٔ ورود، جای آن را نمی‌گیرد.

سه متغیر CPANEL_SERVER، CPANEL_USERNAME و CPANEL_API_TOKEN را در محیط اجرای خصوصی برنامه تنظیم کنید. برای اولی، آدرس HTTPS سرور مانند https://server.example.com:2083 را از اطلاعات سرویس بردارید. نام کاربری، همان نام حساب cPanel است.

import json
import os
from urllib.request import Request, urlopen

server = os.environ["CPANEL_SERVER"].rstrip("/")
username = os.environ["CPANEL_USERNAME"]
token = os.environ["CPANEL_API_TOKEN"]

if not server.startswith("https://"):
    raise ValueError("CPANEL_SERVER must use HTTPS")

request = Request(
    f"{server}/execute/DomainInfo/list_domains",
    headers={"Authorization": f"cpanel {username}:{token}"},
)
with urlopen(request, timeout=15) as response:
    result = json.load(response)["result"]

if result["status"] != 1:
    raise RuntimeError(result.get("errors") or "cPanel API request failed")

print(json.dumps(result["data"], ensure_ascii=False, indent=2))
    

نمونه از کتابخانه‌های استاندارد پایتون استفاده می‌کند. هدر احراز هویت به شکل Authorization: cpanel USERNAME:TOKEN ارسال می‌شود؛ توکن را در URL قرار ندهید. موفقیت UAPI را با result.status بررسی کنید؛ مقدار 1 نشانهٔ موفقیت است. دریافت HTTP 200 به‌تنهایی کافی نیست.

اگر خطای گواهی TLS دیدید، نام میزبان و گواهی سرور را بررسی کنید. اعتبارسنجی HTTPS را برای عبور از خطا خاموش نکنید. برای آماده‌کردن محیط برنامه، آموزش اجرای Flask روی cPanel هم می‌تواند کمک کند.

۶. لغو یا جایگزینی توکن

در Manage API Tokens، روبه‌روی توکن موردنظر Manage را بزنید؛ سپس Revoke و Yes, Revoke the Token را انتخاب کنید. برنامهٔ استفاده‌کننده بعد از لغو باید با توکن دیگری تنظیم شود.

توکن منقضی‌شده خودکار از فهرست حذف نمی‌شود. اگر کلید گم شد یا احتمال افشای آن وجود دارد، همان توکن را لغو و کلید جدیدی ایجاد کنید.