Patch функция

Применимо к: Приложения На основе холста 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

Когда вы закрываете коллекцию с помощью записи из источника данных с значениями по умолчанию, операция патча обновляет коллекцию как указанными значениями патча, так и значениями по умолчанию из источника данных. 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, ... ])

  • DataSource — обязательный аргумент. Это источник данных, содержащий запись, которую необходимо изменить. Или же тот, который будет содержать запись, которую вы хотите создать.
  • BaseRecord – обязателен. Это запись, которую необходимо изменить или создать. Если запись была взята из источника данных, функция находит и изменяет запись. Если используется результат Defaults , функция создаёт запись. DataSource инструкции исправления и DataSource функции Defaults должны соответствовать, чтобы создать новую запись.
  • ChangeRecords – Обязательно. Одна или несколько записей, содержащих свойства для изменения в BaseRecord. Функция обрабатывает записи изменений в порядке от начала списка аргументов до конца, при этом последующие значения свойств переопределяют более ранние.

Изменение или создание набора записей в источнике данных

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

  • DataSource — обязательный аргумент. Это источник данных, содержащий запись, которую необходимо изменить. Или же тот, который будет содержать запись, которую вы хотите создать.
  • BaseRecordTable – Обязательно. Таблица записей, которые нужно изменить или создать. Если запись была взята из источника данных, функция находит и изменяет запись. Если используется результат Defaults , функция создаёт запись. DataSource инструкции исправления и DataSource функции Defaults должны соответствовать, чтобы создать новую запись.
  • 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( Мороженое,
LookUp( IceCream, Flavor = "Шоколад"), { Количество: 400 } )		 Изменяет запись в источнике данных IceCream.
  • Столбец записи ID, которую необходимо изменить, содержит значение 1. (Это значение задано для записи Chocolate.)
  • Значение в столбце Quantity изменится на 400.
 { ИДЕНТИФИКАТОР: 1, Вкус: "Шоколад", Количество: 400 }

Запись о шоколаде в источнике данных мороженого изменена.
Patch( IceCream, Defaults( IceCream), { Вкус: "Клубника" } ) Функция создает запись в источнике данных IceCream.
  • Столбец ID содержит значение 3, которое источник данных создает автоматически.
  • Столбец Quantity содержит значение 0, которое является значением по умолчанию для этого столбца в источнике данных IceCream в соответствии с функцией Defaults.
  • Столбец Flavor содержит значение Strawberry.
 { идентификатор: 3, вкус: "Клубника", Количество: 0 }

В источнике данных Ice Cream создаётся запись Strawberry.

После оценки предыдущих формул источник данных заканчивается на следующих значениях:

Скриншот источника данных Ice Cream после Patch оценки формул.

Объединение записей (вне источника данных)

Formula Description Result
Patch( { Имя: "Джеймс", Оценка: 90 }, { Имя: "Джим", Передано: true } ) Функция объединяет две записи вне источника данных.
  • Значения в столбце Name для каждой записи не совпадают. Результат содержит значение (Jim) в записи в конце списка аргументов вместо значения (James) в начале этого списка.
  • Первая запись содержит столбец (Score), который отсутствует во второй записи. Результат содержит этот столбец со значением (90).
  • Вторая запись содержит столбец (Passed), который отсутствует в первой записи. Результат содержит этот столбец со значением (true).
 { Имя: "Джим", оценка: 90, передано: true }

Модифицировать или создавать набор записей (в источнике данных)

Когда вы используете 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 }.

В этом примере создаётся несколько новых записей с использованием 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 , чтобы предоставить пользователям значимое сообщение.

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

  • Ошибки разрешения: если у пользователя нет разрешения на создание или изменение записей в источнике данных, Patch вызов не обходится. Используйте IfError для обнаружения ошибок, связанных с разрешениями, и руководства пользователя.

Для общих паттернов обработки ошибок см. раздел «Обработка ошибок».

Использование As или ThisRecord

Используйте ключевые слова As или ThisRecord в формуле, чтобы избежать неоднозначного контекста оценки.

В следующем примере рассмотрим первый Lookup из утверждения If . (OrderID = A[@OrderID])ожидается, что будет сравнивать OrderId в сфере OrderId с коллекцией A в ForAll сфере примененияLookup. В этом случае, скорее всего, стоит 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, см. статью «Операторы ».

  • Last updated on