شعار أوراباسي
aurabaseمستندات
مستندات›Edge Functions›SDK reference

جافا سكريبت SDK: الوظائف

كل طريقة من أساليب aura.functions وتوقيعها والدور الذي تحتاجه وما تعيده.

8 د قراءة·المستوى مرجع·تمت المراجعة في 12‏/10‏/2026
تم إنشاء هذا النص الإنجليزي تلقائيًا من النص الأصلي الفرنسي ولم تتم مراجعته بعد.
تمت ترجمة هذه الصفحة تلقائيًا. النسخة الإنجليزية موثوقة.
#
الإعداد

1. احصل على العميل

aura.functions هو FunctionsService. أنت تقريبًا لا تبنيها بنفسك.

client.tstypescript
import { createClient } from '@aurabase/aurabase-js'

const aura = createClient('https://my-app.aurabase.cloud', 'aura_anon_…')
aura.functions.invoke('hello')

تم تثبيت الحزمة @aurabase/functions مع @aurabase/aurabase-js. قم بتثبيته بمفرده فقط إذا قمت بتكوين العميل الخاص بك من @aurabase/core. يتطلب Node.js 20 أو إصدار أحدث ويشحن وحدات ES وCommonJS مع إعلانات النوع.

تُرجع كل دالة Promise<AuraResponse<T>>، وهو كائن { data, error } لا يُرمى أبدًا:

القضيةdataerror
النجاحالقيمةnull
النجاح بدون محتوى (204، نص فارغ)nullnull
الفشلnullAuraError

اختبر data بدلاً من error عندما تحتاج إلى القيمة: عندها فقط يعرف TypeScript أنها ليست null.

الطريقةالدور مطلوب
invokeالمفتاح العام (anon) أو المستخدم أو service_role
كل وسيلة أخرىservice_role (الخادم فقط)
#
اتصل

2. استدعاء

signaturetypescript
invoke<T = unknown>(
  name: string,
  options?: {
    body?: unknown
    method?: string
    path?: string
    headers?: Record<string, string>
    signal?: AbortSignal
    timeout?: number
    responseType?: 'json' | 'text' | 'blob' | 'arrayBuffer'
  },
): Promise<AuraResponse<T>>
الخيارالافتراضي
bodyلا شيءJSON قابل للتسلسل. تقوم المصفوفة المكتوبة Blob أو ArrayBuffer أو FormData أو URLSearchParams أو ReadableStream بإرجاع الخطأ invalid_body دون أي طلب.
method'POST'الطريقة التي تراها الوظيفة
path'/'المسار الذي تراه الوظيفة
headersلا شيءالرؤوس المعطاة للوظيفة. يتم تجاهل authorization و apikey و x-request-id و x-aura-* بواسطة النظام الأساسي.
timeoutالافتراضي للعميل، 30 ثانيةميلي ثانية. يلغي المكالمة ويعيد الرمز timeout.
signalلا شيءالخاص بك AbortSignal. تقوم المكالمة الملغاة بإرجاع الرمز timeout.
responseType'json'كيف يتم فك تشفير data: قيمة محللة، أو سلسلة، أو Blob أو ArrayBuffer

تم ترميز name في عنوان URL، لذا لا يمكن للقيمة التي تحتوي على / أو ? أو # أن تترك موضعها. ببساطة لم يتم العثور على الاسم الذي يحتوي على مثل هذه الأحرف.

يقوم invoke بتحديث جلسة مستخدم منتهية الصلاحية أولاً، ويرسل JWT للمستخدم عند وجود جلسة، ولا يعيد محاولة الاتصال مطلقًا.

كيفية استخدامه: استدعاء وظيفة. كيف يفشل: الأخطاء والمهلات وإعادة المحاولة.

#
إدارة

3. قائمة والحصول على

signaturestypescript
list(): Promise<AuraResponse<FunctionDef[]>>
get(nameOrId: string): Promise<AuraResponse<FunctionDef>>

