Conectar-se ao Barramento de Serviço do Azure a partir dos 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 de um fluxo de trabalho nos Aplicativos Lógicos do Azure usando o conector do Barramento de Serviço. Então, você poderá criar fluxos de trabalho automatizados que são executados quando disparados por eventos em um barramento de serviço ou executar ações para gerenciar itens do barramento de serviço, por exemplo:

• Monitorar quando mensagens chegam (preenchimento automático) ou são recebidas (peek-lock) em filas, tópicos e assinaturas de tópicos.
• Enviar mensagens.
• Criar e excluir assinaturas de tópicos.
• Gerenciar mensagens em filas e assinaturas de tópicos; por exemplo, get, get deferred, complete, defer, abandon e dead-letter.
• Renovar bloqueios em mensagens e sessões nas filas e assinaturas de tópicos.
• Fechar sessões em filas e tópicos.

Você pode usar gatilhos para obter respostas do Barramento de Serviço do Azure e disponibilizar a saída para outras ações em fluxo de trabalho. Você também pode fazer com que outras ações usem a saída das ações do Barramento de Serviço.

Referência técnica do conector

O conector do Barramento de Serviço tem versões diferentes, com base no tipo de fluxo de trabalho do aplicativos lógico e no ambiente do host.

Pré-requisitos

• Uma conta e uma assinatura do Azure. Se você não tiver uma assinatura do Azure, inscreva-se em uma conta gratuita do Azure.

• Um namespace de Barramento de Serviço e a entidade de mensagens, como uma fila. Para saber mais, consulte a seguinte documentação:

  • Criar um namespace do Barramento de Serviço

  • Criar um namespace do Barramento de Serviço e da fila

  • Criar um namespace do Barramento de Serviço e do tópico com assinatura

• O fluxo de trabalho do aplicativo lógico em que você se conecta ao namespace do Barramento de Serviço e à entidade de mensagens. Se você quiser iniciar o fluxo de trabalho com um gatilho do Barramento de Serviço, precisará começar com um fluxo de trabalho em branco. Para usar uma ação do Barramento de Serviço no fluxo de trabalho, inicie o fluxo de trabalho com qualquer gatilho.

• Se o recurso do aplicativo lógico usar uma identidade gerenciada para autenticação do acesso ao namespace do Barramento de Serviço e à entidade de mensagens, verifique se você atribuiu as 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 de aplicativo lógico deve usar apenas uma identidade gerenciada, mesmo que o fluxo de trabalho do aplicativo lógico acesse diferentes entidades de mensagens.

  • Cada identidade gerenciada que acessa uma assinatura de fila ou tópico deve usar sua própria conexão de API do Barramento de Serviço.

  • As operações do Barramento de Serviço que trocam mensagens com diferentes entidades de mensagens e exigem permissões diferentes devem usar suas próprias conexões de API do Barramento de Serviço.

  Para obter mais informações sobre identidades gerenciadas, consulte Autenticar acesso aos recursos do Azure com identidades gerenciadas nos Aplicativos Lógicos do Azure.

• Por padrão, as operações internas do conector do Barramento de Serviço são sem estado. Para executar essas operações no modo com estado, consulte Como habilitar o modo com estado para conectores internos sem estado.

Considerações sobre as operações de Barramento de Serviço do Azure

Loops infinitos

Limite de sessões salvas no cache do conector

Por entidade de mensagens do Barramento de Serviço, como uma assinatura ou um tópico, o conector do Barramento de Serviço pode economizar 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, confira Sessões de mensagem.

Enviar mensagens correlacionadas na ordem

Quando você precisar enviar mensagens relacionadas em uma ordem específica, poderá criar um fluxo de trabalho usando o conector do Barramento de Serviço e o padrão de comboio sequencial. As mensagens correlacionadas têm uma propriedade que define a relação entre elas, como a ID da sessão no Barramento de Serviço do Azure.

Ao criar um fluxo de trabalho do aplicativo lógico de Consumo, você pode selecionar o modelo De entrega em ordem correlacionado usando sessões do barramento de serviço, que implementa o padrão de comboio sequencial. Para obter mais informações, consulte Enviar mensagens relacionadas na ordem.

Suporte a mensagens grandes

