Patch دالة

ينطبق على: تعمل تطبيقات Canvas Copilot Studio Desktop على تدفقات التطبيقات المستندة إلى النموذج لوظائف Power Platform CLI Dataverse

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

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

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

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

نظرة عامة‬

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

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

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

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

إشعار

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

حتى إذا كنت لا تعمل مع مصدر بيانات، يمكنك استخدام 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 – مطلوب. مصدر البيانات الذي يحتوي على السجل الذي تريد تعديله أو سيحتوي على السجل الذي تريد إنشاءه.
• السجل الأساسي- مطلوب. السجل المراد تعديله أو إنشائه. إذا كان السجل من مصدر بيانات ، فسيتم العثور على السجل وتعديله. في حالة استخدام نتيجة Defaults يتم إنشاء سجل. يجب أن يتطابق DataSource لبيان التصحيح وDataSource للدالة Defaults من أجل إنشاء سجل جديد.
• سجلات التغيير - مطلوب. سجل واحد أو أكثر يحتوي على خصائص للتعديل في BaseRecord. تتم معالجة سجلات التغيير بالترتيب من بداية قائمة الوسائط إلى النهاية ، مع تجاوز قيم الخصائص اللاحقة القيم السابقة.

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

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

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

دمج السجلات

Patch( Record1, Record2 [, ...] )

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

الأمثلة

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

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

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

عندما تستخدم الصيغة نطاقات متعددة مع 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 راجع مقالة المشغلون .