Controlar recursos para aplicativos cliente com grupos de aplicativos

Os Hubs de Eventos do Azure permite controlar cargas de trabalho de streaming de eventos para aplicativos cliente que se conectam aos Hubs de Eventos usando grupos de aplicativos. Para obter mais informações, confira Governança de recursos com grupos de aplicativos.

Este artigo mostra como executar as seguintes tarefas:

• Criar um grupo de aplicativos.
• Habilitar ou desabilitar um grupo de aplicativos
• Definir limites e aplicar políticas de limitação a um grupo de aplicativos
• Validar a limitação com logs de diagnóstico

Observação

Os grupos de aplicativos estão disponíveis atualmente apenas nas camadas Premium e Dedicada.

Criar um grupo de aplicativos

Esta seção mostra como criar um grupo de aplicativos usando o portal do Azure, a CLI, o PowerShell e um modelo do ARM (Azure Resource Manager).

Azure portal

Seguindo estas etapas, é possível criar um grupo de aplicativos usando o portal do Azure.

1. Navegue até o namespace dos Hubs de Eventos.

2. No menu à esquerda, selecione Grupos de aplicativos em Configurações.

3. Na página Grupos de aplicativos, selecione + Grupo de aplicativos na barra de comandos.

   

4. Na página Adicionar grupo de aplicativos, siga estas etapas:

   1. Especifique um nome para o grupo de aplicativos.

   2. Certifique-se de selecionar Habilitado. Para desabilitar o grupo de aplicativos, desmarque a opção Habilitado. Esse sinalizador determina se os clientes de um grupo de aplicativos podem acessar os Hubs de Eventos ou não.

   3. Para Tipo de contexto de segurança, selecione Política de acesso compartilhado do namespace, política de acesso compartilhado do hub de eventos ou Aplicativo do Microsoft Entra. O grupo de aplicativos dá suporte à seleção da chave da SAS no namespace ou no nível da entidade (hub de eventos). Ao criar o grupo de aplicativos, associe uma SAS (assinatura de acesso compartilhado) ou uma ID de aplicativo do Microsoft Entra, que é usada por aplicativos cliente.

   4. Se você selecionou Política de acesso compartilhado do namespace, faça o seguinte:

      1. Em Nome da chave SAS, selecione a política SAS que pode ser usada como um contexto de segurança para o grupo de aplicativos. Selecione Adicionar política de SAS para adicionar uma política e, em seguida, associar ao grupo de aplicativos.

         

   5. Se você selecionou a política de acesso compartilhado dos Hubs de Eventos:

      1. Para o nome de chave da SAS, copie o nome de política da SAS da página "Políticas de Acesso Compartilhado" dos Hubs de Eventos e cole na caixa de texto

         

   6. Caso selecionou o aplicativo do Microsoft Entra:

      1. Para a ID do Aplicativo (cliente) do Microsoft Entra , especifique o aplicativo do Microsoft Entra ou a ID do cliente.

      

Tipo de contexto de segurança com suporte

Examine a ID do grupo de clientes gerada automaticamente, que é a ID exclusiva associada ao grupo de aplicativos. O escopo da governança do aplicativo (namespace ou nível de entidade) dependeria do nível de acesso da ID do aplicativo do Microsoft Entra usada. A tabela a seguir mostra a ID do Grupo de Clientes gerada automaticamente para tipos de contexto de segurança diferentes:

Tipo de contexto de segurança	ID do grupo de clientes gerado automaticamente
Chave de acesso compartilhado do namespace	NamespaceSASKeyName=<NamespaceLevelKeyName>
Aplicativo do Microsoft Entra	AADAppID=<AppID>
Chave de acesso compartilhado dos Hubs de Eventos	EntitySASKeyName=<EntityLevelKeyName>

Observação

Todos os grupos de aplicativos existentes criados com a chave de acesso compartilhado continuariam a trabalhar com a ID do grupo de clientes começando com SASKeyName. No entanto, todos os novos grupos de aplicativos teriam atualizado a ID do grupo de clientes, conforme mostrado acima.

