CloudFlow:Entradas e saídas

Fluxos e etapas

Dados são frequentemente transferidos entre etapas em um fluxo. Uma etapa na Flow Definition Language (FDL) assemelha-se a uma função em linguagens de programação funcional: aceita uma entrada e retorna uma saída. O sistema salve a saída na variável local da etapa pai (a chamadora). Tanto a entrada quanto a saída devem estar no formato de objeto JSON. O tipo da variável local varia conforme a etapa. Por exemplo, uma etapa de tarefa usa o resultado de uma chamada de função do Function Compute como variável local. Já uma etapa paralela utiliza um array com as saídas de todos os seus ramos como variável local. O tamanho total combinado da entrada, da saída e das variáveis locais de uma etapa não pode exceder 32 KiB. A execução do fluxo falha caso esse limite seja ultrapassado.

Quando uma etapa contém outra, a etapa externa é chamada de etapa pai e a interna, de etapa filha. O próprio fluxo atua como pai das etapas mais externas. Etapas que compartilham a mesma etapa pai são consideradas etapas irmãs.

Tanto fluxos quanto etapas possuem entradas, saídas e variáveis locais. A lista a seguir descreve as transformações aplicadas:

• Mapeamentos de entrada da etapa (inputMappings): direcionam a entrada e as variáveis locais de uma etapa pai para a entrada de uma etapa filha.

• Mapeamentos de saída da etapa (outputMappings): direcionam a entrada e as variáveis locais da etapa atual para a saída dessa mesma etapa.

• Mapeamentos de entrada do fluxo (inputMappings): direcionam a entrada fornecida pelo usuário ao executar um fluxo para a entrada do fluxo.

• Mapeamentos de saída do fluxo (outputMappings): direcionam a entrada e as variáveis locais do fluxo para a saída do fluxo.

A variável local de uma etapa pai armazena as saídas mescladas de todas as suas etapas filhas. Se as saídas contiverem chaves com o mesmo nome, o resultado da etapa executada posteriormente substitui o resultado da etapa executada anteriormente. Na maioria dos casos, não é necessário especifique mapeamentos de entrada e saída; utilize o comportamento de mapeamento padrão. As transformações padrão funcionam da seguinte forma:

• Sem um mapeamento de entrada definido, a entrada da etapa filha resulta da mesclagem da entrada e das variáveis locais da etapa pai. Caso existam chaves com nomes idênticos nas variáveis locais e na entrada, os valores das variáveis locais prevalecem sobre os valores da entrada.

• Na ausência de um mapeamento de saída, todas as etapas (exceto as paralelas e foreach) utilizam suas variáveis locais como saída.

Para obter maior controle sobre entradas e saídas, compreenda as regras detalhadas de mapeamento.

A figura a seguir ilustra os mapeamentos de entrada e saída de um fluxo de exemplo. Neste cenário, step1 é a etapa pai de step2 e step3, enquanto step1 e step4 representam as etapas mais externas.

version: v1
type: flow
steps:
  - type: parallel
    name: step1
    branches:
      - steps:
        - type: pass
          name: step2
      - steps:
        - type: pass
          name: step3
  - type: pass
    name: step4      

O código a seguir detalha esses mapeamentos para facilitar o entendimento.

func flow(input0 Input) (output0 Output) {
  local0 := {}
  input1 := buildInput(step1InputMappings, input0, local0)
  output1 := step1(input1)
  save(local0, output1)
  input4 := buildInput(step4InputMappings, input0, local0)
  output4 := step4(input4)
  save(local0, output4)
  return buildOutput(flowOutputMappings, input0, local0)
}
func step1(input1 Input) (output1 Output) {
  local10 := {}
  input2 := buildInput(step2InputMappings, input1, local10)
  output2 := step2(input2)
  save(local10, output2)
  local11 := {}
  input3 := buildInput(step3InputMappings, input1, local11)
  output3 := step3(input3)
  save(local11, output3)
  return buildOutput(step1OutputMappings, [local10, local11])
}
func step2(input2 Input) (output2 Output) {
}
func step3(input3 Input) (output3 Output) {
}
func step4(input4 Input) (output4 Output) {
}       

Neste exemplo, o fluxo contém duas etapas filhas: step1 e step4. A etapa step1 é paralela e engloba outras duas etapas filhas: step2 e step3.

1. Ao iniciar a execução do fluxo, o sistema transforma a entrada de StartExecution na entrada do fluxo (input0) com base no mapeamento de entrada do fluxo.

2. No início do flow, a variável local local0 está vazia.

3. O sistema prepara a entrada input1 para a step1 utilizando seu mapeamento de entrada (step1InputMappings). A origem desse mapeamento compreende a entrada input0 e a variável local local0 do flow.

4. O sistema invoca a step1, transmite a entrada input1 e recebe a saída output1 retornada pela step1.

   • Quando a step1 inicia, sua variável local está vazia. Como a step1 é uma etapa paralela, cada ramo mantém sua própria variável local para evitar problemas de acesso concorrente à local0.

   • O sistema prepara a entrada input2 para a step2 com base no mapeamento de entrada correspondente (step2InputMappings). Essa operação utiliza a entrada input1 e a variável local local10 da step1 como origem.

   • O sistema chama a step2, passa a entrada input2 e obtém a saída output2 retornada pela step2.

   • O sistema salva a saída da step2 na variável local local10 da step1.

   • De modo semelhante, o sistema executa a step3 e armazena o resultado na variável local local11 da step1.

