معرفی WHM API: راهنمای گام به گام برای شروع استفاده پرینت

معرفی و کاربرد WHM API

رابط برنامه‌نویسی کاربردی WHM که به اختصار WHM API نامیده می‌شود، ابزاری قدرتمند برای مدیران سرورهای هاستینگ و توسعه‌دهندگان است که امکان تعامل مستقیم و برنامه‌ریزی‌شده با پنل مدیریت WHM را فراهم می‌کند. این رابط کاربری امکان می‌دهد تا وظایف مدیریتی پیچیده و تکراری را به صورت خودکار انجام دهید، که در محیط‌های هاستینگ بزرگ یا برای توسعه ابزارهای سفارشی بسیار مفید است. این بخش از مقاله به معرفی کلی WHM API و بررسی دو روش اصلی استفاده از آن می‌پردازد: فراخوانی توابع API از طریق مرورگر وب و همچنین به صورت اسکریپت‌نویسی. درک قابلیت‌های این API برای هر مدیر سرور و ارائه‌دهنده خدمات هاست حیاتی است، چرا که به افزایش کارایی و اتوماسیون وظایف روزمره کمک شایانی می‌کند. این قابلیت‌ها طیف وسیعی از عملیات مدیریتی را شامل می‌شوند، از ایجاد حساب‌های کاربری و دامنه‌ها گرفته تا پیکربندی تنظیمات پیشرفته سرور و DNS.

کشف قابلیت‌ها و مستندات API در WHM

پیش از هرگونه اقدامی برای استفاده از WHM API، ضروری است که با توابع و قابلیت‌های آن آشنا شوید. WHM API مجموعه‌ای گسترده از توابع را ارائه می‌دهد که هر یک برای انجام وظیفه‌ای خاص طراحی شده‌اند. برای مشاهده لیستی جامع از تمامی توابع قابل فراخوانی API، می‌توانید به مستندات رسمی cPanel مراجعه کنید. این صفحه مرجعی ارزشمند برای برنامه‌نویسان و مدیران سرورهای WHM است که می‌خواهند بدانند چه عملیاتی را می‌توانند از طریق API انجام دهند. با کلیک بر روی هر تابع در این لیست، می‌توانید جزئیات مربوط به آن، شامل پارامترهای مورد نیاز و نحوه استفاده را مشاهده کنید. به عنوان مثال، تابع `adddns` که برای افزودن یک zone DNS جدید استفاده می‌شود، یکی از توابع پرکاربرد است که ما در این راهنما از آن به عنوان نمونه استفاده خواهیم کرد. درک دقیق مستندات و پارامترهای هر تابع، کلید موفقیت در ساخت `API call` های صحیح و کارآمد است. این دانش به مدیران هاستینگ کمک می‌کند تا بتوانند نیازهای خود را به بهترین شکل ممکن از طریق `API` برآورده سازند و سیستم‌های خودکار پیشرفته‌ای توسعه دهند.

فراخوانی توابع API از طریق مرورگر

آسان‌ترین راه برای آشنایی و تست WHM API، فراخوانی توابع آن از طریق مرورگر وب است. درست همانند بازدید از یک وب‌سایت با وارد کردن یک URL، می‌توانید یک URL خاص را وارد کنید که فراخوانی API را انجام دهد. در طول استفاده از رابط کاربری WHM، احتمالاً متوجه شده‌اید که پس از آدرس URL معمول `https://x.x.x.x:2087` داده‌های اضافی وجود دارد. ما می‌توانیم این داده‌ها را برای انجام وظایف مدیریتی در سرور دستکاری کنیم. اگرچه فراخوانی توابع با استفاده از API ممکن است زائد به نظر برسد، زیرا شما قبلاً به `WHM` وارد شده‌اید و به تمامی ابزارهای رابط کاربری گرافیکی دسترسی کامل دارید، اما این روش به شما امکان می‌دهد تا مطمئن شوید که فراخوانی `API` شما طبق انتظار عمل می‌کند و در صورت بروز مشکل، خروجی‌های مفیدی (با فرمت `JSON` یا `XML`، هر کدام که ترجیح می‌دهید) به شما ارائه می‌دهد. این بازخورد فوری برای `دیباگینگ` و اطمینان از صحت عملکرد `API call` ها بسیار ارزشمند است و به ویژه در مراحل اولیه توسعه یا تست خودکارسازی‌ها کارآمد خواهد بود.

ساختار پایه یک فراخوانی API در مرورگر، شباهت زیادی به صفحه ورود به WHM دارد، اما شامل داده‌های اضافی پس از Session ID است. لازم به ذکر است که روش‌های زیر مستلزم آن است که شما از قبل به عنوان کاربر `root` در WHM وارد شده باشید و یک توکن امنیتی داشته باشید. این به معنای داشتن یک Session ID ۱۰ رقمی منحصر به فرد در قالب `https://x.x.x.x:2087:cpsess##########` است. در مثال‌های بعدی، ما از IP لوکال هاست `127.0.0.1` و `cpsess##########` برای جلوگیری از سردرگمی استفاده خواهیم کرد؛ بنابراین اطمینان حاصل کنید که این دستورات را با جزئیات مناسب برای سرور خود ویرایش کنید تا بتوانید آنها را امتحان کنید. این اقدامات پیش‌نیاز حیاتی برای هر گونه تعامل موفق با WHM API است و تضمین می‌کند که شما مجوزهای لازم برای انجام عملیات مورد نظر را دارید.