1. Para bloquear uma política, siga estas etapas:

   1. Insira um nome para a política.

   2. Para Tipo, selecione Política de limitação.

   3. Para ID de métrica, selecione uma das seguintes opções: Mensagens de entrada, Mensagens de saída, Bytes de entrada, Bytes de saída. No exemplo a seguir, as Mensagens de entrada são selecionadas.

   4. Para Limite de taxa, insira o valor limite. No exemplo a seguir, 10.000 é especificado como o limite para o número de mensagens recebidas.

      

      Veja a seguir uma captura de tela da página com outra política adicionada.

      

2. Agora, na página Adicionar grupo de aplicativos, selecione Adicionar.

3. Confirme se você vê o grupo de aplicativos na lista de grupos de aplicativos.

   

   É possível excluir o grupo de aplicativos da lista selecionando o botão do ícone da lixeira próximo a ele na lista.

CLI do Azure

Use o comando da CLI: az eventhubs namespace application-group create para criar um grupo de aplicativos no namespace dos hubs de eventos ou no nível do Hubs de Eventos. Você deve definir --client-app-group-identifier com base no tipo de contexto de segurança que você está escolhendo. Revise a tabela acima para saber o tipo de contexto de segurança com suporte

O exemplo a seguir cria o grupo de aplicativos myAppGroup no namespace mynamespace do grupo de recursos MyResourceGroup do Azure. Ele usa as configurações a seguir.

• A política de acesso compartilhado é usada como contexto de segurança
• A ID do grupo de aplicativos cliente está definida como NamespaceSASKeyName=<NameOfTheSASkey>.
• Primeira política de limitação para a métrica Incoming messages com o limite 10000.
• Segunda política de limitação para a métrica Incoming bytes com o limite 20000.

az eventhubs namespace application-group create --namespace-name mynamespace \
                                                -g MyResourceGroup \
                                                --name myAppGroup \
                                                --client-app-group-identifier NamespaceSASKeyName=keyname \
                                                --throttling-policy-config name=policy1 metric-id=IncomingMessages rate-limit-threshold=10000 \
                                                --throttling-policy-config name=policy2 metric-id=IncomingBytes rate-limit-threshold=20000

Para saber mais sobre o comando da CLI, confira az eventhubs namespace application-group create.

PowerShell do Azure

Use o comando do PowerShell: New-AzEventHubApplicationGroup para criar um grupo de aplicativos no namespace dos hubs de eventos ou no nível do Hubs de Eventos. Você deve definir -ClientAppGroupIdentifier com base no tipo de contexto de segurança que você está escolhendo. Revise a tabela acima para saber o tipo de contexto de segurança com suporte

O exemplo a seguir usa New-AzEventHubThrottlingPolicyConfig para criar duas políticas que serão associadas ao aplicativo.

• Primeira política de limitação para a métrica Incoming bytes com o limite 12345.
• Segunda política de limitação para a métrica Incoming messages com o limite 23416.

Em seguida, ele cria o grupo de aplicativos myappgroup no namespace mynamespace do grupo de recursos myresourcegroup do Azure especificando as políticas de limitação e a política de acesso compartilhado como o contexto de segurança.

$policy1 = New-AzEventHubThrottlingPolicyConfig -Name policy1 -MetricId IncomingBytes -RateLimitThreshold 12345

$policy2 = New-AzEventHubThrottlingPolicyConfig -Name policy2 -MetricId IncomingMessages -RateLimitThreshold 23416

New-AzEventHubApplicationGroup -ResourceGroupName myresourcegroup -NamespaceName mynamespace -Name myappgroup 
		-ClientAppGroupIdentifier NamespaceSASKeyName=myauthkey -ThrottlingPolicyConfig $policy1, $policy2

Para saber mais sobre o comando do PowerShell, confira New-AzEventHubApplicationGroup.

Modelo de ARM