O suporte a mensagens grandes só está disponível para fluxos de trabalho Standard, quando você usa as operações internas do conector do Barramento de Serviço. Por exemplo, você pode receber e enviar mensagens grandes usando gatilhos internos e ações, respectivamente.

Para o conector gerenciado do Barramento de Serviço, o tamanho máximo da mensagem é limitado a 1 MB, mesmo quando você usa um namespace do Barramento de Serviço de camada premium.

Aumentar o tempo limite para receber e enviar mensagens

Nos fluxos de trabalho Standard que usam as operações internas do Barramento de Serviço, 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 do conector gerenciado do Barramento de Serviço

• Para o conector gerenciado do Barramento de Serviço, todos os gatilhos são de sondagem longa. Esse tipo de gatilho processa todas as mensagens e aguarda 30 segundos para que mais mensagens apareçam na fila ou na assinatura do tópico. Se nenhuma mensagem aparecer em 30 segundos, a execução do gatilho será ignorada. Caso contrário, o gatilho continuará lendo as mensagens até que a fila ou a assinatura do tópico esteja vazia. A próxima sondagem 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 disparados, eles retornam entre um e o número de mensagens especificado pela propriedade Contagem máxima de mensagens.

  Observação

  O gatilho de preenchimento automático conclui automaticamente uma mensagem, mas a conclusão ocorre somente na próxima chamada para o Barramento de Serviço. Esse comportamento pode afetar o design do fluxo de trabalho. Por exemplo, evite alterar a simultaneidade no gatilho de preenchimento automático, pois essa alteração poderá resultar em mensagens duplicadas se o fluxo de trabalho entrar em um estado de restrição. Alterar o controle de simultaneidade cria as seguintes condições:

  • Os gatilhos limitados são ignorados com o código WorkflowRunInProgress.

  • A operação de conclusão não é executada.

  • A próxima execução do gatilho ocorre após o intervalo de sondagem.

  Você precisa definir a duração do bloqueio do barramento de serviço como um valor maior que o intervalo de sondagem. No entanto, apesar dessa configuração, a mensagem ainda poderá não ser preenchida se o fluxo de trabalho permanecer em um estado de restrição no próximo intervalo de sondagem.

  No entanto, se você ativar a configuração de simultaneidade de um gatilho do Barramento de Serviço, o valor padrão para a propriedade maximumWaitingRuns será 10. Com base na configuração de duração do bloqueio da entidade do Barramento de Serviço e na duração do 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 seu cenário, comece a testar com um valor de 1 ou 2 para a maximumWaitingRuns propriedade . Para alterar o valor máximo de execuções em espera, examine Alterar limite de execuções em espera.

Gatilhos do conector interno do Barramento de Serviço

Para o conector interno do Barramento de Serviço, os gatilhos não relacionados a sessões seguem um padrão de gatilho de sondagem contínuo que é totalmente gerenciado pelo conector. Esse padrão faz com que o gatilho verifique constantemente se há mensagens na fila ou assinatura do tópico. Os gatilhos de sessão seguem o padrão de gatilho de sondagem longa e sua configuração é regida pela configuração do Azure Functions chamada clientRetryOptions:tryTimeout. Atualmente, as configurações do gatilho interno do Barramento de Serviço são compartilhadas entre a extensão de host do Azure Functions, que é definido no arquivo host.json do aplicativo lógico e as configurações de gatilho definidas no fluxo de trabalho do aplicativo lógico, que você pode configurar por meio do designer ou da exibição de código. Esta seção aborda os dois locais de configurações.

• Em fluxos de trabalho Standard, alguns gatilhos, como quando as mensagens estão disponíveis em um gatilho de fila, podem retornar uma ou mais mensagens. Quando esses gatilhos são acionados, eles retornam entre um e o número de mensagens. Para esse tipo de gatilho e onde não há suporte para o parâmetro de contagem máxima de mensagens, 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 Standard.

  "extensions": {
    "serviceBus": {
        "maxMessageBatchSize": 25
    }
  }
  

