Função ForAll no PowerAppsForAll function in PowerApps

Calcula valores e realiza ações para todos os registos de uma tabela.Calculates values and performs actions for all records of a table.

DescriçãoDescription

A função ForAll avalia uma fórmula para todos os registos de uma tabela.The ForAll function evaluates a formula for all records of a table. A fórmula pode calcular um valor e/ou realizar ações, como, por exemplo, modificar os dados ou trabalhar com uma ligação.The formula can calculate a value and/or perform actions, such as modifying data or working with a connection.

Fields of the record currently being processed are available within the formula. You simply reference them by name as you would any other value. You can also reference control properties and other values from throughout your app. For more details, see the examples below and working with record scope.

Valor devolvidoReturn value

O resultado de cada avaliação de fórmula é devolvido numa tabela, pela mesma ordem da tabela de entrada.The result of each formula evaluation is returned in a table, in the same order as the input table.

Se o resultado da fórmula for um valor único, a tabela resultante será uma tabela de uma só coluna.If the result of the formula is a single value, the resulting table will be a single column table. Se o resultado for um registo, a tabela resultante conterá registos com as mesmas colunas que o registo do resultado.If the result of the formula is a record, the resulting table will contain records with the same columns as the result record.

Se o resultado for um valor blank (em branco), não haverá registos na tabela resultante relativa a esse registo de entrada.If the result of the formula is a blank value, then there will be no record in the result table for that input record. Neste caso, haverá menos registos na tabela resultante do que na tabela de origem.In this case, there will be fewer records in the result table than the source table.

Realizar açõesTaking action

A fórmula pode inclui funções que realizam ações, como modificar os registos de uma origem de dados com as funções Patch e Collect.The formula can include functions that take action, such as modifying the records of a data source with the Patch and Collect functions. A fórmula também pode chamar métodos em ligações.The formula can also call methods on connections. Podem ser realizadas várias ações por registo com o operador ;.Multiple actions can be performed per record by using the ; operator. Não pode modificar a tabela que é o alvo da função ForAll.You can't modify the table that is the subject of the ForAll function.

Ao escrever a sua fórmula, tenha em atenção que os registos podem ser processados por qualquer ordem e, sempre que possível, em paralelo.When writing your formula, keep in mind that records can be processed in any order and, when possible, in parallel. O primeiro registo da tabela pode ser processado após o último.The first record of the table may be processed after the last record. Tenha atenção para evitar dependências de ordenação.Take care to avoid ordering dependencies. Por este motivo, não pode utilizar as funções UpdateContext, Clear e ClearCollect numa função ForAll, pois poderiam ser facilmente utilizadas para conter variáveis que seriam suscetíveis para este efeito.For this reason, you can't use the UpdateContext, Clear, and ClearCollect functions within a ForAll function because they could easily be used to hold variables that would be susceptible to this effect. Pode utilizar Collect, mas a ordem pela qual os registos são adicionados é indefinida.You can use Collect, but the order in which records are added is undefined.

Muitas funções que modificam as origens de dados, incluindo Collect, Remove e Update, devolvem as origens de dados modificadas como o valor de retorno.Several functions that modify data sources, including Collect, Remove, and Update, return the changed data source as their return value. Estes valores de retorno podem ser grandes e consumir recursos significativos se forem devolvidos para todos os registos da tabela ForAll.These return values can be large and consume significant resources if returned for every record of the ForAll table. Também poderá achar que estes valores não são aqueles que esperava, porque ForAll pode funcionar em paralelo e pode separar os efeitos secundários destas funções, impedindo-as de obterem os respetivos resultados.You may also find that these return values are not what you expect, because ForAll can operate in parallel and may separate the side effects of these functions from obtaining their result. Felizmente, se o valor de retorno de ForAll não for realmente utilizado, que é muitas vezes o caso com as funções de modificação de dados, esse valor não será criado e não haverá lugar a preocupações relativas a recursos ou ordenações.Fortunately, if the return value from ForAll is not actually used, which is often the case with data modification functions, then the return value will not be created and there are no resource or ordering concerns. Contudo, se utilizar o resultado de uma função ForAll e uma das funções que devolvem uma origem de dados, pense cuidadosamente em como estruturar o resultado e experimente primeiro em pequenos conjuntos de dados.But if you are using the result of a ForAll and one of the functions that returns a data source, think carefully about how you structure the result and try it out first on small data sets.