O exemplo a seguir mostra como criar um grupo de aplicativos usando um modelo do ARM. Neste exemplo, o grupo de aplicativos é associado ao nome de uma política de SAS existente chamada contososaspolicy por meio da definição do cliente AppGroupIdentifier como NamespaceSASKeyName=contososaspolicy. As políticas do grupo de aplicativos também são definidas no modelo do ARM. Você deve definir ClientAppGroupIdentifier com base no tipo de contexto de segurança que você está escolhendo. Revise a tabela acima para saber o tipo de contexto de segurança com suporte

{
	"type": "ApplicationGroups",
	"apiVersion": "2022-01-01-preview",
	"name": "[parameters('applicationGroupName')]",
	"dependsOn": [
		"[resourceId('Microsoft.EventHub/namespaces/', parameters('eventHubNamespaceName'))]",
		"[resourceId('Microsoft.EventHub/namespaces/authorizationRules', parameters('eventHubNamespaceName'),parameters('namespaceAuthorizationRuleName'))]"
	],
	"properties": {
		"ClientAppGroupIdentifier": "NamespaceSASKeyName=contososaspolicy",
		"policies": [{
				"Type": "ThrottlingPolicy",
				"Name": "ThrottlingPolicy1",
				"metricId": "IncomingMessages",
				"rateLimitThreshold": 10
			},
			{
				"Type": "ThrottlingPolicy",
				"Name": "ThrottlingPolicy2",
				"metricId": "IncomingBytes",
				"rateLimitThreshold": 3951729
			}
		],
		"isEnabled": true
	}
}

Habilitar ou desabilitar um grupo de aplicativos

Você pode impedir que aplicativos cliente acessem o namespace dos Hubs de Eventos desabilitando o grupo de aplicativos que contém esses aplicativos. Quando o grupo de aplicativos estiver desabilitado, os aplicativos cliente não poderão publicar ou consumir dados. As conexões estabelecidas nos aplicativos cliente desse grupo de aplicativos também serão encerradas.

Esta seção mostra como habilitar ou desabilitar um grupo de aplicativos usando o portal do Azure, o PowerShell, a CLI e o modelo do ARM.

Azure portal

1. Na página Namespace dos Hubs de Eventos, selecione Grupos de aplicativos no menu à esquerda.

2. Selecione o grupo de aplicativos que você deseja habilitar ou desabilitar.

   

3. Na página Editar grupo de aplicativos, desmarque a caixa de seleção ao lado de Habilitado para desabilitar um grupo de aplicativos e clique em Atualizar na parte inferior da página. Da mesma forma, marque a caixa de seleção para habilitar um grupo de aplicativos.

   

CLI do Azure

Use o comando az eventhubs namespace application-group update com --is-enabled definido como false para desabilitar um grupo de aplicativos. Da mesma forma, para habilitar um grupo de aplicativos, defina essa propriedade como true e execute o comando.

O comando de exemplo a seguir desabilita o grupo de aplicativos myappgroup no namespace mynamespace dos Hubs de Eventos que está no grupo de recursos myresourcegroup.

az eventhubs namespace application-group update --namespace-name mynamespace -g myresourcegroup --name myappgroup --is-enabled false

PowerShell do Azure

Use o comando Set-AzEventHubApplicationGroup com -IsEnabled definido como false para desabilitar um grupo de aplicativos. Da mesma forma, para habilitar um grupo de aplicativos, defina essa propriedade como true e execute o comando.

O comando de exemplo a seguir desabilita o grupo de aplicativos myappgroup no namespace mynamespace dos Hubs de Eventos que está no grupo de recursos myresourcegroup.

Set-AzEventHubApplicationGroup -ResourceGroupName myresourcegroup -NamespaceName mynamespace -Name myappgroup -IsEnabled false

Modelo de ARM

O modelo do ARM a seguir mostra como atualizar um namespace existente (contosonamespace) para desabilitar um grupo de aplicativos definindo a propriedade isEnabled como false. O identificador do grupo de aplicativos é SASKeyName=RootManageSharedAccessKey.

