به محتوای اصلی

فانکشن‌ها

قوانین روی نوشتن و خواندن یک موجودیت می‌نشینند. فانکشن جای کاری است که به هیچ موجودیتی وصل نیست: یک آدرس HTTP که خودتان نامش را می‌گذارید و داخلش جاوااسکریپت می‌نویسید.

مثال‌های واقعی‌اش این‌هاست: فرم تماس که ایمیل می‌فرستد، وب‌هوک درگاه پرداخت که باید تأیید و ثبت شود، سبد خرید که باید در یک درخواست چند رکورد را با هم بسازد، یا صدا زدن یک سرویس بیرونی که کلیدش نباید در اپ کلاینت باشد.

اول سراغ API آماده بروید: خواندن، نوشتن، ثبت‌نام کاربر و «فقط رکوردهای خودش» همه بدون کد کار می‌کنند، و چک کردن ورودی (نوع فیلد، «الزامی») کار خود جدول است. فانکشن برای کاری است که این‌ها انجام نمی‌دهند — و وقتی نوشتید، کوتاه نگهش دارید و بقیه را به همان جدول بسپارید.

فرم تماس با یک فانکشن۵:۱۳با صدای گوینده و زیرنویسقدم‌ها و متن کامل ویدیو

آدرس

POST https://api.fikaro.ir/{اسلاگ-پروژه}/v1/fn/{نام-فانکشن}

GET هم کار می‌کند. متدهای دیگر ۴۰۵ می‌گیرند.

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

سطح دسترسی

هر فانکشن یکی از این سه را دارد. پیش‌فرض بسته‌ترین است، چون باز کردنش یک تصمیم آگاهانه می‌خواهد:

سطحچه کسی می‌تواند صدا بزند
فقط کلید API (پیش‌فرض)سرور خودتان، با کلید API پروژه
کلید API + کاربران واردشدهعلاوه بر آن، اپ کلاینت با توکن کاربر
عمومیبا کلید فقط خواندنی، و حتی بدون احراز هویت

«عمومی» برای فرم تماس یا وب‌هوک درگاه درست است — جایی که فرستنده کلید ندارد. برای بقیه، پیش‌فرض را نگه دارید.

آنچه کد شما در اختیار دارد

داخل فانکشن یک شیء ctx دارید. هیچ awaitی لازم نیست؛ همه‌چیز هم‌زمان جواب می‌دهد.

درخواست و پاسخ

const { method, path, query, body, headers } = ctx.request;

ctx.respond({ ok: true });        // ۲۰۰ با این بدنه
ctx.respond(201, { id: rec.id }); // با کد وضعیت دلخواه

ctx.respond اجرا را همان‌جا تمام می‌کند — خطی که بعدش بنویسید اجرا نمی‌شود.

برای رد کردن با خطا:

if (!ctx.request.body.email) {
  ctx.reject("ایمیل الزامی است");
}

دیتابیس، با دو دسته

const rows = ctx.db.list("order", { limit: 20 });
const one  = ctx.db.get("order", id);
ctx.db.create("order", { total: 1000 });
ctx.db.update("order", id, { status: "paid" });
ctx.db.delete("order", id);

فیلتر، جست‌وجو و مرتب‌سازی را به خود list بسپارید، نه به یک حلقه در جاوااسکریپت — همان کاری است که API انجام می‌دهد، سمت دیتابیس:

const rows = ctx.db.list("question", {
  filter: { language: "arabic", "difficulty[in]": ["easy", "medium"] },
  search: "فعل",
  sort: "-createdAt",
  limit: 50,
});

کلید فیلتر نام فیلد است و می‌تواند عملگر بگیرد، مثل "price[gte]": 1000؛ عملگرها همان‌هایی‌اند که در کار با API آمده. کلیدی که قابل خواندن نباشد خطای invalid_filter می‌دهد.

رابطه‌ها را هم مثل ?include= در API، با include در همان list بخوانید؛ مثلاً خدمت‌هایی که یک کارشناس ارائه می‌دهد (رابطهٔ چندبه‌چند):

