Primeiros passos com a integração da Apigee e a conexão do Pub/Sub

Aviso: o Application Integration já está disponível para seu projeto do Google Cloud. Agora é possível usar a Apigee Integration e o Application Integration no mesmo projeto do Google Cloud. Saiba mais

Saiba neste tutorial como usar integrações e conectores para criar uma integração de amostra que aciona a publicação de uma mensagem do Cloud Pub/Sub. Para seguir o tutorial, é necessário ter um conhecimento prático sobre a Integração com a Apigee.

Neste exemplo, chamar um endpoint da API aciona a publicação de uma mensagem em um tópico do Cloud Pub/Sub. As etapas abaixo descrevem como configurar o acionador da API e a conexão do Pub/Sub necessárias para executar uma integração bem-sucedida.

Antes de começar

Antes de começar este tutorial, confirme as credenciais de login e os detalhes da organização do Google Cloud. Essas informações são necessárias para acessar a IU do Connectors. Suas credenciais da Apigee são necessárias para acessar a tarefa do Conectores no designer de integração da Apigee. As etapas de pré-requisito adicionais são descritas abaixo:

• Antes de criar uma conexão pela primeira vez, conclua as etapas a seguir:

  Observação: essas etapas serão necessárias apenas se você estiver ativando os complementos de integração e conectores da Apigee pela primeira vez para uso com a Apigee.
  1. Crie uma nova instância da Apigee. Novas instâncias da Apigee podem ser provisionadas com a IU de provisionamento.

     Para ver a lista de regiões compatíveis, consulte Regiões de conectores compatíveis.

  2. Confirme se os recursos de integração e conectores da Apigee têm direito à assinatura da Apigee.
  3. Ative os recursos de integração e conectores da Apigee usando o seguinte comando:

     curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H \
     "content-type:application/json" \
     "https://apigee.googleapis.com/v1/organizations/PROJECT_ID:setAddons" -XPOST \
     -d '{"addonsConfig": {"integrationConfig": {"enabled": true}, "connectorsPlatformConfig": {"enabled": true}}}'

     Aviso: quando você executa um comando de complemento, todos os complementos atuais são substituídos. Portanto, se você tiver complementos, inclua-os no comando de complementos. Caso contrário, o comando para ativar a integração e os conectores da Apigee desativará todos os outros complementos na organização. Se um complemento estiver desativado, a Apigee excluirá todas as configurações dele. Por exemplo, se você desativar o complemento, todas as integrações serão excluídas.
  4. Se você não tiver uma conta de serviço, crie uma.

     Uma conta de serviço é um tipo especial de Conta do Google destinada a representar um usuário não humano que precisa ser autenticado e autorizado a acessar dados nas APIs do Google. Se você não tiver uma conta de serviço, será necessário criar uma. Para mais informações, consulte Como criar uma conta de serviço.

• Antes de criar uma conexão do Pub/Sub para usar na integração, faça o seguinte:
  • Crie um tópico do Pub/Sub e adicione uma assinatura, conforme descrito no Guia de início rápido do Cloud Pub/Sub: como usar o console.
  • Conceda permissão para publicar no tópico do Pub/Sub. Por exemplo, é possível usar o papel roles/pubsub.publisher para publicar em tópicos. Para saber mais sobre os papéis do Pub/Sub, consulte Controle de acesso.
  • Gere uma chave para a conta de serviço. O arquivo de chave JSON será usado em uma etapa posterior para configurar a conexão do Pub/Sub.

Ativar serviços obrigatórios

Os conectores exigem que você ative os seguintes serviços do Google:

Nome	Nome
apigee.googleapis.com	API Apigee
secretmanager.googleapis.com	API Secret Manager
connectors.googleapis.com	API Connectors

Se esses serviços não foram ativados para seu projeto anteriormente, será solicitado que você os ative ao criar a conexão na página "Criar conexão".

Criar uma conexão do Pub/Sub

Para configurar uma conexão:

1. No console do Cloud, acesse a página Integration Connectors > Conexões e selecione ou crie um projeto do Google Cloud.

   Acessar a página "Conexões"

