Patch Função

Aplica-se a: Aplicativos do Canvas Fluxos do Copilot Studio Desktop Aplicativos orientados por modelos Funções do Power Platform CLI Dataverse

Modifica ou cria um ou mais registos numa origem de dados, ou intercala registos fora de uma origem 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 usa formulários que abrangem várias telas.

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 saber como utilizar a Patch função:

Descrição geral

Use a Patch função 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, esta fórmula altera o número de telefone de um cliente com o nome Criativos:

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

Use Patch com a função Padrões para criar registros. 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 que você não esteja trabalhando com uma fonte de dados, poderá usar Patch para mesclar dois ou mais registros. 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 registro base pode ter vindo por meio da propriedade Items de uma galeria, ter sido colocado em uma variável de contexto ou vir por algum outro caminho. Mas pode rastrear o registo de base novamente para a origem de dados. Isso é importante, pois o registro inclui informações adicionais para ajudar a encontrar o registro novamente para modificação.
• 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 de Patch é o registro que você modificou ou criou. Se você criou um registro, o valor de retorno pode incluir propriedades que a fonte 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 você atualiza uma fonte de dados, um ou mais problemas podem surgir. Use IfError e IsError com o valor de retorno de para detetar e responder a erros, como descreve o Tratamento de PatchErros . 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

Patch também pode ser usado para criar ou modificar vários registros 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.

Ao usar Patch dessa maneira, o valor de retorno também é uma tabela com cada registro correspondendo um por um com os registros 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.

Patch Retorna o registro mesclado e não modifica seus argumentos ou registros em nenhuma fonte 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. 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 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. 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 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 [, ...] )

• Registos - 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:

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

Intercale registos (fora de uma origem de dados)

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 OrderId escopo de pesquisa com o OrderId de coleção A no ForAll escopo. 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. Como é 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.