إجراء Dataverse وأساليب الدالة للصفحات التوليدية

استخدم أساليب الإجراء والدالة للكائن dataApi لاستدعاء واجهات برمجة التطبيقات المخصصة Dataverse المرتبطة بالصفحة.

Note

أساليب العمل والدالة اختيارية في العقد المشترك dataApi . لا يقوم بعض المضيفين بتنفيذها، لذا تحقق من وجود أسلوب قبل استدعائه. لا يعني الأسلوب الموجود أن العملية مرتبطة بالصفحة أو ممكنة لوقت التشغيل أو مسموح بها للمستخدم الحالي. على عكس أساليب الموصل، لا تطرح هذه الأساليب أبدا حالات الفشل المتوقعة؛ يتم حلها باستخدام ok: false ورمز خطأ بدلا من ذلك. التعامل مع خصائص والنتيجة okerror بشكل صريح.

listBoundActions إرجاع الإجراءات والوظائف التي يسمح بها تكوين وقت التشغيل الحالي للصفحة عند تمكين هذا الاكتشاف؛ ليس ضمانا أن المستخدم الحالي يحتفظ بامتيازات Dataverse اللازمة لتنفيذ كل عملية مدرجة.

Method	Description
executeAction	استدعاء واجهة برمجة تطبيقات Dataverse مخصصة مرتبطة بالصفحة كإجراء.
executeFunction	استدعاء واجهة برمجة تطبيقات مخصصة Dataverse مرتبطة بالصفحة كدالة.
listBoundActions	يسرد واجهات برمجة التطبيقات المخصصة Dataverse (الإجراءات والوظائف) المرتبطة بالصفحة.

طريقة executeAction

استدعاء واجهة برمجة تطبيقات Dataverse مخصصة يرتبط بها صانع الصفحة كإجراء (رسالة قد تغير البيانات).

Parameters

تعيين قيمة لهذه المعلمة المطلوبة.

Name	النوع	Description
request	طلب DataverseAction	الإجراء لاستدعاء ومعلمات الإدخال الخاصة به.

طلب DataverseAction

Name	النوع	Description
name	string	الاسم الفريد لواجهة برمجة التطبيقات المخصصة، مسبوقة بالناشر، مثل new_ApproveExpenseReport.
parameters	object	(اختياري) معلمات الإدخال المطلوبة من قبل الإجراء، التي تم مفتاحها بواسطة اسم فريد للمعلمة.
boundTo	object	(اختياري) مرجع صف الهدف (entityName و id) للإجراءات المرتبطة بالوحدة. حذف الإجراءات العمومية (غير المنضمة).

إرجاع

وعد يحتوي على DataverseActionResult. لا يطرح هذا الأسلوب أبدا حالات الفشل المتوقعة (مثل خطأ إذن 403 أو معلمة 400 غير صحيحة أو عدم ربط العملية أو تمكينها) — تحقق من الخاصية ok بدلا من ذلك.

DataverseActionResult

Name	النوع	Description
ok	boolean	يشير إلى ما إذا كان الإجراء قد نجح أم لا.
status	number	رمز حالة HTTP الذي تم إرجاعه بواسطة Dataverse، أو 0 عندما لا تتوفر حالة HTTP. 0 قد تعني الحالة أن وقت التشغيل رفض الاستدعاء قبل إرساله (على سبيل المثال، not_enabledأو invalid_parameterwrong_operation_kindnot_permittedinvalid_bound_tonot_bound)، أو فشل الطلب دون استجابة HTTP، أو أن النتيجة غير معروفة (indeterminate هي ).true استخدم error.code و indeterminate لفصل هذه الحالات عن بعضها البعض.
outputs	object	معلمات الإخراج التي تم إرجاعها بواسطة الإجراء، التي تم مفتاحها باسم فريد. فارغ للإجراءات بدون مخرجات.
indeterminate	boolean	(اختياري) true عندما تكون المهلة أو فشل آخر بعد الإرسال يعني أن الخادم قد ارتكب الإجراء؛ لا تعيد المحاولة تلقائيا.
error	object	(اختياري) تفاصيل الخطأ عندما ok يكون false، بما في ذلك قابل code للقراءة الآلية ومطهر message. codeهو واحد من not_enabledأو not_boundأو not_permittedwrong_operation_kindأو indeterminateinvalid_bound_tonetworkinvalid_parameterرمز حالة HTTP للإجراء كسلسلة (على سبيل المثال، "404") عندما أرجع Dataverse استجابة خطأ، أو "0" عندما لا تتوفر حالة HTTP. not_permitted يعني أن الإجراء أو الدالة ليست في قائمة السماح الخاصة بالبيئة للصفحات التوليدية - فهي لا تشير إلى ما إذا كان المستخدم الحالي يحتفظ بامتيازات Dataverse لتشغيلها. عادة ما تظهر فشل الامتيازات كما هو الحال status: 403 مع رمز "403"الخطأ ؛ إذا لم يتمكن المضيف من تحديد حالة HTTP، فإنه يرجع status: 0 بدلا من ذلك.