كلاهما يحتاج إلى مفتاح service_role. get يقبل اسم أو معرف ؛ إذا تم تسمية وظيفة مثل معرف، يفوز الاسم. يحتوي FunctionDef على الكود المصدري ومتغيرات الوظيفة، ولهذا السبب يستقبل المفتاح العام 403.

لا توجد طريقة لنشر وظيفة أو تحديثها أو حذفها أو كتابة الأسرار: استخدم HTTP API أو CLI.

#
الخلفية

4. الوظائف

signaturestypescript
enqueueJob(
  functionName: string,
  options?: { payload?: unknown; delaySecs?: number; maxAttempts?: number },
): Promise<AuraResponse<Job>>

listJobs(options?: { status?: string; limit?: number }): Promise<AuraResponse<Job[]>>
getJob(jobId: string): Promise<AuraResponse<Job>>
  • يقوم enqueueJob بإرجاع { code: 'bad_request', status: 400 } بدون أي طلب عندما يكون functionName فارغًا أو مسافات فقط، ويقطع الاسم بخلاف ذلك.
  • يقوم listJobs بتصفية status (pending, running, completed, failed, dead) ويعيد ما بين 1 إلى 500 وظيفة، 50 بشكل افتراضي.
  • لا توجد طريقة لإعادة محاولة المهام الميتة: راجع قائمة انتظار الأحرف الميتة .
#
الجدول الزمني

5. كرون

signaturestypescript
listCronJobs(): Promise<AuraResponse<CronJob[]>>
createCronJob(
  name: string,
  schedule: string,
  functionName: string,
  options?: { payload?: unknown },
): Promise<AuraResponse<CronJob>>
deleteCronJob(name: string): Promise<AuraResponse<null>>

يحتوي schedule على 5 أو 6 حقول بالتوقيت العالمي المنسق (UTC). deleteCronJob يأخذ الاسم ويعيد 404 لاسم غير معروف. لا يوجد getCronJob أو updateCronJob.

#
مرجع

6. الأنواع والأخطاء

تم التصدير بواسطة @aurabase/aurabase-js و @aurabase/functions:

importstypescript
import {
  FunctionsHttpError,
  FunctionsRelayError,
  isRelayStatus,
  type FunctionsResponseType,
} from '@aurabase/aurabase-js'
تصديرما هو عليه
FunctionsHttpErrorتم الرد على وظيفتك (أو مسار الإدارة) بخطأ. error.context يحمل الجسد الذي أعاده.
FunctionsRelayErrorفشل النظام الأساسي: الشبكة (status 0) أو 502, 503, 504 التي تنتجها البوابة أو وقت التشغيل.
isRelayStatus(status)true لـ 0, 502, 503, 504.
FunctionsResponseType`'json' \

يمتد كلا فئتي الخطأ إلى AuraError، لذا فإن isAuraError(error) صحيح. AuraError يحتوي على status و code و message و details و retryAfter و الحروف isNotFound و isUnauthorized و isForbidden و isRateLimited.

أنواع البيانات المصدرة بواسطة @aurabase/aurabase-js:

اكتبالحقول
FunctionDefid, project_id, name, runtime, code, code_hash, env_vars, permissions, is_active, created_at, updated_at
FunctionPermissionsallow_net: string[], memory_mb: number, timeout_secs: number
Jobid, project_id, function_name, status, payload, attempts, max_attempts, error?, scheduled_at, started_at?, created_at, completed_at?
CronJobid, project_id, name, schedule, function_name, payload, is_active, last_run?, next_run?, created_at
AuraResponse<T>{ data, error, meta? }
خصائص متوافقة مع الإصدارات السابقة

عندما تقوم دالة بإرجاع كائن JSON، فإن data يحمل أيضًا خاصيتين غير قابلتين للإحصاء، body و status، يتم الاحتفاظ بهما للتعليمات البرمجية المكتوبة مقابل الإصدارات الأقدم. لا تعتمد عليها في التعليمات البرمجية الجديدة.