أساليب الموصل للصفحات التوليدية

استخدم أساليب الموصل للكائن dataApi للعمل مع البيانات التي يعرضها موصل Power Platform المرتبط بالصفحة.

Note

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

على عكس أساليب الإجراء والدالة، ترفض أساليب الموصل الوعد الذي تم إرجاعه عند فشل المكالمة — على سبيل المثال، عندما لا يمكن حل مرجع الاتصال، أو يكون الاتصال غير مصرح به ولا يكمل المستخدم مطالبة الموافقة، أو يقوم الموصل بإرجاع حالة خطأ. executeConnectorOperation يحل مع ok: false لمعظم حالات الخطأ، ولكن لا يزال يرفض لعملية مفقودة، أو اتصال غير مصرح به (403) دون موافقة كاملة، أو فشل النقل. التفاف مكالمات الموصل في try/catch.

Method	Description
createConnectorRow	إنشاء صف جديد في جدول الموصل المحدد.
deleteConnectorRow	حذف صف من جدول الموصل المحدد.
executeConnectorOperation	استدعاء عملية مسماة مكشوفة بواسطة موصل REST (مفتاح العملية)، مثل مستخدمو Office 365.
getConnectorSwagger	استرداد تعريف Swagger (OpenAPI) للموصل.
getConnectorTableSchema	استرداد المخطط لجدول (يسمى أيضا كيانا أو قائمة) يعرضه الموصل.
listConnectorDatasets	يسرد مجموعات البيانات المتوفرة للموصل.
listConnectorOperations	يسرد العمليات التي يعرضها موصل REST (مفتاح العملية).
listConnectorTables	يسرد الجداول المتوفرة في مجموعة بيانات الموصل المحددة.
queryConnectorTable	الاستعلام عن جدول يعرضه الموصل بالخيارات المحددة.
retrieveConnectorRow	استرداد صف واحد من جدول الموصل المحدد.
updateConnectorRow	تحديث صف موجود في جدول الموصل المحدد.

طريقة queryConnectorTable

الاستعلام عن جدول يعرضه الموصل باستخدام الخيارات المحددة.

Parameters

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

Name	النوع	Description
connectorLogicalName	string	الاسم المنطقي لمرجع الاتصال المرتبط بالصفحة (على سبيل المثال، sp_shared_sharepointonline).
dataset	string	مجموعة البيانات التي تحتوي على الجدول، مثل عنوان URL لموقع SharePoint.
tableName	string	الاسم الداخلي للجدول، من الخاصية التي name تم إرجاعها بواسطة listConnectorTables. لا تستخدم اسم العرض.
options	QueryConnectorTableOptions	خيارات للاستعلام عن الجدول.

QueryConnectorTableOptions

Name	النوع	Description
select	string[]	(مستحسن) صفيف أسماء الأعمدة المراد استردادها.
filter	string	(اختياري) تعبير عامل التصفية المعتمد من قبل الموصل.
orderBy	string	(اختياري) تعبير ترتيب حسب معتمد من قبل الموصل.
top	number	(اختياري) الحد الأقصى لعدد الصفوف التي يجب إرجاعها.

إرجاع

وعد يحتوي على نتيجة العملية. عند نجاح العملية، يقوم الوعد بإرجاع كائن يحتوي على جدول بيانات مع النتائج مع هذه الخصائص:

Name	النوع	Description
rows	Object[]	صفيف بيانات الصف.
hasMoreRows	boolean	يشير إلى ما إذا كان هناك المزيد من الصفوف المتوفرة.

queryConnectorTable إرجاع صفحة واحدة من النتائج. لا ترجع دالة متابعة، ولا توجد حاليا طريقة مدعومة لإحضار الصفحة التالية. عندما hasMoreRows يكون true، يتم مطابقة صفوف أكثر مما تم إرجاعه. قم بتضييق نطاق الاستعلام باستخدام filter، أو أخبر المستخدم بأن النتائج غير مكتملة.

مثال على queryConnectorTable

