Consulte os conetores suportados para a solução Application Integration.

Tarefa de ciclo For Each

A tarefa For Each Loop permite-lhe fazer chamadas repetidas a uma subintegração a partir da sua integração atual (principal). A tarefa itera a variável de matriz configurada e chama a subintegração para cada elemento na matriz. O número de vezes que a subintegração é chamada é igual à dimensão da variável de matriz.

O ID do acionador da API e o nome da integração identificam a subintegração que quer executar.

A tarefa também permite recolher a resposta de cada execução de subintegração e armazenar o valor na sua integração atual para utilização em tarefas posteriores. Pode usar qualquer uma das seguintes abordagens para recolher as respostas:

• Recolha a resposta de cada execução numa variável de matriz, em que cada elemento da matriz tem a resposta de uma execução específica. Para reunir as respostas, configure a propriedade Collect values from sub-integration output(s).
• Agregue as respostas de todas as execuções numa única variável. Para agregar as respostas, configure a propriedade Response parameter override mapping.

Nota:

• Uma tarefa For Each Loop pode ser executada um máximo de 8000 iterações.
• O tamanho cumulativo dos dados recolhidos de cada execução da subintegração não pode exceder 50 MB. Se o tamanho exceder 50 MB, a integração falha e as tarefas a jusante não são executadas.
• Se uma integração na tarefa For Each Loop falhar, toda a tarefa falha e as tarefas a jusante não são executadas. Para evitar a falha de toda a integração, pode especificar uma estratégia de execução para a tarefa no respetivo painel de configuração de união. Consulte Participar para ver mais detalhes.

Antes de começar

• Certifique-se de que anexou uma conta de serviço gerida pelo utilizador à sua integração. Se a sua integração não tiver uma conta de serviço gerida pelo utilizador configurada, é utilizada por predefinição a conta de serviço predefinida ([e-mail]) para autenticação.
• Certifique-se de que a sua conta de serviço tem a função do IAM Application Integration Invoker. Para obter informações sobre a atribuição de funções a uma conta de serviço, consulte o artigo Faça a gestão do acesso às contas de serviço.

Propriedades de configuração

A tabela seguinte descreve as propriedades de configuração da tarefa For Each Loop.

Propriedade	Tipo de dados	Descrição
API Trigger ID	String	ID do acionador da subintegração a executar. Este valor está disponível no campo ID do acionador da API Trigger na subintegração.
Integration name	String	Nome da subintegração a executar.
List to iterate	Uma matriz do tipo booleano, string, inteiro, duplo ou JSON.	Lista de valores para os quais a subintegração deve ser executada. A subintegração é executada para cada valor na lista, um após o outro. Pode transmitir o valor iterado para a subintegração definindo a propriedade Mapeamento da subintegração do elemento de iteração. Nesta propriedade, especifique a variável na subintegração à qual o valor iterado tem de ser mapeado.
Iteration element sub-integration mapping	N/A	Variável na subintegração à qual o elemento iterado atual tem de ser atribuído.
Map to additional sub-integration input(s)	N/A	Valores adicionais a transmitir da integração atual para a subintegração. Os valores desta propriedade estão no formato de pares de chave-valor, em que a chave é uma variável na integração atual e o valor é a variável de entrada correspondente na subintegração. Por exemplo, suponhamos que a sua integração principal tem a variável productID, que quer mapear para a variável de subintegração subIntProductID. Selecionaria productID no menu pendente Variável de integração a partir da qual mapear e selecionaria subIntProductID no menu pendente Entrada de subintegração a mapear.
Collect values from sub-integration output(s)	N/A	Recolha os resultados das execuções da subintegração. Sempre que a subintegração é executada, pode armazenar a saída da subintegração numa variável de matriz da integração atual. Selecione a variável de saída da subintegração no menu pendente Saída da subintegração a recolher de e a variável de matriz na integração atual no menu pendente Variável de integração a recolher em. Cada elemento da matriz tem a resposta de uma execução de subintegração específica. Por exemplo, se a variável de matriz for resultsArray, resultsArray[0] tiver a resposta da primeira execução e resultsArray[1] tiver a resposta da segunda execução.
Response parameter override mapping	N/A	Leia a variável de saída de uma execução de subintegração e armazene-a numa variável da integração atual. Selecione a variável de saída da subintegração no menu pendente Saída da subintegração a partir da qual mapear e selecione a variável correspondente na integração atual no menu pendente Variável de integração a substituir. Pode enviar a variável substituída na integração atual para a próxima execução da subintegração mapeando a variável na propriedade Mapear para entradas de subintegração adicionais. Como resultado, pode agregar cumulativamente as respostas das execuções de subintegração.
Loop metadata	Matriz JSON	A variável de saída que tem os detalhes de execução das subintegrações, como o ID de execução da subintegração, as mensagens de erro e os valores das variáveis transmitidos durante a execução. Os metadados do ciclo contêm variáveis, incluindo as seguintes variáveis de saída: current_iteration_count, sub_integration_execution_ids, failure_location, current_element, iteration_element e failure_message. Aviso: nos metadados do Loop, encontra chaves duplicadas para a variável de saída, por exemplo, Current Iteration Count e current_iteration_count. Recomendamos que use as variáveis que contêm o símbolo de sublinhado (_), porque as outras chaves vão ser descontinuadas.