مثال على executeAction

if (!dataApi.executeAction) {
  throw new Error("executeAction isn't available on this page.");
}

const result = await dataApi.executeAction({
  name: "new_ApproveExpenseReport",
  parameters: { comments: "Approved by manager" },
  boundTo: { entityName: "new_expensereport", id: "30dc51e9-947d-47d8-ad48-4fc48fba4a95" },
});

if (result.ok) {
  console.log(result.outputs);
}
else {
  console.log(result.error?.code);
}

طريقة executeFunction

استدعاء واجهة برمجة تطبيقات Dataverse مخصصة يرتبط بها صانع الصفحة كدالة (رسالة للقراءة فقط مع دلالات GET).

Parameters

تعيين قيمة لهذه المعلمة المطلوبة.

Name	النوع	Description
request	طلب DataverseFunction	الدالة لاستدعاء ومعلمات الإدخال الخاصة بها.

طلب DataverseFunction

Name	النوع	Description
name	string	الاسم الفريد لواجهة برمجة التطبيقات المخصصة، مسبوقة بالناشر، مثل new_GetExchangeRate.
parameters	object	(اختياري) معلمات الإدخال المطلوبة من قبل الدالة، التي تم مفتاحها بواسطة اسم فريد للمعلمة.
boundTo	object	(اختياري) مرجع الصف الهدف (entityName و id) للوظائف المرتبطة بالوحدة. حذف الدالات العمومية (غير المنضمة).

إرجاع

وعد يحتوي على DataverseActionResult. كما هو الحال مع executeAction، لا يطرح هذا الأسلوب أبدا حالات الفشل المتوقعة — تحقق من الخاصية ok بدلا من ذلك.

مثال executeFunction

if (!dataApi.executeFunction) {
  throw new Error("executeFunction isn't available on this page.");
}

const result = await dataApi.executeFunction({
  name: "new_GetExchangeRate",
  parameters: { currencyCode: "EUR" },
});

if (result.ok) {
  console.log(result.outputs);
}

طريقة listBoundActions

يسرد واجهات برمجة التطبيقات المخصصة Dataverse (الإجراءات والوظائف) التي ربطها صانع بالصفحة.

Parameters

لا يوجد.

إرجاع

وعد يحتوي على صفيف من إدخالات DataverseActionInfo. إرجاع صفيف فارغ عند عدم تمكين الاكتشاف لوقت التشغيل.

DataverseActionInfo

DataverseActionInfo يعكس ما ربطه صانع الصفحة بهذا الإجراء أو الوظيفة، وليس بيانات تعريف Dataverse المباشرة. لا تستخدمه لإنشاء نماذج إدخال أو التحقق من صحة المخرجات — تحقق من متطلبات المعلمات وأشكال الإخراج مقابل تعريف واجهة برمجة تطبيقات Dataverse المخصص الفعلي.

Name	النوع	Description
name	string	الاسم الفريد (المنطقي) لواجهة برمجة تطبيقات Dataverse المخصصة.
displayName	string	اسم العرض لواجهة برمجة تطبيقات مخصصة.
isFunction	boolean	true إذا كانت واجهة برمجة تطبيقات Dataverse المخصصة دالة (للقراءة فقط)؛ false إذا كان إجراء، بما في ذلك عندما لا يتم تسجيل هذه القيمة في وقت الربط.
bindingType	string	نوع الربط: "Global" أو "Entity".
boundEntityLogicalName	string	(اختياري) الجدول الذي يرتبط به الإجراء أو الدالة، عندما bindingType يكون ."Entity"
parameters	Object[]	معلمات الإدخال المسجلة عند ربط واجهة برمجة تطبيقات Dataverse المخصصة بالصفحة، لكل منها و namedeclaredKind. type دائما "unknown" ودائما optionalfalse - لا يعكس أي منهما بيانات التعريف الفعلية لواجهة برمجة تطبيقات Dataverse المخصصة.
outputs	Object[]	دائما صفيف فارغ. لا يسجل اكتشاف الربط معلمات الإخراج.

مثال لـ listBoundActions

const actions = await dataApi.listBoundActions?.();