2. Clique em + CRIAR NOVO para abrir a página Criar conexão.
3. Configure a conexão:
   1. Na seção Criar conexão, faça o seguinte:
      • Conector: selecione Cloud Pub/Sub na lista suspensa de conectores disponíveis.
      • Versão do conector: selecione a versão do conector na lista suspensa de versões disponíveis.
      • No campo Nome da conexão, insira um nome para a instância de conexão

        Os nomes de conexão precisam atender aos seguintes critérios:

        • Os nomes de conexões podem usar letras, números ou hifens.
        • As letras precisam ser minúsculas.
        • Os nomes das conexões precisam começar com uma letra e terminar com uma letra ou um número.
        • Os nomes das conexões não podem exceder 63 caracteres.
      • Como opção, insira uma Descrição para a instância de conexão.
      • Conta de serviço: selecione uma conta de serviço que tenha os papéis necessários.
      • ID do projeto: o ID do projeto do Google Cloud em que a instância Pubsub reside.
      • ID do tópico: o nome do tópico em que a mensagem vai ser publicada.
      • Outra opção é clicar em + ADICIONAR MARCADOR para adicionar um rótulo à conexão na forma de um par de chave-valor.
      • Clique em PRÓXIMA.
   2. Local: escolha o local da conexão.
      • Selecione um local em que a Apigee está disponível na lista suspensa Região.

        Veja abaixo as regiões com suporte com o conector:

        Para ver a lista de todas as regiões com suporte, consulte Locais.

      • Clique em PRÓXIMA.
   3. Autenticação: os tipos de autenticação suportados pela conexão do Cloud Pub/Sub:
      • AUTH_TYPE_UNSPECIFIED

      Digite os detalhes com base na autenticação que você quer usar.

      • AUTH_TYPE_UNSPECIFIED
   4. Clique em PRÓXIMA.
   5. Revisão: revise os detalhes de conexão e autenticação.
4. Clique em Criar.
Observação: pode levar alguns minutos para que a criação da conexão seja concluída. Após a conclusão, a conexão exibirá um status Ativo na visualização em lista Conectores.

Criar uma nova integração

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

1. Acesse a IU da Apigee e faça login no mesmo projeto em que sua conexão foi criada.
2. Clique em Desenvolver > Integrações.
3. Clique em CRIAR NOVA.
4. Digite um nome e uma descrição na caixa de diálogo Criar integração.
   Observação: os nomes de integração precisam atender aos seguintes requisitos:

   • Os nomes precisam começar e terminar com letras ou números.
   • Os nomes não podem conter espaços ou mais de um traço ou sublinhado em uma linha.
5. Clique em Criar para abrir o designer de integração.

Adicionar 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. Este tutorial usa o acionador da API para invocar diretamente a execução da integração.

Para adicionar um gatilho de API a uma integração nova ou atual, siga estas etapas:

1. No designer de integração, clique em + Adicionar uma tarefa/gatilho para ver a tarefa e acionar a caixa de diálogo de seleção.
2. Clique em Acionadores para visualizar os acionadores disponíveis.
3. Arraste o elemento gatilho da API para o designer.

Nenhuma configuração adicional é necessária para esse gatilho. Para ver o ID do gatilho da API, clique no elemento Gatilho da API no designer de integração. O painel de configuração mostra o ID do gatilho, que é um ID gerado por máquina no formato api_trigger/TRIGGER_NAME.

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.

Este tutorial usa a tarefa dos Conectores. Os detalhes de configuração de cada tarefa são descritos nas etapas abaixo.

Criar uma tarefa dos Conectores com uma conexão do Pub/Sub

Para configurar a tarefa dos Conectores na Integração da Apigee e usar a conexão do Pub/Sub:

1. Acesse a IU da Apigee e faça login.
2. Selecione a organização usando o menu suspenso no canto superior esquerdo da IU.
3. Clique em Desenvolver > Integrações.
4. Busque ou selecione a integração para fazer edições na lista Integrações e clique para abrir o designer de integração.
5. Clique em +Adicionar uma tarefa/gatilho > Tarefas para ver a lista de tarefas disponíveis.
6. Arraste o elemento de tarefa dos Conectores para o designer de integração.
7. Clique no elemento de tarefa dos Conectores no designer para ver o painel de configuração da tarefa dos Conectores.
8. Também é possível clicar no para editar o nome da tarefa. Isso permite alterar o nome da tarefa de Conectores genérico para um nome significativo para sua integração.
9. Na guia Configuração da seção Configuração, clique no botão Configurar tarefa para abrir o painel Configurar tarefa do conector.
1. Na coluna Conexão, escolha a conexão do Pub/Sub criada em uma etapa anterior na lista de conexões disponíveis.
2. Depois que uma conexão é escolhida, a coluna Tipo é exibida. Para este exemplo, selecione Actions e depois publishMessage na lista de ações disponíveis.
   • Uma Entity pode ser considerada como um objeto ou um conjunto de propriedades no aplicativo ou serviço conectado que pode ser exposto a uma integração por meio da interface do Connector. A conexão do Pub/Sub não expõe nenhuma entidade.
   • Uma ação é uma função de primeira classe disponibilizada para a integração por meio da interface do conector. As funções são definidas no aplicativo ou serviço conectado e definem uma alteração ou série de alterações que podem ser feitas em uma entidade ou entidades. A conexão do Pub/Sub tem uma Ação disponível
3. Clique em Concluído para concluir a configuração da conexão e feche o painel.
10. O painel de configuração de tarefas dos Conectores para uma conexão do Pub/Sub também exibe as variáveis Entrada de tarefa e Saída de tarefa geradas automaticamente pela Entidade e operação ou Ação selecionada na etapa anterior para uso na conexão. Essas variáveis podem ser acessadas como entradas para tarefas subsequentes ou condicionais configuradas na integração atual. Para configurar a Entrada de tarefa:
    1. Clique no ícone de variável da carga de entrada do conector para abrir o painel Configurar variável.
    2. No campo Valor padrão, digite o seguinte texto: {"message": "test message from integration platform"}.
    3. Marque a caixa de seleção Usar como entrada.
    4. Clique em Salvar.

11. É possível configurar várias estratégias de repetição para lidar com erros em uma tarefa. As estratégias de repetição permitem especificar como executar novamente a tarefa em caso de erro. Para mais informações, consulte Estratégias de tratamento de erros.

12. Para adicionar uma conexão de borda do elemento gatilho da API ao elemento dos Conectores, passe o cursor sobre um ponto de controle no elemento API Trigger. Em seguida, clique e arraste uma linha até um ponto de controle no elemento de tarefa dos Conectores. Os pontos de controle e a linha de borda ficarão amarelos. A borda indica o fluxo de controle da tarefa do gatilho API para a tarefa dos Conectores.

Testar a integração

Para testar a nova integração:

1. Clique no botão Publicar na barra de ferramentas do designer de integração.
2. Clique em Testar para acionar e executar a integração. Isso abrirá a janela Test Integration, que exibe a variável de entrada (mensagem) definida em uma etapa anterior. Se você quiser, a variável de entrada pode ser modificada aqui.
3. Clique em Testar integração.
4. Após a conclusão, a janela Test Integration exibirá uma mensagem de sucesso com o valor dos payloads de entrada e saída da integração.
5. Clique em Fechar para sair da janela Integração de teste.

Para verificar o sucesso da sua integração:

• Acesse a página Pub/Sub.

  Ir para o Pub/Sub

  Selecione seu tópico do Pub/Sub e clique em Visualizar mensagens para confirmar o recebimento da mensagem enviada pela integração.
  Observação: pode haver um atraso de até vários minutos antes que a mensagem apareça.
• Inspecione os registros de integração do Apigee para ver o status de uma determinada integração. Para ver os registros:
  1. Clique em Registros na barra de ferramentas do designer 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 da execução
     • Status
     • Horário de início
     • Duração
     • ID de integração
     • ID de acionamento
  3. Clique na seta de expansão (>) ao lado da integração executada para ver uma lista expandida de tarefas e variáveis na integração, além do status da tarefa e payloads de variável.

Parabéns! Você acabou de criar e testar uma conexão do Pub/Sub com a integração da Apigee.

A seguir

• Veja a lista de conectores compatíveis na Apigee.
• Saiba como criar e gerenciar conexões.