Tarefa "Mapeamento de dados"

A tarefa Mapeamento de dados permite executar atribuições de variáveis na sua integração, receber e definir propriedades de objetos JSON e aplicar funções de transformação aninhadas a valores. As variáveis podem ser variáveis de integração ou de tarefa.

Por exemplo, é possível atribuir valores da variável de integração X a uma variável de tarefa Y ou a uma variável de tarefa Y a uma variável de integração X. Para mais informações sobre variáveis na Integração com a Apigee, consulte Como usar variáveis na Integração com a Apigee.

Configurar a tarefa "Mapeamento de dados"

Para configurar uma tarefa de mapeamento de dados, siga estas etapas:

  1. Na IU da Apigee, selecione sua organização da Apigee.
  2. Clique em Desenvolver > Integrações.
  3. Selecione uma integração existente ou clique em Criar integração.

    Caso você esteja criando uma nova integração, siga estas etapas:

    1. Digite um nome e uma descrição na caixa de diálogo Criar integração.
    2. Selecione uma Região para a integração na lista de regiões compatíveis.
    3. Clique em Criar.

    Isso abre a integração na página do designer de integração.

  4. Na barra de navegação do designer de integração, clique em +Adicionar uma tarefa/gatilho> Tarefas para conferir a lista de tarefas disponíveis.
  5. Clique e posicione o elemento Mapeamento de dados no editor de integração.
  6. Clique no elemento Mapeamento de dados no designer para visualizar o painel de configuração da tarefa Mapeamento de dados.
  7. Clique em Abrir editor de mapeamento de dados para visualizar os valores padrão da tarefa e adicionar um novo mapeamento. Para ver etapas detalhadas sobre como adicionar um mapeamento, consulte Adicionar um mapeamento.

    Para mais informações sobre o layout do editor de mapeamento de dados, consulte Visão geral do mapeamento de dados.

Adicionar um mapeamento

Para adicionar um mapeamento, execute as seguintes etapas:

  1. No painel de configuração da tarefa de mapeamento de dados, clique em Abrir editor de mapeamento de dados.
  2. Configure a entrada do mapeamento:
    1. Arraste uma variável ou o subcampo da lista Variáveis para a linha Entrada. Para ver os subcampos disponíveis de uma variável, clique em (Expandir) ao lado dela na lista Variáveis.
    2. Como alternativa, na linha Entrada, clique em Variável ou valor e faça o seguinte:
      • Selecione Variável para pesquisar e usar uma variável existente. Para criar uma nova variável, clique em + Adicionar nova variável e insira o nome e o tipo de dados da nova variável.
      • Selecione Valor para inserir um valor literal do tipo string, integer, double ou Boolean.
      • Selecione Função para pesquisar e usar uma função base.

        Uma função base é usada para recuperar ou gerar valores durante a execução de uma integração. Por exemplo, gerar um UUID aleatório ou recuperar a região de integração atual. Para informações sobre as funções de base compatíveis, consulte Funções de base compatíveis.

      • Clique em Save.
    3. Clique em + (Adicionar uma função) em qualquer variável de entrada, valor ou função base na linha Entrada para adicionar uma função de mapeamento da lista de funções de mapeamento disponíveis. Uma função de mapeamento pode ter um ou mais parâmetros. Cada parâmetro pode ter um valor, uma variável ou uma função base seguida de uma cadeia de funções de mapeamento.
      • Para adicionar uma função aninhada, clique em + (Adicionar uma função) ao lado do parâmetro da função. Para remover ou excluir a função adicionada mais recentemente, clique em - (Excluir função anterior).
      • Para adicionar, remover ou alterar uma função entre uma expressão de mapeamento, clique em uma função e selecione Adicionar função, Remover função ou Alterar função respectivamente no menu suspenso.

        • Para saber mais sobre as funções de mapeamento, consulte Funções de mapeamento.

        Para informações sobre as funções de mapeamento compatíveis, consulte Tipos de dados e funções de mapeamento compatíveis.

      • Para remover uma variável de uma expressão de mapeamento, clique em (Remover) ao lado da linha da variável.
      • Para remover toda a linha Entrada, clique em (Limpar) na linha.
  3. Configure a Saída do mapeamento:
    1. Arraste uma variável da lista de Variáveis para a linha Saída. Se a variável não estiver disponível, clique em criar uma nova para configurar o nome e o tipo de dados da nova variável. Também é possível clicar na variável de saída e escolher se quer usá-la como saída da integração ou como entrada para outra integração.
    2. Para remover a variável de saída, clique em (Limpar).
  4. (Opcional) Para excluir uma linha de mapeamento, clique em (Excluir este mapeamento).
  5. Feche o Editor de mapeamento de dados quando o mapeamento for concluído. Todas as alterações serão salvas automaticamente.

