Patch Função

Aplica-se a: Aplicativos de tela Copilot Studio Desktop flui aplicativos baseados em modelo funções do Power Platform CLI Dataverse

Modifica ou cria um ou mais registros em uma fonte de dados ou mescla registros fora de uma fonte de dados.

Use a Patch função para modificar registros em situações complexas, como quando você faz atualizações que não exigem interação do usuário ou usam formulários que abrangem várias telas.

Para atualizar registros em um fonte de dados com mais facilidade para alterações simples, em vez disso, use o controle Edit form. Quando você adiciona um controle Edit form, você fornece aos usuários um formulário a ser preenchido e salva as alterações em uma fonte de dados. Para obter mais informações, consulte Noções básicas de formulários de dados.

Assista a este vídeo para saber como usar a Patch função:

Overview

Use a Patch função para modificar um ou mais registros de uma fonte de dados. Ele atualiza os valores de campos específicos sem afetar outras propriedades. Por exemplo, essa fórmula altera o número de telefone de um cliente chamado Contoso:

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

Use Patch com a função Padrões para criar registros. Use esse comportamento para criar uma única tela para criar e editar registros. Por exemplo, esta fórmula cria um registro para um cliente chamado Contoso:

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

Mesmo se você não estiver trabalhando com uma fonte de dados, poderá usar Patch para mesclar dois ou mais registros. Por exemplo, esta fórmula mescla dois registros em um que identifica o número de telefone e a localização de Contoso:

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

Description

Modificar ou criar um registro em uma fonte de dados

Para usar essa função com uma fonte de dados, especifique a fonte de dados e, em seguida, especifique um registro de base:

• Para modificar um registro, o registro base precisa vir de uma fonte de dados. Você pode obter o registro base pela propriedade Itens de uma galeria, colocá-lo em uma variável de contexto ou obtê-lo por outro caminho. Mas você deve ser capaz de rastrear o registro base até a fonte de dados. Esse requisito é importante porque o registro inclui informações extras que ajudam você a encontrar o registro novamente para modificação.
• Para criar um registro, use a função Defaults para criar um registro de base com valores padrão.

Em seguida, especifique um ou mais registros de alteração, cada um deles contém novos valores de propriedade que substituem os valores de propriedade do registro de base. Registros de alteração são processados na ordem do início da lista de argumentos para o final, com valores de propriedade mais atuais substituindo os mais antigos.

O valor retornado Patch é o registro que você modificou ou criou. Se você criou um registro, o valor retornado poderá incluir propriedades que a fonte de dados gerou automaticamente. No entanto, o valor de retorno não fornece um valor para os campos de uma tabela relacionada.

Por exemplo, você usa Set(MyAccount, Patch(Accounts, First(Account), 'Account Name': "Example name")); e depois MyAccount.'Primary Contact'.'Full Name'. Você não pode fornecer um nome completo neste caso. Em vez disso, para acessar os campos de uma tabela relacionada, use uma pesquisa separada, como:

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

Quando você atualiza uma fonte de dados, pode surgir um ou mais problemas. Use IfError e IsError com o valor retornado para Patch detectar e responder a erros, como descreve o Tratamento de Erros . Também é possível usar a função Errors para identificar e examinar problemas, conforme descrito em Trabalhando com fontes de dados.

Funções relacionadas incluem a função Update para substituir um registro inteiro, e a função Collect para criar um registro. Use a função UpdateIf para modificar propriedades específicas de vários registros com base em uma condição.

Modificar ou criar um conjunto de registros em uma fonte de dados

Você também pode usar Patch para criar ou modificar múltiplos registros com uma única chamada.

Em vez de passar um único registro base, forneça uma tabela dos registros base no segundo argumento. Fornecer registros de alterações em uma tabela também, correspondendo um a um com os registros base. O número de registros em cada tabela de alteração deve ser igual ao número de registros na tabela de base.

Quando você usa Patch dessa forma, o valor de retorno também é uma tabela com cada registro correspondendo um por um aos registros base e de mudança.

Mesclar registros fora de uma fonte de dados

Especifique dois ou mais registros que deseja mesclar. A função processa os registros na ordem do início da lista de argumentos até o fim, com valores de propriedades posteriores sobrescrevendo os anteriores.

Patch retorna o registro mesclado e não modifica seus argumentos ou registros em nenhuma fonte de dados.

Syntax

Modificar ou criar um registro em uma fonte de dados

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

• DataSource – Obrigatório. A fonte de dados que contém o registro que deseja modificar ou conterá o registro que deseja criar.
• BaseRecord – Obrigatório. O registro a ser modificado ou criado. Se o registro veio de uma fonte de dados, a função encontra e modifica o registro. Se o resultado de Defaults for usado, a função cria um registro. O DataSource da instrução patch e o DataSource da função Defaults devem corresponder para criar um novo registro.
• ChangeRecords – Obrigatório. Um ou mais registros que contêm propriedades para modificar no BaseRecord. A função processa registros em ordem do início ao fim da lista de argumentos, com valores de propriedades posteriores sobrescrevendo os anteriores.

Modificar ou criar um conjunto de registros em uma fonte de dados

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

• DataSource – Obrigatório. A fonte de dados que contém os registros que deseja modificar ou conterá os registros que deseja criar.
• BaseRecordTable – Obrigatório. Uma tabela de registros a ser modificada ou criada. Se o registro veio de uma fonte de dados, a função encontra e modifica o registro. Se o resultado de Defaults for usado, a função cria um registro. O DataSource da instrução patch e o DataSource da função Defaults devem corresponder para criar um novo registro.
• ChangeRecordTables – Obrigatório. Uma ou mais tabelas de registros que contêm propriedades para modificar para cada registro do BaseRecordTable. A função processa registros em ordem do início ao fim da lista de argumentos, com valores de propriedades posteriores sobrescrevendo os anteriores.