const [person] = ctx.db.list("staff", {
  filter: { id: staffId },
  include: "services",
  limit: 1,
});
// person.services: آرایهٔ خدمت‌های وصل‌شده

در پروژه‌ای که سیاست دسترسی فعال دارد، include هنوز پشتیبانی نمی‌شود و خطای policy_path_unsupported می‌دهد.

فیلدهایی که خودتان به user اضافه کرده‌اید (مثل نام نمایشی) با ctx.db.update("user", id, …) عوض می‌شوند. خود حساب — ایمیل، موبایل، نقش و رمز — از این راه عوض نمی‌شود و خطای user_account_field می‌دهد.

ctx.db با دسترسی صداکننده کار می‌کند: اگر کاربری با توکن خودش آمده و موجودیت روی «فقط رکوردهای خود کاربر» تنظیم شده، همان محدودیت اینجا هم برقرار است.

در موجودیت policy، همین grantهای ردیفی و محدودیت‌های فیلدی در REST و ctx.db اعمال می‌شوند. خواندن والد، مجوز فرزند یا جدول خصوصی membership/share نمی‌دهد. برای پروفایل خود کاربر، فانکشن را با سطح «کاربران واردشده» ذخیره و صریح فعال کنید:

const profile = ctx.db.get("user", ctx.user.id);
ctx.respond({ mobile: profile.mobile });

این خواندن هم‌زمان است و به مجوز خواندن عادی همان user وابسته است. اگر خواندن رد شده باشد، ctx.db آن را دور نمی‌زند. password_hash همواره پنهان می‌ماند؛ برای این کار توکن را forward نکنید و خواندن مقدماتی با admin انجام ندهید. به‌روزرسانی user شخص دیگری با حدس email/mobile نیز اختیار ایجاد نمی‌کند.

JSON سیاست در ویرایشگر، اعداد صحیح و اعشاری پشتیبانی‌شده را دقیق حفظ می‌کند. عدد جاوااسکریپت در فانکشن و arithmetic قوانین CEL همچنان عدد ممیزشناور است؛ برای محاسبات exact پولی به عدد بزرگِ جاوااسکریپت اتکا نکنید.

ctx.db.admin همان عملیات را با دسترسی کامل شما انجام می‌دهد و قوانین دسترسی را دور می‌زند. برای کاری مثل «شمارش کل سفارش‌ها» لازم است — ولی هر جا نوشتیدش، یعنی صریحاً گفته‌اید این خط از طرف پروژه اجرا می‌شود، نه از طرف کاربر. کم استفاده‌اش کنید.

چه کسی صدا زده

ctx.auth  // "key" | "user" | "publishable" | "anonymous"
ctx.user  // { id, role } — فقط وقتی با توکن کاربر آمده باشد

روی یک فانکشن عمومی، ctx.auth تنها راه تشخیص است. اگر رفتار متفاوتی برای کاربر واردشده می‌خواهید، همین‌جا شاخه بزنید.

سرویس بیرونی و secrets

const res = ctx.http.post(
  "https://example.com/api",
  ctx.request.body,
  { headers: { Authorization: "Bearer " + ctx.secrets.PARTNER_KEY } }
);
if (!res.ok) {
  ctx.respond(502, { error: "سرویس مقصد جواب نداد" });
}
ctx.respond(res.json);

ctx.secrets مقادیر محرمانه‌ی پروژه است. در پاسخ و لاگ نمی‌آیند مگر خودتان بنویسیدشان — پس کلید را در پیام خطا برنگردانید.

secrets را در پنل تعریف می‌کنید، از دو جا: تنظیمات پروژه ← کارت «secrets پروژه»، یا دکمهٔ «secrets» بالای فهرست فانکشن‌ها در همین صفحه. نام انگلیسی است (مثل SMS_PANEL_KEY) و مقدار بعد از ذخیره دیگر نشان داده نمی‌شود؛ فقط می‌شود عوضش کرد یا حذفش کرد. مثال رایج: کلید پنل پیامک یا درگاه پرداخت خودتان، که فانکشن با ctx.http صدایش می‌زند.

اشکال‌زدایی

