Conectar-se ao Barramento de Serviço do Azure a partir de fluxos de trabalho nos Aplicativos Lógicos do Azure
Aplica-se a: Aplicativos Lógicos do Azure (Consumo + Padrão)
Este guia mostra como acessar o Barramento de Serviço do Azure a partir de um fluxo de trabalho nos Aplicativos Lógicos do Azure usando o conector do Service Bus. Em seguida, você pode criar fluxos de trabalho automatizados que são executados quando acionados por eventos em um barramento de serviço ou executar ações para gerenciar itens do barramento de serviço, por exemplo:
- Monitore quando as mensagens chegam (preenchimento automático) ou são recebidas (peek-lock) em filas, tópicos e assinaturas de tópicos.
- Envie mensagens.
- Crie e exclua assinaturas de tópicos.
- Gerencie mensagens em filas e assinaturas de tópicos, por exemplo, obter, ser adiado, concluir, adiar, abandonar e letra morta.
- Renove bloqueios em mensagens e sessões em filas e assinaturas de tópicos.
- Feche sessões em filas e tópicos.
Você pode usar gatilhos que obtêm respostas do Barramento de Serviço do Azure e disponibilizam a saída para outras ações em seus fluxos de trabalho. Você também pode fazer com que outras ações usem a saída das ações do Service Bus.
Referência técnica do conector
O conector do Service Bus tem versões diferentes, com base no tipo de fluxo de trabalho do aplicativo lógico e no ambiente do host.
| Aplicação lógica | Environment | Versão do conector |
|---|---|---|
| Consumo | Aplicativos Lógicos do Azure Multilocatário | Conector gerenciado (classe Standard). Para obter mais informações, consulte a seguinte documentação: - Referência do conector gerenciado do Service Bus - Conectores gerenciados em Aplicativos Lógicos do Azure |
| Consumo | Ambiente de serviço de integração (ISE) | Conector gerenciado (classe Standard) e versão ISE, que tem limites de mensagem diferentes da classe Standard. Para obter mais informações, consulte a seguinte documentação: - Referência do conector gerenciado do Service Bus - Limites de mensagens ISE - Conectores gerenciados em Aplicativos Lógicos do Azure |
| Standard | Aplicativos Lógicos do Azure e Ambiente do Serviço de Aplicativo v3 de locatário único (somente planos do Windows) | Conector gerenciado (hospedado no Azure) e conector interno, que é baseado em provedor de serviços. A versão integrada geralmente fornece melhor desempenho, recursos, preços e assim por diante. Nota: Os gatilhos do conector interno do Service Bus seguem o padrão de gatilho de sondagem, o que significa que o gatilho verifica continuamente se há mensagens na fila ou na assinatura de tópico. Para obter mais informações, consulte a seguinte documentação: - Referência do conector gerenciado do Service Bus - Operações de conector integrado do Service Bus - Conectores internos nos Aplicativos Lógicos do Azure |
Pré-requisitos
Uma conta e subscrição do Azure. Se não tiver uma subscrição do Azure, inscreva-se para obter uma conta do Azure gratuita.
Um namespace do Service Bus e uma entidade de mensagens, como uma fila. Para obter mais informações, consulte a seguinte documentação:
O fluxo de trabalho do aplicativo lógico no qual você se conecta ao namespace e à entidade de mensagens do Service Bus. Para iniciar seu fluxo de trabalho com um gatilho do Service Bus, você precisa começar com um fluxo de trabalho em branco. Para usar uma ação do Service Bus em seu fluxo de trabalho, inicie seu fluxo de trabalho com qualquer gatilho.
Se o recurso do aplicativo lógico usar uma identidade gerenciada para autenticar o acesso ao namespace e à entidade de mensagens do Service Bus, verifique se você atribuiu permissões de função nos níveis correspondentes. Por exemplo, para acessar uma fila, a identidade gerenciada requer uma função que tenha as permissões necessárias para essa fila.
Cada recurso do aplicativo lógico deve usar apenas uma identidade gerenciada, mesmo que o fluxo de trabalho do aplicativo lógico acesse entidades de mensagens diferentes.
Cada identidade gerenciada que acessa uma fila ou assinatura de tópico deve usar sua própria conexão de API do Service Bus.
As operações do Service Bus que trocam mensagens com entidades de mensagens diferentes e exigem permissões diferentes devem usar suas próprias conexões de API do Service Bus.
Para obter mais informações sobre identidades gerenciadas, consulte Autenticar o acesso aos recursos do Azure com identidades gerenciadas nos Aplicativos Lógicos do Azure.
Por padrão, as operações internas do conector do Service Bus são sem monitoração de estado. Para executar essas operações no modo com monitoração de estado, consulte Habilitar o modo com monitoração de estado para conectores internos sem monitoração de estado.
Considerações para operações do Barramento de Serviço do Azure
Loops infinitos
Importante
Tenha cuidado ao selecionar um gatilho e uma ação que tenham o mesmo tipo de conector e usá-los para trabalhar com a mesma entidade, como uma fila de mensagens ou uma assinatura de tópico. Essa combinação pode criar um loop infinito, o que resulta em um aplicativo lógico que nunca termina.
Limite de sessões salvas no cache do conector
Por entidade de mensagens do Service Bus, como uma assinatura ou tópico, o conector do Service Bus pode salvar até 1.500 sessões exclusivas de cada vez no cache do conector. Se a contagem de sessões exceder esse limite, as sessões antigas serão removidas do cache. Para obter mais informações, consulte Sessões de mensagens.
Enviar mensagens correlacionadas em ordem
Quando precisar enviar mensagens relacionadas em uma ordem específica, você poderá criar um fluxo de trabalho usando o conector do Service Bus e o padrão de comboio sequencial. As mensagens correlacionadas têm uma propriedade que define a relação entre essas mensagens, como a ID da sessão no Barramento de Serviço do Azure.
Ao criar um fluxo de trabalho de aplicativo lógico de consumo, você pode selecionar o modelo Entrega no pedido correlacionada usando sessões de barramento de serviço, que implementa o padrão de comboio sequencial. Para obter mais informações, consulte Enviar mensagens relacionadas em ordem.
Suporte a mensagens grandes
O suporte a mensagens grandes está disponível apenas para fluxos de trabalho padrão quando você usa as operações de conector interno do Service Bus. Por exemplo, você pode receber e receber mensagens grandes usando os gatilhos e ações internos, respectivamente.
Para o conector gerenciado do Service Bus, o tamanho máximo da mensagem é limitado a 1 MB, mesmo quando você usa um namespace do Service Bus de camada premium.
Aumente o tempo limite para receber e enviar mensagens
Em fluxos de trabalho padrão que usam as operações internas do Service Bus, você pode aumentar o tempo limite para receber e enviar mensagens. Por exemplo, para aumentar o tempo limite para receber uma mensagem, altere a seguinte configuração na extensão do Azure Functions:
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle.Workflows",
"version": "[1.*, 2.0.0)"
},
"extensions": {
"serviceBus": {
"batchOptions": {
"operationTimeout": "00:15:00"
}
}
}
}
Para aumentar o tempo limite para enviar uma mensagem, adicione a configuração do aplicativo ServiceProviders.ServiceBus.MessageSenderOperationTimeout.
Gatilhos de conector gerenciado do Service Bus
Para o conector gerenciado do Service Bus, todos os gatilhos são de sondagem longa. Esse tipo de gatilho processa todas as mensagens e, em seguida, aguarda 30 segundos para que mais mensagens apareçam na fila ou na assinatura de tópico. Se não aparecerem mensagens no prazo de 30 segundos, o acionador será ignorado. Caso contrário, o acionador continuará a ler as mensagens até que a subscrição de tópico ou fila esteja vazia. A próxima pesquisa de gatilho é baseada no intervalo de recorrência especificado nas propriedades do gatilho.
Alguns gatilhos, como o gatilho Quando uma ou mais mensagens chegam em uma fila (preenchimento automático), podem retornar uma ou mais mensagens. Quando esses gatilhos são acionados, eles retornam entre um e o número de mensagens especificado pela propriedade Maximum message count do gatilho.
Nota
O gatilho de preenchimento automático conclui automaticamente uma mensagem, mas a conclusão só acontece na próxima chamada para o Service Bus. Esse comportamento pode afetar o design do fluxo de trabalho. Por exemplo, evite alterar a simultaneidade no gatilho de preenchimento automático porque essa alteração pode resultar em mensagens duplicadas se o fluxo de trabalho entrar em um estado limitado. Alterar o controle de simultaneidade cria as seguintes condições:
Os gatilhos acelerados são ignorados com o
WorkflowRunInProgresscódigo.A operação de conclusão não será executada.
A próxima execução de gatilho ocorre após o intervalo de sondagem.
Você precisa definir a duração do bloqueio do barramento de serviço para um valor maior do que o intervalo de sondagem. No entanto, apesar dessa configuração, a mensagem ainda pode não ser concluída se o fluxo de trabalho permanecer em um estado limitado no próximo intervalo de sondagem.
No entanto, se você ativar a configuração de simultaneidade de um gatilho do Service Bus, o valor padrão para a
maximumWaitingRunspropriedade será 10. Com base na configuração de duração de bloqueio da entidade do Service Bus e na duração de execução do seu fluxo de trabalho, esse valor padrão pode ser muito grande e pode causar uma exceção de "bloqueio perdido". Para encontrar o valor ideal para o seu cenário, comece a testar com um valor de 1 ou 2 para amaximumWaitingRunspropriedade. Para alterar o valor máximo de execuções em espera, consulte Alterar limite de execuções em espera.
Gatilhos de conector internos do Service Bus
Atualmente, as definições de configuração para o gatilho interno do Service Bus são compartilhadas entre a extensão de host do Azure Functions, que é definida no arquivo de host.json do seu aplicativo lógico, e as configurações de gatilho definidas no fluxo de trabalho do seu aplicativo lógico, que você pode configurar por meio do designer ou da exibição de código. Esta seção aborda ambos os locais de configurações.
Em fluxos de trabalho padrão, alguns gatilhos, como o gatilho Quando as mensagens estão disponíveis em uma fila , podem retornar uma ou mais mensagens. Quando esses gatilhos disparam, eles retornam entre um e o número de mensagens. Para esse tipo de gatilho e onde o parâmetro Maximum message count não é suportado, você ainda pode controlar o número de mensagens recebidas usando a propriedade maxMessageBatchSize no arquivo host.json . Para localizar esse arquivo, consulte Editar configurações de host e aplicativo para aplicativos lógicos padrão.
"extensions": { "serviceBus": { "maxMessageBatchSize": 25 } }Você também pode habilitar a simultaneidade no gatilho do Service Bus, por meio do designer ou no código:
"runtimeConfiguration": { "concurrency": { "runs": 100 } }Ao configurar a simultaneidade usando um lote, mantenha o número de execuções simultâneas maior do que o tamanho geral do lote. Dessa forma, as mensagens lidas não entram em um estado de espera e são sempre captadas quando são lidas. Em alguns casos, o gatilho pode ter até o dobro do tamanho do lote.
Se você habilitar a simultaneidade, o limite de SplitOn será reduzido para 100 itens. Esse comportamento é verdadeiro para todos os gatilhos, não apenas para o gatilho do Service Bus. Verifique se o tamanho do lote especificado é menor do que esse limite em qualquer gatilho em que você habilite a simultaneidade.
Existem alguns cenários em que o gatilho pode exceder as configurações de simultaneidade. Em vez de falhar essas execuções, os Aplicativos Lógicos do Azure as enfileiram em um estado de espera até que possam ser iniciadas. A configuração maximumWaitingRuns controla o número de execuções permitidas no estado de espera:
"runtimeConfiguration": { "concurrency": { "runs": 100, "maximumWaitingRuns": 50 } }Com o gatilho do Service Bus, certifique-se de testar cuidadosamente essas alterações para que as execuções não esperem mais do que o tempo limite de bloqueio da mensagem. Para obter mais informações sobre os valores padrão, consulte Simultaneidade e limites de eliminação de lotes aqui.
Se você habilitar a simultaneidade, haverá um atraso de 30 segundos entre as leituras em lote, por padrão. Esse atraso retarda o gatilho para atingir os seguintes objetivos:
Reduza o número de chamadas de armazenamento enviadas para verificar o número de execuções nas quais aplicar simultaneidade.
Mimetize o comportamento do gatilho do conector gerenciado do Service Bus, que tem uma pesquisa longa de 30 segundos quando nenhuma mensagem é encontrada.
Você pode alterar esse atraso, mas certifique-se de testar cuidadosamente todas as alterações no valor padrão:
"workflow": { "settings": { "Runtime.ServiceProviders.FunctionTriggers.DynamicListenerEnableDisableInterval": "00:00:30" } }
Etapa 1: Verificar o acesso ao namespace do Service Bus
Para confirmar se o recurso do aplicativo lógico tem permissões para acessar o namespace do Service Bus, use as seguintes etapas:
No portal do Azure, abra seu namespace do Service Bus.
No menu namespace, em Configurações, selecione Políticas de acesso compartilhado. Em Declarações, verifique se você tem permissões de gerenciamento para esse namespace.
Etapa 2: Obter requisitos de autenticação de conexão
Mais tarde, quando você adicionar um gatilho ou ação do Service Bus pela primeira vez, serão solicitadas informações de conexão, incluindo o tipo de autenticação de conexão. Com base no tipo de fluxo de trabalho do aplicativo lógico, na versão do conector do Service Bus e no tipo de autenticação selecionado, você precisará dos seguintes itens:
Autenticação de conector gerenciado (fluxos de trabalho padrão e de consumo)
| Authentication type | Informações necessárias |
|---|---|
| Chave de Acesso | A cadeia de conexão para seu namespace do Service Bus. Para obter mais informações, consulte Obter cadeia de conexão para namespace do Service Bus |
| Microsoft Entra integrado | A URL do ponto de extremidade para seu namespace do Service Bus. Para obter mais informações, consulte Obter URL do ponto de extremidade para namespace do Service Bus. |
| Identidade gerenciada de aplicativos lógicos | A URL do ponto de extremidade para seu namespace do Service Bus. Para obter mais informações, consulte Obter URL do ponto de extremidade para namespace do Service Bus. |
Autenticação de conector integrada (somente fluxos de trabalho padrão)
| Authentication type | Informações necessárias |
|---|---|
| Cadeia de Ligação | A cadeia de conexão para seu namespace do Service Bus. Para obter mais informações, consulte Obter cadeia de conexão para namespace do Service Bus |
| Active Directory OAuth | - O nome totalmente qualificado para seu namespace do Service Bus, por exemplo, <your-Service-Bus-namespace.servicebus.windows.net.> Para obter mais informações, consulte Obter nome totalmente qualificado para namespace do Service Bus. Para obter os outros valores de propriedade, consulte Autenticação de abertura do Microsoft Entra ID. |
| Identidade gerida | O nome totalmente qualificado para seu namespace do Service Bus, por exemplo, <your-Service-Bus-namespace.servicebus.windows.net.> Para obter mais informações, consulte Obter nome totalmente qualificado para namespace do Service Bus. |
Obter cadeia de conexão para namespace do Service Bus
Para criar uma conexão ao adicionar um gatilho ou ação do Service Bus, você precisa ter a cadeia de conexão para seu namespace do Service Bus. A cadeia de conexão começa com o prefixo sb:// .
No portal do Azure, abra seu namespace do Service Bus.
No menu namespace, em Configurações, selecione Políticas de acesso compartilhado.
No painel Políticas de acesso compartilhado, selecione RootManageSharedAccessKey.
Ao lado da cadeia de conexão primária ou secundária, selecione o botão Copiar.
Nota
Para verificar se a cadeia de caracteres é para o namespace, não uma entidade de mensagens específica, pesquise a cadeia de conexão para o
EntityPathparâmetro. Se você encontrar esse parâmetro, a cadeia de conexão será para uma entidade específica e não será a cadeia de caracteres correta a ser usada com seu fluxo de trabalho.Salve a cadeia de conexão para uso posterior.
Obter URL de ponto de extremidade para namespace do Service Bus
Se você usar o conector gerenciado do Service Bus, precisará dessa URL de ponto de extremidade se selecionar o tipo de autenticação para Microsoft Entra integrado ou Identidade Gerenciada de Aplicativos Lógicos. A URL do ponto de extremidade começa com o prefixo sb:// .
No portal do Azure, abra seu namespace do Service Bus.
No menu namespace, em Configurações, selecione Propriedades.
Em Propriedades, ao lado do ponto de extremidade do Service Bus, copie a URL do ponto de extremidade e salve para uso posterior quando precisar fornecer a URL do ponto de extremidade do barramento de serviço.
Obter nome totalmente qualificado para namespace do Service Bus
No portal do Azure, abra seu namespace do Service Bus.
No menu namespace, selecione Visão geral.
No painel Visão geral, localize a propriedade Nome do host e copie o nome totalmente qualificado, que se parece com< your-Service-Bus-namespace.servicebus.windows.net.>
Etapa 3: Opção 1 - Adicionar um gatilho do Service Bus
As etapas a seguir usam o portal do Azure, mas com a extensão apropriada de Aplicativos Lógicos do Azure, você também pode usar as seguintes ferramentas para criar fluxos de trabalho de aplicativos lógicos:
Fluxos de trabalho do aplicativo lógico de consumo: Visual Studio ou Visual Studio Code
Fluxos de trabalho de aplicativos lógicos padrão: Visual Studio Code
No portal do Azure, abra seu recurso de aplicativo lógico de consumo com fluxo de trabalho em branco no designer.
No designer, siga estas etapas gerais para adicionar o gatilho do Barramento de Serviço do Azure desejado.
Este exemplo continua com o gatilho chamado Quando uma mensagem é recebida em uma fila (preenchimento automático).
Se solicitado, forneça as seguintes informações para sua conexão. Quando tiver terminado, selecione Criar.
Property Necessário Description Nome da ligação Sim Um nome para a sua ligação Tipo de Autenticação Sim O tipo de autenticação a ser usado para acessar seu namespace do Service Bus. Para obter mais informações, consulte Autenticação do conector gerenciado. Cadeia de Ligação Sim A cadeia de conexão que você copiou e salvou anteriormente. Por exemplo, essa conexão usa a autenticação de chave de acesso e fornece a cadeia de conexão para um namespace do Service Bus:
Depois que a caixa de informações do gatilho aparecer, forneça as informações necessárias, por exemplo:
Property Necessário Description Nome da fila Sim A fila selecionada para acessar Tipo de fila Não O tipo para a fila selecionada Com que frequência você deseja verificar se há itens? Sim O intervalo de sondagem e a frequência para verificar a fila de itens 
Para adicionar outras propriedades disponíveis ao gatilho, abra a lista Adicionar novo parâmetro e selecione as propriedades desejadas.
Adicione todas as ações necessárias ao seu fluxo de trabalho.
Por exemplo, você pode adicionar uma ação que envia e-mail quando uma nova mensagem chega. Quando o gatilho verifica a fila e encontra uma nova mensagem, o fluxo de trabalho executa as ações selecionadas para a mensagem encontrada.
Quando tiver terminado, guarde o fluxo de trabalho. Na barra de ferramentas do estruturador, selecione Guardar.
Etapa 3: Opção 2 - Adicionar uma ação do Service Bus
As etapas a seguir usam o portal do Azure, mas com a extensão apropriada de Aplicativos Lógicos do Azure, você também pode usar as seguintes ferramentas para criar fluxos de trabalho de aplicativos lógicos:
Fluxos de trabalho do aplicativo lógico de consumo: Visual Studio ou Visual Studio Code
Fluxos de trabalho de aplicativos lógicos padrão: Visual Studio Code
No portal do Azure, abra seu aplicativo lógico de consumo e fluxo de trabalho no designer.
No designer, siga estas etapas gerais para adicionar a ação do Barramento de Serviço do Azure desejada.
Este exemplo continua com a ação Enviar mensagem .
Se solicitado, forneça as seguintes informações para sua conexão. Quando tiver terminado, selecione Criar.
Property Necessário Description Nome da ligação Sim Um nome para a sua ligação Tipo de Autenticação Sim O tipo de autenticação a ser usado para acessar seu namespace do Service Bus. Para obter mais informações, consulte Autenticação do conector gerenciado. Cadeia de Ligação Sim A cadeia de conexão que você copiou e salvou anteriormente. Por exemplo, essa conexão usa a autenticação de chave de acesso e fornece a cadeia de conexão para um namespace do Service Bus:
Depois que a caixa de informações da ação for exibida, forneça as informações necessárias, por exemplo:
Property Necessário Description Nome da fila/tópico Sim A fila selecionada ou o destino do tópico para enviar a mensagem ID da sessão Não O ID da sessão se enviar a mensagem para uma fila ou tópico com reconhecimento de sessão Propriedades do sistema Não - Nenhuma
- Detalhes da execução: adicione informações de propriedade de metadados sobre a execução como propriedades personalizadas na mensagem.
Para adicionar outras propriedades disponíveis à ação, abra a lista Adicionar novo parâmetro e selecione as propriedades desejadas.
Adicione quaisquer outras ações de que seu fluxo de trabalho precisa.
Por exemplo, você pode adicionar uma ação que envia e-mail para confirmar que sua mensagem foi enviada.
Quando tiver terminado, guarde o fluxo de trabalho. Na barra de ferramentas do estruturador, selecione Guardar.
Configurações do aplicativo conector integrado do Service Bus
Em um recurso de aplicativo lógico padrão, o conector interno do Service Bus inclui configurações de aplicativo que controlam vários limites, como tempo limite para envio de mensagens e número de remetentes de mensagens por núcleo de processador no pool de mensagens. Para obter mais informações, consulte Referência para configurações do aplicativo - local.settings.json.
Ler mensagens de filas de mensagens mortas com gatilhos internos do Service Bus
Em Fluxos de trabalho padrão, para ler uma mensagem de uma fila de mensagens mortas em uma fila ou uma assinatura de tópico, siga estas etapas usando os gatilhos especificados:
No fluxo de trabalho em branco, com base no cenário, adicione o gatilho de conector interno do Service Bus chamado Quando as mensagens estiverem disponíveis em uma fila ou Quando uma mensagem estiver disponível em uma assinatura de tópico (peek-lock).
No gatilho, defina os seguintes valores de parâmetro para especificar a fila de letras mortas padrão da sua fila ou fila de letras mortas da assinatura de tópico, que você pode acessar como qualquer outra fila:
Quando as mensagens estiverem disponíveis em um gatilho de fila: defina o parâmetro Nome da fila como queuename/$deadletterqueue.
Quando uma mensagem estiver disponível em um gatilho de assinatura de tópico (peek-lock): defina o parâmetro Nome do tópico como topicname/Subscriptions/subscriptionname/$deadletterqueue.
Para obter mais informações, consulte Visão geral das filas de mensagens mortas do Service Bus.
Resolução de Problemas
Atrasos nas atualizações do seu fluxo de trabalho a entrar em vigor
Se o intervalo de sondagem de um gatilho do Service Bus for pequeno, como 10 segundos, as atualizações do seu fluxo de trabalho podem não ter efeito por até 10 minutos. Para contornar esse problema, você pode desabilitar o recurso de aplicativo lógico, fazer as alterações e, em seguida, habilitar o recurso de aplicativo lógico novamente.
Nenhuma sessão disponível
Ocasionalmente, operações como concluir uma mensagem ou renovar uma sessão produzem o seguinte erro:
{
"status": 400,
"message": "No session available to complete the message with the lock token 'ce440818-f26f-4a04-aca8-555555555555'. clientRequestId: facae905-9ba4-44f4-a42a-888888888888",
"error": {
"message": "No session available to complete the message with the lock token 'ce440818-f26f-4a04-aca8-555555555555'."
}
}
O conector do Service Bus usa cache na memória para dar suporte a todas as operações associadas às sessões. O recetor de mensagens do Service Bus é armazenado em cache na memória da instância de função (máquina virtual) que recebe as mensagens. Para processar todas as solicitações, todas as chamadas para a conexão são roteadas para essa mesma instância de função. Esse comportamento é necessário porque todas as operações do Service Bus em uma sessão exigem o mesmo recetor que recebe as mensagens para uma sessão específica.
Existe a chance de que as solicitações não sejam roteadas para a mesma instância de função, devido a motivos como uma atualização de infraestrutura, implantação de conector e assim por diante. Se esse evento acontecer, as solicitações falharão porque o recetor que executa as operações na sessão não está disponível na instância de função que atende a solicitação.
Contanto que esse erro aconteça apenas ocasionalmente, o erro é esperado. Quando o erro acontece, a mensagem ainda é preservada no barramento de serviço. O próximo gatilho ou fluxo de trabalho executado tenta processar a mensagem novamente.