Merge records

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

• Registros - Obrigatório. Pelo menos, dois registros que você deseja mesclar. A função processa registros em ordem do início da lista de argumentos até o fim, com valores de propriedades posteriores sobrepondo-se aos anteriores.

Examples

Modificar ou criar um registro (em uma fonte de dados)

Nesses exemplos, você modifica ou cria um registro em uma fonte de dados chamada IceCream. A fonte de dados contém os dados desta tabela e gera automaticamente os valores na colunaID:

Para criar uma versão em memória dessa fonte de dados para que você possa tentar estes exemplos, avalie esta fórmula:

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

Após a avaliação das fórmulas anteriores, a fonte de dados termina com estes valores:

Mesclar registros (fora de uma fonte de dados)

Modificar ou criar um conjunto de registros (em uma fonte de dados)

Quando você usa Patch com tabelas em vez de registros únicos, pode criar ou modificar múltiplos registros em uma única chamada. O valor de retorno é uma tabela de registros que corresponde um a um com as tabelas de entrada.

Este exemplo atualiza a Quantidade para múltiplos sabores na fonte de dados do Sorvete ao mesmo tempo:

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

O resultado é uma tabela com os registros atualizados: { ID: 1, Flavor: "Chocolate", Quantity: 300 } e { ID: 2, Flavor: "Vanilla", Quantity: 400 }.

Este exemplo cria múltiplos registros novos usando Defaults:

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

Para detectar erros ao modificar múltiplos registros, use o IfError. IfError é o mecanismo preferido e funciona entre hosts Power Fx:

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

Patch com tipos de colunas do Dataverse

Os exemplos a seguir se aplicam especificamente a fontes de dados Microsoft Dataverse. Os formatos dos registros variam conforme a fonte de dados (por exemplo, SharePoint e SQL Server têm formatos diferentes).

Coluna de escolha: Para definir uma coluna de Escolha, use o valor de enum diretamente. Este exemplo define uma coluna de escolha de Status em uma tabela de Contas :

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

Coluna de pesquisa: Para definir uma coluna de Pesquisa, forneça um registro com a chave primária da tabela relacionada. Este exemplo define a consulta de Contato Primário em um registro de Contas :

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

Delegação em fórmulas que utilizam Patch

A Patch função em si não está sujeita a delegação porque ela escreve na fonte de dados em vez de consultá-la. No entanto, avisos de delegação podem aparecer em fórmulas que usam Patch se a parte de seleção de registros da fórmula (como Filter, LookUp ou ForAll) envolver uma consulta que exceda os limites de delegação da fonte de dados.

Quando você vê um aviso de delegação em uma fórmula que inclui Patch, verifique se o aviso se aplica às funções de recuperação de dados e não a Patch si mesmo. Para mais informações sobre delegação, veja Entender delegação em um aplicativo canvas.

Erros comuns com a Patch função

Quando você usa a Patch função, erros podem ocorrer devido à conectividade da fonte de dados, permissões ou conflitos de dados. Use IfError e IsError para detectar erros e responder adequadamente.

• "Erro de rede ao usar Patch a função": Esse erro normalmente indica que o app não consegue alcançar a fonte de dados. Causas comuns incluem perda de conexão com a internet, a fonte de dados temporariamente indisponível ou permissões insuficientes para o usuário atual. Envolva a Patch chamada no IfError para fornecer uma mensagem significativa aos usuários.

• "Existem conflitos com mudanças no servidor": Esse erro ocorre quando outro usuário ou processo modifica o mesmo registro entre o momento em que seu app lê o registro e grava a alteração. Atualize a fonte de dados chamando a função Refresh e tente novamente a operação.

• Erros de permissão: Se o usuário não tiver permissão para criar ou modificar registros na fonte de dados, a Patch chamada falha. Use o IfError para detectar erros relacionados a permissão e orientar o usuário.

Para padrões gerais de tratamento de erros, veja Tratamento de erros.

Uso de As ou ThisRecord

Use as palavras-chave As ou ThisRecord na sua fórmula para evitar contextos ambíguos de avaliação.

No exemplo a seguir, considere o primeiro Lookup da If afirmação. (OrderID = A[@OrderID]) espera-se que compare o OrderId no Lookup escopo com o OrderId de coleção A no ForAll escopo. Nesse caso, provavelmente você quer A[@OrderId] resolver como um parâmetro local. Mas é ambíguo.

Power Apps atualmente interpreta tanto o lado esquerdo OrderId quanto o lado direito A[@OrderId] como um campo no escopo Lookup. Portanto, Lookup sempre encontra a primeira linha em [dbo].[Orders1] porque a condição é sempre verdadeira (ou seja, a de OrderId qualquer linha é igual a si mesma).

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"
       }
   )
    )
)

Uso de As ou ThisRecord

Sempre que possível, use o operador As ou a palavra-chave ThisRecord para desambiguar o lado esquerdo. Como é recomendado para o cenário anterior.

Quando sua fórmula usa múltiplos escopos com ForAll, Filter, e Lookup na mesma fonte de dados ou tabela, parâmetros de escopo podem colidir com o mesmo campo em outro lugar. Portanto, use o operador As ou ThisRecord para resolver o nome do campo e evitar ambiguidades.

Por exemplo, você pode usar o operador As para desambiguar no exemplo a seguir.

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"
       }
   )
    )
)

Como alternativa, você pode usar ThisRecord para a mesma finalidade.

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"
       }
   )
    )
)

Para saber mais sobre o uso do operador As e do ThisRecord, veja o artigo Operators .