ctx.log("رسید:", ctx.request.body);

خروجی ctx.log فقط در کنسول اجرای آزمایشی پنل دیده می‌شود و هرگز در پاسخ API نمی‌آید.

ایجنت (ctx.ai.ask)

فانکشن می‌تواند از یکی از ایجنت‌های همین حساب بپرسد و با جوابش کاری بکند؛ مثلاً هر تیکت تازه را با ایجنت دسته‌بند برچسب بزند، بدون سرور جدا و بدون کلید ایجنت:

ctx.ai.ask(agentId, question, { history, data })  // history و data اختیاری‌اند
  • agentId شناسهٔ ایجنت است (صفحهٔ «کلید و API» همان ایجنت) و question متن پرسش. history و data همان‌هایی‌اند که API ایجنت می‌گیرد و همان‌طور بررسی می‌شوند.
  • فراخوانی همزمان است، مثل ctx.db؛ await نمی‌خواهد.
  • جواب دقیقاً همان بدنهٔ پاسخ API ایجنت است: answered، answer، output، sources، requestId، handoff، knowledgeIds و pendingAction (که این‌جا همیشه null است).
  • هشدار «ارجاع به انسان» برای پرسش‌های فانکشن فرستاده نمی‌شود؛ اگر handoff در جواب true بود، کار بعدی را خود کدتان انجام دهد.
  • فقط ایجنت‌های حسابی که صاحب این پروژه است جواب می‌دهند. شناسهٔ ایجنت حساب دیگر، ایجنت حذف‌شده و شناسهٔ نادرست همه یک خطا دارند: bot_not_found.

مثال برچسب تیکت (فانکشن new_ticket، با یک ایجنت برچسبی مثل دسته‌بند تیکت، که output آن همان رشتهٔ برچسب است):

const t = ctx.db.create("ticket", { title: ctx.input.title, body: ctx.input.body });
try {
  const r = ctx.ai.ask("<شناسهٔ ایجنت>", t.body, { data: { title: t.title } });
  if (r.answered && r.output) ctx.db.admin.update("ticket", t.id, { label: r.output });
} catch (e) {
  ctx.log("ایجنت جواب نداد:", e.code); // تیکت بی‌برچسب می‌ماند
}
ctx.respond(201, { id: t.id });

اگر ایجنت جواب ندهد، ctx.ai.ask یک شیء {code, message} پرتاب می‌کند که با try/catch می‌گیرید و روی e.code شاخه می‌زنید (برای rate_limit_exceeded، e.retryAfter هم ثانیه‌های صبر را دارد):

کدیعنی
bot_not_foundایجنت نیست، حذف شده یا مال حساب صاحب پروژه نیست
bot_pausedایجنت خاموش است
insufficient_fundsموجودی کیف پول کافی نیست، یا ایجنت به‌خاطر هزینهٔ ساعتی خاموش شده
cash_requiredفقط اعتبار هدیه مانده؛ هدیه پاسخ ایجنت را نمی‌پردازد
monthly_cap_reachedسقف هزینهٔ ماهانهٔ ایجنت پر شده
rate_limit_exceededپرسش‌ها از سقف سرعت پلن ایجنت یا حساب گذشت؛ e.retryAfter ثانیه صبر کنید
ai_unavailableسرویس الان در دسترس نیست یا مهلت ctx.ai در این اجرا تمام شده
output_invalidمدل جواب قابل‌استفاده‌ای نداد (هزینه‌اش گرفته شد)
input_required / input_too_longمتن پرسش خالی یا بلندتر از سقف است
invalid_data / invalid_historydata یا history شکل درست را ندارد
invalid_ai_callآرگومان‌ها نوع درست ندارند (شناسه و پرسش رشته، سومی شیء)
ai_call_limitبیش از ۲ بار در یک اجرا
ai_not_allowedاین‌جا ctx.ai بسته است (قانون‌ها، و تابعی که ایجنت صدا می‌زند)

