Função Patch

  • Artigo

Aplica-se a: Aplicações de tela Aplicações condicionadas por modelo CLI do Power Platform

Modifica ou cria um ou mais registos numa origem de dados, ou intercala registos fora de uma origem de dados.

Utilize a função Patch para modificar registos em situações complexas, como ao efetuar atualizações que não necessitam de interação do utilizador ou ao utilizar formulários que abrangem vários ecrãs.

Para atualizar mais facilmente os registos numa origem de dados para alterações simples, utilize o controlo Edit form. Quando adiciona um controlo Edit form, pode disponibilizar aos utilizadores um formulário para preencher e, em seguida, guardar as alterações numa origem de dados. Para obter mais informações, consulte Compreender formulários de dados.

Veja este vídeo para aprender a usar a função Patch:

Descrição geral

Utilize a função Patch para modificar um ou mais registos de uma origem de dados. Os valores de campos específicos são modificados sem afetar outras propriedades. Por exemplo, esta fórmula altera o número de telefone de um cliente com o nome Criativos:

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

Utilize a função Patch com a função Defaults para criar registos. Utilize este comportamento para criar um único ecrã para criar e editar registos. Por exemplo, esta fórmula cria um registo de um cliente com o nome Criativos:

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

Mesmo se não estiver a trabalhar com uma origem de dados, pode utilizar o Patch para intercalar dois ou mais registos. Por exemplo, esta fórmula intercala dois registos num que identifica o número de telefone e a localização da Criativos:

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

Descrição

Modifique ou crie um registo numa origem de dados

Para utilizar esta função com uma origem de dados, especifique a origem de dados e, em seguida, especifique um registo de base:

  • Para modificar um registo, o registo de base tem de ser proveniente de uma origem de dados. O registo de base pode ser proveniente de uma propriedade de Items da galeria, ter sido colocado numa variável de contexto ou vir de outro caminho. Mas pode rastrear o registo de base novamente para a origem de dados. Isto é importante porque o registo irá incluir informações adicionais para ajudar a encontrar o registo novamente para ser modificado.
  • Para criar um registo, utilize a função Defaults para criar um registo de base com valores predefinidos.

Em seguida, especifique um ou mais registos de alteração, cada um dos quais contém novos valores de propriedade que substituem os valores de propriedade no registo de base. Os registos de alteração são processados por ordem, do início ao fim da lista de argumentos, com valores de propriedade posteriores que substituem os anteriores.

O valor de retorno do Patch é o registo modificado ou criado. Se tiver criado um registo, o valor de retorno pode incluir propriedades que a origem de dados gerou automaticamente. No entanto, o valor de retorno não fornece um valor para campos de uma tabela relacionada.

Por exemplo, utilize Set(MyAccount, Patch(Accounts, First(Account), 'Account Name': "Example name")); e, em seguida, MyAccount.'Primary Contact'.'Full Name'. Não pode produzir um nome completo neste caso. Em vez disso, para aceder aos campos de uma tabela relacionada, utilize uma análise separada, como:

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

Quando atualizar uma origem de dados, um ou mais problemas podem surgir. Utilize IfError e IsError com o valor obtido de Patch para detetar e responder a erros, como descrito pelo Processamento de Erros. Também pode utilizar a função Errors para identificar e examinar problemas, conforme descrito em Trabalhar com Origens de Dados.

As funções relacionadas incluem a função Update, para substituir um registo completo e a função Collect para criar um registo. Utilize a função UpdateIf para modificar as propriedades específicas de vários registos com base numa condição.

Modifique ou crie um conjunto de registos numa origem de dados

O Patch também pode ser utilizado para criar ou modificar vários registos com uma única chamada.

Em vez de transmitir um único registo de base, uma tabela de registos de base pode ser oferecida no segundo argumento. Os registos de alteração também são oferecidos numa tabela, correspondendo a um-para-um com os registos de base. O número de registos de cada tabela de alterações tem de ser igual ao número de registos na tabela de base.

Quando utilizar o Patch desta forma, o valor de retorno também é uma tabela com cada registo correspondendo a um-para-um com os registos de base e de alteração.

Intercale registos fora de uma origem de dados

Especifique dois ou mais registos que pretende intercalar. Os registos são processados por ordem, do início ao fim da lista de argumentos, com valores de propriedade posteriores que substituem os anteriores.

O Patch devolve o registo intercalado e não altera os respetivos argumentos ou registos em quaisquer origens de dados.

Sintaxe

Modifique ou crie um registo numa origem de dados

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

  • DataSource – Obrigatório. A origem de dados que contém o registo que pretende modificar ou irá conter o registo que pretende criar.
  • BaseRecord – Obrigatório. O registo a modificar ou criar. Se o registo provém de uma origem de dados, o registo é encontrado e modificado. Se o resultado da função Defaults é utilizado, é criado um registo.
  • ChangeRecord(s) – Obrigatório. Um ou mais registos que contêm propriedades para modificar no BaseRecord. Os registos de alteração são processados por ordem, do início ao fim da lista de argumentos, com valores de propriedade posteriores que substituem os anteriores.