AlternativasAlternatives

Muitas funções do PowerApps podem processar mais de um valor ao mesmo tempo mediante a utilização de uma tabela de coluna única.Many functions in PowerApps can process more than one value at a time through the use of a single-column table. Por exemplo, a função Len pode processar uma tabela de valores de texto, devolvendo uma tabela de comprimentos, da mesma forma que ForAll faria.For example, the Len function can process a table of text values, returning a table of lengths, in the same manner that ForAll could. Esta alternativa pode eliminar a necessidade de utilizar ForAll em muitos casos, pode ser mais eficiente e mais fácil de ler.This can eliminate the need to use ForAll in many cases, can be more efficient, and is easier to read.

Outra consideração é que ForAll não pode ser delegada, ao passo que outras funções o podem ser, como Filtrer.Another consideration is that ForAll is not delegable while other functions may be, such as Filter.

DelegaçãoDelegation

When used with a data source, this function can't be delegated. Only the first portion of the data source will be retrieved and then the function applied. The result may not represent the complete story. A blue dot will appear at authoring time to remind you of this limitation and to suggest switching to delegable alternatives where possible. For more information, see the delegation overview.

SintaxeSyntax

ForAll( Tabela, Fórmula )ForAll( Table, Formula )

  • Tabela - Necessário.Table - Required. Tabela onde vai ser executada a função.Table to be acted upon.
  • Fórmula - Necessário.Formula - Required. A fórmula a ser avaliada para todos os registos da Tabela.The formula to evaluate for all records of the Table.

ExemplosExamples

CálculosCalculations

Os exemplos seguintes utilizam a origem de dados Squares:The following examples use the Squares data source:

Para criar esta origem de dados como uma coleção, defina a propriedade OnSelect de um controlo de Botão como esta fórmula, abra o Modo de pré-visualização e, em seguida, clique ou toque no botão:To create this data source as a collection, set the OnSelect property of a Button control to this formula, open Preview mode, and then click or tap the button:

  • ClearCollect( Squares, [ "1", "4", "9" ] )ClearCollect( Squares, [ "1", "4", "9" ] )
FórmulaFormula DescriçãoDescription ResultadoResult
ForAll( Squares, Sqrt( Valor ) )ForAll( Squares, Sqrt( Value ) )

Sqrt( Squares )Sqrt( Squares )
Calcula a raiz quadrada da coluna Valor de todos os registos da tabela de entrada.For all the records of the input table, calculates the square root of the Value column. A função Sqrt também pode ser utilizada com tabelas de uma só coluna, o que permite realizar este exemplo sem ForAll.The Sqrt function can also be used with a single-column table, making it possible perform this example without using ForAll.
ForAll( Squares, Power( Valor, 3 ) )ForAll( Squares, Power( Value, 3 ) ) Eleva a coluna Valor à terceira potência de todos os registos da tabela de entrada.For all the records of the input table, raises the Value column to the third power. A função Power não suporta tabelas de uma só coluna.The Power function does not support single-column tables. Por conseguinte, ForAll tem de ser utilizado neste caso.Therefore, ForAll must be used in this case.

Utilizar ligaçõesUsing a connection

Os exemplos seguintes utilizam a origem de dados Expressions:The following examples use the Expressions data source:

Para criar esta origem de dados como uma coleção, defina a propriedade OnSelect de um controlo de Botão como esta fórmula, abra o Modo de pré-visualização e, em seguida, clique ou toque no botão:To create this data source as a collection, set the OnSelect property of a Button control to this formula, open Preview mode, and then click or tap the button:

  • ClearCollect( Expressions, [ "Hello", "Good morning", "Thank you", "Goodbye" ] )ClearCollect( Expressions, [ "Hello", "Good morning", "Thank you", "Goodbye" ] )

Este exemplo também utiliza uma ligação do Microsoft Translator.This example also uses a Microsoft Translator connection. Para adicionar esta ligação à sua aplicação, veja o tópico Manage connections (Gerir ligações).To add this connection to your app, see the topic about how to manage connections.

FórmulaFormula DescriçãoDescription ResultadoResult
ForAll( Expressions, MicrosoftTranslator.Translate( Value, "es" ) )ForAll( Expressions, MicrosoftTranslator.Translate( Value, "es" ) ) Traduz os conteúdos da coluna Value para espanhol (abreviado para “es”) de todos os registos da tabela Expressions.For all the records in the Expressions table, translate the contents of the Value column into Spanish (abbreviated "es").
ForAll( Expressions, MicrosoftTranslator.Translate( Value, "fr" ) )ForAll( Expressions, MicrosoftTranslator.Translate( Value, "fr" ) ) Traduz os conteúdos da coluna Value para francês (abreviado para “fr”) de todos os registos da tabela Expressions.For all the records in the Expressions table, translate the contents of the Value column into French (abbreviated "fr").

Copiar tabelasCopying a table

Por vezes, é necessário filtrar, formatar, ordenar e manipular dados.Sometimes you need to filter, shape, sort, and manipulate data. O PowerApps disponibiliza várias funções para o fazer, como Filter, AddColumns e Sort.PowerApps provides a number of functions for doing this, such as Filter, AddColumns, and Sort. O PowerApps processa cada tabela como um valor, permitindo-lhe fluir através de fórmulas e ser facilmente consumida.PowerApps treats each table as a value, allowing it to flow through formulas and be consumed easily.

E é possível que numa determinada altura queira fazer uma cópia desse resultado, para utilizar mais tarde.And sometime you will want to make a copy of this result for later use. Ou poderá querer mover informações de uma origem de dados para outra.Or you will want to move information from one data source to another. O PowerApps disponibiliza a função Collect para copiar dados.PowerApps provides the Collect function to copy data.

Mas antes de fazer a cópia, pense cuidadosamente se é realmente necessária.But before you make that copy, think carefully if it is really needed. É possível resolver muitas destas situações ao filtrar e formatar a origem de dados subjacente a pedido com uma fórmula.Many situations can be addressed by filtering and shaping the underlying data source on demand with a formula. Algumas das desvantagens de fazer cópias incluem:Some of the downsides to making a copy include:

  • Duas cópias das mesmas informações significa que uma destas pode ficar dessincronizada.Two copies of the same information means that one of them can fall out of sync.
  • A criação de cópias pode consumir muita memória do computador, largura de banda de rede e/ou tempo.Making a copy can consume a lot of computer memory, network bandwidth, and/or time.
  • Na maioria das origens de dados, a criação de cópias não pode ser delegada, o que limita a quantidade de dados que podem ser movidos.For most data sources, copying cannot be delegated, limiting how much data can be moved.

Os exemplos seguintes utilizam a origem de dados Products:The following examples use the Products data source:

Para criar esta origem de dados como uma coleção, defina a propriedade OnSelect de um controlo de Botão como esta fórmula, abra o Modo de pré-visualização e, em seguida, clique ou toque no botão:To create this data source as a collection, set the OnSelect property of a Button control to this formula, open Preview mode, and then click or tap the button:

  • ClearCollect( Products, Table( { Product: "Widget", 'Quantity Requested': 6, 'Quantity Available': 3 }, { Product: "Gadget", 'Quantity Requested': 10, 'Quantity Available': 20 }, { Product: "Gizmo", 'Quantity Requested': 4, 'Quantity Available': 11 }, { Product: "Apparatus", 'Quantity Requested': 7, 'Quantity Available': 6 } ) )ClearCollect( Products, Table( { Product: "Widget", 'Quantity Requested': 6, 'Quantity Available': 3 }, { Product: "Gadget", 'Quantity Requested': 10, 'Quantity Available': 20 }, { Product: "Gizmo", 'Quantity Requested': 4, 'Quantity Available': 11 }, { Product: "Apparatus", 'Quantity Requested': 7, 'Quantity Available': 6 } ) )

O nosso objetivo é trabalhar com uma tabela derivada que inclui apenas os itens que foram mais pedidos face aos que há disponíveis e para os quais temos de fazer encomenda:Our goal is to work with a derivative table that includes only the items where more has been requested than is available, and for which we need to place an order:

Esta tarefa pode ser feita de algumas formas diferentes, sendo que todas produzem o mesmo resultado, com vários prós e contras.We can perform this task in a couple of different ways, all of which produce the same result, with various pros and cons.

Formatação de tabelas a pedidoTable shaping on demand

Não faça essa cópia!Don't make that copy! Podemos utilizar a fórmula abaixo onde quer que seja necessário:We can use the following formula anywhere we need:

  • ShowColumns( AddColumns( Filter( Products, 'Quantity Requested' > 'Quantity Available' ), "Quantity To Order", 'Quantity Requested' - 'Quantity Available' ), "Product", "Quantity To Order" )ShowColumns( AddColumns( Filter( Products, 'Quantity Requested' > 'Quantity Available' ), "Quantity To Order", 'Quantity Requested' - 'Quantity Available' ), "Product", "Quantity To Order" )

As funções Filter e AddColumns criam um âmbito de registo para realizar as operações de comparação e subtração, respetivamente, com os campos “Quantity Requested” e “Quantity Available” de cada registo.A record scope is created by the Filter and AddColumns functions to perform the comparison and subtraction operations, respectively, with the 'Quantity Requested' and 'Quantity Available' fields of each record.

Neste exemplo, a função Filter pode ser delegada.In this example, the Filter function can be delegated. Isto é importante, pois pode encontrar todos os produtos que correspondem aos critérios, mesmo que sejam apenas alguns registos de uma tabela que tenha milhões.This is important, as it can find all the products that meet the criteria, even if that is only a few records out of a table of millions. Neste momento, ShowColumns e AddColumns não podem ser delegadas, pelo que o número real de produtos que têm de ser ordenados será limitado.At this time, ShowColumns and AddColumns cannot be delegated, so the actual number of products that needs to be ordered will be limited. Se souber que o tamanho deste resultado será sempre relativamente pequeno, esta abordagem é adequada.If you know the size of this result will always be relatively small, this approach is fine.

E visto que não fizemos uma cópia, não é necessário fazer a gestão de cópias adicionais das informações nem se corre o risco de tais cópias ficarem desatualizadas.And because we didn't make a copy, there is no additional copy of the information to manage or fall out of date.

ForAll a pedidoForAll on demand

Outra abordagem é utilizar a função ForAll para substituir as funções de formatação de tabela:Another approach is to use the ForAll function to replace the table-shaping functions:

  • ForAll( Products, If( 'Quantity Requested' > 'Quantity Available', { Product: Product, 'Quantity To Order': 'Quantity Requested' - 'Quantity Available' } ) )ForAll( Products, If( 'Quantity Requested' > 'Quantity Available', { Product: Product, 'Quantity To Order': 'Quantity Requested' - 'Quantity Available' } ) )

Algumas pessoas podem achar esta fórmula mais fácil de ler e escrever.This formula may be simpler for some people to read and write.