Observação

O exemplo a seguir também adiciona duas políticas de limitação

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "namespace_name": {
      "defaultValue": "contosonamespace",
      "type": "String"
    },
    "client-app-group-identifier": {
      "defaultValue": "SASKeyName=RootManageSharedAccessKey",
      "type": "String"
    }
  },
  "resources": [
    {
      "type": "Microsoft.EventHub/namespaces/applicationGroups",
      "apiVersion": "2022-01-01-preview",
      "name": "[concat(parameters('namespace_name'), '/contosoappgroup')]",
      "properties": {
        "clientAppGroupIdentifier": "[parameters('client-app-group-identifier')]",
        "isEnabled": false,
		"policies": [
			{
				"type": "ThrottlingPolicy",
				"name": "incomingmsgspolicy",
				"metricId": "IncomingMessages",
				"rateLimitThreshold": 10000
			},
			{
				"type": "ThrottlingPolicy",
				"name": "incomingbytespolicy",
				"metricId": "IncomingBytes",
				"rateLimitThreshold": 20000
			}
		]
      }
    }
  ]
}

Aplicar políticas de limitação

Você pode adicionar nenhuma ou mais políticas ao criar um grupo de aplicativos ou a um grupo de aplicativos existente. Por exemplo, você pode adicionar políticas de limitação relacionadas a IncomingMessages, IncomingBytes ou OutgoingBytes ao contosoAppGroup. Essas políticas serão aplicadas a cargas de trabalho de streaming de eventos dos aplicativos cliente que usam a política de SAS contososaspolicy.

Para saber como adicionar políticas ao criar um grupo de aplicativos, confira a seção Criar um grupo de aplicativos.

Também é possível adicionar políticas após a criação de um grupo de aplicativos.

Azure portal

1. Na página Namespace dos Hubs de Eventos, selecione Grupos de aplicativos no menu à esquerda.

2. Selecione o grupo de aplicativos no qual você deseja adicionar, atualizar ou excluir uma política.

   

3. Na página Editar grupo de aplicativos, siga estas etapas:

   1. Atualizar configurações (incluindo valores de limite) de políticas existentes
   2. Adicionar uma política

CLI do Azure

Use az eventhubs namespace application-group policy add para adicionar uma política a um grupo de aplicativos existente.

Exemplo:

az eventhubs namespace application-group policy add --namespace-name mynamespace -g MyResourceGroup --name myAppGroup --throttling-policy-config name=policy1 metric-id=OutgoingMessages rate-limit-threshold=10500 --throttling-policy-config name=policy2 metric-id=IncomingBytes rate-limit-threshold=20000

PowerShell do Azure

Use o comando Set-AzEventHubApplicationGroup com -ThrottingPolicyConfig definido para valores apropriados.

Exemplo:

$policyToBeAppended = New-AzEventHubThrottlingPolicyConfig -Name policy1 -MetricId IncomingBytes -RateLimitThreshold 12345

$appGroup = Get-AzEventHubApplicationGroup -ResourceGroupName myresourcegroup -NamespaceName mynamespace -Name myappgroup

$appGroup.ThrottlingPolicyConfig += $policyToBeAppended

Set-AzEventHubApplicationGroup -ResourceGroupName myresourcegroup -NamespaceName mynamespace -Name myappgroup -ThrottlingPolicyConfig $appGroup.ThrottlingPolicyConfig

Modelo de ARM

