Função de Patch no PowerAppsPatch function in PowerApps

Modifica ou cria um ou mais registos numa origem de dados, ou intercala registos fora de uma origem de dados.Modifies or creates one or more records in a data source, or merges records outside of a data source.

Utilize a função de Patch para modificar registos em situações complexas, como ao realizar atualizações que não necessitam de interação do utilizador ou ao utilizar formulários que abrangem vários ecrãs.Use the Patch function to modify records in complex situations, such as when you perform updates that require no user interaction or use forms that span multiple screens.

Em situações menos complexas, pode utilizar o controlo Editar formulário para atualizar registos numa origem de dados mais facilmente.In less complex situations, you can use the Edit form control to update records in a data source more easily. Quando adiciona um controlo Editar formulário, pode disponibilizar aos utilizadores um formulário para preencher e, em seguida, guardar as alterações numa origem de dados.When you add an Edit form control, you provide users with a form to fill in and then save the changes to a data source. Para obter mais informações, veja Understand data forms (Compreender formulários de dados).For more information, see Understand data forms.

Descrição geralOverview

Utilize a função de Patch para modificar um ou mais registos de uma origem de dados.Use the Patch function to modify one or more records of a data source. Os valores de campos específicos são modificados sem afetar outras propriedades.The values of specific fields are modified without affecting other properties. Por exemplo, esta fórmula altera o número de telefone de um cliente com o nome Criativos:For example, this formula changes the phone number for a customer named Contoso:

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

Utilize o Patch com a função Predefinições para criar registos.Use Patch with the Defaults function to create records. Utilize este comportamento para criar um único ecrã para criar e editar registos.Use this behavior to build a single screen for both creating and editing records. Por exemplo, esta fórmula cria um registo de um cliente com o nome Criativos:For example, this formula creates a record for a customer named Contoso:

Patch( Customers, Defaults( Customer ), { Name: "Criativos" } )Patch( Customers, Defaults( Customer ), { Name: “Contoso” } )

Mesmo se não estiver a trabalhar com uma origem de dados, pode utilizar o Patch para intercalar dois ou mais registos.Even if you're not working with a data source, you can use Patch to merge two or more records. Por exemplo, esta fórmula intercala dois registos num que identifica o número de telefone e a localização da Criativos:For example, this formula merges two records into one that identifies both the phone number and the location for Contoso:

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

DescriçãoDescription

Modifique ou crie um registo numa origem de dadosModify or create a record in a data source

Para utilizar esta função com uma origem de dados, especifique a origem de dados e, em seguida, especifique um registo de base:To use this function with a data source, specify the data source, and then specify a base record:

  • Para modificar um registo, o registo de base tem de ser proveniente de uma origem de dados.To modify a record, the base record needs to have come from a data source. O registo de base pode ser proveniente de uma propriedade de Itens da galeria, ter sido colocado numa variável de contexto ou vir de outro caminho.The base record may have come through a gallery's Items property, been placed in a context variable, or come through some other path. Mas deve ser capaz de rastrear o registo de base novamente para a origem de dados.But you should be able to trace the base record back to the data source. Isto é importante porque o registo irá incluir informações adicionais para ajudar a encontrar o registo novamente para ser modificado.This is important as the record will include additional information to help find the record again for modification.
  • Para criar um registo, utilize a função Predefinições para criar um registo de base com valores predefinidos.To create a record, use the Defaults function to create a base record with default values.

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.Then specify one or more change records, each of which contains new property values that override property values in the base record. 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.Change records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

O valor de retorno do Patch é o registo modificado ou criado.The return value of Patch is the record that you modified or created. Se tiver criado um registo, o valor de retorno pode incluir propriedades que a origem de dados gerou automaticamente.If you created a record, the return value may include properties that the data source generated automatically.

Quando atualizar uma origem de dados, um ou mais problemas podem surgir.When you update a data source, one or more issues may arise. Utilize a função de Erros para identificar e examinar problemas, conforme descrito em Trabalhar com Origens de Dados.Use the Errors function to identify and examine issues, as Working with Data Sources describes.

As funções relacionadas incluem a função de Atualização, que pode utilizar para substituir um registo completo e a função Recolher, que pode utilizar para criar um registo.Related functions include the Update function, which you can use to replace an entire record, and the Collect function, which you can use to create a record. Pode utilizar a função UpdateIf para modificar as propriedades específicas de vários registos com base numa condição.You can use the UpdateIf function to modify specific properties of multiple records based on a condition.

Modifique ou crie um conjunto de registos numa origem de dadosModify or create a set of records in a data source

O Patch também pode ser utilizado para criar ou modificar vários registos com uma única chamada.Patch can also be used to create or modify multiple records with a single call.

Em vez de transmitir um único registo de base, uma tabela de registos de base pode ser oferecida no segundo argumento.Instead of passing a single base record, a table of base records can be provided in the second argument. Os registos de alteração também são oferecidos numa tabela, correspondendo a um-para-um com os registos de base.Change records are provided in a table as well, corresponding one-for-one with the base records. O número de registos de cada tabela de alterações tem de ser igual ao número de registos na tabela de base.The number of records in each change table must be the same as the number of records in the base table.

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.When using Patch in this manner, the return value is also a table with each record corresponding one-for-one with the base and change records.

Intercale registos fora de uma origem de dadosMerge records outside of a data source

Especifique dois ou mais registos que pretende intercalar.Specify two or more records that you want to merge. 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.Records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

O Patch devolve o registo intercalado e não altera os respetivos argumentos ou registos em quaisquer origens de dados.Patch returns the merged record and doesn't modify its arguments or records in any data sources.

SintaxeSyntax