Nenhuma parte de ForAll pode ser delegada.No part of the ForAll is delegable. Só será avaliada a primeira parte da tabela Produtos, o que poderá constituir um problema se esta for demasiado grande.Only the first portion of the Products table will be evaluated, which could be a problem if this table is very large. Uma vez que Filter podia ser delegado no exemplo anterior, poderia funcionar melhor com conjuntos de dados grandes.Because Filter could be delegated in the previous example, it could work better with large data sets.

Recolher o resultadoCollect the result

Em algumas situações, poderá ser necessária uma cópia dos dados.In some situations, a copy of data may be required. Poderá dar-se o caso de querer mover informações de uma origem de dados para outra.You may need to move information from one data source to another. Neste exemplo, as encomendas são feitas através de uma tabela NewOrder no sistema de um fornecedor.In this example, orders are placed through a NewOrder table on a vendor's system. Para interações de alta velocidade por parte dos utilizadores, poderá querer colocar em cache uma cópia local de uma tabela, para que não haja latência de servidor.For high-speed user interactions, you may want to cache a local copy of a table so that there is no server latency.

Utilizamos a mesma forma de tabela dos dois exemplos anteriores, mas reunimos o resultado numa coleção:We use the same table shaping as the previous two examples, but we capture the result into a collection:

  • ClearCollect( NewOrder, ShowColumns( AddColumns( Filter( Products, 'Quantity Requested' > 'Quantity Available' ), "Quantity To Order", 'Quantity Requested' - 'Quantity Available' ), "Product", "Quantity To Order" ) )ClearCollect( NewOrder, ShowColumns( AddColumns( Filter( Products, 'Quantity Requested' > 'Quantity Available' ), "Quantity To Order", 'Quantity Requested' - 'Quantity Available' ), "Product", "Quantity To Order" ) )
  • ClearCollect( NewOrder, ForAll( Products, If( 'Quantity Requested' > 'Quantity Available', { Product: Product, 'Quantity To Order': 'Quantity Requested' - 'Quantity Available' } ) ) )ClearCollect( NewOrder, ForAll( Products, If( 'Quantity Requested' > 'Quantity Available', { Product: Product, 'Quantity To Order': 'Quantity Requested' - 'Quantity Available' } ) ) )

ClearCollect e Collect não podem ser delegados.ClearCollect and Collect can't be delegated. Como resultado, a quantidade de dados que podem ser movidos desta forma é limitada.As a result the amount of data that can be moved in this manner is limited.

Recolher com ForAllCollect within ForAll

Por fim, podemos realizar a função Collect diretamente em ForAll:Finally, we can perform the Collect directly within the ForAll:

  • Clear( ProductsToOrder ); ForAll( Products, If( 'Quantity Requested' > 'Quantity Available', Collect( NewOrder, { Product: Product, 'Quantity To Order': 'Quantity Requested' - 'Quantity Available' } ) ) )Clear( ProductsToOrder ); ForAll( Products, If( 'Quantity Requested' > 'Quantity Available', Collect( NewOrder, { Product: Product, 'Quantity To Order': 'Quantity Requested' - 'Quantity Available' } ) ) )

Novamente, a função ForAll não pode ser delegada atualmente.Again, the ForAll function can't be delegated at this time. Se a tabela Produtos for grande, ForAll olha apenas para o primeiro conjunto de registos e poderemos perder alguns produtos que têm de ser encomendados.If our Products table is large, ForAll will look at the first set of records only and we may miss some products that need to be ordered. Mas esta abordagem é adequada para as tabelas que sabemos que vão permanecer pequenas.But for tables that we know will remain small, this approach is fine.

Tenha em atenção não estamos a reunir o resultado de ForAll.Note that we are not capturing the result of the ForAll. As chamadas da função Collect feitas a partir deste vão devolver a origem de dados NewOrder de todos os registos, o que pode devolver muitos dados se estivermos a reunir o resultado do mesmo.The Collect function calls made from within it will return the NewOrder data source for all the records, which could add up to a lot of data if we were capturing it.