O mapeamento de dados concluído está disponível para visualização no painel de configuração da tarefa Mapeamento de dados, conforme mostrado na imagem a seguir:

imagem mostrando o editor de mapeamento de dados imagem mostrando o editor de mapeamento de dados

Tipos de dados e funções de mapeamento compatíveis

A integração com a Apigee é compatível com os seguintes tipos de dados de variáveis na tarefa Mapeamento de dados:

  • String e matriz de strings
  • Inteiros e matriz de inteiros
  • Dupla e matriz de duplas
  • Booleano e matriz de booleanos
  • JSON
Veja na tabela a seguir as funções de mapeamento de dados disponíveis para cada um dos tipos de dados.
Data type Funções de mapeamento compatíveis
Booleano AND, EQUALS, NAND, NOR, NOT, OR, TO_JSON TO_STRING, XNOR XOR
Matriz booleana APPEND, APPEND_ALL, CONTAINS, FILTER, FOR_EACH, GET, REMOVE, REMOVE_AT, SET, SIZE, TO_JSON, TO_SET
Dobro ADD, DIVIDE, CEIL, EQUALS, EXPONENT, GREATER_THAN, GREATER_THAN_EQUAL_TO, FLOOR, LESS_THAN, LESS_THAN_EQUAL_TO, MOD, MULTIPLY, ROUND, SUBTRACT, TO_JSON, TO_STRING
Matriz dupla APPEND, APPEND_ALL, AVG, CONTAINS, FILTER, FOR_EACH, GET, MAX, MIN, REMOVE, REMOVE_AT, SET, SIZE, SUM, TO_JSON, TO_SET
Inteiro ADD, DIVIDE, EPOCH_TO_HUMAN_READABLE_TIME, EQUALS, EXPONENT, GREATER_THAN, GREATER_THAN_EQUAL_TO, LESS_THAN, LESS_THAN_EQUAL_TO, MOD, MULTIPLY, SUBTRACT e TO_DOUBLE, TO_JSON, TO_STRING
Matriz de números inteiros APPEND, APPEND_ALL, AVG, CONTAINS, FILTER, FOR_EACH, GET, MAX, MIN, REMOVE, REMOVE_AT, SET, SIZE, SUM, TO_JSON, TO_SET
JSON APPEND_ELEMENT, FLATTEN, FILTER, FOR_EACH, GET_ELEMENT, GET_PROPERTY, MERGE, REMOVE_PROPERTY, RESOLVE_TEMPLATE, SET_PROPERTY, SIZE, TO_BOOLEAN, TO_BOOLEAN_ARRAY, TO_DOUBLE, TO_DOUBLE_ARRAY, TO_INT, TO_INT_ARRAY, TO_STRING, TO_STRING_ARRAY
String CONCAT, CONTAINS, DECODE_BASE64_STRING, EQUALS, EQUALS_IGNORE_CASE, LENGTH, REPLACE_ALL, RESOLVE_TEMPLATE, SPLIT, SUBSTRING, TO_BASE_64, TO_BOOLEAN, TO_DOUBLE, TO_INT, TO_JSON, TO_LOWERCASE, TO_UPPERCASE
Matriz de strings APPEND, APPEND_ALL, CONTAINS, FILTER, FOR_EACH, GET, REMOVE, REMOVE_AT, SET, SIZE, TO_JSON, TO_SET
Para mais informações sobre cada uma das funções de mapeamento de dados, consulte Referência de funções de mapeamento de dados.

Funções de base compatíveis

