# For Each **For Each** cria um loop dentro de uma estrutura JSON, processando cada elemento da matriz em um subpipeline. A expressão configurada deve retornar uma matriz. Caso contrário, o loop For Each não será executado. [Saiba mais sobre as aplicações práticas do For Each](/documentation/connectors-and-triggers/pt-br/connectors/logic/for-each/for-each-example-of-use.md). ## Parâmetros Configure o conector usando os parâmetros abaixo. Os campos que suportam expressões Double Braces estão marcados na coluna **Suporta DB**. | **Parâmetro** | **Descrição** | **Tipo** | **Suporta DB** | **Padrão** | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------- | ---------- | | **Alias** | Nome (alias) para a saída deste conector, permitindo que você faça referência a ele posteriormente no fluxo usando expressões Double Braces. | String | ✅ | for-each-1 | | **Expression** | A expressão usada para filtrar e recuperar a estrutura JSON para iteração. Suporta expressões **Double Braces** e expressões **JSON Path**. | String | ✅ | $ | | **Element Identifier** | Elemento único que identifica a linha em processamento (por exemplo, elemento "id"). | String | ❌ | N/A | | **Parallel Execution** | Se ativado, este parâmetro processa até 10 elementos da matriz simultaneamente. À medida que cada execução é concluída, a próxima começa automaticamente até a conclusão. Se desativado, o processamento é serial, exigindo que cada elemento seja concluído antes do início do próximo. | Booleano | ❌ | *False* | | **Advanced** | Habilita opções avançadas. | Boolean | ❌ | False | | **Max Number Length** | Comprimento máximo permitido para valores numéricos em JSON. Se não for especificado, o limite padrão definido pelo Jackson (1000) será aplicado. | Integer | ✅ | N/A | | **Fail On Error** | Quando ativado, este parâmetro suspende o pipeline apenas se ocorrer um erro crítico dentro da estrutura de iteração, impedindo sua conclusão. Ele não é acionado para erros dentro dos subpipelines **onProcess** ou **onException**. Para interrupções baseadas em qualquer ocorrência, use o conector **Do While**. | Booleano | ❌ | *False* | ## Opções de sintaxe Cada conector permite dois métodos para definir a matriz de entrada: * **Expressões JSON Path**: o caminho tradicional (por exemplo: `$.body.items`). * **Expressões Double Braces:** permitem usar referências diretas de etapas anteriores ou funções integradas. ### **Exemplos de Expressões JSON Path** ``` $.[?(@.status == 'EXPIRED')] ``` A expressão acima mostra como a mensagem recebida pelo componente pode ser filtrada: neste exemplo, o *array* é a raiz do objeto e somente os elementos cujo atributo status seja EXPIRED serão processados pelo componente **For Each**. ``` $.body.* ``` Obtém todo o conteúdo do *body* da mensagem recebida. ``` $.body.products.* ``` Obtém o conteúdo de uma matriz de produtos que está dentro do corpo da mensagem recebida. Recomendamos que as expressões usadas no parâmetro Expressão JSON Path sejam validadas usando a seguinte referência: [https://jsonpath.com/ ](https://jsonpath.com/) ### Exemplos de Double Braces O conector **For Each** suporta todas as funções de **Double Braces** existentes que retornam valores de array para iteração de arrays. ``` {{step.stepName.response.array}} ``` A expressão acima representa uma referência ou um array proveniente de um componente específico. Você pode usar `step.stepName` no formulário de configuração do **For Each**. #### Acessando o elemento da iteração atual Ao usar o conector **For Each** na Digibee Integration Platform, cada iteração processa um elemento do array de entrada. Durante a execução, os conectores dentro da iteração podem sobrescrever o payload. Quando isso acontece, o elemento original que está sendo processado pode deixar de estar acessível usando `{{$.}}`. Para garantir acesso consistente ao elemento atual, a plataforma fornece uma referência reservada: ``` {{iterators..current}} ``` **Exemplo** Se o alias do seu **For Each** for `for-each-1`, você pode acessar o elemento atual usando: ``` {{iterators.for-each-1.current}} ``` Essa referência permanece disponível durante toda a iteração, mesmo que outros conectores retornem novos payloads. ## Definindo o subpipeline que é executado a cada iteração Para definir o *subpipeline* que será executado a cada iteração, basta clicar no ícone **onProcess** do componente **For Each.** ![](/files/CJPwB7VfGEePPxy8kNkT) Ao clicar nesse ícone, um *subpipeline* será criado (ou exibido, caso já exista). Então basta construir o fluxo desejado conforme a necessidade de execução de cada iteração. {% hint style="info" %} Caso sejam utilizados componentes [**Session Management**](/documentation/connectors-and-triggers/pt-br/connectors/structured-data/session-management.md) para manipular dados de cada elemento do *array* no *subpipeline* do **For Each** e a opção **Parallel Execution** esteja ativa, é necessário que a opção **Scoped** do **Session Management** esteja ativa para que cada execução em paralelo acesse os seus respectivos dados. {% endhint %} ## Tratando erros no loop O comportamento padrão do **For Each** é interromper a execução caso algum erro seja encontrado. Erros são situações atípicas na execução de um *pipeline* que incorrem em uma parada. Por exemplo, o uso de um componente [**Assert V2** ](/documentation/connectors-and-triggers/pt-br/connectors/tools/assert-v2.md)causa um erro no *pipeline* quando a condição de asserção não for satisfeita. Outras situações de erro ocorrem quando são utilizados componentes com a configuração **Fail On Error** habilitada. Conforme explicado anteriormente, é possível definir um *subpipeline* para tratamento de erros. A definição desse *subpipeline* é feita através do ícone **onException** do componente **For Each**: ![](/files/iP2JcYtwzjzI6xqXqvLK) [ Leia o artigo sobre subpipelines para entender melhor o funcionamento](/documentation/developer-guide/pt-br/development-cycle/build-overview/pipelines/subpipelines.md). {% hint style="warning" %} Não é possível interromper a execução de todo o loop **For Each**. A interrupção pode ser feita apenas na iteração atual, através de componentes que possuam o parâmetro **Fail On Error** ativado dentro dos *subpipelines* *onProcess* e *onException*. {% endhint %} ## Erro grave de estrutura durante o *subpipeline* onException * o *loop* será interrompido; * o erro será lançado para o próximo componente ao qual o componente For Each esteja associado; * caso o **For Each** esteja no fluxo principal do *pipeline*, então o *pipeline* será interrompido; * se o **For Each** estiver dentro de um componente que possui *subpipeline*, então o *subpipeline onException* será invocado e o erro será informado na entrada desse *subpipeline*. ### Fluxo de mensagens #### Entrada For Each aceita qualquer estrutura JSON que contenha uma matriz. Essa matriz pode ser localizada por meio do JSON Path ou injetada por meio de chaves duplas. Se a expressão (independentemente da sintaxe escolhida) não retornar uma matriz válida, nenhuma iteração será realizada. #### Saída * **total:** número total de elementos processados. * **success:** número total de elementos processados com sucesso. * **failed:** número total de elementos que não puderam ser processados. {% hint style="info" %} Para informar que uma linha foi processada corretamente e iterar o valor do campo `"success"`, cada execução do *subpipeline* *onProcess* deve responder com `{ "success": true }` ao seu término. Somente desta forma a mensagem de saída representará corretamente o resultado dos processamentos. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/logic/for-each.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.