Patch функція

Застосовується до: Програми Canvas Copilot Studio Desktop flows Model-driven apps Power Platform CLI Dataverse functions

Змінює або створює один або кілька записів у джерелі даних або об’єднує записи за межами джерела даних.

Patch Використовуйте функцію, щоб змінювати записи в складних ситуаціях, наприклад під час виконання оновлень, які не потребують взаємодії з користувачем або використання форм, що охоплюють кілька екранів.

Щоб спростити оновлення записів у джерелі даних для простих змін, використовуйте натомість елемент керування Редагування форми. Під час додавання елемента керування Редагування форми користувач має заповнити форму, а потім зберегти зміни в джерелі даних. Щоб отримати додаткові відомості, див. розділ Ознайомлення з формами даних.

Перегляньте це відео, щоб дізнатися, як використовувати 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

Коли ви патчуєте колекцію, використовуючи запис із джерела даних із значеннями за замовчуванням, операція патча оновлює колекцію як вказаними значеннями патчу, так і значеннями за замовчуванням із джерела даних. DataSource оператора патчу та DataSource функції Defaults повинні співпадати для створення нового запису.

Навіть якщо ви не працюєте з джерелом даних, можна об'єднати Patch кілька записів. Наприклад, ця формула об’єднує два записи в один, який ідентифікує як номер телефону, так і розташування для Contoso:

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

Description

Зміна або створення запису в джерелі даних

Щоб використовувати цю функцію з джерелом даних, укажіть джерело даних, а потім укажіть базовий запис.

• Щоб змінити запис, базовий запис має походити з джерела даних. Ви можете отримати базовий запис через властивість 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 повертає об'єднаний запис і не змінює його аргументи або записи в будь-яких джерелах даних.

Syntax

Зміна або створення запису в джерелі даних

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

• Джерело даних– Обов’язковий. Джерело даних, що містить запис, який потрібно змінити, або буде містити запис, який необхідно створити.
• BaseRecord – обов’язковий. Запис, який потрібно змінити або створити. Якщо запис походить із джерела даних, функція знаходить і змінює запис. Якщо використовується результат Defaults , функція створює запис. Щоб створити новий запис, необхідно відповідати джерелу даних і функції DataSource за промовчанням.
• ChangeRecords – Обов’язковий. Один або кілька записів, що містять властивості, які потрібно змінити в BaseRecord. Функція обробляє записи змін у порядку від початку списку аргументів до кінця, причому пізніші значення властивостей перекреслюють попередні.

Зміна або створення набору записів у джерелі даних

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

• Джерело даних– Обов’язковий. Джерело даних, що містить записи, які потрібно змінити, або буде містити записи, які необхідно створити.
• BaseRecordTable – обов’язковий. Таблиця записів, які потрібно змінити або створити. Якщо запис походить із джерела даних, функція знаходить і змінює запис. Якщо використовується результат Defaults , функція створює запис. Щоб створити новий запис, необхідно відповідати джерелу даних і функції DataSource за промовчанням.
• ChangeRecordTables – обов’язковий. Одна або кілька таблиць записів, що містять властивості, які необхідно змінити для кожного запису BaseRecordTable. Функція обробляє записи змін у порядку від початку списку аргументів до кінця, причому пізніші значення властивостей перекреслюють попередні.

Merge records

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

• Записи - обов’язкові. Виберіть принаймні два записи для об’єднання. Функція обробляє записи у порядку від початку списку аргументів до кінця, причому пізніші значення властивостей замінюють попередні.

Examples

Зміна або створення запису (в джерелі даних)

У цих прикладах ви змінюєте або створюєте запис у джерелі даних під назвою IceCream. Джерело даних містить дані в цій таблиці і автоматично генерує значення у стовпці ID:

Щоб створити версію цього джерела даних у пам'яті і спробувати ці приклади, оцініть таку формулу:

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

Formula	Description	Result
Patch(IceCream, LookUp( IceCream, Flavor = "Chocolate" ), { Кількість: 400 } )	Змінює запис у джерелі даних IceCream: Стовпець Ідентифікатор запису, який потрібно змінити, містить значення 1. (Запис Chocolate не має ідентифікатора.) Значення в стовпці Кількість зміниться на 400.	{ ID: 1, Смак: "Шоколад", Кількість: 400 } Запис про шоколад у джерелі даних Ice Cream змінено.
Patch( IceCream, Defaults( IceCream ), { Flavor: "Полуниця" } )	Створює запис у джерелі даних IceCream: Стовпець Ідентифікатор містить значення 3, яке джерело даних створює автоматично. Стовпець Кількість містить значення 0, яке є значенням за замовчуванням для цього стовпця в джерелі даних IceCream відповідно до функції Defaults. У стовпці Аромат міститься значення Strawberry.	{ ID: 3, Смак: "Полуниця", Кількість: 0 } У джерелі даних Ice Cream створюється запис Strawberry.

