استخدم دالة Patch لإنشاء سجلات وتحريرها

  • 8 دقائق

تستخدَم دالة Patch لإنشاء سجلات وتحريرها فِي مصدر بيانات عند استخدام عنصر تحكم نموذج لا يلبي احتياجاتك. يتم استخدام دالة Patch فِي أغلب الأحيان عندما تحتاج إلى العمل بناءً على البيانات دون تفاعل المستخدم بطريقة متكررة. يمكنك استخدامه أيضاً إذا كان تصميم تطبيقك لا يسمح باستخدام النماذج.

استخدم دالة Patch لإنشاء سجل

يمكن استخدام دالة Patch لإنشاء سجل جديد فِي مصدر البيانات. لإنشاء سجل جديد، توجد ثلاثة أجزاء للمعادلة.

  1. قم بتضمين اسم مصدر البيانات الذي تريد تحريره. يمكن أن يكون هذا مصدر بيانات جدولي (مثل Microsoft Dataverse أو SharePoint) أو مجموعة. على سبيل المثال، تستخدم CustomerOrders كاسم لمصدر البيانات.

  2. تعمل دالة Defaults على إرجاع سجل يحتوي على القيم الافتراضية لمصدر البيانات. إذا لم يكن لعمود داخل مصدر البيانات قيمة افتراضية، فلن تكون هذه الخاصية موجودة. باستخدام دالة Defaults مع مصدر البيانات، يقوم هذا بإخطار دالة Patch لإنشاء سجل جديد.

  3. قم بتضمين الأعمدة التي تريد نشرها فِي السجل الجديد. تقوم هنا بتحديد اسم العمود المراد تحديثه متبوعًا بالقيمة للكتابة إلى هذا العمود. بالنسبة لهذا المثال، تقوم بتحديث عمود Region وCountry مع قيمة سلسلة.

وتكون المعادلة على النحو التالي:

Patch(CustomerOrders, Defaults(CustomerOrders), {Region: "Americas", Country: "Canada"})

تقوم هذه المعادلة بإنشاء سجل جديد فِي مصدر بيانات CustomerOrders وتقوم بتعيين Region إلى Americas وCountry إلى Canada. لاحظ أنه لا يتم تعريف أية معلومات مفتاح أساسية (عمود المعرف) التي يتم تحديثها بواسطة مصدر البيانات وفقًا لإعداداته.

استخدم دالة Patch لتحرير سجل

من الممكن أيضًا تحرير سجل فِي مصدر البيانات. لتحرير سجل واحد، توجد ثلاثة أجزاء للمعادلة.

  1. قم بتضمين اسم مصدر البيانات الذي تريد تحريره. يمكن أن يكون هذا مصدر بيانات جدولي (مثل Dataverse أو SharePoint) أو مجموعة. على سبيل المثال، تستخدم CustomerOrders كاسم لمصدر البيانات.

  2. السجل الذي تريد تحريره فِي مصدر البيانات. الطريقة الأكثر شيوعاً لتحديد هذا السجل هي استخدام دالة LookUp لاسترداد السجل من مصدر البيانات. وهناك خيار آخر إذا كنت تستخدم معرض وتريد تحديث السجل الحالي هو استخدام دالة ThisItem للرجوع إلى السجل. بالنسبة لهذا المثال، تستخدم دالة "LookUp".

  3. قم بتضمين التغييرات التي تريدها إجراءها. تقوم هنا بتحديد اسم العمود المراد تحديثه متبوعًا بالقيمة للكتابة إلى هذا العمود. بالنسبة لهذا المثال، تقوم بتحديث عمود Region وCountry مع قيمة سلسلة.

وتكون المعادلة على النحو التالي:

Patch(CustomerOrders, LookUP(CustomerOrders, ID = 1), {Region: "Asia", Country: "China"})

تعمل هذه المعادلة على تحديث السجل بمعرف 1 فِي الجدول CustomerOrders من خلال تعيين عمود Region إلى Asia وعمود Country إلى China. في حالة وجود قيم موجودة فِي هذه الحقول، تتم الكتابة فوقها.

تحديث الأعمدة بدالة Patch

إن المنطق الأساسي لمعظم دوال Patch هو تحديث الأعمدة المناسبة بالمعلومات الصحيحة. يكون هذا مصدر العديد من اكتشاف أخطاء دالة Patch ومحاولة إصلاحها. استخدم النقاط التالية لمساعدتك على العمل عبر دالة Patch.

  • تأكد من تحديث كافة الأعمدة المطلوبة من مصدر البيانات.

  • يمكنك تحديث الأعمدة الاختيارية التي تريدها سواء كانت كثيرة أو قليلة.

  • تأكد من أن أسماء الأعمدة مكتوبة بأحرف صحيحة وكبيرة. تأتي أسماء الأعمدة مميزة لحالة الأحرف.

  • تأكد من كتابة نوع البيانات الصحيح. على سبيل المثال، إذا كان العمود فِي مصدر البيانات هو نوع الرقم، فلا يمكنك كتابة قيمة سلسلة، حتى وان كانت هذه السلسلة تحتوي على رقم.

