Ir para o conteúdo

Publicar e receber mensagens do Google Pub/Sub no Jitterbit Studio

Introdução

Google Cloud Pub/Sub é um serviço de mensagens gerenciado que desacopla sistemas roteando mensagens através de tópicos e assinaturas. Um publicador escreve mensagens em um tópico; um ou mais assinantes recebem essas mensagens através de assinaturas anexadas a esse tópico.

O conector Google Pub/Sub fornece atividades para ambos os lados desse padrão:

  • Publicação: Use a atividade Publish Message para escrever mensagens em um tópico Pub/Sub a partir de uma operação no Studio, por exemplo quando um registro é criado em um sistema de origem e serviços downstream precisam ser notificados.
  • Recebimento: Use a atividade Get Message para pesquisar uma assinatura por mensagens pendentes e, em seguida, use a atividade Acknowledge Message para confirmar que cada mensagem foi processada.

Este guia cobre ambos os padrões. Para consumo de mensagens acionado por eventos (onde o Studio escuta continuamente em vez de pesquisar), consulte a referência da atividade Listen Message, que requer um cluster de agente privado com configuração de rede específica.

Este guia pressupõe o seguinte:

  • Uma conta de serviço do Google Cloud com a API Pub/Sub ativada e funções apropriadas atribuídas, conforme descrito em Pré-requisitos do Google Pub/Sub.
  • O tópico e a assinatura já existem no Google Pub/Sub.

Parte 1: Configurar a conexão do Google Pub/Sub

  1. No Studio, abra seu projeto e acesse a guia Project endpoints and connectors na paleta de componentes de design.

  2. Clique no conector Google Pub/Sub para abrir a configuração de conexão.

  3. Connection Name: Digite um nome único (por exemplo, Google Pub/Sub). O nome não pode conter barras ou dois-pontos.

  4. Project ID: Digite o valor project_id do arquivo JSON de credenciais da conta de serviço.

  5. Client Email: Digite o valor client_email do arquivo JSON de credenciais.

  6. Private Key String: Digite o valor private_key do arquivo JSON de credenciais, formatado como:

    -----BEGIN PRIVATE KEY-----<private_key>-----END PRIVATE KEY-----
    

    Nota

    O valor private_key no arquivo JSON usa \n para representar quebras de linha. Substitua cada \n por um retorno de carro real antes de colar neste campo. Se a chave for colada com caracteres \n literais, o teste de conexão retorna um erro Invalid PKCS#8 data.

  7. Clique em Test para verificar a conexão.

  8. Clique em Save Changes.

Parte 2: Publicar uma mensagem em um tópico

A atividade Publish Message é uma atividade de destino. Use-a no final de uma transformação para escrever dados como uma mensagem em um tópico Pub/Sub.

Padrão de design

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart LR A[Source activity] --> B[Transformation] --> C[Publish Message activity]

A operação começa com uma atividade de origem que fornece os dados a publicar. Pode ser qualquer atividade que retorne dados, como uma atividade Query de banco de dados ou Salesforce, uma fonte de arquivo ou a resposta de outro conector. A transformação na Etapa 2 mapeia os dados da origem para a solicitação Publish Message. As etapas abaixo pressupõem que uma atividade de origem já está em vigor na operação; para a configuração da atividade de origem, consulte a documentação do conector relevante.

Etapa 1: Configurar a atividade Publish Message

  1. Na tela de design, arraste uma atividade Publish Message da conexão Google Pub/Sub para a tela.

  2. Name: Digite um nome descritivo (por exemplo, Publish Order Created).

  3. Choose Topic: Selecione como especificar o tópico:

    • Select Existent Topic: Escolha em uma lista de tópicos carregados do seu projeto do Google Cloud. Requer a permissão pubsub.topics.list na conta de serviço.
    • Inform Topic Manually: Digite o nome do tópico diretamente. Use esta opção se o nome do tópico for dinâmico ou se a conta de serviço não tiver permissão de listagem.
  4. Tópico: Digite ou selecione o nome do tópico (por exemplo, order-events).

  5. Clique em Próximo, revise o esquema da requisição e clique em Concluído.