A tabela a seguir lista as funções base de mapeamento de dados disponíveis:
Data type Funções de base compatíveis
Inteiro NOW_IN_MILLIS
Matriz de números inteiros INT_LIST
String GENERATE_UUID, GET_EXECUTION_ID, GET_INTEGRATION_NAME, GET_INTEGRATION_REGION, GET_PROJECT_ID
Para mais informações sobre cada uma das funções de mapeamento de dados, consulte Referência de funções de mapeamento de dados.

Práticas recomendadas

Usar a tarefa Mapeamento de dados pode ser uma maneira poderosa de transformar e transmitir variáveis de chave para várias tarefas na sua integração. Veja a seguir algumas dicas a serem lembradas ao criar a integração:

  • Os mapeamentos são executados em sequência de cima para baixo. Ou seja, se a variável de entrada A for mapeada para uma variável de saída B na primeira linha, a variável B estará disponível para mapeamento nas linhas subsequentes.
  • Em cada linha, o tipo de dados da linha Entrada precisa corresponder ao tipo de dados da linha Saída. Para fazer a transmissão entre tipos, use funções de transformação, como TO_STRING e TO_INT.
  • Não há limitações no comprimento do encadeamento de transformação. No entanto, a depuração de transformações grandes encadeadas pode ser difícil. Recomendamos manter as transformações de entrada legíveis e dividir as transformações complexas em vários mapeamentos.
  • Se um mapeamento exigir um valor substituto, defina um valor substituto para o mapeamento. Se você não fornecer um valor substituto, o mapeamento retornará um erro quando o valor de entrada ou a transformação retornar null.
  • Ao excluir uma variável, exclua todos os mapeamentos que a contêm.

Para informações sobre os limites de uso que se aplicam à tarefa de Mapeamento de dados, consulte Limites de uso.

Considerações

Para variáveis JSON, com base em um esquema JSON, a Integração com a Apigee interpreta a propriedade filha da variável como um tipo JSON nos seguintes casos:

  • Se o tipo da propriedade filha especificar nulo. Exemplo: 
    {
  "properties": {
    "PersonID": {
      "type": [
        "double",
        "null"
      ],
      "readOnly": false
    }
  }
}
  • Se o tipo da propriedade filha especificar vários tipos de dados. Exemplo: 
    {
  "properties": {
    "PersonID": {
      "type": [
        "integer",
        "string",
        "number"
      ],
      "readOnly": false
    }
  }
}

Nesses casos, usando as funções de mapeamento de dados, você precisa converter explicitamente as variáveis filhas para o tipo desejado.

Os exemplos a seguir ilustram os vários tipos de declarações de propriedade e mostram como usar as funções de mapeamento de dados para chegar ao tipo desejado:

Exemplo 1

{
  "type": "object",
  "properties": {
    "dbIntegers": {
      "type": "array",
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    },
    "dbBooleans": {
      "type": [
        "array"
      ],
      "items": {
        "type": "boolean"
      }
    }
  }
}
A Integração com a Apigee interpreta dbIntegers como um tipo JSON, e dbBooleans como um tipo BOOLEAN_ARRAY.

Para converter dbIntegers, use: 

dbIntegers.TO_INT_ARRAY()

Exemplo 2

{
  "type": "object",
  "properties": {
    "dbId": {
      "type": [
        "number",
        "null"
      ],
      "readOnly": false
    },
    "dbStatus": {
      "type": [
        "boolean",
        "null"
      ],
      "readOnly": false
    }
  }
}
A Integração da Apigee reconhece dbId e dbStatus como tipos JSON, mas dbId é um parâmetro que pode usar um único valor duplo ou nulo, e dbStatus é um parâmetro que pode receber um único valor booleano ou um valor nulo.

Para converter dbId e dbStatus, use: 

dbId.TO_DOUBLE()
dbStatus.TO_BOOLEAN()

Exemplo 3

{
  "type": "object",
  "properties": {
    "dbString": {
      "type": [
        "string"
      ],
      "readOnly": false
    }
  }
}
A Integração com a Apigee reconhece dbString como um tipo de string.

Estratégia de solução de erros

A estratégia de solução de erros para uma tarefa especifica a ação a ser realizada se a tarefa falhar devido a um erro temporário. Para mais informações sobre como usar uma estratégia de tratamento de erros e conhecer os diferentes tipos de estratégias de tratamento de erros, consulte Estratégias de tratamento de erros.