Controlar recursos para aplicativos cliente com grupos de aplicativos

Os Hubs de Eventos do Azure permitem que você controle cargas de trabalho de streaming de eventos para aplicativos cliente que se conectam a Hubs de Eventos usando grupos de aplicativos. Para obter mais informações, consulte Governança de recursos com grupos de aplicativos.

Este artigo mostra como executar as tarefas seguintes:

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

Nota

Os grupos de aplicativos estão disponíveis apenas em níveis premium e dedicado .

Criar um grupo de aplicativos

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

Portal do Azure

Você pode criar um grupo de aplicativos usando o portal do Azure seguindo estas etapas.

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. Confirme se a opção Ativado está selecionada. Para que o grupo de aplicativos esteja no estado desabilitado primeiro, desmarque a opção Habilitado . Esse sinalizador determina se os clientes de um grupo de aplicativos podem acessar Hubs de Eventos ou não.

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

   4. Se você selecionou a política de acesso compartilhado de namespace:

      1. Para Nome da chave SAS, selecione a diretiva SAS que pode ser usada como um contexto de segurança para este grupo de aplicativos. Você pode selecionar Adicionar política SAS para adicionar uma nova 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 da chave SAS, copie o nome da política SAS da página "Políticas de acesso compartilhado" dos Hubs de Eventos e cole na caixa de texto

         

   6. Se você selecionou o aplicativo Microsoft Entra:

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

      

Tipo de contexto de segurança suportado

Revise a ID do grupo Cliente 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 para a ID do aplicativo Microsoft Entra usado. A tabela a seguir mostra a ID do Grupo de Clientes gerada automaticamente para diferentes tipos de contexto de segurança:

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

Nota

Todos os grupos de aplicativos existentes criados com chave de acesso compartilhado de namespace continuariam a funcionar com ID de 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 adicionar uma política, siga estes passos:

   1. Insira um nome para a política.

   2. Em 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, Mensagens de entrada é selecionado.

   4. Em Limite de taxa, insira o valor do limite. No exemplo a seguir, 10000 é especificado como o limite para o número de mensagens de entrada.

      

      Aqui está 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 que você vê o grupo de aplicativos na lista de grupos de aplicativos.

   

   Você pode excluir o grupo de aplicativos na lista selecionando o botão do ícone da lixeira ao lado dele na lista.

CLI do Azure

Use o comando CLI: az eventhubs namespace application-group create para criar um grupo de aplicativos no namespace de Hubs de Eventos ou no nível do hub de eventos. Você deve definir --client-app-group-identifier com base no tipo de contexto de segurança escolhido. Consulte a tabela acima para saber o tipo de contexto de segurança suportado

O exemplo a seguir cria um grupo de aplicativos nomeado myAppGroup no namespace mynamespace no grupo MyResourceGroupde recursos do Azure . Ele usa as seguintes configurações.

• 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 Incoming messages métrica com 10000 como limite.
• Segunda política de limitação para a Incoming bytes métrica com 20000 como limite.

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 CLI, consulte az eventhubs namespace application-group create.

Azure PowerShell

Use o comando PowerShell: New-AzEventHubApplicationGroup para criar um grupo de aplicativos no namespace dos Hubs de Eventos ou no nível do hub de eventos. Você deve definir -ClientAppGroupIdentifier com base no tipo de contexto de segurança escolhido. Consulte a tabela acima para saber o tipo de contexto de segurança suportado

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

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

Em seguida, ele cria um grupo de aplicativos nomeado myappgroup no namespace mynamespace no grupo myresourcegroup de recursos 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 PowerShell, consulte New-AzEventHubApplicationGroup.

Modelo ARM

O exemplo a seguir mostra como criar um grupo de aplicativos usando um modelo ARM. Neste exemplo, o grupo de aplicativos é associado a um nome contososaspolicy de diretiva SAS existente definindo o cliente AppGroupIdentifier como NamespaceSASKeyName=contososaspolicy. As políticas de grupo de aplicativos também são definidas no modelo ARM. Você deve definir ClientAppGroupIdentifier com base no tipo de contexto de segurança escolhido. Consulte a tabela acima para saber o tipo de contexto de segurança suportado

{
	"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 seu namespace de Hubs de Eventos desabilitando o grupo de aplicativos que contém esses aplicativos. Quando o grupo de aplicativos é desabilitado, os aplicativos cliente não poderão publicar ou consumir dados. Quaisquer conexões estabelecidas de 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, PowerShell, CLI e modelo ARM.

Portal do Azure

1. Na página Namespace de 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 selecione 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 az eventhubs namespace application-group update comando com --is-enabled set to 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 nomeado myappgroup no namespace mynamespace Hubs de Eventos que está no grupo myresourcegroupde recursos .

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

Azure PowerShell

Use o comando Set-AzEventHubApplicationGroup com -IsEnabled set to 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 nomeado myappgroup no namespace mynamespace Hubs de Eventos que está no grupo myresourcegroupde recursos .

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

Modelo ARM

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

Nota

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 zero 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 ao IncomingMessages, IncomingBytes ou OutgoingBytes ao contosoAppGroup. Essas políticas serão aplicadas a cargas de trabalho de streaming de eventos de aplicativos cliente que usam a política SAS contososaspolicy.

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

Você também pode adicionar políticas depois que um grupo de aplicativos é criado.

Portal do Azure

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

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

   

3. Na página Editar grupo de aplicativos, você pode executar as seguintes etapas:

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

CLI do Azure

Use o 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

Azure PowerShell

Use o comando Set-AzEventHubApplicationGroup com -ThrottlingPolicyConfig valores definidos como 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 ARM

O modelo 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étricas de Aplicativo para observar a taxa de transferência usual em seu sistema e, consequentemente, decidir 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 em Hubs de Eventos com logs de Métricas de Aplicativo como categoria selecionada e escolha Análise de Log como destino.

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

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

4. Vá para o espaço de trabalho do Log Analytics e consulte o nome da atividade correta (com base na (resource-governance-overview.md#throttling-policy---threshold-limits)) na tabela AzureDiagnostics . A consulta de exemplo a seguir é definida para controlar o valor limite para mensagens de entrada:

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

5. Selecione a seção Gráfico no espaço de trabalho do Log Analytics e plote 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 cruzou mais de 550 mensagens (taxa de transferência atual esperada). Essa observação ajuda a definir o valor limite real.

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

Publicar ou consumir eventos

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

Nota

Quando seus aplicativos cliente são limitados, você deve experimentar uma lentidão na publicação ou consumo de dados.

Validar a limitação com grupos de aplicativos

Semelhante a Decidir limites de limite para políticas de limitação, você pode usar logs de métricas de aplicativos 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 de tempo. 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 do consumidor no hub de eventos ( OutgoingMessages ou OutgoingBytes). Quando as solicitações são limitadas no lado do consumidor, você observaria uma taxa de transferência de saída lenta.

Próximos passos

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