الدالة Patch

تنطبيق على: Canvas apps التطبيقات المستندة إلى النماذج Power Platform CLI تدفقات سطح المكتب

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

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

لتحديث السجلات في مصدر البيانات بطريقه أكثر سهوله للتغييرات البسيطة، استخدم عنصر تحكم Edit form بدلاً من ذلك. عندما تضيف عنصر تحكم Edit form فانك توفر للمستخدمين نموذجا لملء التغييرات وحفظها على مصدر البيانات. للحصول على مزيد من المعلومات، راجع فهم نماذج البيانات.

شاهد هذا الفيديو للتعرف على كيفية استخدام وظيفة Patch:

نظرة عامة‬

استخدم وظيفة Patch لتعديل واحد أو أكثر من السجلات الخاصة بمصدر البيانات. يتم تعديل قيم الحقول المحددة بدون التأثير على الخصائص الأخرى. على سبيل المثال، تغير هذه الصيغة رقم الهاتف لعميل يسمى Contoso:

Patch( Customers, First( Filter( Customers, Name = "Contoso" ) ), { Phone: "1-212-555-1234" } )

استخدم وظيفة Patch مع Defaults لإنشاء السجلات. استخدم هذا السلوك لإنشاء شاشة واحدة لإنشاء السجلات وتحريرها. على سبيل المثال، تقوم هذه الصيغة بإنشاء سجل لعميل يسمى Contoso:

Patch( Customers, Defaults( Customers ), { Name: "Contoso" } )

حتى إذا لم تكن تستخدم مصدر بيانات، فيمكنك استخدام وظيفة Patch لدمج سجلين أو أكثر. على سبيل المثال ، تدمج هذه الصيغة سجلين في سجل يحدد رقم الهاتف وموقع Contoso:

Patch( { Name: "Contoso", Phone: "1-212-555-1234" }, { Name: "Contoso", Location: "Midtown" } )

‏‏الوصف

تعديل أو إنشاء سجل في مصدر بيانات

لاستخدام هذه الوظيفة مع مصدر بيانات، حدد مصدر البيانات، ثم حدد السجل الأساسي:

• لتعديل سجل ، يجب أن يأتي السجل الأساسي من مصدر بيانات. قد يكون السجل الأساسي من خلال خاصية Items الخاصة بمعرض في متغير السياق، أو يأتي من مسار آخر. ولكن ، يمكنك تتبع السجل الأساسي مرة أخرى إلى مصدر البيانات. هذا مهم لأن السجل سيتضمن معلومات إضافية للمساعدة في العثور على السجل مرة أخرى للتعديل.
• لإنشاء سجل، استخدم وظيفة Defaults لإنشاء سجل أساسي بالقيم الافتراضية.

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

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

على سبيل المثال، يمكنك استخدام Set(MyAccount, Patch(Accounts, First(Account), 'Account Name': "Example name")); ثم MyAccount.'Primary Contact'.'Full Name'. لا يمكنك تقديم اسم كامل في هذه الحالة. وبدلا من ذلك، للوصول إلى حقول جدول مرتبط، استخدم عمليةبحث منفصلة مثل:

LookUp(Accounts, Account = MyAccount.Account).'Primary Contact'.'Full Name'

عند القيام بتحديث مصدر البيانات، قد تظهر مشكلة واحدة أو أكثر. استخدم IfError وIsError مع القيمة المرجعة من Patch للكشف عن الأخطاء والاستجابة لها، كما هو موضح في معالجة الأخطاء. يمكنك أيضا استخدام دالة Errors لتحديد المشكلات وفحصها، كما هو موضح في العمل مع مصادر البيانات.

تتضمن الوظائف ذات الصلة وظيفة Update لاستبدال سجل بالكامل، ووظيفة Collect لإنشاء سجل. استخدم وظيفة UpdateIf لتعديل خصائص محدده لسجلات متعددة استنادا إلى شرط.

تعديل أو إنشاء مجموعة من السجلات في مصدر بيانات

ويمكن أيضًا استخدام Patch لإنشاء سجلات متعددة باستدعاء واحد أو تعديله.

بدلاً من تمرير سجل أساسي واحد ، يمكن توفير جدول السجلات الأساسية في الوسيطة الثانية. يتم توفير سجلات التغيير في الجدول أيضًا ، بحيث تتطابق السجلات الفردية مع واحد مقابل واحد. يجب أن يكون عدد السجلات في كل جدول تغيير هو نفس عدد السجلات في الجدول الأساسي.