O modelo do ARM a seguir mostra como atualizar um namespace existente (contosonamespace) para adicionar políticas de limitação. O identificador do grupo de aplicativos é NamespaceSASKeyName=RootManageSharedAccessKey.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "namespace_name": {
      "defaultValue": "contosonamespace",
      "type": "String"
    },
    "client-app-group-identifier": {
      "defaultValue": "NamespaceSASKeyName=RootManageSharedAccessKey",
      "type": "String"
    }
  },
  "resources": [
    {
      "type": "Microsoft.EventHub/namespaces/applicationGroups",
      "apiVersion": "2022-01-01-preview",
      "name": "[concat(parameters('namespace_name'), '/contosoappgroup')]",
      "properties": {
        "clientAppGroupIdentifier": "[parameters('client-app-group-identifier')]",
        "isEnabled": true,
		"policies": [
			{
				"type": "ThrottlingPolicy",
				"name": "incomingmsgspolicy",
				"metricId": "IncomingMessages",
				"rateLimitThreshold": 10000
			},
			{
				"type": "ThrottlingPolicy",
				"name": "incomingbytespolicy",
				"metricId": "IncomingBytes",
				"rateLimitThreshold": 20000
			}
		]
      }
    }
  ]
}

Decidir o valor do limite para políticas de limitação

Os Hubs de Eventos do Azure dão suporte à funcionalidade de Logs de métrica do aplicativo para observar a taxa de transferência usual em seu sistema e decidir adequadamente sobre o valor limite para o grupo de aplicativos. Você pode seguir estas etapas para decidir sobre um valor limite:

1. Ative as configurações de diagnóstico nos Hubs de Eventos com logs de métrica do aplicativo como categoria selecionada e escolha o Log Analytics como destino.

2. Crie um grupo de aplicativos vazio sem nenhuma política de limitação.

3. Continue enviando mensagens/eventos para o hub de eventos na taxa de transferência habitual.

4. Acesse o workspace do Log Analytics e consulte o nome de atividade certo na tabela (com base em (resource-governance-overview.md#throttling-policy---threshold-limits)) em AzureDiagnostics. A consulta de exemplo a seguir é definida para acompanhar o valor do limite das mensagens de entrada:

   AzureDiagnostics 
       | where ActivityName_s =="IncomingMessages" 
       | where Outcome_s =="Success"      
   

5. Selecione a seção Gráfico no workspace do Log Analytics e crie um gráfico entre o tempo gerado no eixo Y e a contagem de mensagens enviadas no eixo x.

   

   Neste exemplo, você pode ver que a taxa de transferência usual nunca ultrapassou o valor de 550 mensagens (taxa de transferência atual esperada). Essa observação ajuda você a definir o valor de limite real.

6. Depois de decidir o valor de limite, adicione uma nova política de limitação dentro do grupo de aplicativos.

Publicar ou consumir eventos

Depois de adicionar políticas de limitação com êxito ao grupo de aplicativos, você poderá testar o comportamento da limitação publicando ou consumindo eventos usando os aplicativos cliente que fazem parte do grupo de aplicativos contosoAppGroup. Para isso, use um cliente AMQP ou um aplicativo cliente Kafka e o mesmo nome da política de SAS ou a ID de aplicativo do Microsoft Entra usada para criar o grupo de aplicativos.

Observação

Quando os aplicativos cliente são limitados, você deve observar lentidão na publicação ou no consumo de dados.

Validar a limitação com grupos de aplicativos

Semelhante a Decidir limites para políticas de limitação, você pode usar logs de métrica do aplicativo para validar a limitação e encontrar mais detalhes.

Você pode usar a consulta de exemplo abaixo para descobrir todas as solicitações limitadas em determinado período. Você deve atualizar o ActivityName para corresponder à operação que você espera que seja limitada.

  AzureDiagnostics 
  |  where Category =="ApplicationMetricsLogs"
  | where ActivityName_s =="IncomingMessages" 
  | where Outcome_s =="Throttled"  
	

Devido a restrições no nível do protocolo, os logs de solicitação limitados não são gerados para operações de consumidor no hub de eventos (OutgoingMessages ou OutgoingBytes). Quando as solicitações são limitadas no lado do consumidor, você observa a taxa de transferência de saída lenta.

Próximas etapas

• Para obter informações conceituais sobre grupos de aplicativos, confira Governança de recursos com grupos de aplicativos.
• Confira Referência do Azure PowerShell para Hubs de Eventos
• Confira Referência da CLI do Azure para Hubs de Eventos