ساخت URL و اجرای عملیات نمونه: افزودن DNS Zone

اکنون که ایده اساسی از شکل یک URL برای فراخوانی API داریم، بیایید یک کار پایه را با API انجام دهیم: ایجاد یک DNS zone. بر اساس صفحه توابع که قبلاً در این راهنما به آن اشاره شد، ما از تابع `adddns` استفاده خواهیم کرد. این تابع به مدیران هاستینگ اجازه می‌دهد تا رکوردهای DNS را به صورت برنامه‌ریزی‌شده و بدون نیاز به ورود دستی به رابط کاربری اضافه کنند. با پیروی از راهنمای قالب‌بندی URL و جزئیات طرح‌بندی از راهنمای تابع در مستندات cPanel، می‌توانیم URL خود را به شکل زیر بسازیم:

`https://127.0.0.1:2087/cpsess##########/json-api/adddns?api.version=1&domain=example.com&ip=127.0.0.1`

در این مثال، `127.0.0.1` آدرس IP سرور، `cpsess##########` معرف `session ID` شما، `json-api` نشان‌دهنده استفاده از فرمت خروجی `JSON`، `adddns` تابع مورد نظر، `api.version=1` نسخه `API` و `domain=example.com` و `ip=127.0.0.1` پارامترهای مورد نیاز برای افزودن یک دامنه و IP مربوطه به عنوان یک `DNS zone` جدید هستند. این ساختار نمونه‌ای واضح از چگونگی استفاده از WHM API برای انجام وظایف مدیریتی است که می‌تواند فرآیندهای مدیریت سرور را به میزان قابل توجهی ساده‌تر و خودکارتر کند. با این رویکرد، هاستینگ‌ها می‌توانند سیستم‌های خود را برای ارائه خدمات بهتر و سریع‌تر به مشتریان بهینه‌سازی کنند.

کشف و مشاهده توابع API

استفاده از رابط برنامه‌نویسی کاربردی (API) در WHM، دریچه‌ای به سوی اتوماسیون و مدیریت پیشرفته سرورهای هاستینگ باز می‌کند. برای هر مدیر سرور یا ارائه‌دهنده خدمات میزبانی وب، درک و شناخت توابع API WHM، اولین و مهم‌ترین گام برای بهره‌برداری کامل از قابلیت‌های آن است. این بخش از مقاله به شما کمک می‌کند تا با نحوه کشف، مشاهده و درک عمیق توابع مختلف API آشنا شوید، که این دانش پایه و اساس اجرای موفقیت‌آمیز دستورات و اسکریپت‌های پیچیده‌تر در آینده خواهد بود و به شما امکان می‌دهد تا مدیریت سرورهای cPanel خود را به سطح جدیدی ارتقا دهید.

چرا شناخت توابع API WHM برای مدیریت سرور حیاتی است؟

WHM (Web Host Manager) به خودی خود یک ابزار جامع برای مدیریت سرور و اکانت‌های هاستینگ است. اما در سناریوهایی که نیاز به انجام عملیات‌های تکراری، ادغام با سیستم‌های دیگر یا ایجاد ابزارهای سفارشی برای مدیریت سرویس‌های میزبانی وب داریم، API WHM به یک ضرورت تبدیل می‌شود. شناخت توابع API به ما این امکان را می‌دهد که:

• عملیات مدیریت سرور و حساب‌های کاربری را به صورت خودکار انجام دهیم.
• وظایف خاصی را از طریق اسکریپت‌ها و برنامه‌های سفارشی خارج از محیط GUI WHM اجرا کنیم.
• بدون نیاز به تعامل مستقیم با رابط کاربری گرافیکی، مستقیماً با هسته WHM و cPanel تعامل داشته باشیم.
• فرآیندهای اشکال‌زدایی و عیب‌یابی را با دریافت خروجی‌های دقیق و ساختاریافته (در فرمت‌های JSON یا XML) آسان‌تر کنیم.

راهنمای دسترسی به لیست جامع توابع API WHM

برای شروع فرآیند کشف و استفاده از قابلیت‌های API WHM، مهم‌ترین منبع، لیست "Available Functions" یا توابع موجود است. این لیست جامع که به طور رسمی توسط مستندات cPanel ارائه می‌شود، تمامی فراخوان‌های API که می‌توانید برای مدیریت سرور WHM خود استفاده کنید را در بر می‌گیرد. این صفحه به عنوان یک کاتالوگ کامل عمل کرده و به شما نشان می‌دهد که چه عملیاتی را می‌توان از طریق API انجام داد و چه ابزارهایی برای توسعه‌دهندگان و مدیران سرور فراهم شده است.