Modifique ou crie um conjunto de registos numa origem de dados

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

  • DataSource – Obrigatório. A origem de dados que contém os registos que pretende modificar ou irá conter os registos que pretende criar.
  • BaseRecordTable – Obrigatório. Uma tabela de registos para modificar ou criar. Se o registo provém de uma origem de dados, o registo é encontrado e modificado. Se o resultado da função Defaults é utilizado, é criado um registo.
  • ChangeRecordTable(s) – Obrigatório. Uma ou mais tabelas de registos que contêm propriedades para modificar cada registo do BaseRecordTable. Os registos de alteração são processados por ordem, do início ao fim da lista de argumentos, com valores de propriedade posteriores que substituem os anteriores.

Intercalar registos

Patch( Record1, Record2 [, …] )

  • Record(s) – Obrigatório. Pelo menos dois registos que pretende intercalar. Os registos são processados por ordem, do início ao fim da lista de argumentos, com valores de propriedade posteriores que substituem os anteriores.

Exemplos

Modifique ou crie um registo (numa origem de dados)

Nestes exemplos, irá modificar ou criar um registo numa origem de dados, denominado Gelado, que contém os dados nesta tabela e gera automaticamente os valores na coluna ID:

Exemplo icecream.

Fórmula Description Result
Patch( Gelado,
LookUp( Gelado, Sabor = "Chocolate" ), { Quantidade: 400 } )		 Modifica um registo na origem de dados IceCream:
  • A coluna ID do registo a modificar contém o valor de 1. (O registo Chocolate tem esse ID.)
  • O valor na coluna Quantity é alterado para 400.
 { ID: 1, Sabor: "Chocolate", Quantidade: 400 }

A entrada Chocolate na origem de dados IceCream foi modificada.
Patch( Gelado, Defaults( Gelado ), { Sabor: "Morango" } ) Cria um registo na origem de dados IceCream:
  • A coluna com o ID contém o valor 3, que a origem de dados gera automaticamente.
  • A coluna Quantity contém 0, que é o valor predefinido para essa coluna na origem de dados IceCream, conforme é especificado em Defaults.
  • A coluna Flavor contém o valor da Strawberry.
 { ID: 3, Flavor: "Strawberry", Quantity: 0 }

A entrada Strawberry na origem de dados IceCream foi criada.

Depois das fórmulas anteriores serem avaliadas, a origem de dados termina com estes valores:

Exemplo icecream depois.

Intercale registos (fora de uma origem de dados)

Fórmula Descrição Resultado
Patch( { Nome: "James", Pontuação: 90 }, { Nome: "Jim", Passado: true } ) Intercala dois registos fora de uma origem de dados:
  • Os valores existentes na coluna Name de cada registo não correspondem. O resultado contém o valor (Jim) no registo mais próximo ao fim da lista de argumentos em vez do valor (James) no registo mais próximo ao início.
  • O primeiro registo contém uma coluna (Score) que não existe no segundo registo. O resultado contém essa coluna com o respetivo valor (90).
  • O segundo registo contém uma coluna (Passed) que não existe no primeiro registo. O resultado contém essa coluna com o respetivo valor (true).
 { Nome: "Jim", Pontuação: 90, Passado: true }

Utilização de As ou ThisRecord

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

No exemplo abaixo, considere a primeira pesquisa no If comunicado. (OrderID = A[@OrderID]) espera-se que compare o âmbito de pesquisa OrderId com o OrderId da recolha A no ForAll âmbito. Neste caso, é provável que A[@OrderId] queira ser resolvido como parâmetro local. Mas é ambíguo.

Power Apps atualmente interpreta tanto o lado esquerdo OrderId como o lado direito como um campo no âmbito de pesquisa A[@OrderId] . Portanto, a pesquisa vai sempre encontrar a primeira linha em [dbo].[Orders1] porque a condição é sempre verdadeira (isto é, qualquer linha é igual a si OrderId 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"
       }
   )
    )
)

Usar As ou ThisRecord

Sempre que possível, utilize o operador As ou o de ThisRecord para desambiguar o lado esquerdo. As é recomendado para o cenário acima.

Quando a sua fórmula utiliza múltiplos âmbitos com ForAll, Filter e Lookup na mesma origem de dados ou tabela, é possível que os parâmetros de âmbito possam colidir com um mesmo campo noutro lugar. Por isso, recomenda-se a utilização do operador As ou ThisRecord para resolver o nome de campo e evitar a ambiguidade.

Por exemplo, pode utilizar o operador As para desambiguar 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"
       }
   )
    )
)

Em alternativa, pode utilizar ThisRecord para o mesmo fim.

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

Saiba mais sobre a utilização do operador As e ThisRecord consulte o artigo Operadores.