Todos os produtos
Search
Central de documentação

DataWorks:Nó do-while

Última atualização: Sep 25, 2026

O DataWorks oferece o nó do-while, que implementa a lógica de loop "execute primeiro, depois verifique". Esse nó é ideal quando você precisa repetir uma série de tarefas até que uma condição dinâmica seja atendida, como verificar periodicamente a existência de um arquivo ou processar dados em lotes até que a source esteja vazia. Orquestre um fluxo de tarefas dentro do corpo do loop e utilize um nó End dedicado para controlar a saída.

Casos de uso

No desenvolvimento de dados, o nó do-while simplifica o design de workflows que precisam executar tarefas repetidamente com base em uma condição. Os casos de uso mais comuns incluem:

  • Polling de API: Chame uma API repetidamente até que ela retorne um status específico, como SUCCESS, ou até que os dados da resposta atendam aos requisitos esperados.

  • Verificação de disponibilidade de dados: Aguarde a geração de um arquivo ou partição de dados upstream. O loop verifica a presença dos dados a cada iteração e encerra assim que estiverem disponíveis, disparando as tarefas downstream.

  • Processamento de dados em lotes: Percorra uma lista de itens — como nomes de tabelas ou partições de datas — fornecida por um nó upstream, como um nó de atribuição. O nó do-while itera pela lista, processando um item por vez até que ela seja totalmente consumida.

  • Sincronização de status: Verifique repetidamente o status de um service externo. Quando o status mudar para o estado desejado, como "Available" ou "Complete", o loop encerra e aciona o workflow de sincronização ou processamento de dados subsequente.

Observações de uso

  • Requisitos de versão: Disponível somente no DataWorks Standard Edition e versões superiores.

  • Permissões: Sua conta RAM deve ser adicionada ao workspace de destino e ter a função de developer ou workspace administrator atribuída. Para mais informações, consulte Add members to a workspace.

Como funciona

O nó do-while funciona como um contêiner de loop baseado no mecanismo de "execute primeiro, depois verifique".

image Nó Start → corpo do loop (executa as tarefas) → image Nó End (avalia a condição)

  1. Início e execução: O loop começa no nó image. Todas as tarefas do corpo do loop são executadas pelo menos uma vez.

  2. Avaliação da condição: Após a conclusão do corpo do loop, o nó image é executado. Escreva a lógica de condição nesse nó.

  3. Decisão do loop:

    • Se o nó image gerar a string True, uma nova iteração começa a partir do passo 1.

    • Se o nó image gerar a string False, o loop encerra e o nó do-while conclui com sucesso.

Característica principal : O corpo do loop sempre é executado pelo menos uma vez, independentemente da condição inicial.

Componentes do nó

Clique duas vezes em um nó do-while para abrir seu canvas interno, composto por três partes principais:

  • image Start: Marca o ponto de entrada do loop. Esse nó não pode ser editado nem excluído.

  • Corpo do loop: Um canvas personalizável para suas tarefas. Clique em Create Internal Node para adicionar diferentes tipos de nós internos — como Shell, SQL e Python — e formar o processo de negócio repetível.

  • image End: Avalia a condição do loop. Trata-se de um nó de atribuição no qual você pode escrever código ODPS SQL, Shell ou Python. Ele gera a string True ou False para determinar se o loop continua.

Variáveis integradas

No corpo do loop e no nó End de um nó do-while, utilize as seguintes variáveis integradas para obter o estado atual do loop e os dados de entrada:

Variável integrada

Descrição

Variáveis integradas do sistema

${dag.loopTimes}

O número da iteração atual, começando em 1.

${dag.offset}

O offset da iteração atual, começando em 0. Equivalente a ${dag.loopTimes} - 1.

Uso com nó de atribuição (considerando que o parâmetro de entrada input está vinculado à saída de um nó de atribuição upstream)

${dag.input}

Recupera o conjunto de resultados completo passado do upstream (tipicamente um array bidimensional).

${dag.input.length}

Recupera o número de linhas no conjunto de resultados (total de elementos).

${dag.input[${dag.offset}]}

Recupera a linha de dados processada na iteração atual. O formato de retorno é uma string separada por vírgulas (por exemplo, "user_A,beijing").

${dag.input[i][j]}

(Somente para arrays bidimensionais) Recupera o valor exato na linha i, coluna j (índices começam em 0).

Exemplo: ${dag.input[0][1]} extrai o valor "beijing" da primeira linha e segunda coluna.

Observações

  • Requisito de edição: Este recurso está disponível somente no DataWorks Standard Edition e versões superiores.

  • Limite de iterações: O número máximo padrão de iterações é 128. O máximo configurável é 1024. Ultrapassar esse limite causa falha na tarefa.

  • Mecanismo de execução: O nó do-while opera em modo de execução serial e não suporta processamento concorrente. Cada iteração deve ser concluída antes que a próxima comece.

  • Limitação de depuração: Não é possível executar um teste diretamente na página Data Studio. Primeiro, implante o workflow e, em seguida, utilize o recurso backfill data no Operation Center para verificar a tarefa.

  • Propagação de dependências: Se o nó do-while depender de um nó de atribuição upstream, inicie o backfill a partir do nó upstream para garantir que o pipeline de dados esteja completo.

  • Controle de fluxo: Ao usar um Branch node dentro do corpo do loop, garanta que todos os caminhos de ramificação convirjam em um Merge node para evitar a interrupção do workflow.