توجد أربعة مصادر لتمرير القيم فِي المعادلة لتصحيح مصدر البيانات:

  • يمكنك ترميز إحدى القيم ترميزًا ثابتًا. مثال على ذلك، إذا كنت ترغب فِي تصحيح حالة السجل إلى "Pending"، فإن معادلة Patch ستبدو كما يلي:

    Patch(CustomerOrders, Default(CustomerOrders), {Status: "Pending"})

    تقوم هذه المعادلة بإنشاء سجل جديد وتعيين عمود الحالة إلى قيمة السلسلة "Pending".

  • يمكنك الإشارة إلى متغير. على سبيل المثال، يمكنك تخزين السلسلة "تحت المراجعة" فِي متغير يسمى varStatus مع المعادلة التالية.

    Set(varStatus, "Under Review")

    ثم ستكون معادلة Patch كما يلي:

    Patch(CustomerOrders, Default(CustomerOrders), {Status: varStatus})

    تقوم هذه المعادلة بإنشاء سجل جديد وتعيين عمود الحالة إلى قيمة السلسلة "Under Review."

  • يمكنك الرجوع إلى القيمة من خاصية عنصر تحكم. على سبيل المثال، يتم تعيين القيمة من القائمة المنسدلة التي تسمى Dropdown1 التي تحتوي على المناطق. ثم ستكون معادلة Patch كما يلي:

    Patch(CustomerOrders, Default(CustomerOrders), {Status: Dropdown1.Selected.Value})

    تقوم هذه المعادلة بإنشاء سجل جديد وتعيين عمود الحالة إلى قيمة العنصر المحدّد فِي القائمة المنسدلة.

  • يمكنك استخدام إخراج المعادلة. على سبيل المثال، يتم تعيين قيمة عمود Owner باستخدام FullName من دالة User(). ثم ستكون معادلة Patch كما يلي:

    Patch(CustomerOrders, Default(CustomerOrders), {Owner: User().FullName})

    تقوم هذه المعادلة بإنشاء سجل جديد وتعيين عمود Owner إلى FullName للمستخدم الحالي من Microsoft Entra ID.

مثال على دالة Patch

لنلقِ نظرة على مثال آخر، فِي هذا المثال أنت تحاول إنشاء حل لتوقيع المستخدمين فِي الفئة بمجرد وصولهم. هذا النوع من حلول Power Apps شائع، وتساعدك دالة Patch على تحقيق النتائج بسرعة.

لقطة شاشة لمثال على دالة Patch لحل Power Apps.

تصنيف تفصيلي للحل

يوجد هنا تطبيق لوحة بسيط متصل بمصدر البيانات (تسجيل الدخول إلى فئة التدريب). يحتوي مصدر البيانات على الأعمدة التالية، Training Class وFirstName وLastName وEmailAddress وSignInStatus. هذه هي المعلومات التي نريد التقاطها عندما يحدّد أحد المستخدمين زر Sign In. في شريط المعادلة، سترى التعليمة البرمجية التالية:

Patch(TrainingClassSignIn,Defaults(TrainingClassSignIn),{TrainingClass:TrainingClassDD.Selected.Value, FirstName:FirstNameInput.Text, LastName:LastNameInput.Text, EmailAddress:EmailAddressInput.Text, SignInStatus:"Attended"})

كلما قام شخص ما بتحديد زر Sign In، يكتب Power Apps سجل جديد إلى مصدر بيانات TrainingClassSignIn. فيما يتعلق بالبيانات التي يتم كتابتها مرة أخرى للمستخدم الذي يقوم بتسجيل الدخول، يمكنك أن ترى أنه يحصل على هذه المعلومات من عناصر التحكم المختلفة التي قمنا بإضافتها (مرمزة بالألوان فِي المعادلة). قد تلاحظ أيضاً أن الرمز يعيّن SignInStatus فِي كل مرة إلى "مراقب" لكل سجل جديد يتم إرساله.

كما ترى، فإن دالة Patch مرنة وقوية. تتميز دالة Patch بمزيد من الإمكانيات مثل تحديث سجلات متعددة ودمجها. لمزيد من المعلومات حول هذه السيناريوهات، راجع دالة Patch فِي Power Apps.