if (!dataApi.listConnectorTables || !dataApi.queryConnectorTable) {
  throw new Error("Connector methods aren't available on this page.");
}

const tables = await dataApi.listConnectorTables(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing"
);
const documentsTable = tables.find((table) => table.displayName === "Documents");
if (!documentsTable) {
  throw new Error("The Documents table wasn't found in this dataset.");
}
const documentsTableName = documentsTable.name;

const result = await dataApi.queryConnectorTable(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName,
  {
    select: ["Title", "Modified"],
    top: 50,
  }
);

تفترض الأمثلة التالية أن documentsTableName الجدول name يحتوي على من listConnectorTables، كما هو موضح أعلاه.

طريقة listConnectorTables

يسرد الجداول (القوائم أو الكيانات) المتوفرة في مجموعة بيانات الموصل المحددة.

Parameters

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

Name	النوع	Description
connectorLogicalName	string	الاسم المنطقي لمرجع الاتصال المرتبط بالصفحة.
dataset	string	مجموعة البيانات لسرد الجداول لها.

إرجاع

وعد يحتوي على صفيف من معلومات الجدول. يحتوي كل إدخال على هذه الخصائص:

Name	النوع	Description
name	string	الاسم الداخلي للجدول.
displayName	string	اسم العرض للجدول.

مثال listConnectorTables

const tables = await dataApi.listConnectorTables?.(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing"
);

طريقة listConnectorDatasets

يسرد مجموعات البيانات المتوفرة للموصل، مثل مواقع SharePoint التي يمكن للاتصال الوصول إليها.

Parameters

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

Name	النوع	Description
connectorLogicalName	string	الاسم المنطقي لمرجع الاتصال المرتبط بالصفحة.

إرجاع

وعد يحتوي على صفيف من معلومات مجموعة البيانات. يحتوي كل إدخال على هذه الخصائص:

Name	النوع	Description
name	string	الاسم الداخلي أو المعرف لمجموعة البيانات.
displayName	string	اسم العرض لمجموعة البيانات.

مثال listConnectorDatasets

const datasets = await dataApi.listConnectorDatasets?.("sp_shared_sharepointonline");

طريقة listConnectorOperations

يسرد العمليات المعرفة في تعريف Swagger للموصل، باستثناء العمليات التي تم وضع علامة عليها داخليا، تم فرزها حسب اسم العرض. هذا الأسلوب مفيد للغاية لموصلات REST (مفاتيح التشغيل) مثل مستخدمو Office 365. بالنسبة للموصلات الجدولية، استخدم أساليب الاستعلام والصف بدلا من العمليات التي يسردها هذا الأسلوب.

Parameters

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

Name	النوع	Description
connectorLogicalName	string	الاسم المنطقي لمرجع الاتصال المرتبط بالصفحة.

إرجاع

وعد يحتوي على صفيف من معلومات العملية. يحتوي كل إدخال على هذه الخصائص:

Name	النوع	Description
name	string	معرف العملية كما هو محدد في تعريف Swagger للموصل. مرر هذه القيمة إلى executeConnectorOperation.
displayName	string	اسم العملية التي يمكن للبشر قراءتها للعرض، مثل ملخص Swagger. الرجوع إلى name إذا لم يتم تعريف ملخص.

مثال على listConnectorOperations

const operations = await dataApi.listConnectorOperations?.("sp_shared_sharepointonline");

طريقة getConnectorSwagger

استرداد تعريف Swagger (OpenAPI) للموصل، والذي يصف العمليات التي يعرضها. يصف المستند الذي تم إرجاعه الموصل بشكل عام. لا يتضمن مخططات عمود لكل جدول للموصلات الجدولية. استخدم getConnectorTableSchema لهذه المعلومات.

Parameters

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

Name	النوع	Description
connectorApiId	string	معرف واجهة برمجة تطبيقات الموصل، مثل /providers/Microsoft.PowerApps/apis/shared_sharepointonline. يختلف هذا المعرف عن الاسم المنطقي لمرجع الاتصال (connectorLogicalName) المستخدم من قبل معظم أساليب الموصل الأخرى.

