Função de patch

Aplica-se a: Aplicativos Canvas Aplicativos orientados a modelos Power Platform CLI Fluxos de desktop

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

Use a função Patch para modificar registros em situações complexas, por exemplo, quando você faz atualizações que não exigem nenhuma 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 aprender a usar a função Patch:

Visão Geral

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

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

Use Patch com a função Defaults 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 que você não esteja trabalhando com uma fonte de dados, é possível 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" } )

Descrição

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 de base deve ser proveniente de uma fonte de dados. O registro de base pode ter sido fornecido por meio da propriedade Items da galeria, colocado em uma variável de contexto, ou por meio de outro caminho. Mas, você pode rastrear o registro de base de volta para a fonte de dados. Isso é importante, pois o registro incluirá informações adicionais para ajudar a localizar 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 de Patch é o registro modificado ou criado. Se você criou um registro, o valor retornado pode incluir propriedades de 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, um ou mais problemas podem ocorrer. Use IfError e IsError com o valor de retorno de Patch para detectar e responder a erros, conforme descrito em 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

Patch também pode ser usado para criar ou modificar vários registros com uma única chamada.

Em vez de passar um único registro de base, uma tabela de registros de base pode ser fornecida no segundo argumento. Registros de alteração também são fornecidos em uma tabela, com correspondência de um para um com os registros de base. O número de registros em cada tabela de alteração deve ser igual ao número de registros na tabela de base.

Ao usar Patch dessa maneira, o valor retornado também é uma tabela com cada registro com correspondência de um para um com os registros de base e alteração.

Mesclar registros fora de uma fonte de dados

Especifique dois ou mais registros que deseja mesclar. Registros 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.

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

Sintaxe

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 for proveniente de uma fonte de dados, ele será encontrado e modificado. Se o resultado de Defaults for usado, um registro será criado.
• ChangeRecords – Obrigatório. Um ou mais registros que contêm propriedades para modificar no BaseRecord. 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.

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 for proveniente de uma fonte de dados, ele será encontrado e modificado. Se o resultado de Defaults for usado, um registro será criado.
• ChangeRecordTables – Obrigatório. Uma ou mais tabelas de registros que contêm propriedades para modificar para cada registro do BaseRecordTable. 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.

Mesclar registros

Patch( Registro1, Registro2 [, …] )

• Registros - Obrigatório. Pelo menos, dois registros que você deseja mesclar. Registros 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.

Exemplos

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

Nesses exemplos, você modificará ou criará um registro em uma fonte de dados chamado IceCream, que contém os dados nessa tabela e gera automaticamente os valores da colunaID:

Depois de as fórmulas anteriores terem sido avaliadas, a fonte de dados termina com estes valores:

Mesclar registros (fora de uma fonte de dados)

Uso de As ou ThisRecord

O uso da palavra-chave As ou ThisRecord na fórmula evita um contexto de avaliação ambíguo.

No exemplo abaixo, considere a primeira pesquisa na instrução If. (OrderID = A[@OrderID]) espera-se comparar o OrderId no escopo da pesquisa com o OrderId da coleção A no ForAll escopo. Neste caso, você provavelmente deseja que A[@OrderId] seja resolvido como um parâmetro local. Mas isso é ambíguo.

No momento, o Power Apps interpreta a OrderId do lado esquerdo e a A[@OrderId] do lado direito como um campo no escopo de pesquisa. Portanto, a pesquisa sempre encontrará a primeira linha em [dbo].[Orders1] porque a condição é sempre verdadeira (ou seja, a OrderId de qualquer linha é igual a ela 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 ThisRecord para eliminar a ambiguidade do lado esquerdo. Como é recomendado para o cenário acima.

Quando sua fórmula usa múltiplos escopos com ForAll, Filter, e Lookup na mesma fonte de dados ou tabela, é possível que os parâmetros de escopo colidam com um mesmo campo em outro lugar. Portanto, é recomendável usar o operador As ou ThisRecord para resolver o nome do campo e evitar ambiguidade.

Por exemplo, você pode usar o operador As para eliminar a ambiguidade no exemplo abaixo.

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 ThisRecord, consulte o artigo Operadores.