Exemplos

As secções seguintes fornecem exemplos detalhados de como configurar e usar a tarefa For Each Loop para cenários específicos. Estes exemplos ilustram os passos de configuração para diferentes exemplos de utilização:

• Iterar e transmitir cada elemento
• Recolha resultados da subintegração
• Agregue resultados com substituição de respostas
• Transmita entradas adicionais

Iterar e transmitir cada elemento

Suponha que tem uma integração principal com uma variável de matriz denominada productIds que contém valores como ["P1", "P2", "P3"]. Para chamar uma subintegração denominada GetProductDetails para cada ID do produto, configure a tarefa Ciclo para cada da seguinte forma:

• Defina Lista a iterar como productIds.
• Defina o mapeamento de subintegração do elemento de iteração para mapear o elemento atual de productIds para uma variável em GetProductDetails, por exemplo, subIntProductId.

Cada execução de GetProductDetails recebe, em seguida, um ID do produto de productIds.

Recolha resultados de subintegrações

Tal como no exemplo anterior, suponha que GetProductDetails devolve um objeto JSON numa variável de saída denominada productInfo.

Para recolher todas as saídas productInfo de cada execução de subintegração e armazená-las como elementos numa variável de matriz na integração principal:

• Configure a opção Recolher valores das saídas de subintegração.
• Selecione productInfo em Sub-integration output to collect from (Resultado da subintegração a partir do qual recolher).
• Selecione uma variável de matriz na integração principal, por exemplo, allProductDetails, em Variável de integração a recolher.

Após a conclusão do ciclo, allProductDetails é uma matriz em que cada elemento é o JSON productInfo de uma execução de subintegração.

Agregue resultados com substituição de respostas

Suponha que tem uma integração principal que chama uma subintegração (por exemplo, GetProductDetails) para cada item numa lista e quer calcular o preço total de todos os itens. Para somar um valor numérico devolvido por cada execução de subintegração:

• Certifique-se de que a subintegração devolve um valor numa variável de saída itemPrice.
• Inicialize a variável totalPrice para 0 na integração principal.
• Configure o Mapeamento de substituição de parâmetros de resposta:
  • Mapeie itemPrice (da subintegração) para totalPrice (na integração principal).
• Na secção Mapear para entradas de subintegração adicionais:
  • Mapeie totalPrice (da integração principal) a uma variável de entrada na subintegração, por exemplo, currentTotal.
• Na lógica da subintegração, adicione o preço do artigo atual ao currentTotal recebido da integração principal. Em seguida, devolve esta nova soma na variável de saída denominada itemPrice. Este processo cria uma agregação cumulativa.

Transmita entradas adicionais

Se a sua subintegração GetProductDetails precisar de um código currency da integração principal:

• Na secção Mapear para entradas de subintegração adicionais:
  • Mapeie a variável de integração principal currencyCode à variável de entrada de subintegração subIntCurrency.
• Este currencyCode é transmitido a todas as execuções da subintegração.

Explore os seguintes exemplos de integrações para ver guias práticos passo a passo e exemplos executáveis dos conceitos abordados nas secções anteriores:

• Invocar uma subintegração através de uma tarefa de ciclo For Each
• Exemplo de integração de comércio eletrónico

Práticas recomendadas

Para informações sobre os limites de utilização aplicáveis à tarefa For Each Loop, consulte Limites de utilização.

Estratégia de processamento de erros

Uma estratégia de processamento de erros para uma tarefa especifica a ação a realizar se a tarefa falhar devido a um erro temporário. Para obter informações sobre como usar uma estratégia de processamento de erros e conhecer os diferentes tipos de estratégias de processamento de erros, consulte o artigo Estratégias de processamento de erros.

Quotas e limites

Para informações sobre quotas e limites, consulte o artigo Quotas e limites.

O que se segue?

• Saiba mais sobre todas as tarefas e acionadores.
• Saiba como testar e publicar uma integração.
• Saiba mais acerca do processamento de erros.
• Saiba mais sobre os registos de execução da integração.