تصور کنید قصد دارید یک DNS Zone جدید برای یکی از دامنه‌های میزبانی‌شده روی سرور خود ایجاد کنید. با مراجعه به این لیست، می‌توانید به راحتی تابع مربوطه مانند "adddns" را پیدا کنید. این صفحه نه تنها نام توابع را به شما نشان می‌دهد، بلکه به عنوان یک مرجع حیاتی برای ساخت صحیح دستورات API شما در مراحل بعدی عمل خواهد کرد. هر بار که نیاز به انجام یک عملیات خاص در WHM دارید و می‌خواهید آن را از طریق API مدیریت کنید، اولین قدم شما مراجعه به این لیست برای شناسایی تابع مناسب خواهد بود. این رویکرد به شما اطمینان می‌دهد که از تابع صحیح با پارامترهای لازم استفاده می‌کنید و از بروز خطاهای رایج در مدیریت وب‌سایت‌ها و سرورهای هاستینگ جلوگیری می‌نماید.

بررسی جزئیات هر تابع و اصول ساختاردهی فراخوان‌ها

فراتر از لیست کلی توابع، مستندات cPanel امکان مشاهده جزئیات کامل هر تابع API را نیز فراهم می‌کند. با کلیک بر روی نام هر تابع در لیست "Available Functions"، می‌توانید به صفحه‌ای منتقل شوید که اطلاعات دقیق‌تری را در مورد آن تابع خاص ارائه می‌دهد. این جزئیات برای ساخت دقیق URL API یا کدنویسی اسکریپت‌های شما بسیار حیاتی هستند. به عنوان مثال، برای تابع "adddns" که پیشتر به آن اشاره شد، صفحه جزئیات آن شامل موارد زیر خواهد بود:

• پارامترهای مورد نیاز: اطلاعاتی مانند نام دامنه (domain) و آدرس IP که برای اجرای صحیح تابع ضروری هستند و بدون آن‌ها عملیات با شکست مواجه می‌شود.
• پارامترهای اختیاری: سایر تنظیماتی که می‌توانید برای سفارشی‌سازی عملکرد تابع مشخص کنید و کنترل بیشتری بر روی عملیات هاستینگ داشته باشید.
• مثال‌های کاربردی: نمونه‌هایی از نحوه فراخوانی تابع با استفاده از ساختارهای URL یا اسکریپت‌نویسی که به درک بهتر کمک می‌کند.
• فرمت خروجی: اطلاعاتی در مورد قالب داده‌های بازگشتی (معمولاً JSON یا XML) در صورت موفقیت یا شکست عملیات، که برای تحلیل پاسخ‌های API ضروری است.

با درک کامل پارامترهای هر تابع، می‌توانید اطمینان حاصل کنید که فراخوان‌های API شما به درستی فرمت‌بندی شده‌اند و نتایج مورد انتظار را ارائه می‌دهند. دقت در این مرحله کلید موفقیت در کار با API و جلوگیری از خطاهای رایج است، به خصوص زمانی که قصد دارید عملیات حساسی مانند ایجاد DNS Zone یا مدیریت حساب‌های کاربری cPanel را انجام دهید.

آزمایش اولیه توابع API در مرورگر وب: یک گام عملی

یکی از ساده‌ترین و سریع‌ترین راه‌ها برای آشنایی و آزمایش API سی‌پنل و WHM، فراخوانی توابع مستقیماً از طریق مرورگر وب است. این روش به شما این امکان را می‌دهد که مانند بازدید از یک وب‌سایت با وارد کردن URL، دستورات API را نیز با یک URL خاص اجرا کنید. شاید در ابتدا استفاده از API در حالی که به WHM لاگین کرده‌اید و به ابزارهای GUI دسترسی کامل دارید، کمی زائد به نظر برسد؛ اما این روش برای بررسی عملکرد صحیح فراخوان API شما و مشاهده خروجی‌های مفید (در قالب JSON یا XML) در صورت بروز مشکل، بسیار کارآمد است و به شما کمک می‌کند تا فوراً بازخورد دریافت کنید.