إرجاع

وعد يحتوي على تعريف Swagger للموصل ككائن.

مثال على getConnectorSwagger

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

const swagger = await dataApi.getConnectorSwagger(
  "/providers/Microsoft.PowerApps/apis/shared_sharepointonline"
);

طريقة getConnectorTableSchema

استرداد المخطط (تعريفات الأعمدة) لجدول يعرضه الموصل. يحدد الموصل المخطط الذي يرجعه، ويختلف حسب الموصل. لا تفترض أنه يتضمن كل عمود ديناميكي قد يحتوي عليه الجدول.

Parameters

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

Name	النوع	Description
connectorLogicalName	string	الاسم المنطقي لمرجع الاتصال المرتبط بالصفحة.
dataset	string	مجموعة البيانات التي تحتوي على الجدول.
tableName	string	الاسم الداخلي للجدول، من الخاصية التي name تم إرجاعها بواسطة listConnectorTables. لا تستخدم اسم العرض.

إرجاع

وعد يحتوي على مخطط الجدول ككائن.

مثال على getConnectorTableSchema

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

const schema = await dataApi.getConnectorTableSchema(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName // from listConnectorTables
);

طريقة retrieveConnectorRow

استرداد صف واحد من جدول الموصل المحدد.

Parameters

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

Name	النوع	Description
connectorLogicalName	string	الاسم المنطقي لمرجع الاتصال المرتبط بالصفحة.
dataset	string	مجموعة البيانات التي تحتوي على الجدول.
tableName	string	الاسم الداخلي للجدول، من الخاصية التي name تم إرجاعها بواسطة listConnectorTables. لا تستخدم اسم العرض.
id	string	معرف الصف المراد استرداده.
options	استردادConnectorRowOptions	(اختياري) خيارات استرداد الصف.

استردادConnectorRowOptions

Name	النوع	Description
select	string[]	(مستحسن) صفيف أسماء الأعمدة المراد استردادها. إذا تم حذفه، فلن يتم إرسال أي $select إسقاط - يحدد الموصل الأعمدة التي سيتم إرجاعها ولا يضمن إرجاع كل عمود في الصف.

إرجاع

وعد يحتوي على بيانات الصف.

استرداد مثالConnectorRow

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

const row = await dataApi.retrieveConnectorRow(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName, // from listConnectorTables
  "1"
);

طريقة createConnectorRow

إنشاء صف جديد في جدول الموصل المحدد.

Parameters

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

Name	النوع	Description
connectorLogicalName	string	الاسم المنطقي لمرجع الاتصال المرتبط بالصفحة.
dataset	string	مجموعة البيانات التي تحتوي على الجدول.
tableName	string	الاسم الداخلي للجدول، من الخاصية التي name تم إرجاعها بواسطة listConnectorTables. لا تستخدم اسم العرض.
row	object	بيانات الصف المراد إنشاؤها.

إرجاع

وعد يحتوي على نص الاستجابة الذي تم إرجاعه بواسطة الموصل، إن وجد. اعتمادا على الموصل، يمكن أن تكون هذه القيمة الصف الذي تم إنشاؤه أو صف جزئي أو لا قيمة.

إنشاء مثال علىConnectorRow

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

const newRow = await dataApi.createConnectorRow(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName, // from listConnectorTables
  { Title: "New document" }
);

طريقة updateConnectorRow

تحديث صف موجود في جدول الموصل المحدد.

Parameters

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

Name	النوع	Description
connectorLogicalName	string	الاسم المنطقي لمرجع الاتصال المرتبط بالصفحة.
dataset	string	مجموعة البيانات التي تحتوي على الجدول.
tableName	string	الاسم الداخلي للجدول، من الخاصية التي name تم إرجاعها بواسطة listConnectorTables. لا تستخدم اسم العرض.
id	string	معرف الصف المراد تحديثه.
row	object	بيانات الصف المراد تحديثها.