Modifique ou crie um registo numa origem de dadosModify or create a record in a data source

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

  • OrigemDeDados – necessário.DataSource – Required. A origem de dados que contém o registo que pretende modificar ou irá conter o registo que pretende criar.The data source that contains the record that you want to modify or will contain the record that you want to create.
  • BaseRecord – Necessário.BaseRecord – Required. O registo a modificar ou criar.The record to modify or create. Se o registo provém de uma origem de dados, o registo é encontrado e modificado.If the record came from a data source, the record is found and modified. Se o resultado das Predefinições é utilizado, é criado um registo.If the result of Defaults is used, a record is created.
  • ChangeRecord(s) – Necessário.ChangeRecord(s) – Required. Um ou mais registos que contêm propriedades para modificar no BaseRecord.One or more records that contain properties to modify in the 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.Change records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

Modifique ou crie um conjunto de registos numa origem de dadosModify or create a set of records in a data source

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

  • OrigemDeDados – necessário.DataSource – Required. A origem de dados que contém os registos que pretende modificar ou irá conter os registos que pretende criar.The data source that contains the records that you want to modify or will contain the records that you want to create.
  • BaseRecordTable – Necessário.BaseRecordTable – Required. Uma tabela de registos para modificar ou criar.A table of records to modify or create. Se o registo provém de uma origem de dados, o registo é encontrado e modificado.If the record came from a data source, the record is found and modified. Se o resultado das Predefinições é utilizado, é criado um registo.If the result of Defaults is used, a record is created.
  • ChangeRecordTable(s) – Necessário.ChangeRecordTable(s) – Required. Uma ou mais tabelas de registos que contêm propriedades para modificar cada registo do BaseRecordTable.One or more tables of records that contain properties to modify for each record of the 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.Change records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

Intercalar registosMerge records

Patch( Registo1, Registo2 [, …] )Patch( Record1, Record2 [, …] )

  • Registo(s) – Necessário.Record(s) - Required. Pelo menos dois registos que pretende intercalar.At least two records that you want to merge. 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.Records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

ExemplosExamples

Modifique ou crie um registo (numa origem de dados)Modify or create a record (in a data source)

Nestes exemplos, terá de modificar ou criar um registo numa origem de dados, com o nome Gelado, que contém os dados nesta tabela e gera automaticamente os valores existentes na coluna com o ID:In these examples, you'll modify or create a record in a data source, named IceCream, that contains the data in this table and automatically generates the values in the ID column:

FórmulaFormula DescriçãoDescription ResultadoResult
Patch( IceCream,
First( Filtro( IceCream, Flavor = "Chocolate" ) ), { Quantity: 400 } )
Patch( IceCream,
First( Filter( IceCream, Flavor = "Chocolate" ) ), { Quantity: 400 } )
Modifica um registo na origem de dados Gelado:Modifies a record in the IceCream data source:
  • A coluna com o ID do registo a modificar contém o valor de 1.The ID column of the record to modify contains the value of 1. (O registo Chocolate tem esse ID.)(The Chocolate record has that ID.)
  • O valor na coluna Quantidade é alterado para 400.The value in the Quantity column changes to 400.
{ ID: 1, Flavor: "Chocolate", Quantity: 400 }{ ID: 1, Flavor: "Chocolate", Quantity: 400 }

A entrada Chocolate na origem de dados Gelado foi modificada.The Chocolate entry in the IceCream data source has been modified.
Patch( IceCream, Defaults( IceCream ), { Flavor: "Morango" } )Patch( IceCream, Defaults( IceCream ), { Flavor: “Strawberry” } ) Cria um registo na origem de dados Gelado:Creates a record in the IceCream data source:
  • A coluna com o ID contém o valor 3, que a origem de dados gera automaticamente.The ID column contains the value 3, which the data source generates automatically.
  • A coluna Quantidade contém 0, que é o valor predefinido para essa coluna na origem de dados Gelado, conforme é especificado em Predefinições.The Quantity column contains 0, which is the default value for that column in the IceCream data source, as the Defaults function specifies.
  • A coluna Sabor contém o valor da Morango.The Flavor column contains the value of Strawberry.
{ ID: 3, Flavor: “Strawberry”, Quantity: 0 }{ ID: 3, Flavor: “Strawberry”, Quantity: 0 }

A entrada Morango na origem de dados Gelado foi criada.The Strawberry entry in the IceCream data source has been created.

Depois das fórmulas anteriores serem avaliadas, a origem de dados termina com estes valores:After the previous formulas have been evaluated, the data source ends with these values:

Intercale registos (fora de uma origem de dados)Merge records (outside of a data source)

FórmulaFormula DescriçãoDescription ResultadoResult
Patch( { Name: "Jaime", Score: 90 }, { Name: "João", Passed: true } )Patch( { Name: "James", Score: 90 }, { Name: "Jim", Passed: true } ) Intercala dois registos fora de uma origem de dados:Merges two records outside of a data source:
  • Os valores existentes na coluna Nome de cada registo não correspondem.The values in the Name column of each record don't match. O resultado contém o valor (João) no registo mais próximo ao fim da lista de argumentos em vez do valor (Jaime) no registo mais próximo ao início.The result contains the value (Jim) in the record that's closer to the end of the argument list instead of the value (James) in the record that's closer to the start.
  • O primeiro registo contém uma coluna (Pontuação) que não existe no segundo registo.The first record contains a column (Score) that doesn't exist in the second record. O resultado contém essa coluna com o respetivo valor (90).The result contains that column with its value (90).
  • O segundo registo contém uma coluna (Passou) que não existe no primeiro registo.The second record contains a column (Passed) that doesn't exist in the first record. O resultado contém essa coluna com o respetivo valor (verdadeiro).The result contains that column with its value (true).
{ Name: "João", Score: 90, Passed: true }{ Name: "Jim", Score: 90, Passed: true }