Integração da Apigee com um acionador de API

Neste guia de início rápido, mostramos como criar uma integração de amostra usando a integração da Apigee. As etapas abaixo descrevem como configurar o gatilho, as tarefas, as bordas, as variáveis e os mapeamentos de dados necessários para executar uma integração completa.

Neste guia de início rápido, você extrai o número de visualizações de página de uma API pública, transforma os dados em um formato utilizável e envia a lista resultante em um e-mail, tudo isso no designer de integração.

Criar uma nova integração

Para criar uma nova integração, execute as seguintes etapas:

  1. Na IU da Apigee, selecione sua organização da Apigee.
  2. Clique em Desenvolver > Integrações.
  3. Clique em CRIAR INTEGRAÇÃO.
  4. Digite um nome e uma descrição na caixa de diálogo Criar integração.

    Para este guia de início rápido, insira o nome my-test-integration e a descrição Integration for quickstart.

  5. Selecione uma região para a integração.
  6. Clique em Criar para abrir o editor de integração.

Adicionar e configurar um gatilho de API

Os acionadores são necessários para iniciar a sequência de tarefas que compõem uma integração. Qualquer gatilho disponível pode ser usado para iniciar uma integração. Para usar o guia de início rápido, use o gatilho da API.

Para configurar o acionador da API, faça o seguinte:

  1. No editor de integração, clique em Acionadores para exibir uma lista de acionadores disponíveis.
  2. Clique e posicione o elemento Gatilho da API no editor de integração.
  3. Clique no elemento gatilho da API no designer para abrir o painel de configuração do gatilho.
  4. A integração com a Apigee preenche automaticamente o Rótulo, o nome do gatilho e o código do acionador da Apigee. O Id do gatilho é gerado por máquina e não é possível editar o valor. No entanto, é possível editar o valor das propriedades Rótulo e Nome do gatilho.

    As alterações nas propriedades são salvas automaticamente.

Adicionar e configurar tarefas

Uma tarefa é um conjunto executável de etapas que pode assumir variáveis como entradas e gerar variáveis como saídas. Assim como os gatilhos, qualquer tarefa disponível pode ser usada em uma integração. Neste guia de início rápido, usamos as tarefas Call REST Endpoint, Mapeamento de dados e Enviar e-mail. Os detalhes de configuração de cada tarefa são descritos nas etapas abaixo.

Configurar a tarefa Call REST Endpoint

Para configurar a tarefa Call REST Endpoint, faça o seguinte:

  1. Selecione Tarefas para mostrar uma lista das tarefas disponíveis.
  2. Clique e coloque o elemento Call REST Endpoint no editor de integração.
  3. Adicione uma conexão de borda do elemento API Trigger ao elemento Call REST Endpoint passando o cursor sobre um ponto de controle no elemento gatilho da API. Depois, clique e arraste uma linha para um ponto de controle no elemento de tarefa Call REST Endpoint. A borda indica o fluxo de controle do gatilho da API para a tarefa Call REST Endpoint.

    Uma aresta é uma conexão entre dois elementos em uma integração. A conexão indica a direção do fluxo de controle de um elemento (tarefa ou gatilho) para outro. Para mais informações sobre bordas, consulte Bordas.

  4. Clique no elemento Call REST Endpoint no designer para abrir o painel de configuração da tarefa. Defina as seguintes propriedades:
    • Rótulo: insira um nome personalizado para a tarefa. Por exemplo, insira Call REST Endpoint Task.
    • Autenticação: para este guia de início rápido, um perfil de autenticação não é necessário. Para mais informações sobre como usar perfis de autenticação para outros casos de uso, consulte Criar perfis de autenticação na integração da Apigee.
    • Task Input: insira os detalhes para chamar o endpoint REST. As informações inseridas aqui são usadas como entrada para a tarefa Call REST Endpoint. Digite as seguintes informações:
      • Endpoint base URL: digite https://wikimedia.org/api/rest_v1/metrics/pageviews/per-article/en.wikipedia/desktop/user/Tree/monthly/20201001/20201031. Essa API pública do wikimedia.org retorna o número de visualizações de página de um artigo chamado Tree para um determinado mês.
      • Método HTTP: selecione GET usando a lista suspensa.
    • Task Output: aqui, a integração da Apigee preenche três variáveis para reter a saída de dados de resposta de chamada do endpoint REST:
      • responseHeader(Call REST Endpoint): essa variável contém os dados do cabeçalho de resposta associados à tarefa Call REST Endpoint. Os dados variáveis são do tipo String (STR).
      • responseBody(Call REST Endpoint): essa variável contém os dados do corpo de resposta associados à tarefa Call REST Endpoint. Os dados variáveis são do tipo String (STR).
      • responseStatus(Call REST Endpoint): essa variável contém os dados de status da resposta associados à tarefa Call REST Endpoint. Os dados variáveis são do tipo String (STR).
    • Confira os detalhes de cada variável clicando no nome dela no painel de configuração da tarefa. Para este guia de início rápido, mantenha os valores padrão para cada uma dessas variáveis.
    • Os campos restantes precisam conter os seguintes valores padrão:
      • Siga o redirecionamento: True
      • A tarefa deve falhar no erro HTTP False
      • Estratégia de solução de erros
        • Estratégia para execuções síncronas: None
        • Estratégia para execuções assíncronas: None

    As alterações nas propriedades são salvas automaticamente.

Adicionar e configurar a tarefa de mapeamento de dados