عند استخدام وظيفة Patch بهذه الطريقة، القيمة المرتجعة هي أيضًا جدول مع كل سجل مقابل واحد مع السجلات الأساسية وتغيير السجلات.

دمج السجلات خارج مصدر البيانات

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

تقوم وظيفة Patch بإرجاع السجل المدمج ولا يؤدي إلى تعديل الوسيطات أو السجلات الخاصة به في اي من مصادر البيانات.

بناء الجملة

تعديل أو إنشاء سجل في مصدر بيانات

Patch( DataSource, BaseRecord, ChangeRecord1 [, ChangeRecord2, … ])

• DataSource – مطلوب. مصدر البيانات الذي يحتوي على السجل الذي تريد تعديله أو سيحتوي على السجل الذي تريد إنشاءه.
• BaseRecord – مطلوب. السجل المراد تعديله أو إنشائه. إذا كان السجل من مصدر بيانات ، فسيتم العثور على السجل وتعديله. في حالة استخدام نتيجة Defaults يتم إنشاء سجل.
• ChangeRecord(s) – مطلوب. سجل واحد أو أكثر يحتوي على خصائص للتعديل في BaseRecord. تتم معالجة سجلات التغيير بالترتيب من بداية قائمة الوسائط إلى النهاية ، مع تجاوز قيم الخصائص اللاحقة القيم السابقة.

تعديل أو إنشاء مجموعة من السجلات في مصدر بيانات

Patch( DataSource, BaseRecordsTable, ChangeRecordTable1 [, ChangeRecordTable2, … ] )

• DataSource – مطلوب. مصدر البيانات الذي يحتوي على السجلات التي تريد تعديلها أو يحتوي على السجلات التي تريد إنشاءها.
• BaseRecordTable – مطلوب. جدول سجلات لتعديله أو إنشائه. إذا كان السجل من مصدر بيانات ، فسيتم العثور على السجل وتعديله. في حالة استخدام نتيجة Defaults يتم إنشاء سجل.
• ChangeRecordTable(s) – مطلوب. جدول واحد أو أكثر من السجلات التي تحتوي على خصائص لتعديل كل سجل BaseRecordTable. تتم معالجة سجلات التغيير بالترتيب من بداية قائمة الوسائط إلى النهاية ، مع تجاوز قيم الخصائص اللاحقة القيم السابقة.

دمج السجلات

Patch( Record1, Record2 [, …] )

• السجل (السجلات) – مطلوب. سجلان على الأقل تريد دمجهما. تتم معالجة السجلات بالترتيب من بداية قائمة الوسائط إلى النهاية ، مع تجاوز قيم الخصائص اللاحقة القيم السابقة.

الأمثلة

تعديل أو إنشاء سجل (في مصدر بيانات)

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

الصيغة	الوصف	نتيجة
Patch( IceCream, LookUp( IceCream, Flavor = "Chocolate" ), { Quantity: 400 } )	تعديل سجل في مصدر بيانات IceCream: يحتوي عمود المعرف الخاص بالسجل المراد تعديله على قيمة 1. (يحتوي سجل Chocolate على هذا المعرف.) تتغير القيمة في عمود الكمية إلى 400.	{ ID: 1, Flavor: "Chocolate", Quantity: 400 } تم تعديل Chocolate في مصدر بيانات IceCream.
Patch( IceCream, Defaults( IceCream ), { Flavor: "Strawberry" } )	إنشاء سجل في مصدر بيانات IceCream: يحتوي عمود المعرف على القيمة 3، التي يقوم مصدر البيانات بإنشائها تلقائيًا. يحتوي عمود الكمية على 0 وهي القيمة الافتراضية لهذا العمود في مصدر بيانات IceCream على النحو الموصوف في وظيفة Defaults. يحتوي عمود Flavor على قيمة Strawberry.	{ ID: 3, Flavor: "Strawberry", Quantity: 0 } تم إنشاء إدخال Strawberry في مصدر بيانات IceCream.

بعد تقييم الصيغ السابقة، ينتهي مصدر البيانات بهذه القيم:

دمج السجلات (خارج مصدر البيانات)