إرجاع

وعد يحتوي على نص الاستجابة الذي تم إرجاعه بواسطة الموصل، إن وجد. اعتمادا على الموصل، يمكن أن تكون هذه القيمة صفا محدثا أو صفا جزئيا أو لا قيمة. لقراءة القيم الحالية للصف، قم باستدعاء retrieveConnectorRow.

مثال updateConnectorRow

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

const updatedRow = await dataApi.updateConnectorRow(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName, // from listConnectorTables
  "1",
  { Title: "Updated title" }
);

طريقة deleteConnectorRow

حذف صف من جدول الموصل المحدد.

Parameters

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

Name	النوع	Description
connectorLogicalName	string	الاسم المنطقي لمرجع الاتصال المرتبط بالصفحة.
dataset	string	مجموعة البيانات التي تحتوي على الجدول.
tableName	string	الاسم الداخلي للجدول، من الخاصية التي name تم إرجاعها بواسطة listConnectorTables. لا تستخدم اسم العرض.
id	string	معرف الصف المراد حذفه.

إرجاع

وعد يحتوي على نتيجة العملية. عند نجاح العملية، لا ترجع أي قيمة.

مثال deleteConnectorRow

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

await dataApi.deleteConnectorRow(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName, // from listConnectorTables
  "1"
);

طريقة executeConnectorOperation

استدعاء عملية مسماة مكشوفة بواسطة موصل REST (مفتاح العملية)، مثل HTTP أو Teams send-message أو مستخدمو Office 365. يجب أن تستخدم الموصلات الجدولية أساليب الاستعلام والصف CRUD بدلا من ذلك.

Parameters

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

Name	النوع	Description
connectorLogicalName	string	الاسم المنطقي لمرجع الاتصال المرتبط بالصفحة.
operationName	string	معرف العملية كما هو محدد في تعريف Swagger للموصل.
parameters	object	المعلمات المطلوبة من قبل العملية. تمرير كائن فارغ ({}) إذا لم تأخذ العملية أي معلمات — هذه المعلمة مطلوبة حتى عندما لا يوجد شيء لإرساله.

إرجاع

وعد يحتوي على نتيجة العملية مع هذه الخصائص. يرفض الوعد إذا تعذر حل مرجع الاتصال، ولا يمكن استرداد تعريف Swagger للموصل، أو لم يتم العثور على العملية فيه، أو لا يمكن إرسال المكالمة، أو الاتصال غير مصرح به (HTTP 403) ولا يكمل المستخدم مطالبة الموافقة على الاتصال.

Name	النوع	Description
ok	boolean	true عندما تكون حالة HTTP الأساسية أقل من 400. تتضمن هذه الحالة حالات إعادة التوجيه (3xx)، لذلك لا تعامل ok وحدها كدليل على أن العملية قد أرجعت البيانات — أيضا تحقق أو status افحص body.
status	number	رمز حالة HTTP الخام الذي تم إرجاعه بواسطة الموصل.
body	unknown	نص استجابة JSON الذي تم تحليله، أو السلسلة الأولية إذا لم يكن النص الأساسي JSON.

مثال على executeConnectorOperation

يفترض المثال التالي عملية تسمى CopyFile تقبل المعلمات sourceUrl و destinationUrl . تحقق من معرف العملية ومعلماته مقابل تعريف Swagger الخاص بالموصل (على سبيل المثال، مع listConnectorOperations أو getConnectorSwagger) قبل استخدامه، نظرا لأن العمليات المتاحة والمعلمات الخاصة بها تختلف حسب الموصل.

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

try {
  const result = await dataApi.executeConnectorOperation(
    "sp_shared_sharepointonline",
    "CopyFile",
    { sourceUrl: "/sites/Marketing/Shared Documents/file.docx", destinationUrl: "/sites/Sales/Shared Documents/file.docx" }
  );

  if (result.ok) {
    console.log(result.body);
  }
  else {
    console.log(result.status);
  }
}
catch (error) {
  console.log(error);
}