برای استفاده از این روش، فرض بر این است که شما قبلاً به WHM به عنوان کاربر روت (root) وارد شده‌اید و یک توکن امنیتی معتبر دارید. این توکن امنیتی یک ID جلسه ۱۰ رقمی و منحصر به فرد است که به صورت "cpsess##########" در URL شما نمایش داده می‌شود (به عنوان مثال: https://x.x.x.x:2087:cpsess##########). این ID جلسه برای هر فراخوانی API ضروری است تا سیستم هویت شما را تأیید کند. فرمت کلی یک فراخوان API در مرورگر، شباهت زیادی به URL ورود به WHM دارد، با این تفاوت که اطلاعات اضافی پس از ID جلسه برای تعیین تابع و پارامترهای آن اضافه می‌شود. برای مثال، اگر بخواهید یک DNS zone جدید را با تابع "adddns" ایجاد کنید، URL شما می‌تواند چیزی شبیه به این باشد: https://127.0.0.1:2087/cpsess##########/json-api/adddns?api.version=1 domain=example.com ip=127.0.0.1. با این روش، شما نه تنها می‌توانید تابع "adddns" را تست کنید، بلکه خروجی مستقیم API را مشاهده خواهید کرد که برای اشکال‌زدایی و تأیید اجرای صحیح عملیات مدیریت هاستینگ و وب‌سایت‌ها بسیار مفید است. این تجربه عملی، درک شما را از نحوه کار API WHM به میزان قابل توجهی افزایش می‌دهد و شما را برای کارهای پیچیده‌تر آماده می‌کند.

فراخوانی API از طریق مرورگر

مقدمه‌ای بر فراخوانی API WHM از طریق مرورگر

یکی از ساده‌ترین و کارآمدترین روش‌ها برای آشنایی و تعامل اولیه با API های cPanel و WHM، فراخوانی توابع مورد نظر مستقیماً از طریق مرورگر وب است. این رویکرد، شباهت زیادی به بازدید از یک وب‌سایت با وارد کردن URL آن در نوار آدرس دارد؛ با این تفاوت که شما یک URL خاص را وارد می‌کنید که در پشت صحنه، یک عملیات API را در سرور هاستینگ شما اجرا می‌کند. در طول تجربه کاربری خود با رابط WHM، احتمالاً متوجه داده‌های اضافی پس از URL معمولی ورود به سیستم WHM شده‌اید؛ مانند https://x.x.x.x:2087. نکته هیجان‌انگیز اینجاست که ما می‌توانیم این داده‌های اضافی را دستکاری کرده و از آن‌ها برای انجام عملکردهای مدیریتی متنوعی در سرور خود استفاده کنیم. این قابلیت به مدیران سرور امکان می‌دهد تا وظایف تکراری را خودکارسازی کرده یا اطلاعات خاصی را استخراج نمایند.

ممکن است در نگاه اول، فراخوانی توابع از طریق API وقتی که شما قبلاً به WHM وارد شده‌اید و دسترسی کامل به رابط کاربری گرافیکی و ابزارهای موجود دارید، کمی زائد به نظر برسد. اما این روش مزایای خاص خود را دارد. مهم‌ترین فایده آن، این است که به شما امکان می‌دهد تا نحوه عملکرد فراخوانی API خود را همان‌طور که انتظار دارید، بررسی کنید. همچنین، در صورت بروز هرگونه مشکل یا خطا در حین اجرای فرمان، خروجی‌های بسیار مفیدی را در قالب JSON یا XML (بسته به ترجیح شما) ارائه می‌دهد که به شما در عیب‌یابی کمک شایانی می‌کند. این ویژگی برای توسعه‌دهندگان و مدیران هاستینگ که به دنبال خودکارسازی وظایف و اشکال‌زدایی سریع‌تر هستند، بسیار ارزشمند است، زیرا به آن‌ها دیدی شفاف از پاسخ سرور می‌دهد.

آشنایی با ساختار URL و پیش‌نیازها برای فراخوانی API

برای انجام فراخوانی‌های API از طریق مرورگر، درک ساختار URL مربوطه بسیار حیاتی است. این ساختار تا حد زیادی شبیه به آدرس ورود به سیستم WHM است، اما با اضافه شدن اطلاعاتی خاص پس از Session ID منحصر به فرد شما. اساساً، شما داده‌های اضافی را پس از آدرس معمول WHM وارد می‌کنید که به سرور دستور می‌دهد چه عملیاتی را انجام دهد.

قبل از اینکه به ساختار دقیق URL بپردازیم، ضروری است که پیش‌نیازهای کلیدی را مرور کنیم. این روش‌ها فرض می‌کنند که شما قبلاً به عنوان کاربر root وارد WHM شده‌اید و یک توکن امنیتی معتبر دارید. این بدان معناست که شما یک Session ID منحصر به فرد ۱۰ رقمی خواهید داشت که با فرمت https://x.x.x.x:2087:cpsess########## نمایش داده می‌شود. این Session ID نقش کلید احراز هویت شما را در هر فراخوانی API ایفا می‌کند.

برای جلوگیری از سردرگمی و حفظ امنیت اطلاعات سرور، در مثال‌های آتی، ما از آدرس IP لوکال هاست 127.0.0.1 و cpsess########## به عنوان جایگزین استفاده خواهیم کرد. بسیار مهم است که شما هنگام امتحان کردن این دستورات بر روی سرور cPanel خود، این مقادیر را با جزئیات دقیق و صحیح سرور خود (آدرس IP، پورت 2087 و Session ID معتبر خود) جایگزین کنید تا فراخوانی‌ها با موفقیت انجام شوند. این پیش‌نیازها از اهمیت بالایی برخوردارند، زیرا بدون احراز هویت صحیح و توکن معتبر، سرور درخواست‌های API شما را رد خواهد کرد و امکان انجام عملیات مدیریتی از این طریق وجود نخواهد داشت.

برای شروع کار، می‌توانید لیستی از تمام توابع موجود برای فراخوانی‌های API را در مستندات رسمی cPanel مشاهده کنید. این صفحه مرجع ارزشمندی است که جزئیات هر تابع، پارامترهای مورد نیاز و نحوه استفاده از آن‌ها را توضیح می‌دهد. به عنوان مثال، تابع adddns که برای ایجاد یک DNS Zone جدید استفاده می‌شود، یکی از توابعی است که در این راهنما به عنوان مثال عملی از آن استفاده خواهیم کرد. درک این مستندات به شما کمک می‌کند تا URLهای API خود را به درستی بسازید و از قابلیت‌های گسترده WHM API بهره‌مند شوید.

گام‌به‌گام: ساخت URL فراخوانی API (مثال افزودن DNS Zone)

حالا که با مفهوم کلی و پیش‌نیازهای فراخوانی API از طریق مرورگر آشنا شدیم، زمان آن رسیده است که یک کار عملی و اساسی را با استفاده از این روش انجام دهیم: ایجاد یک DNS Zone جدید. بر اساس صفحه توابع که قبلاً به آن اشاره شد، برای این منظور باید از تابع adddns استفاده کنیم. این تابع به شما امکان می‌دهد تا یک رکورد DNS جدید برای دامنه خود در سرور cPanel ایجاد کنید و مدیریت DNS را تسهیل می‌بخشد. برای مشاهده جزئیات بیشتر در مورد تابع adddns، می‌توانید به مستندات رسمی cPanel مراجعه کنید که تمامی پارامترهای لازم و نحوه استفاده از آن‌ها را به وضوح توضیح داده است.

با دنبال کردن راهنمای ساختار URL که در بخش‌های قبلی توضیح داده شد و جزئیات مربوط به تابع adddns از مستندات، می‌توانیم URL مورد نیاز خود را به شکل زیر بسازیم. توجه داشته باشید که این URL تمامی اطلاعات مورد نیاز برای اجرای موفقیت‌آمیز عملیات را در خود جای داده است و به عنوان یک ابزار قدرتمند برای مدیریت هاستینگ عمل می‌کند:

https://127.0.0.1:2087/cpsess##########/json-api/adddns?api.version=1&domain=example.com&ip=127.0.0.1

بیایید این URL را دقیق‌تر بررسی کنیم تا هر بخش آن را بهتر درک کنیم:

• https://127.0.0.1:2087: این قسمت، آدرس IP یا نام هاست سرور WHM شما به همراه پورت پیش‌فرض 2087 است. همانطور که اشاره شد، شما باید 127.0.0.1 را با IP سرور واقعی خود جایگزین کنید.
• /cpsess##########: این بخش شامل Session ID ده رقمی و منحصر به فرد شما است که نشان‌دهنده احراز هویت شما در WHM به عنوان کاربر root است. حتماً آن را با Session ID فعال خود جایگزین کنید.
• /json-api/adddns: این قسمت نشان می‌دهد که ما در حال فراخوانی یک تابع API JSON هستیم و نام تابع مورد نظر ما adddns است که برای افزودن یک DNS Zone جدید به کار می‌رود.
• ?api.version=1&domain=example.com&ip=127.0.0.1: این‌ها پارامترهای تابع adddns هستند. api.version=1 نسخه API را مشخص می‌کند، domain=example.com دامنه‌ای است که می‌خواهیم DNS Zone را برای آن ایجاد کنیم و ip=127.0.0.1 آدرس IP مربوط به این DNS Zone است. شما باید این پارامترها را بر اساس نیازهای خاص خود تغییر دهید. به عنوان مثال، example.com را با دامنه واقعی خود و 127.0.0.1 را با IP سرور یا دامنه‌ی مورد نظر جایگزین کنید.

با وارد کردن این URL کامل در نوار آدرس مرورگر خود و فشردن Enter، عملیات ایجاد DNS Zone از طریق API اجرا خواهد شد. خروجی (که معمولاً در فرمت JSON یا XML خواهد بود) وضعیت موفقیت یا شکست عملیات را به همراه جزئیات مربوطه به شما نمایش می‌دهد. این روش قدرتمند و در عین حال ساده، به مدیران هاستینگ و توسعه‌دهندگان امکان می‌دهد تا وظایف مدیریتی را با دقت و سرعت بیشتری انجام دهند و عملکرد سرورهای cPanel و WHM خود را بهینه سازند.

نکات مهم: ورود به WHM و توکن امنیتی

در دنیای پویای هاستینگ و مدیریت سرور، ابزارهایی نظیر رابط برنامه‌نویسی کاربردی (API) در WHM نقش حیاتی در اتوماسیون و ساده‌سازی فرآیندهای پیچیده ایفا می‌کنند. این ابزار قدرتمند به مدیران سرور، توسعه‌دهندگان و حتی ارائه‌دهندگان خدمات هاستینگ اجازه می‌دهد تا وظایف مدیریتی گسترده‌ای را به صورت برنامه‌ریزی‌شده و کارآمد انجام دهند. با این حال، برای بهره‌برداری کامل و امن از پتانسیل‌های API، آشنایی با پیش‌نیازهای اساسی و درک نکات امنیتی مربوط به ورود به WHM و استفاده از توکن امنیتی امری ضروری است. این بخش به تفصیل به این ملاحظات کلیدی می‌پردازد تا کاربران بتوانند با اطمینان خاطر و به شکل صحیح از API بهره‌مند شوند.

اهمیت دسترسی روت در WHM برای فراخوانی‌های API

اساس هرگونه تعامل موفق با APIهای WHM، ورود به پنل WHM با دسترسی کاربر روت (root) است. این امر نه تنها یک توصیه، بلکه یک شرط لازم برای انجام بخش عمده‌ای از عملیات مدیریتی از طریق API است. همانطور که می‌دانید، WHM امکانات گسترده‌ای برای کنترل کامل سرور، از مدیریت حساب‌های cPanel و دامنه‌ها گرفته تا پیکربندی‌های حیاتی DNS و تنظیمات امنیتی، ارائه می‌دهد. استفاده از API، این قابلیت‌ها را به سطحی بالاتر از اتوماسیون و برنامه‌ریزی می‌برد.

با توجه به سطح بالای اختیارات مورد نیاز برای انجام این وظایف، WHM اطمینان حاصل می‌کند که فقط کاربرانی با بالاترین سطح دسترسی، یعنی کاربر روت، مجاز به انجام این عملیات حساس از طریق API هستند. بدون دسترسی روت، تلاش برای فراخوانی بسیاری از توابع API با پیغام خطا مواجه خواهد شد یا به سادگی به دلیل عدم مجوز لازم، عملیات مورد نظر انجام نخواهد شد. این رویکرد امنیتی، از سوءاستفاده‌های احتمالی جلوگیری کرده و سلامت و پایداری سرور هاستینگ شما را تضمین می‌کند. بنابراین، همیشه قبل از اقدام به فراخوانی API، مطمئن شوید که به عنوان کاربر روت وارد محیط WHM شده‌اید.

آشنایی با توکن امنیتی (Session ID) و نقش آن در API

پس از ورود موفقیت‌آمیز به WHM به عنوان کاربر روت، سیستم یک توکن امنیتی منحصربه‌فرد که غالباً به عنوان Session ID شناخته می‌شود، برای شما ایجاد می‌کند. این توکن یک شناسه ۱۰ رقمی است که به صورت موقت، اعتبار نشست فعلی شما را در WHM تأیید می‌کند. ساختار URL در نوار آدرس مرورگر شما پس از ورود، به خوبی این Session ID را نشان می‌دهد؛ برای مثال، آن را در قالبی شبیه به https://x.x.x.x:2087:cpsess########## مشاهده خواهید کرد که x.x.x.x آدرس IP سرور شما و ########## همان Session ID منحصر به فرد شماست.

این توکن امنیتی عنصری حیاتی در هر فراخوانی API است، چه از طریق مرورگر انجام شود و چه از طریق اسکریپت‌های خط فرمان. هر فراخوانی API باید این Session ID را در URL خود حمل کند تا WHM بتواند هویت درخواست‌کننده را تأیید کرده و مجوزهای لازم را برای اجرای عملیات مورد نظر بررسی کند. بدون این توکن، درخواست‌های API نامعتبر شناخته شده و رد می‌شوند. اهمیت این سازوکار در این است که نیاز به ارسال مجدد اطلاعات ورود مانند نام کاربری و رمز عبور را برای هر فراخوانی API از بین می‌برد و در عین حال، لایه امنیتی لازم را حفظ می‌کند.

توکن امنیتی تا زمانی که نشست شما فعال باشد یا شما به صورت دستی از WHM خارج شوید، معتبر باقی می‌ماند. این بدان معناست که برای انجام چندین عملیات API پی در پی، می‌توانید از یک Session ID یکسان استفاده کنید. با این حال، بسیار مهم است که در هنگام کپی کردن و استفاده از نمونه‌های URL API، مقادیر پیش‌فرض مانند 127.0.0.1 (آدرس IP لوکال هاست) و cpsess########## را با آدرس IP واقعی سرور و Session ID فعال خود جایگزین کنید. این جایگزینی دقیق، برای عملکرد صحیح و بدون خطای فراخوانی‌های API بر روی سرور هاستینگ شما کاملاً ضروری است. عدم انجام این کار منجر به عدم شناسایی درخواست شما توسط WHM و در نتیجه، شکست عملیات خواهد شد.

مزایای فراخوانی API حتی با دسترسی کامل به رابط کاربری WHM

برخی ممکن است تعجب کنند که چرا باید از API برای انجام کارهایی استفاده کرد که می‌توان به راحتی از طریق رابط گرافیکی WHM انجام داد. این دیدگاه در نگاه اول منطقی به نظر می‌رسد، زیرا هر دو ابزار به یک مدیر سرور امکان مدیریت را می‌دهند. با این حال، چندین دلیل محکم وجود دارد که استفاده از API را حتی برای کاربرانی که به رابط کاربری WHM دسترسی کامل دارند، توجیه می‌کند و مزایای قابل توجهی به همراه دارد:

• **تست و اعتبارسنجی عملیات:** یکی از مهم‌ترین دلایل، امکان تست مستقیم و سریع فراخوانی‌های API است. این قابلیت به توسعه‌دهندگان و مدیران کمک می‌کند تا بدون نیاز به پیمایش در رابط گرافیکی، صحت عملکرد یک فرمان خاص API را بررسی کنند. در صورت بروز خطا، خروجی API که معمولاً در فرمت‌های ساختاریافته JSON یا XML ارائه می‌شود، اطلاعات دقیقی برای عیب‌یابی فراهم می‌آورد. این ویژگی به سرعت بخشیدن به فرآیند توسعه و اشکال‌زدایی کمک شایانی می‌کند.
• **اتوماسیون وظایف تکراری:** API قلب اتوماسیون در مدیریت هاستینگ است. وظایف تکراری مانند ایجاد چندین حساب cPanel، تنظیمات DNS برای دامنه‌های جدید، یا اعمال تغییرات پیکربندی در مقیاس وسیع، می‌تواند به جای انجام دستی و زمان‌بر، از طریق اسکریپت‌های خودکارسازی شده با API انجام شود. این امر بهینه‌سازی زمان، کاهش خطاهای انسانی و افزایش چشمگیر کارایی را به دنبال دارد.
• **یکپارچه‌سازی با سیستم‌های دیگر:** API امکان یکپارچه‌سازی WHM را با سیستم‌های خارجی مانند سیستم‌های CRM، سیستم‌های صورتحساب، یا پلتفرم‌های مدیریت ابری فراهم می‌کند. این یکپارچه‌سازی به شرکت‌های هاستینگ و سازمان‌های بزرگ اجازه می‌دهد تا فرآیندهای کسب‌وکار خود را یکپارچه‌تر و کارآمدتر مدیریت کنند.
• **انعطاف‌پذیری در اجرای فرمان‌ها:** با استفاده از API، مدیران می‌توانند فرمان‌ها را به صورت برنامه‌ریزی‌شده (مثلاً با cron jobs)، از راه دور از طریق برنامه‌های سفارشی، یا به عنوان بخشی از یک گردش کار پیچیده‌تر که فراتر از قابلیت‌های رابط گرافیکی است، اجرا کنند. این انعطاف‌پذیری، سطح جدیدی از کنترل بر سرور را فراهم می‌آورد.

در مجموع، در حالی که رابط کاربری گرافیکی WHM یک ابزار عالی برای مدیریت روزمره است، API افق‌های جدیدی را برای اتوماسیون، بهینه‌سازی و یکپارچه‌سازی در حوزه هاستینگ باز می‌کند. درک صحیح این پیش‌نیازها و مزایا، گام اول برای تبدیل شدن به یک مدیر سرور کارآمدتر و حرفه‌ای‌تر است.

مثال عملی: ساخت منطقه DNS با API

همانطور که قبلاً اشاره شد، WHM API ابزاری قدرتمند برای انجام وظایف مدیریتی در سرور است. برای آشنایی اولیه با نحوه عملکرد این API، ساده‌ترین راه فراخوانی یک تابع از طریق مرورگر وب است. این روش به شما این امکان را می‌دهد تا بدون نیاز به کدنویسی پیچیده، عملکرد API را بررسی کرده و خروجی‌های آن را مشاهده کنید. درک این فرآیند، پایه و اساس استفاده از API در سناریوهای پیشرفته‌تر مانند اسکریپت‌نویسی با Perl را فراهم می‌آورد.

در طول استفاده روزمره از رابط کاربری WHM، احتمالاً متوجه شده‌اید که پس از آدرس URL معمول (مانند https://x.x.x.x:2087) اطلاعات اضافی نمایش داده می‌شود. WHM API به شما اجازه می‌دهد تا این داده‌ها را دستکاری کرده و از آن‌ها برای انجام عملکردهای مدیریتی مختلف در سرور استفاده کنید. هدف اصلی از فراخوانی توابع API از طریق مرورگر، درک ساختار فرمان‌ها و بررسی صحت عملکرد آن‌هاست. این کار به شما کمک می‌کند تا مطمئن شوید که فراخوانی API شما همانطور که انتظار دارید کار می‌کند و در صورت بروز مشکل، خروجی‌های مفیدی (در فرمت JSON یا XML، بسته به ترجیح شما) دریافت خواهید کرد.

آشنایی با توابع موجود در WHM API

پیش از هرگونه اقدام برای استفاده از WHM API، ضروری است که با توابع و قابلیت‌های آن آشنا شوید. cPanel و WHM مستندات جامعی را ارائه می‌دهند که لیستی از تمام توابع موجود برای فراخوانی‌های API را در بر می‌گیرد. این لیست به شما کمک می‌کند تا دقیقاً بدانید چه عملیاتی را می‌توانید از طریق API انجام دهید و چه پارامترهایی برای هر تابع لازم است. این مستندات منبعی ارزشمند برای ساختاردهی صحیح دستورات API شما خواهند بود.

علاوه بر لیست کلی توابع، شما می‌توانید جزئیات خاص هر تابع را نیز مشاهده کنید. برای مثال، تابع adddns که برای ایجاد یک منطقه DNS جدید به کار می‌رود، دارای مستندات اختصاصی است که پارامترهای لازم، فرمت فراخوانی و مثال‌های کاربردی آن را توضیح می‌دهد. در طول این راهنما، ما از تابع adddns به عنوان مثال عملی خود برای نشان دادن نحوه کار با WHM API استفاده خواهیم کرد تا مفاهیم به شکل ملموسی درک شوند.

ساختار URL برای فراخوانی API در مرورگر

فراخوانی توابع API در مرورگر مستلزم ساخت یک URL با فرمت خاص است. این URL شامل آدرس سرور WHM، شناسه جلسه (session ID) و پارامترهای مربوط به تابع API مورد نظر می‌شود. توجه داشته باشید که برای انجام این کار، باید قبلاً به WHM به عنوان کاربر روت وارد شده باشید و یک توکن امنیتی فعال داشته باشید. این به معنای آن است که شما یک شناسه جلسه ۱۰ رقمی منحصربه‌فرد در فرمت https://x.x.x.x:2087:cpsess########## خواهید داشت. این شناسه جلسه برای احراز هویت درخواست‌های API شما حیاتی است.

در مثال‌های زیر، برای جلوگیری از هرگونه سردرگمی، ما از IP لوکال هاست 127.0.0.1 و یک شناسه جلسه فرضی cpsess########## استفاده خواهیم کرد. اگر قصد دارید این دستورات را روی سرور خود امتحان کنید، حتماً این مقادیر را با جزئیات مربوط به سرور خود (آدرس IP واقعی و شناسه جلسه فعال خود) جایگزین کنید تا فراخوانی‌ها به درستی انجام شوند. این مرحله برای اطمینان از امنیت و صحت اجرای دستورات API بسیار مهم است.

ساخت منطقه DNS جدید با API: گام به گام

اکنون که با مفاهیم اولیه و ساختار URL آشنا شدیم، اجازه دهید یک وظیفه اساسی را با WHM API انجام دهیم: ایجاد یک منطقه DNS جدید. همانطور که از صفحه توابع API در مستندات cPanel دریافتیم، برای این منظور باید از تابع adddns استفاده کنیم. این تابع به ما امکان می‌دهد تا یک دامنه جدید را به عنوان یک منطقه DNS به سرور اضافه کنیم و پارامترهای اولیه آن را مشخص سازیم.

با در نظر گرفتن راهنمای فرمت URL که پیش‌تر توضیح داده شد و جزئیات مربوط به تابع adddns از مستندات رسمی، می‌توانیم URL لازم برای ایجاد منطقه DNS را به شکل زیر بسازیم:

https://127.0.0.1:2087/cpsess##########/json-api/adddns?api.version=1&domain=example.com&ip=127.0.0.1

در این URL، بخش https://127.0.0.1:2087/cpsess########## همان بخش معمول ورود به WHM همراه با شناسه جلسه فعال شماست. /json-api/adddns مسیر فراخوانی تابع adddns را مشخص می‌کند و ?api.version=1&domain=example.com&ip=127.0.0.1 پارامترهایی هستند که به تابع ارسال می‌شوند. api.version=1 نسخه API را مشخص می‌کند، domain=example.com نام دامنه جدیدی است که می‌خواهیم منطقه DNS آن را ایجاد کنیم و ip=127.0.0.1 آدرس IP مرتبط با این دامنه است. پس از اجرای این URL در مرورگر، WHM API درخواست شما را پردازش کرده و نتیجه را در قالب JSON یا XML به شما برمی‌گرداند که نشان‌دهنده موفقیت یا شکست عملیات و در صورت لزوم، پیام‌های خطا خواهد بود.

جمع‌بندی و توصیه‌های نهایی

در این بخش، ما یک نمای کلی از نحوه شروع استفاده از WHM API و تمرکز بر فراخوانی توابع از طریق مرورگر را بررسی کردیم. با یادگیری چگونگی شناسایی توابع مورد نیاز و ساختاردهی URL درخواست، قادر خواهید بود وظایف مدیریتی را با کارایی بیشتری انجام دهید. مثال عملی ایجاد منطقه DNS با تابع adddns نشان داد که چگونه می‌توان یک عملیات پیچیده را به سادگی از طریق یک URL انجام داد.

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