الصيغة	الوصف	نتيجة
Patch( { Name: "James", Score: 90 }, { Name: "Jim", Passed: true } )	دمج سجلين خارج مصدر البيانات: القيم الموجودة في عمود Name لكل سجل غير متطابقة. وتحتوي النتيجة على القيمة (Jim) في السجل الأقرب إلى نهاية قائمة الوسائط بدلاً من القيمة (James) في السجل الذي يكون أقرب إلى البداية. يحتوي السجل الأول على عمود (Score) غير موجود في السجل الثاني. وتحتوي النتيجة على العمود الذي يحتوي على قيمتها (90). يحتوي السجل الثاني على عمود (Passed) غير موجود في السجل الأول. وتحتوي النتيجة على العمود الذي يحتوي على قيمتها (صواب).	{ Name: "Jim", Score: 90, Passed: true }

استخدام As أو ThisRecord

يؤدي استخدام الكلمة الرئيسية As أو ThisRecord في الصيغة إلى تجنب سياق التقييم الغامض.

في المثال أدناه، ضع في اعتبارك البحث الأول في عبارة If . يُتوقع(OrderID = A[@OrderID]) أن يقارن OrderId في نطاق البحث مع OrderId للمجموعة A في نطاق ForAll . في هذه الحالة، من المحتمل ان تحتاج A[@OrderId] إلى حل كمعلمة محلية. ولكنها غامضة.

يفسر Power Apps حاليًا كلاً من الجانب الأيسر OrderId والجانب الأيمن A[@OrderId] كحقل في نطاق البحث. لذا، سيعثر البحث دائمًا على الصف الأول في [dbo].[Orders1] لأن الشرط دائمًا صحيح (أي، أي صف OrderId يساوي نفسه.)

ClearCollect(
    A,
    Filter(
        '[dbo].[Orders1]',
        OrderId = 8888888
    )
);
ForAll(
    A,
    If(
        LookUp(
            '[dbo].[Orders1]',
            OrderId = A[@OrderId],
            "OK"
        ) = "OK",
        Patch(
            '[dbo].[Orders1]',
            LookUp(
                '[dbo].[Orders1]',
                OrderId = A[@OrderId]
            ),
            {
      OrderName: "val1"
       }
   ),
   Patch(
            '[dbo].[Orders1]',
            Defaults('[dbo].[Orders1]'),
            {
      OrderName: "val2"
       }
   )
    )
)

استخدام As أو ThisRecord

كلما أمكن ، استخدم عامل التشغيل As أو ThisRecord لإزالة الغموض عن الجانب الأيسر. يُوصى بـ As للسيناريو أعلاه.

عندما تستخدم الصيغة نطاقات متعددة مع ForAll و Filter و Lookup في نفس مصدر البيانات أو الجدول، فمن المحتمل أن تتعارض معلمات النطاق مع نفس الحقل في مكان آخر. لذلك ، يوصى باستخدام عامل التشغيل As أو ThisRecord لحل اسم الحقل وتجنب الغموض.

على سبيل المثال، يمكنك استخدام عامل التشغيل As لإزالة الغموض في المثال أدناه.

ClearCollect(
    A,
    Filter(
        '[dbo].[Orders1]',
        OrderId = 8888888
    )
);
ForAll(
    A,
    If(
        LookUp(
            '[dbo].[Orders1]' As B,
            B.OrderId = A[@OrderId],
            "OK"
        ) = "OK",
        Patch(
            '[dbo].[Orders1]',
            LookUp(
                '[dbo].[Orders1]' As C,
                C.OrderId = A[@OrderId]
            ),
            {
      OrderName: "val1"
       }
   ),
   Patch(
            '[dbo].[Orders1]',
            Defaults('[dbo].[Orders1]'),
            {
      OrderName: "val2"
       }
   )
    )
)

وبدلاً من ذلك، يمكنك استخدام ThisRecord للغرض نفسه.

ClearCollect(
    A,
    Filter(
        '[dbo].[Orders1]',
        OrderId = 8888888
    )
);
ForAll(
    A,
    If(
        LookUp(
            '[dbo].[Orders1]',
            ThisRecord.OrderId = A[@OrderId],
            "OK"
        ) = "OK",
        Patch(
            '[dbo].[Orders1]',
            LookUp(
                '[dbo].[Orders1]',
                ThisRecord.OrderId = A[@OrderId]
            ),
            {
      OrderName: "val1"
       }
   ),
   Patch(
            '[dbo].[Orders1]',
            Defaults('[dbo].[Orders1]'),
            {
      OrderName: "val2"
       }
   )
    )
)

لمعرفة المزيد حول استخدام عامل التشغيل ‏‫باعتباره و ThisRecord راجع مقالة المشغلون .