Enviar e receber mensagens do Azure Service Bus no Jitterbit Studio
Introdução
Azure Service Bus é um serviço de mensagens gerenciado que suporta dois padrões de mensagens:
- Filas: Mensagens ponto a ponto onde cada mensagem é consumida por um único receptor.
- Tópicos e assinaturas: Mensagens publicar-assinar onde cada mensagem é entregue a múltiplos assinantes através de assinaturas de tópicos.
O conector Microsoft Azure Service Bus fornece atividades para ambos os padrões. Este guia aborda os fluxos de trabalho mais comuns:
- Enviar uma mensagem para uma fila ou tópico usando a atividade Send Message.
- Recuperar mensagens de uma fila usando a atividade Get Queue Message.
- Recuperar mensagens de uma assinatura de tópico usando a atividade Get Topic Message.
Para consumo orientado por eventos (onde o Studio escuta continuamente mensagens recebidas), consulte as referências de atividades Consume Queue e Consume Topic, que exigem um cluster de agentes privados com configuração de rede específica.
Este guia assume o seguinte:
- Um namespace do Azure Service Bus está configurado com as filas ou tópicos necessários.
- O principal de serviço ou política usado para autenticação possui a função ou os direitos apropriados, conforme descrito em Pré-requisitos do Azure Service Bus.
Parte 1: Configurar a conexão do Azure Service Bus
O conector suporta dois tipos de autenticação. Use Microsoft Entra ID ao conectar via um registro de aplicativo do Azure (recomendado para produção). Use Shared Access Signatures para configurações mais simples ou onde o Entra ID não está disponível.
-
No Studio, abra seu projeto e acesse a aba Project endpoints and connectors na paleta de componentes de design.
-
Clique no conector Microsoft Azure Service Bus para abrir a configuração de conexão.
-
Connection Name: Digite um nome único (por exemplo,
Azure Service Bus). O nome não pode conter barras invertidas ou dois-pontos. -
Authentication Type: Selecione um dos seguintes:
Microsoft Entra ID:
- Namespace / Hostname: Digite o nome do namespace do Service Bus (por exemplo,
my-namespace) ou o nome de host completo (por exemplo,my-namespace.servicebus.windows.net). - Tenant ID: Digite o ID de diretório (locatário) do seu Azure Active Directory.
- Client ID: Digite o ID do aplicativo (cliente) do registro de aplicativo.
- Client Secret: Digite o valor do segredo do cliente para o registro de aplicativo.
Shared Access Signatures:
- Namespace / Hostname: Digite o nome do namespace ou nome de host completo.
- Policy Name: Digite o nome da Política de Acesso Compartilhado configurada no namespace ou fila.
- Primary Key: Digite o valor da chave primária para a política.
- Namespace / Hostname: Digite o nome do namespace do Service Bus (por exemplo,
-
Clique em Test para verificar a conexão.
-
Clique em Save Changes.
Parte 2: Enviar uma mensagem
A atividade Send Message é uma atividade de destino que escreve uma mensagem em uma fila ou tópico. Use-a quando o Studio precisar publicar eventos ou dados para sistemas downstream.
Padrão de design
Etapa 1: Configurar a atividade Send Message
-
Na tela de design, arraste uma atividade Send Message da conexão do Azure Service Bus para a tela.
-
Name: Digite um nome descritivo (por exemplo,
Send Order to Queue). -
Choose Queue/Topic: Selecione Select Existent Queue/Topic para escolher de uma lista, ou Inform Queue/Topic Manually para inserir o nome diretamente.
-
Digite ou selecione o nome da fila ou tópico.
-
Clique em Avançar, analise o esquema da requisição e clique em Concluído.
Etapa 2: Mapear a transformação
-
Adicione uma etapa de Transformação entre a atividade de origem e a atividade Enviar Mensagem.
-
Abra a transformação e mapeie os campos de dados para o esquema de requisição de Enviar Mensagem. O esquema inclui um campo
bodypara o conteúdo da mensagem. Para dados estruturados, serialize para JSON antes do mapeamento:JSONStringify($record_data)O esquema também inclui campos opcionais para propriedades da mensagem, como
contentType,correlationIdesessionId. Defina-os se seus consumidores downstream dependerem deles para roteamento ou filtragem.
Parte 3: Recuperar mensagens de uma fila
A atividade Obter Mensagem da Fila é uma atividade de origem que consulta uma fila em busca de mensagens pendentes. O Studio processa cada mensagem recuperada por uma transformação e a escreve no destino.
Padrão de design
Etapa 1: Configurar a atividade Obter Mensagem da Fila
-
Na tela de design, arraste uma atividade Obter Mensagem da Fila da conexão do Barramento de Serviço do Azure para a tela.
-
Nome: Digite um nome descritivo (por exemplo,
Obter Pedidos da Fila). -
Escolher Fila: Selecione ou digite o nome da fila.
-
Modo de Recebimento: Selecione uma das seguintes opções:
- Peek Lock: A mensagem é bloqueada por um período configurável enquanto o Studio a processa. A mensagem permanece na fila até ser explicitamente excluída. Use este modo quando o processamento confiável for importante: se a operação falhar, o bloqueio expira e a mensagem fica disponível novamente.
- Receber e Excluir: A mensagem é excluída da fila imediatamente quando recuperada. Use este modo apenas quando a perda de mensagens em caso de falha for aceitável.
-
Número de Mensagens: Digite o número de mensagens a recuperar por execução (1–100, padrão
1). -
Tempo de Espera: Digite o tempo máximo em segundos para aguardar mensagens se a fila estiver vazia (padrão
10, máximo245). -
Clique em Avançar, analise o esquema de resposta e clique em Concluído.
Etapa 2: Processar e excluir a mensagem
Ao usar o modo Peek Lock, as mensagens devem ser explicitamente excluídas após o processamento bem-sucedido para removê-las da fila. Adicione uma operação Excluir Mensagem da Fila encadeada ao sucesso da operação de processamento:
-
Na tela de design, crie uma segunda operação contendo uma atividade Excluir Mensagem da Fila.
-
Na operação de processamento de Obter Mensagem da Fila, armazene o token de bloqueio da mensagem em uma variável global durante a transformação:
$lock_token = Source.lockToken; -
Configure a atividade Excluir Mensagem da Fila com o mesmo nome de fila e mapeie
lock_tokenpara o esquema de requisição de exclusão. -
Nas configurações da operação de processamento, configure a operação Excluir Mensagem da Fila para ser executada Em Caso de Sucesso.
Dica
Se a operação falhar antes de excluir a mensagem, o bloqueio expira após a duração configurada do bloqueio e a mensagem fica disponível para reprocessamento. Projete sua lógica de processamento para ser idempotente, de modo que mensagens reenviadas não causem efeitos duplicados.
Parte 4: Recuperar mensagens de uma assinatura de tópico
Recuperar de uma assinatura de tópico segue o mesmo padrão da recuperação de fila, mas requer seleção de um tópico e uma assinatura.
-
Na tela de design, arraste uma atividade Obter Mensagem do Tópico da conexão do Barramento de Serviço do Azure para a tela.
-
Configure a atividade da mesma forma que Obter Mensagem da Fila (consulte Parte 3), mas:
- Selecione um nome de Tópico.
- Após selecionar o tópico, selecione uma Assinatura dentro desse tópico.
-
Para excluir mensagens processadas, use uma atividade Excluir Mensagem do Tópico em vez de Excluir Mensagem da Fila e selecione o mesmo tópico e assinatura.
Verificar a integração
Envio: Execute a operação de envio e verifique no portal do Azure se a contagem de mensagens na fila ou tópico aumentou. Use o recurso Service Bus Explorer no portal para inspecionar o corpo da mensagem e suas propriedades.
Recebimento: Envie uma mensagem de teste para a fila ou tópico usando o Service Bus Explorer do portal do Azure. Execute a operação Get Queue Message ou Get Topic Message e verifique os logs de operação para confirmar que a mensagem foi recuperada. Verifique se o destino foi gravado com os dados esperados. Se estiver usando Peek Lock, confirme que a mensagem foi deletada da fila verificando a contagem de mensagens no portal.
Se o teste de conexão falhar, verifique se a entidade de serviço ou a Política de Acesso Compartilhado tem a função Azure Service Bus Data Owner ou os direitos apropriados de envio/escuta, conforme descrito em Pré-requisitos do Azure Service Bus.