Etapa 2: Mapear a transformação

  1. Adicione uma etapa de Transformação entre a atividade de origem e a atividade Publicar Mensagem.

  2. Abra a transformação. Mapeie os campos de dados da origem para o esquema de requisição de Publicar Mensagem.

    O esquema de requisição inclui um nó body para a carga útil da mensagem. Se o tópico tiver um esquema configurado no Google Pub/Sub, o nó body reflete esse esquema. Se nenhum esquema estiver configurado, body aceita um valor de string; serialize seus dados para JSON antes de mapeá-los:

    JSONStringify($source_data)
    
  3. Implante e execute a operação para publicar uma mensagem.

Parte 3: Receber e confirmar mensagens de uma assinatura

Receber mensagens requer duas operações: uma para recuperar mensagens pendentes de uma assinatura e outra para confirmá-las após o processamento. O Pub/Sub reentrega mensagens não confirmadas após o prazo de confirmação expirar.

Padrão de design

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart LR A[Get Message activity] --> B[Transformation] --> C[Target activity] B -->|On Success| D[Transformation] --> E[Acknowledge Message activity]

Etapa 1: Configurar a atividade Obter Mensagem

  1. Na tela de design, arraste uma atividade Obter Mensagem da conexão Google Pub/Sub para a tela.

  2. Nome: Digite um nome descritivo (por exemplo, Get Order Events).

  3. Escolher Assinatura: Selecione Selecionar Assinatura Existente ou Informar Assinatura Manualmente e digite ou selecione o nome da assinatura.

  4. Quantidade de Mensagens: Digite o número de mensagens a recuperar por execução da operação (1–100, padrão 1). Defina isso com o tamanho de lote que seu processamento downstream consegue lidar.

  5. Prazo de Confirmação em Segundos: Opcionalmente, defina por quanto tempo o Pub/Sub mantém a mensagem antes de reentregar se não for confirmada (1–600 segundos). Deixe em branco para usar o prazo configurado da assinatura.

  6. Clique em Próximo, revise o esquema de resposta e clique em Concluído.

Etapa 2: Processar as mensagens em uma transformação

  1. Adicione uma etapa de Transformação após a atividade Obter Mensagem.

  2. Abra a transformação e mapeie os campos de mensagem do esquema de resposta para o destino.

    O esquema de resposta inclui um campo messageId e um campo body para a carga útil da mensagem. Se o corpo da mensagem for JSON, desserialize-o na transformação:

    JSONParser(Source.body)
    

    Armazene o messageId (ou o campo ackId) em uma variável global para que a etapa de confirmação possa referenciá-lo:

    $ack_id = Source.ackId;
    

Etapa 3: Configurar a atividade Confirmar Mensagem

Após as mensagens serem processadas, confirme-as para evitar reentrega.

  1. Na tela de design, arraste uma atividade Confirmar Mensagem da conexão Google Pub/Sub para a tela.

  2. Nome: Digite um nome descritivo (por exemplo, Acknowledge Order Events).

  3. Escolher Assinatura: Selecione a mesma assinatura usada na atividade Obter Mensagem.

  4. Clique em Próximo, revise o esquema e clique em Concluído.

  5. Adicione uma etapa de Transformação entre a transformação de processamento e a atividade Confirmar Mensagem. Mapeie o valor ackId armazenado em ack_id para o esquema de requisição de confirmação.

  6. Nas configurações da operação, configure a operação Confirmar Mensagem para ser executada Ao Sucesso da operação de processamento.

Aviso

Sempre confirme mensagens após o processamento bem-sucedido. Se a operação falhar antes de confirmar, o Pub/Sub reentrega a mensagem após o prazo de confirmação. Projete sua lógica de processamento para ser idempotente, de modo que mensagens reentreg não causem efeitos colaterais duplicados.

Verificar a integração

Publicação: Envie um registro de teste pela operação e verifique no Google Cloud Console (Pub/Sub > Topics > [nome do tópico]) se a contagem de mensagens aumentou. Alternativamente, use o padrão Get Message para recuperar a mensagem e confirmar o payload.

Recebimento: Publique uma mensagem de teste no tópico da assinatura usando o Google Cloud Console (Pub/Sub > Topics > [nome do tópico] > Publish Message). Execute a operação Get Message e verifique os logs de operação para confirmar se a mensagem foi recuperada. Verifique se o destino foi preenchido com os dados esperados e confirme se a mensagem não aparece mais na assinatura (indicando reconhecimento bem-sucedido).

Se o teste de conexão falhar, verifique se a conta de serviço tem as funções corretas atribuídas conforme descrito em Pré-requisitos do Google Pub/Sub.