• Você também pode habilitar a simultaneidade no gatilho do Barramento de Serviço 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 que o tamanho geral do lote. Dessa forma, as mensagens de leitura 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 SplitOn será reduzido para 100 itens. Esse comportamento é verdadeiro para todos os gatilhos, não apenas para o gatilho do Barramento de Serviço. Verifique se o tamanho do lote especificado é menor 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 nessas execuções, os Aplicativos Lógicos do Azure os enfileiram em um estado de espera até que possam ser iniciados. 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 Barramento de Serviço, verifique se você testa 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 limites de simultaneidade e desproteção de lote aqui.

• Se você habilitar a simultaneidade, um atraso de 30 segundos existirá entre leituras em lote, por padrão. Esse atraso retarda o gatilho para atingir as seguintes metas:

  • Reduza o número de chamadas de armazenamento enviadas para verificar o número de execuções nas quais aplicar simultaneidade.

  • Imita o comportamento do gatilho do conector gerenciado do Barramento de Serviço, que tem uma sondagem longa de 30 segundos quando nenhuma mensagem é encontrada.

  Você pode alterar esse atraso, mas verifique se testa cuidadosamente as alterações no valor padrão:

  "workflow": {
      "settings": {
          "Runtime.ServiceProviders.FunctionTriggers.DynamicListenerEnableDisableInterval": "00:00:30"
      }
  }
  
  

Etapa 1: Verificar o acesso ao namespace do Barramento de Serviço

Para confirmar que o recurso do aplicativo lógico tem permissões para acessar o namespace do Barramento de Serviço, use as seguintes etapas:

1. No portal do Azure, abra o namespace do Barramento de Serviço.

2. No menu do 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

Posteriormente, ao adicionar um gatilho ou uma ação do Barramento de Serviço pela primeira vez, você será solicitado a obter as informações de conexão, incluindo o tipo de autenticação da conexão. Com base no tipo de fluxo de trabalho do aplicativo lógico, na versão do conector do Barramento de Serviço e no tipo de autenticação selecionado, você precisará dos seguintes itens:

Autenticação do conector gerenciado (fluxos de trabalho de Consumo e Standard)

Autenticação interna do conector (somente fluxos de trabalho Standard)

Obter a cadeia de conexão para o namespace do Barramento de Serviço

Para criar uma conexão ao adicionar um gatilho ou ação do Barramento de Serviço, você precisa ter a cadeia de conexão para o namespace do Barramento de Serviço. A cadeia de conexão começa com o prefixo sb://.

1. No portal do Azure, abra o namespace do Barramento de Serviço.

2. No menu do namespace, em Configurações, selecione Políticas de acesso compartilhado.

3. No painel Políticas de acesso compartilhado, selecione RootManageSharedAccessKey.

4. Ao lado da cadeia de conexão primária ou secundária, selecione o botão copiar.

   

   Observação

   Para verificar se a cadeia de caracteres é para o namespace, e não uma entidade de mensagens específica, pesquise a cadeia de conexão para o parâmetro EntityPath. Se encontrar esse parâmetro, a cadeia de conexão servirá para uma entidade específica e não será a cadeia correta a ser usada com o fluxo de trabalho.

5. Salve a cadeia de conexão para uso posterior.

Obter a URL do ponto de extremidade para o namespace do Barramento de Serviço

Se você usar o conector gerenciado do Barramento de Serviço, precisará dessa URL de ponto de extremidade se selecionar o tipo de autenticação para integrada do Microsoft Entra ou Identidade Gerenciada de Aplicativos Lógicos. A URL do ponto de extremidade começa com o prefixo sb://.

1. No portal do Azure, abra o namespace do Barramento de Serviço.

2. No menu do namespace, em Configurações, selecione Propriedades.

3. Em Propriedades, ao lado do ponto de extremidade do Barramento de Serviço, 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 um nome totalmente qualificado para o namespace do Barramento de Serviço

1. No portal do Azure, abra o namespace do Barramento de Serviço.

2. No menu namespace, selecione Visão geral.

3. No painel Visão geral, localize a propriedade Nome do Host e copie o nome totalmente qualificado, semelhante a <your-Service-Bus-namespace>.servicebus.windows.net.

Etapa 3: Opção 1 – Adicionar um gatilho do Barramento de Serviço

As seguintes etapas usam o portal do Azure, mas com a extensão de Aplicativos Lógicos do Azure apropriada, você também pode usar as seguintes ferramentas para criar fluxos de trabalho do aplicativo lógico:

• Fluxos de trabalho do aplicativo lógico de consumo: Visual Studio ou Visual Studio Code

• Fluxos de trabalho de aplicativo lógico padrão: Visual Studio Code

Etapa 3: Opção 2 – Adicionar uma ação do Barramento de Serviço

As seguintes etapas usam o portal do Azure, mas com a extensão de Aplicativos Lógicos do Azure apropriada, você também pode usar as seguintes ferramentas para criar fluxos de trabalho do aplicativo lógico:

• Fluxos de trabalho do aplicativo lógico de consumo: Visual Studio ou Visual Studio Code

• Fluxos de trabalho de aplicativo lógico padrão: Visual Studio Code

Configurações de aplicativo do conector interno do Barramento de Serviço

Em um recurso de aplicativo lógico Standard, o conector interno do Barramento de Serviço 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 de aplicativo – local.settings.json.

Ler mensagens de filas de mensagens mortas com gatilhos internos do Barramento de Serviço

Nos fluxos de trabalho Standard, 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:

1. Em seu fluxo de trabalho em branco, com base em seu cenário, adicione o gatilho do conector interno do Barramento de Serviço chamado Quando as mensagens estiverem disponíveis em uma fila ou Quando uma mensagem estiver disponível em uma assinatura de tópico (bloqueio de inspeção).

2. No gatilho, defina os seguintes valores de parâmetro para especificar a fila ou a fila de mensagens mortas padrão da sua assinatura de tópico, que você pode acessar como qualquer outra fila:

   • Gatilho Quando as mensagens estiverem disponíveis em uma fila: defina o parâmetro Nome da fila como queuename/$deadletterqueue.

   • Gatilho Quando uma mensagem estiver disponível em uma assinatura de tópico (bloqueio de inspeção): defina o parâmetro Nome do tópico como topicname/Subscriptions/subscriptionname/$deadletterqueue.

   Para obter mais informações, consulte a Visão geral das filas de mensagens mortas do Barramento de Serviço.

Solução de problemas

Atrasos nas atualizações do fluxo de trabalho que estão em vigor

Se o intervalo de sondagem de um gatilho do Barramento de Serviço for pequeno, como 10 segundos, as atualizações do fluxo de trabalho poderão não ter efeito por até 10 minutos. Para resolver esse problema, você pode desabilitar o recurso do aplicativo lógico, fazer as alterações e habilitar o recurso do aplicativo lógico novamente.

Nenhuma sessão disponível ou pode estar bloqueado por outro receptor

Ocasionalmente, operações como concluir uma mensagem ou renovar uma sessão produzem o seguinte erro:

{
  "status": 400,
  "error": {
    "message": "No session available to complete the message with the lock token 'ce440818-f26f-4a04-aca8-555555555555'."
  }
}

Ocasionalmente, um gatilho baseado em sessão pode falhar com o seguinte erro:

{
  "status": 400,
  "error": {
    "message": "Communication with the Service Bus namespace 'xxxx' and 'yyyy' entity failed. The requested session 'zzzz' cannot be accepted. It may be locked by another receiver."
  }
}

O conector do Barramento de Serviço usa o cache na memória para dar suporte a todas as operações associadas às sessões. O receptor de mensagem do Barramento de Serviço é 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 Barramento de Serviço em uma sessão exigem o mesmo receptor que recebe as mensagens para uma sessão específica.

Devido a motivos como uma atualização de infraestrutura, implantação de conector e assim por diante, existe a possibilidade de solicitações não serem roteadas para a mesma instância de função. Se este evento acontecer, as solicitações falharão por um dos seguintes motivos:

• O receptor que executa as operações na sessão não está disponível na instância de função que atende à solicitação.

• A nova instância de função tenta obter a sessão, que atingiu o tempo limite na instância de função antiga ou não foi encerrada.

Desde que esse erro ocorra apenas ocasionalmente, isso é esperado. Quando o erro acontece, a mensagem ainda é preservada no barramento de serviço. A próxima execução de gatilho ou fluxo de trabalho tenta processar a mensagem novamente.

Próximas etapas

• Conectores gerenciados dos Aplicativos Lógicos do Azure
• Conectores internos de Aplicativos Lógicos do Azure
• O que são os conectores nos Aplicativos Lógicos do Azure