Після обчислення попередніх формул джерело даних завершується такими значеннями:

Об’єднання записів (поза межами джерела даних)

Formula	Description	Result
Patch( { Ім'я: "Джеймс", оцінка: 90 }, { Ім'я: "Джим", передано: true } )	Об’єднує записи поза межами джерела даних: Значення в стовпці Ім’я для кожного запису не збігаються. Результат містить значення (Jim) у записі в кінці списку аргументів замість значення (James) на початку цього списку. Перший запис містить стовпець (Показник), якого немає в другому записі. Результат містить цей стовпець зі значенням (90). Другий запис містить стовпець (Передано), якого немає в першому записі. Результат містить цей стовпець зі значенням (істина).	{ Ім'я: "Джим", оцінка: 90, передано: true }

Модифікувати або створювати набір записів (у джерелі даних)

Коли ви використовуєте Patch таблиці замість окремих записів, ви можете створювати або змінювати кілька записів за один дзвінок. Повернене значення — це таблиця записів, яка відповідає один до одного з таблицями введення.

Цей приклад оновлює кількість для кількох смаків у джерелі даних Ice Cream одночасно:

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 }.

Цей приклад створює кілька нових записів за допомогою Defaults:

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 з типами стовпців Dataverse

Наступні приклади стосуються саме Microsoft Dataverse джерел даних. Форми записів відрізняються залежно від джерела даних (наприклад, SharePoint і SQL Server мають різні формати).

Колонка вибору: Щоб встановити стовпець Choice, використовуйте значення enum безпосередньо. Цей приклад встановлює стовпець вибору статусу в таблиці Рахунків :

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

Колонка пошуку: Щоб встановити стовпець Lookup, надайте запис із первинним ключем відповідної таблиці. Цей приклад встановлює пошук Primary Contact у записі Account :

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

Note

Ці приклади типу стовпців специфічні для Dataverse. Інші джерела даних, такі як SharePoint або SQL Server, можуть вимагати різних форм записів для подібних типів стовпців. Зверніться до документації для вашого конкретного джерела даних для правильного формату.

Делегування у формулах, які використовують Patch

Patch Сама функція не підлягає делегуванні, оскільки вона записує у джерело даних, а не звертається до нього. Однак попередження про делегування можуть з'являтися у формулах, які використовують Patch , якщо частина вибору запису (наприклад , Filter, LookUp або ForAll) передбачає запит, що перевищує ліміти делегування джерела даних.

Коли ви бачите попередження про делегування у формулі, яка включає Patch, перевірте, чи стосується це попередження функцій отримання даних, а не самого Patch себе. Для отримання додаткової інформації про делегування дивіться розділ «Зрозуміти делегування в додатку Canvas».

Поширені помилки функції Patch

Коли ви використовуєте цю Patch функцію, можуть виникати помилки через підключення джерел даних, дозволи або конфлікти даних. Використовуйте IfError та IsError для виявлення помилок і відповідної відповіді.

• "Мережева помилка при використанні Patch функції": ця помилка зазвичай означає, що додаток не може дістатися до джерела даних. Поширеними причинами є втрата інтернет-з'єднання, тимчасова недоступність джерела даних або недостатні дозволи для поточного користувача. Загорніть Patch дзвінок у IfError , щоб надати користувачам змістовне повідомлення.

• "Конфлікти існують при змінах на сервері": ця помилка виникає, коли інший користувач або процес змінює той самий запис між тим, як ваш додаток читає запис і записує зміну. Оновіть джерело даних, викликавши функцію Refresh , і спробуйте повторити операцію.

• Помилки дозволу: Якщо користувач не має дозволу створювати або змінювати записи у джерелі даних, Patch виклик не спрацьовує. Використовуйте IfError для виявлення помилок, пов'язаних із дозволами, і спрямування користувача.

Для загальних патернів обробки помилок див. Обробка помилок.

Використання As або ThisRecord

Використовуйте ключове слово As або ThisRecord у формулі, щоб уникнути неоднозначного контексту оцінки.

У наступному прикладі розглянемо перший Lookup пункт у твердженні If . (OrderID = A[@OrderID]) очікується, що буде порівнюватися OrderId в Lookup межах обсягу з 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, дивіться статтю про операторів .