Patch دالة

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

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

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

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

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

Overview

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

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

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

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

Note

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

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

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

Description

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

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

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

Syntax

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

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

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

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

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

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

Merge records

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

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

Examples

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

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

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

ClearCollect( IceCream,
    { ID: 1, Flavor: "Chocolate", Quantity: 100 },
    { ID: 2, Flavor: "Vanilla", Quantity: 200 }
)

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

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

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

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

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

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

يقوم هذا المثال بتحديث الكمية لعدة نكهات في مصدر بيانات الآيس كريم في نفس الوقت:

Patch(
    IceCream,
    Table(
        { ID: 1, Flavor: "Chocolate", Quantity: 150 },
        { ID: 2, Flavor: "Vanilla", Quantity: 200 }
    ),
    Table(
        { Quantity: 300 },
        { Quantity: 400 }
    )
)

النتيجة هي جدول يحتوي على السجلات المحدثة: { ID: 1, Flavor: "Chocolate", Quantity: 300 } و { ID: 2, Flavor: "Vanilla", Quantity: 400 }.

هذا المثال ينشئ عدة سجلات جديدة باستخدام الإعدادات الافتراضية:

Patch(
    IceCream,
    Table( Defaults( IceCream ), Defaults( IceCream ) ),
    Table(
        { Flavor: "Mint", Quantity: 60 },
        { Flavor: "Peach", Quantity: 80 }
    )
)

Note

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

لاكتشاف الأخطاء عند تعديل عدة سجلات، استخدم IfError. IfError هي الآلية المفضلة وتعمل عبر مضيفي Power Fx:

IfError(
    Patch(
        IceCream,
        baseRecords,
        changeRecords
    ),
    Notify( "Some records failed to update: " & FirstError.Message, NotificationType.Error )
)

Patch مع أنواع أعمدة داتافيرس

تنطبق الأمثلة التالية تحديدا على مصادر البيانات Microsoft Dataverse. تختلف أشكال السجلات حسب مصدر البيانات (على سبيل المثال، SharePoint و SQL Server لهما صيغ مختلفة).

عمود الاختيار: لتعيين عمود Choice، استخدم قيمة enum مباشرة. هذا المثال يحدد عمود اختيار الحالة على جدول الحسابات :

Patch(
    Accounts,
    LookUp( Accounts, 'Account Name' = "Contoso" ),
    { 'Status': 'Status (Accounts)'.Active }
)

عمود البحث: لتعيين عمود بحث، قدم سجلا يحتوي على المفتاح الأساسي للجدول ذي الصلة. هذا المثال يحدد البحث عن جهات الاتصال الأساسية في سجل الحسابات :

Patch(
    Accounts,
    LookUp( Accounts, 'Account Name' = "Contoso" ),
    { 'Primary Contact': LookUp( Contacts, 'Full Name' = "John Smith" ) }
)

Note

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

التفويض في الصيغ التي تستخدم Patch

الدالة Patch نفسها لا تخضع للتفويض لأنها تكتب إلى مصدر البيانات بدلا من الاستعلام عنه. ومع ذلك، قد تظهر تحذيرات التفويض في الصيغ التي تستخدم Patch إذا كان جزء اختيار السجلات من الصيغة (مثل Filter، LookUp، أو ForAll) يتضمن استعلاما يتجاوز حدود تفويض مصدر البيانات.

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

الأخطاء الشائعة في الدالة Patch

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

• "خطأ في الشبكة عند استخدام Patch الوظيفة": عادة ما يشير هذا الخطأ إلى أن التطبيق لا يستطيع الوصول إلى مصدر البيانات. تشمل الأسباب الشائعة فقدان اتصال الإنترنت، أو عدم توفر مصدر البيانات مؤقتا، أو عدم كفاية الأذونات للمستخدم الحالي. لف المكالمة Patch في IfError لتقديم رسالة ذات معنى للمستخدمين.

• "توجد تعارضات مع التغييرات على الخادم": يحدث هذا الخطأ عندما يقوم مستخدم أو عملية أخرى بتعديل نفس السجل بين الوقت الذي يقرأ فيه تطبيقك السجل ويكتب فيه التغيير. قم بتحديث مصدر البيانات عن طريق استدعاء دالة التحديث وإعادة محاولة العملية.

• أخطاء في الأذون: إذا لم يكن لدى المستخدم إذن لإنشاء أو تعديل سجلات في مصدر البيانات، تفشل الدعوة Patch . استخدم IfError لاكتشاف أخطاء الأذونات وتوجيه المستخدم.

للاطلاع على أنماط معالجة الأخطاء العامة، انظر معالجة الأخطاء.

استخدام As أو ThisRecord

استخدم الكلمة المفتاحية As أو ThisRecord في صيغتك لتجنب سياق التقييم الغامض.

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

يفسر Power Apps حاليا كلا من الجانب الأيسر OrderId والجانب الأيمن A[@OrderId] كحقل في نطاق Lookup. لذلك، Lookup دائما يجد الصف الأول في [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"
       }
   )
    )
)

لمعرفة المزيد عن استخدام مشغل AsوThisRecord، راجع مقالة المشغلين .