5. O sistema grava a saída da step1 na variável local local0 do flow.

6. Seguindo a mesma lógica, o sistema prepara a entrada input4 para a step4 conforme seu mapeamento de entrada. A origem para esse mapeamento inclui a entrada input0 e a variável local local0 do flow.

   Nota

   Neste momento, a variável local

   local0

   já pode conter a saída da

   step1

   . É assim que ocorre a transferência de dados entre a

   step1

   e a

   step4

   .

7. O sistema invoca a step4, fornece a entrada input4 e recebe a saída output4 gerada pela step4.

8. O sistema armazena a saída da step4 na variável local local0 do flow.

9. Por fim, o sistema converte a local0 na saída do fluxo, aplicando o mapeamento de saída do fluxo.

Definições de tipos

Os mapeamentos de entrada e de saída consistem em arrays formados por pares de target e source. O campo source indica a origem do valor de um parâmetro, enquanto o target define o nome do parâmetro de destino. Quando um valor de source começa com $, trata-se de uma expressão JSON Path que o sistema analisa para extrair um valor específico. Caso contrário, o sistema interpreta o valor como uma constante. Por exemplo, $input.key indica que o valor do parâmetro corresponde ao valor de key dentro do objeto input. Use esta ferramenta para testar expressões JSON Path.

• Source

  O campo source aceita valores constantes dos tipos number, string, boolean, array, object ou null.

  O exemplo abaixo apresenta um mapeamento que utiliza diferentes tipos de constantes e a saída resultante.

  outputMappings:
    - target: int_key
      source: 1
    - target: bool_key
      source: true
    - target: string_key
      source: abc
    - target: float_key
      source: 1.234
    - target: null_key
      source: null
    - target: array1
      source: [1, 2, 3]
    - target: array2
      source:
        - 1
        - 2
        - 3
    - target: object1
      source: {a: b}
    - target: object2
      source:
        a: b          

  {
    "array1": [1, 2, 3],
    "array2": [1, 2, 3],
    "bool_key": true,
    "float_key": 1.234,
    "int_key": 1,
    "null_key": null,
    "object1": {
      "a": "b"
    },
    "object2": {
      "a": "b"
    },
    "string_key": "abc"
  }            

• Target

  O alvo deve ser obrigatoriamente uma constante do tipo string.

Mapeamento de entrada

Um mapeamento de entrada converte a entrada da etapa pai ($input), as variáveis locais da etapa pai ($local) ou constantes na entrada da etapa filha. Caso nenhum mapeamento de entrada seja especificado, o sistema mescla a entrada e as variáveis locais da etapa pai para formar a entrada da etapa filha. Se houver chaves duplicadas entre a entrada e as variáveis locais da etapa pai, os valores das variáveis locais substituem os valores da entrada.

inputMappings:
  - target: key1
    source: $input.key1
  - target: key2
    source: $local.key2
  - target: key3
    source: literal         

{
"key1":"value1"
}

{
    "key2":"value2"
    }

inputMappings:
      - target: key1
        source: $input.key1
      - target: key2
        source: $local.key2
      - target: key3
        source: literal

{
    "key1":"value1",
    "key2":"value2",
    "key3":"literal"
    }

{
"key1":"value1"
}

{
    "key2":"value2"
    }

{
    "key1":"value1",
    "key2":"value2"
    }

{
"key1":"value1"
}

{
    "key1":"value2"
    }

{
    "key1":"value2"
    }

Mapeamento de saída

Um mapeamento de saída transforma a entrada da etapa atual ($input), as variáveis locais ($local) ou constantes na saída da etapa. Se você não definir um mapeamento de saída, as etapas de escolha e de loop utilizarão suas variáveis locais como saída. Etapas de tarefa usam o resultado da execução da tarefa como saída. Como as variáveis locais das etapas paralelas e foreach são arrays, defina um mapeamento de saída para converter o resultado em array para um objeto JSON. Por padrão, essas variáveis locais não fazem parte da saída. Para mais detalhes, consulte as descrições das respectivas etapas.

outputMappings:
  - target: key1
    source: $input.key1
  - target: key2
    source: $local.key2
  - target: key3
    source: literal          

{
"key1":"value1"
}

{
    "key2":"value2"
    }

outputMappings:
      - target: key1
        source: $input.key1
      - target: key2
        source: $local.key2
      - target: key3
        source: literal

{
    "key1":"value1",
    "key2":"value2",
    "key3":"literal"
    }

{
"key1":"value1"
}

[
      {
        "key2":"value2.1"
      },
      {
        "key2":"value2.2"
      }
    ]

outputMappings:
      - target: key1
        source: $input.key1
      - target: key2
        source: $local[*].key2
      - target: key3
        source: literal

{
      "key1":"value1",
      "key2":["value2,1","value2,2"],
      "key3":"literal"
    }

{
"key1":"value1"
}

{
    "key2":"value2"
    }

{
    "key2":"value2"
    }

Como as saídas são salvas nas variáveis locais da etapa pai

O sistema mescla a saída da etapa filha ($output) às variáveis locais da etapa pai. Se ambos possuírem chaves com o mesmo nome, o valor proveniente da saída sobrescreve o valor correspondente nas variáveis locais.

{
"key1":"value1"
}

{
    "key2":"value2"
    }

{
      "key1":"value1",
      "key2":"value2"
    }

{
"key1":"value11"
}

{
      "key1":"value1",
      "key2":"value2"
    }

{
      "key1":"value11",
      "key2":"value2"
    }