Para configurar a tarefa Mapeamento de dados:

  1. Selecione Tarefas para mostrar uma lista das tarefas disponíveis.
  2. Clique e posicione o elemento Mapeamento de dados no editor de integração.
  3. Adicione uma conexão de borda do elemento Call REST Endpoint ao elemento Mapeamento de dados passando o cursor sobre um ponto de controle no elemento Call REST Endpoint. Depois, clique e arraste uma linha para um ponto de controle no elemento da tarefa Mapeamento de dados. A borda indica o fluxo de controle da tarefa Call REST Endpoint para a tarefa Mapeamento de dados.
  4. Clique na tarefa Mapeamento de dados no designer para abrir o painel de configuração da tarefa.
  5. Clique em Abrir editor de mapeamento de dados.

    O Editor de mapeamento de dados permite mapear variáveis de entrada para as variáveis de saída desejadas, usando as funções de transformação disponíveis. A saída é disponibilizada como uma variável para qualquer outra tarefa ou gatilho de integração. Para mais detalhes sobre como transmitir dados como variáveis, consulte Como usar variáveis na integração da Apigee.

    Para este guia de início rápido, crie um mapeamento usando o responseBody(Call REST Endpoint) como entrada:

    1. Arraste a variável responseBody do painel responseBody para a primeira linha responseBody.
    2. Clique em + (Adicionar uma função) no ícone de variável responseBody para conferir a lista suspensa de funções disponíveis.
    3. Várias funções podem ser aplicadas para transformar os dados na variável de entrada.

      Nesse caso, é possível converter o payload em JSON e depois iterar na matriz de resposta para obter a lista de nomes de produtos necessária para as notificações por e-mail.

      • Selecione TO_JSON() para converter a string responseBody em JSON.
      • Clique em + (Adicionar uma função) novamente no ícone de variável responseBody para selecionar e encadear a função GET_PROPERTY().
      • Para adicionar o parâmetro de entrada para GET_PROPERTY(), clique em Variável ou valor e, em Valor, insira items.

        Essa função extrairá uma propriedade do payload JSON. Transmita a propriedade items como o parâmetro para esta função. Com isso, será retornada uma lista APENAS com nomes de produtos, sem outras informações do produto. Sua função será semelhante a esta: 

        responseBody(Call REST Endpoint).TO_JSON().GET_PROPERTY(items)
      • Se você precisar remover ou excluir uma função, clique no símbolo -.
    4. Clique no primeiro campo na coluna Saída para criar uma nova variável de saída que armazene o valor dos dados transformados. Preencha os seguintes campos:
      • Nome: insira JSONList.
      • Tipo de dados: JSON
      • Marque a caixa de seleção Usar como saída de integração.
      • Clique em Criar para criar a variável e fechar o painel. A nova variável JSONList será exibida na lista JSONList à esquerda do editor de mapeamento de dados.
    5. Feche o Editor de mapeamento de dados quando o mapeamento for concluído. Todas as alterações serão salvas automaticamente.

Adicionar e configurar a tarefa "Enviar e-mail"

Para configurar a tarefa Enviar e-mail, siga estas etapas:

  1. Selecione Tasks no editor de integração para mostrar a lista de tarefas disponíveis.
  2. Clique e posicione o elemento Enviar e-mail no editor de integração.
  3. Adicione uma conexão de borda pelo elemento Mapeamento de dados ao elemento Enviar e-mail passando o cursor sobre um ponto de controle no elemento Mapeamento de dados. Em seguida, clique e arraste uma linha para um ponto de controle no elemento da tarefa Enviar e-mail. A borda indica o fluxo de controle da tarefa Mapeamento de dados para a tarefa Enviar e-mail.
  4. Clique no elemento Enviar e-mail no designer para abrir o painel de configuração da tarefa. Defina as seguintes propriedades:
    • Para os destinatários: digite seu endereço de e-mail. Você usará esse e-mail para confirmar a conclusão da integração.
    • Assunto: insira Email from Apigee Integration.
    • Corpo em texto simples: selecione a variável JSONList criada anteriormente na tarefa Mapeamento de dados.
    • As opções restantes podem ser deixadas na configuração padrão.

    As alterações nas propriedades são salvas automaticamente.

Verificar as conexões edge necessárias

Verifique se você adicionou conexão de borda entre elementos na integração. A conexão indica a direção do fluxo de controle de um elemento (tarefa ou gatilho) para outro. Para mais informações sobre bordas, consulte Bordas.

O mapeamento concluído será exibido como na figura abaixo:

imagem mostrando o fluxo do guia de início rápido imagem mostrando o fluxo do guia de início rápido

Testar a integração

Para testar a nova integração:

  1. Clique em Testar na barra de ferramentas do editor de integração.

    O painel Test Integration é exibido.

  2. Clique em Testar integração.

Para mais informações sobre testes, consulte Testar e publicar integrações.

Após a conclusão, a integração enviará um e-mail com os valores JSON ao endereço de e-mail especificado na tarefa Send Email. Confirme o recebimento da mensagem no seu cliente de e-mail.

O e-mail enviado pela integração precisa ter um corpo semelhante a este: 

[{
   "project": "en.wikipedia",
   "article": "Tree",
   "granularity": "monthly",
   "timestamp": "2020100100",
   "access": "desktop",
   "agent": "user",
   "views": 33828.0
}]

Além de verificar o conteúdo do e-mail, é possível inspecionar os registros para visualizar o status e o payload de uma determinada integração. Para conferir os registros:

  1. Clique em Registros na barra de ferramentas do editor de integração.
  2. Na página Execution Logs, você pode ver detalhes sobre cada tentativa de executar uma integração. Cada entrada inclui detalhes para a tentativa de execução, incluindo:
    • Nome da integração
    • ID de execução
    • Status
    • Horário de início
    • Duração
    • Versão da integração
    • ID de acionamento
  3. Clique na seta de expansão (>) ao lado da integração executada para conferir uma lista expandida de tarefas e variáveis na integração, além do status da tarefa e payloads de variável.