خطایی که نگیرید فانکشن را با 500 function_failed تمام می‌کند، نه با 402: وضعیت کیف پول شما به صداکنندهٔ فانکشن گفته نمی‌شود. کد و پیام در گزارش اجرای فانکشن در پنل می‌آید.

  • هزینه و سقف‌ها درست مثل پرسش از API ایجنت است: از کیف پول شما (صاحب ایجنت) کم می‌شود، با همان نرخ و سقف ماهانه و همان قاعده که اعتبار هدیه پاسخ ایجنت را نمی‌پردازد. اجرای آزمایشی پنل هم پرسش واقعی است و هزینه دارد.
  • فانکشن باز یعنی خرج باز. اگر سطح دسترسی فانکشن «عمومی» یا «+ کاربران واردشده» باشد، هر کسی که آن را صدا بزند می‌تواند در هر درخواست تا ۲ پرسش پولی از کیف پول شما خرج کند. برای چنین فانکشنی سقف ماهانهٔ ایجنت را بگذارید، یا فقط وقتی بپرسید که واقعاً لازم است.
  • هر تلاش در سقف ۲ شمرده می‌شود، حتی وقتی رد شود (مثلاً bot_not_found یا کیف پول خالی)؛ ردهایی که به مدل نرسیده‌اند هزینه ندارند؛ output_invalid یعنی مدل جواب داده و هزینهٔ همان تلاش گرفته شده است.
  • حداکثر ۲ بار در هر اجرا. زمانی که ایجنت برای جواب صرف می‌کند از ۱۰ ثانیهٔ فانکشن کم نمی‌شود؛ پرسش‌های یک اجرا روی هم تا ۳۵ ثانیه وقت دارند و کار دیگر فانکشن همچنان ۱۰ ثانیه.
  • هر پرسش در «گزارش سؤال‌ها»ی ایجنت با منبع «فانکشن» ثبت می‌شود و سؤال بی‌جوابش هم مثل بقیه در «بی‌جواب» می‌آید.
  • ایجنتی که از فانکشن صدا زده شده، تابع نوشتنی‌اش را اجرا نمی‌کند؛ نوشتن را با ctx.db در همان فانکشن انجام دهید.
  • چرا در قانون‌ها نه: قانون کد وسط ذخیرهٔ رکورد اجرا می‌شود و جواب ایجنت ۷ تا ۱۷ ثانیه طول می‌کشد؛ یعنی هر ذخیره همین‌قدر کند می‌شد. در قانون، ctx.ai.ask همیشه خطای ai_not_allowed می‌دهد. به‌جایش، رکورد را با یک فانکشن بسازید و برچسب را همان‌جا بزنید، مثل مثال بالا.

یک مثال کامل

فرم تماس: عمومی، بدون کلید، با اعتبارسنجی و ثبت رکورد.

const { name, email, message } = ctx.request.body || {};

if (!email || !message) {
  ctx.reject("ایمیل و متن پیام الزامی است");
}
if (message.length > 2000) {
  ctx.reject("متن پیام طولانی است");
}

const rec = ctx.db.admin.create("contact_message", {
  name: name || "",
  email: email,
  message: message,
  source: ctx.auth,
});

ctx.respond(201, { id: rec.id });

ctx.db.admin اینجا لازم است چون صداکننده ناشناس است و اجازه‌ی نوشتن مستقیم ندارد — و همین یک خط، مرز بین «هر کسی می‌تواند پیام بفرستد» و «هر کسی می‌تواند در جدول بنویسد» را نگه می‌دارد.

محدودیت‌ها

  • بدنه‌ی درخواست تا ۱ مگابایت. فانکشن آرگومان می‌گیرد، نه فایل؛ برای بایت‌ها API فایل‌ها هست.
  • عمق فراخوانی ۳. فانکشنی که آدرس خودش را صدا بزند (یا حلقه‌ای از سرویس‌ها که برگردد اینجا) در عمق سوم قطع می‌شود.
  • فقط GET و POST.
  • ctx.ai.ask حداکثر ۲ بار در هر اجرا، با ۳۵ ثانیه برای همهٔ پرسش‌ها روی هم، جدا از ۱۰ ثانیهٔ خود فانکشن؛ در قانون‌ها کار نمی‌کند.

بیشتر بخوانید