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:

Overview

Use a Patch função para modificar um ou mais registros de uma fonte de dados. Atualiza os valores de campos específicos 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" } )

Description

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 base precisa de vir de uma fonte de dados. Podes obter o registo base através da propriedade Itens de uma galeria, colocá-lo numa variável de contexto ou obtê-lo por outro caminho. Mas deve ser capaz de rastrear o registo base até à fonte de dados. Este requisito é importante porque o registo inclui informações adicionais que o ajudam a encontrar novamente o registo 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

Também pode usar Patch para criar ou modificar múltiplos registos com uma única chamada.

Em vez de passar um único registo base, forneça uma tabela dos registos base no segundo argumento. Fornecer também registos de alterações numa tabela, correspondendo um a um com os registos 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 se usa Patch desta forma, o valor de retorno é também uma tabela com cada registo correspondente um por um aos registos base e de alteração.

Intercale registos fora de uma origem de dados

Especifique dois ou mais registos que pretende intercalar. A função processa registos pela ordem desde o início até ao fim da lista de argumentos, com valores de propriedades posteriores a sobreporem-se aos anteriores.

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

Syntax

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 veio de uma fonte de dados, a função encontra e modifica o registo. Se for usado o resultado de Defaults , a função cria 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 processos funcionais alteram registos por ordem desde o início até ao fim da lista de argumentos, com valores de propriedades posteriores a sobreporem-se aos 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 veio de uma fonte de dados, a função encontra e modifica o registo. Se for usado o resultado de Defaults , a função cria 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 processos funcionais alteram registos por ordem desde o início até ao fim da lista de argumentos, com valores de propriedades posteriores a sobreporem-se aos anteriores.

Merge records

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

• Registos - Obrigatório. Pelo menos dois registos que pretende intercalar. A função processa registos por ordem desde o início até ao fim da lista de argumentos, com valores de propriedades posteriores a sobreporem-se aos anteriores.

Examples

Modifique ou crie um registo (numa origem de dados)

Nestes exemplos, modifica ou cria um registo numa 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 desta fonte de dados para que possa experimentar 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:

Intercale registos (fora de uma origem de dados)

Modificar ou criar um conjunto de registos (numa fonte de dados)

Quando usa Patch com tabelas em vez de registos únicos, pode criar ou modificar múltiplos registos numa única chamada. O valor de retorno é uma tabela de registos que corresponde um por um às tabelas de entrada.

Este exemplo atualiza a Quantidade para múltiplos sabores na fonte de dados do IceCream 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 registos atualizados: { ID: 1, Flavor: "Chocolate", Quantity: 300 } e { ID: 2, Flavor: "Vanilla", Quantity: 400 }.

Este exemplo cria múltiplos registos novos usando os Defaults:

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

Para detetar erros quando modificas múltiplos registos, usa o IfError. IfError é o mecanismo preferido e funciona entre os hosts Power Fx:

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

Patch com tipos de colunas Dataverse

Os exemplos seguintes aplicam-se especificamente a fontes de dados Microsoft Dataverse. As formas dos registos variam consoante a fonte de dados (por exemplo, SharePoint e SQL Server têm formatos diferentes).

Coluna de escolha: Para definir uma coluna de Escolha, use diretamente o valor de enum. Este exemplo define uma coluna de escolha de Estado numa 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 registo com a chave primária da tabela relacionada. Este exemplo define a consulta de Contacto Primário num registo 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 escreve na fonte de dados em vez de a consultar. No entanto, avisos de delegação podem aparecer em fórmulas que utilizam Patch se a parte de seleção de registos da fórmula (como Filter, LookUp ou ForAll) envolver uma consulta que exceda os limites de delegação da fonte de dados.

Quando vê um aviso de delegação numa 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 própria. Para mais informações sobre delegação, consulte Compreender delegação numa aplicação canvas.

Erros comuns com a Patch função

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

• "Erro de rede ao usar Patch função": Este erro normalmente indica que a aplicação não consegue aceder à fonte de dados. As causas comuns incluem perda de ligação à internet, a fonte de dados temporariamente indisponível ou permissões insuficientes para o utilizador atual. Envolva a Patch chamada no IfError para fornecer uma mensagem significativa aos utilizadores.

• "Existem conflitos com alterações no servidor": Este erro ocorre quando outro utilizador ou processo modifica o mesmo registo entre o momento em que a sua aplicação lê o registo e escreve 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 utilizador não tiver permissão para criar ou modificar registos na fonte de dados, a Patch chamada falha. Use o IfError para detetar erros relacionados com permissões e orientar o utilizador.

Para padrões gerais de tratamento de erros, veja Gestão de erros.

Utilização de As ou ThisRecord

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

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

Power Apps atualmente interpreta tanto o lado esquerdo OrderId como o lado direito A[@OrderId] como um campo no âmbito Lookup. Portanto, Lookup encontra sempre a primeira linha em [dbo].[Orders1] porque a condição é sempre verdadeira (isto é, a de OrderId qualquer linha é igual a si própria).

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, use o operador As ou a palavra-chave ThisRecord para desambiguar o lado esquerdo. Como é recomendado para o cenário anterior.

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

Por exemplo, pode usar o operador As para desambiguar no exemplo seguinte.

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

Para saber mais sobre a utilização do operador As e do ThisRecord, consulte o artigo Operators .