SDK زبان JavaScript / TypeScript
بسته arianet کلاینت رسمی JavaScript و TypeScript برای وب سرویسهای آریانت است. از fetch داخلی استفاده میکند، وابستگی زمان اجرا ندارد، به Node.js نسخه ۲۰ یا بالاتر نیاز دارد و تعریف نوع (TypeScript) همه متدها و پارامترها را همراه دارد. بسته به صورت ES module منتشر میشود.
- سورس: github.com/ariaservice/arianet-js (نسخه فعلی 0.1.0)
نصب
npm install arianet
تا زمان انتشار بسته در npm، میتوانید آن را از صفحه نسخهها در GitHub نصب کنید:
npm install https://github.com/ariaservice/arianet-js/releases/download/v0.1.0/arianet-0.1.0.tgz
شروع سریع
در پنل یک توکن شخصی API بسازید و آن را export کنید:
export ARIANET_TOKEN="paste-your-token-here"
import { Client } from "arianet";
const client = new Client(); // reads ARIANET_TOKEN
const page = await client.cloud.listServers({ per_page: 50 });
for (const server of page.data) {
console.log(server.id, server.name, server.status);
}
توکن را فقط سمت سرور نگه دارید و هرگز آن را در کد مرورگر قرار ندهید.
گروههای API
| ویژگی | وب سرویس |
|---|---|
client.core | حساب، توکنها، VPS، کلیدهای SSH، فایروالها، موجودی و فاکتورها |
client.cloud | ابر آریانت |
client.regionalVps | VPS منطقهای |
client.hosting | هاستینگ |
client.baremetal | سرور اختصاصی |
client.sms | پیامک |
نام متدها شکل camelCase همان operationId است. ترتیب آرگومانها: پارامترهای مسیر، بدنه JSON، شیء query (با نوع <Group><Method>Query، مثلاً CloudListServersQuery) و در آخر RequestOptions (idempotencyKey، headers، region و signal). هر متد یک Promise از پاسخ JSON decode شده برمیگرداند.
const server = await client.cloud.createServer({
name: "web-1",
plan_id: 101,
image: "ubuntu-24.04",
datacenter: "ovh",
});
تنظیمات
const client = new Client({
token: process.env.MY_TOKEN, // default: ARIANET_TOKEN
baseUrl: "https://api.ariaservice.net", // default, or ARIANET_API_URL
timeout: 60_000,
maxRetries: 3,
maxRetryWait: 60_000,
});
timeout و maxRetryWait بر حسب میلیثانیهاند. اگر Retry-After بیشتر از maxRetryWait باشد، RateLimitError بلافاصله پرتاب میشود و مقدار retryAfter (ثانیه) را دارد. برای اینکه تکرار سفارش حتی بعد از ریاستارت برنامه هم امن باشد، { idempotencyKey } را خودتان بفرستید.
مدیریت خطا
import { APIConnectionError, APIError, ErrorCode } from "arianet";
try {
await client.core.createServer(order);
} catch (err) {
if (err instanceof APIError) {
if (err.code === ErrorCode.INSUFFICIENT_BALANCE) {
// top up the wallet
}
console.error(err.status, err.code, err.message);
} else if (err instanceof APIConnectionError) {
// no answer: DNS, TLS, timeout
} else {
throw err;
}
}
هر وضعیت HTTP کلاس خطای خودش را دارد: AuthenticationError (۴۰۱)، PaymentRequiredError (۴۰۲)، PermissionDeniedError (۴۰۳)، NotFoundError (۴۰۴)، ConflictError (۴۰۹)، UnprocessableEntityError (۴۲۲)، RateLimitError (۴۲۹) و InternalServerError (۵xx)؛ همه از APIError ارث میبرند. err.reason در بعضی خطاها جزئیات بیشتری میدهد.
ریجن و endpointهای جدید
const iran = client.regionalVps.withRegion("iran-1");
const servers = await iran.listServers();
// Any path, with the same auth, retries and errors:
await client.request("GET", "/cloud/v1/new-endpoint", { query: { page: 2 } });