Procedimento: Criar uma tarefa de loop simples

Este exemplo apresenta o processo de criação de uma tarefa que executa 5 iterações e imprime o número da iteração atual em cada ciclo.

Passo 1: Configure o corpo do loop (adicione um nó Shell)

  1. Crie um nó do-while no seu workflow.

  2. Clique duas vezes no nó para entrar no canvas interno. Na área do corpo do loop, clique em Create Internal Node, selecione Shell e nomeie-o print_loop_times.

  3. Clique com o botão direito no nó e selecione Open Node.

  4. Insira o seguinte comando no editor de código:

    # Use the built-in variable ${dag.loopTimes} to get the current loop count
    echo "This is loop number: ${dag.loopTimes}"
  5. Clique no ícone de salvar para salvar o nó.

Passo 2: Defina a condição de saída

  1. Volte ao canvas interno do nó do-while, clique com o botão direito no nó image End e selecione Open Node.

  2. Altere a linguagem para Python.

  3. Insira o seguinte código Python:

    # When the loop count is less than 5, output True and continue looping
    # When the loop count reaches 5, output False and exit the loop
    if ${dag.loopTimes} < 5:
        print True
    else:
        print False
  4. Salve o nó End.

Passo 3: Implante, execute e verifique

  1. Volte ao canvas principal do workflow e clique em Deploy na barra de ferramentas para implantar o workflow completo.

  2. Acesse o Operation Center e localize o nó do-while.

  3. Clique com o botão direito no nó e escolha Backfill Data > Current Node para iniciar uma execução de teste.

  4. Após a execução bem-sucedida da instância, clique com o botão direito no nó novamente e selecione View Internal Nodes.

  5. Visualize as cinco iterações do loop. Expanda qualquer iteração (por exemplo, a 5ª), clique com o botão direito na instância print_loop_times correspondente e selecione View Runtime Log. A saída exibida deve ser:

    This is loop number: 5

Uso avançado: Processar uma lista de dados com um nó de atribuição

Este é um cenário comum e prático: use um nó do-while para iterar e processar um conjunto de dados gerado por um nó de atribuição upstream. Neste exemplo, um nó de atribuição ODPS SQL upstream consulta duas linhas de informações de usuário, e o nó do-while processa cada linha.

Passo 1: Configure o nó de atribuição upstream

  1. Crie um nó de atribuição (por exemplo, com o nome assign_sql_data) e defina-o como upstream do nó do-while.

  2. Utilize ODPS SQL para consultar dados no nó:

    SELECT 'user_A', 'beijing'
    UNION ALL
    SELECT 'user_B', 'shanghai';
  3. Salve o nó. Seu parâmetro outputs gerará um array bidimensional contendo duas linhas de dados.

Passo 2: Configure o nó do-while para consumir os dados

  1. No painel Schedule Settings à direita do nó do-while, localize Input Parameters of This Node.

  2. Clique em Add e configure o seguinte parâmetro:

    • Parameter Name: input (personalizável)

    • Value Source: selecione assign_sql_data.outputs

  3. No corpo do loop do nó do-while, crie um nó Shell e insira o seguinte script para processar a linha atual:

    # Get the data row being processed in the current loop iteration
    echo "Processing data row: ${dag.input[${dag.offset}]}"
  4. Abra o nó image End e use Python para definir a condição de saída:

    # If the number of times executed is less than the total number of data rows, continue looping
    if ${dag.loopTimes} < ${dag.input.length}:
        print True
    else:
        print False
  5. Implante o workflow e, no Operation Center, inicie o backfill a partir do nó assign_sql_data para garantir que os dados fluam corretamente para o loop.

Após uma execução bem-sucedida, os logs mostrarão que as duas iterações processaram "user_A,beijing" e "user_B,shanghai", respectivamente.

Apêndice: Comparação entre os nós do-while e for-each

Recurso

Nó do-while

Nó for-each

Lógica central

Orientado por condição: repete a execução até que a condição deixe de ser atendida.

Orientado por dados: executa uma vez para cada elemento da lista de entrada.

Número de iterações

Indeterminado; depende de quando a condição é satisfeita.

Determinado; igual ao número de elementos na lista de entrada.

Garantia de execução

Executa pelo menos uma vez (mesmo que a condição inicial já não seja atendida).

Se a entrada estiver vazia, nenhuma execução ocorre.

Casos de uso

Polling, espera, verificações de status e processamento em lotes até que a source seja esgotada.

Processamento em lote de uma lista conhecida (como sincronizar um conjunto de tabelas ou processar múltiplas partições).

Método de controle

Controlado pelo nó End, que gera True / False para determinar se o loop continua.

Encerra automaticamente após percorrer todos os elementos.