Régir les ressources pour les applications clientes avec des groupes d’applications

Azure Event Hubs vous permet de régir les charges de travail de streaming d’événements pour les applications clientes qui se connectent à Event Hubs à l’aide de groupes d’applications. Pour plus d’informations, consultez Gouvernance des ressources avec des groupes d’applications.

Cet article explique comment exécuter les tâches suivantes :

• Créer un groupe d’applications.
• Activer ou désactiver un groupe d’applications
• Définir des limites de seuil et appliquer des stratégies de limitation à un groupe d’applications
• Valider la limitation avec les journaux de diagnostic

Notes

Les groupes d’applications sont actuellement disponibles uniquement avec les niveaux Premium et Dédié.

Créer un groupe d’applications

Cette section vous montre comment créer un groupe d’applications en utilisant le portail Azure, CLI, PowerShell et un modèle ARM (Azure Resource Manager).

Azure portal

Vous pouvez créer un groupe d’applications avec le portail Azure en effectuant ces étapes.

1. Accédez à votre espace de noms Event Hubs.

2. Dans le menu de gauche, sélectionnez Groupes d’applications sous Paramètres.

3. Dans la page Groupes d’applications, sélectionnez + Groupe d’applications dans la barre de commandes.

   

4. Dans la page Ajouter un groupe d’applications, effectuez les étapes suivantes :

   1. Attribuez un nom au groupe d’applications.

   2. Vérifiez que l’option Activé est sélectionnée. Pour que le groupe d’applications soit d’abord à l’état désactivé, désélectionnez l’option Activé. Cet indicateur détermine si les clients d’un groupe d’applications peuvent ou non accéder à Event Hubs.

   3. Pour Type de contexte de sécurité, sélectionnez Stratégie d’accès partagé d’espace de noms, Stratégie d’accès partagé de hub d’événements ou Application Microsoft Entra. Le groupe d’applications prend en charge la sélection de la clé SAS au niveau de l’espace de noms ou de l’entité (hub d’événements). Quand vous créez le groupe d’applications, vous devez l’associer à une signature d’accès partagé (SAS) ou à un ID d’application Microsoft Entra ID, qui est utilisé par les applications clientes.

   4. Si vous avez sélectionné Stratégie d’accès partagé de l’espace de noms :

      1. Pour le nom de clé SAP, sélectionnez la stratégie SAP qui peut être utilisée comme contexte de sécurité pour ce groupe d’applications. Vous pouvez sélectionner Ajouter une stratégie SAP pour ajouter une nouvelle stratégie, puis l’associer au groupe d’applications.

         

   5. Si vous avez sélectionné Stratégie d’accès partagé Event Hubs :

      1. Pour Nom de la clé SAP, copiez le nom de la stratégie SAP à partir de la page « Stratégies d’accès partagé » d’Event Hubs et collez-le dans la zone de texte

         

   6. Si vous avez sélectionné Application Microsoft Entra :

      1. Pour ID d’application Microsoft Entra (client), spécifiez l’ID d’application Microsoft Entra ou l’ID client.

      

Type de contexte de sécurité pris en charge

Vérifiez l’ID de groupe de clients généré automatiquement. Il s’agit d’un ID unique associé au groupe d’applications. L’étendue de la gouvernance des applications (au niveau de l’espace de noms ou de l’entité) dépend du niveau d’accès de l’ID d’application Microsoft Entra utilisé. Le tableau suivant montre l’ID de groupe de clients généré automatiquement pour différents types de contexte de sécurité :

Type de contexte de sécurité	ID de groupe de clients généré automatiquement
Clé d’accès partagé d’un espace de noms	NamespaceSASKeyName=<NamespaceLevelKeyName>
Application Microsoft Entra	AADAppID=<AppID>
Clé d’accès partagé Event Hubs	EntitySASKeyName=<EntityLevelKeyName>

Notes

Tous les groupes d’applications existants créés avec la clé d’accès partagé de l’espace de noms continuent de fonctionner avec l’ID de groupe de clients à partir de SASKeyName. Cependant, tous les nouveaux groupes d’applications auront un ID de groupe de clients mis à jour, comme indiqué ci-dessus.

1. Pour ajouter une stratégie, effectuez les étapes suivantes :

   1. Attribuez un nom à la stratégie.

   2. Pour Type, sélectionnez Stratégie de limitation.

   3. Pour ID de métrique, sélectionnez l’une des options suivantes : Messages entrants, Messages sortants, Octets entrants, Octets sortants. Dans l’exemple suivant, Messages entrants est sélectionné.

   4. Pour Seuil limite du débit, entrez la valeur de seuil. Dans l’exemple suivant, le seuil spécifié pour le nombre de messages entrants est 10000.

      

      Voici une capture d’écran de la page avec une autre stratégie ajoutée.

      

2. À présent, dans la page Ajouter un groupe d’applications, sélectionnez Ajouter.

3. Vérifiez que vous voyez le groupe d’applications dans la liste des groupes.

   

   Pour supprimer le groupe d’applications dans la liste, sélectionnez l’icône de la corbeille à côté du groupe dans la liste.

Azure CLI

Utilisez la commande CLI az eventhubs namespace application-group create pour créer un groupe d’applications dans un espace de noms Event Hubs ou un niveau de hub d’événements. Vous devez définir --client-app-group-identifier en fonction du type de contexte de sécurité que vous choisissez. Consultez le tableau ci-dessus pour connaître le type de contexte de sécurité pris en charge

L’exemple suivant crée un groupe d’applications nommé myAppGroup dans l’espace de noms mynamespace du groupe de ressources Azure MyResourceGroup. Il utilise les configurations suivantes.

• La stratégie d’accès partagé est utilisée comme contexte de sécurité
• L’ID du groupe d’applications client est défini sur NamespaceSASKeyName=<NameOfTheSASkey>.
• Première stratégie de limitation pour la métrique Incoming messages avec 10000 comme seuil.
• Deuxième stratégie de limitation pour la métrique Incoming bytes avec 20000 comme seuil.

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

Pour en savoir plus sur la commande CLI, consultez az eventhubs namespace application-group create.

Azure PowerShell

Utilisez la commande PowerShell New-AzEventHubApplicationGroup pour créer un groupe d’applications dans un espace de noms Event Hubs. Vous devez définir -ClientAppGroupIdentifier en fonction du type de contexte de sécurité que vous choisissez. Consultez le tableau ci-dessus pour connaître le type de contexte de sécurité pris en charge

L’exemple suivant utilise New-AzEventHubThrottlingPolicyConfig pour créer deux stratégies qui seront associées à l’application.

• Première stratégie de limitation pour la métrique Incoming bytes avec 12345 comme seuil.
• Deuxième stratégie de limitation pour la métrique Incoming messages avec 23416 comme seuil.

Ensuite, il crée un groupe d’applications nommé myappgroup dans l’espace de noms mynamespace dans le groupe de ressources Azure myresourcegroup en spécifiant les stratégies de limitation et la stratégie d’accès partagé comme contexte de sécurité.

$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

Pour en savoir plus sur la commande PowerShell, consultez New-AzEventHubApplicationGroup.

Modèle ARM

L’exemple suivant montre comment créer un groupe d’applications à l’aide d’un modèle ARM. Dans cet exemple, le groupe d’applications est associé à un nom de stratégie SAS existant contososaspolicy en définissant le client AppGroupIdentifier comme NamespaceSASKeyName=contososaspolicy. Les stratégies de groupe d’applications sont également définies dans le modèle ARM. Vous devez définir ClientAppGroupIdentifier en fonction du type de contexte de sécurité que vous choisissez. Consultez le tableau ci-dessus pour connaître le type de contexte de sécurité pris en charge

{
	"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
	}
}

Activer ou désactiver un groupe d’applications

Vous pouvez empêcher les applications clientes d’accéder à votre espace de noms Event Hubs en désactivant le groupe d’applications qui contient ces applications. Quand le groupe d’applications est désactivé, les applications clientes ne peuvent pas publier ni consommer de données. Toutes les connexions établies à partir d’applications clientes de ce groupe d’applications sont également arrêtées.

Cette section vous montre comment activer ou désactiver un groupe d’applications avec le portail Azure, PowerShell, CLI et un modèle ARM.

Azure portal

1. Dans la page Espace de noms Event Hubs, sélectionnez Groupes d’applications dans le menu de gauche.

2. Sélectionnez le groupe d’applications que vous souhaitez activer ou désactiver.

   

3. Dans la page Modifier le groupe d’applications, décochez la case Activé pour désactiver un groupe d’applications, puis sélectionnez Mettre à jour en bas de la page. De même, cochez la case pour activer un groupe d’applications.

   

Azure CLI

Utilisez la commande az eventhubs namespace application-group update avec --is-enabled défini sur false pour désactiver un groupe d’applications. De même, pour activer un groupe d’applications, définissez cette propriété sur true et exécutez la commande.

L’exemple de commande suivant désactive le groupe d’applications nommé myappgroup dans l’espace de noms Event Hubs mynamespace qui se trouve dans le groupe de ressources myresourcegroup.

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

Azure PowerShell

Utilisez la commande Set-AzEventHubApplicationGroup avec -IsEnabled défini sur false pour désactiver un groupe d’applications. De même, pour activer un groupe d’applications, définissez cette propriété sur true et exécutez la commande.

L’exemple de commande suivant désactive le groupe d’applications nommé myappgroup dans l’espace de noms Event Hubs mynamespace qui se trouve dans le groupe de ressources myresourcegroup.

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

Modèle ARM

Le modèle ARM suivant montre comment mettre à jour un espace de noms existant (contosonamespace) pour désactiver un groupe d’applications en définissant la propriété isEnabled sur false. L’identificateur du groupe d’applications est SASKeyName=RootManageSharedAccessKey.

Notes

L’exemple suivant ajoute également deux stratégies de limitation.

{
  "$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
			}
		]
      }
    }
  ]
}

Appliquer des stratégies de limitation

Vous pouvez ajouter zéro ou plusieurs stratégies quand vous créez un groupe d’applications ou pour un groupe d’applications existant. Vous pouvez par exemple ajouter des stratégies de limitation liées à IncomingMessages, IncomingBytes ou OutgoingBytes au contosoAppGroup. Ces stratégies s’appliquent aux charges de travail de streaming d’événements des applications clientes qui utilisent la stratégie SAS contososaspolicy.

Pour savoir comment ajouter des stratégies lors de la création d’un groupe d’applications, consultez la section Créer un groupe d’applications.

Vous pouvez également ajouter des stratégies après la création d’un groupe d’applications.

Azure portal

1. Dans la page Espace de noms Event Hubs, sélectionnez Groupes d’applications dans le menu de gauche.

2. Sélectionnez le groupe d’applications pour lequel vous souhaitez ajouter, mettre à jour ou supprimer une stratégie.

   

3. Dans la page Modifier le groupe d’applications, vous pouvez effectuer les étapes suivantes :

   1. Mettre à jour les paramètres (notamment les valeurs de seuil) pour les stratégies existantes
   2. Ajouter une nouvelle stratégie

Azure CLI

Utilisez az eventhubs namespace application-group policy add pour ajouter une stratégie à un groupe d’applications existant.

Exemple :

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

Utilisez la commande Set-AzEventHubApplicationGroup avec -ThrottingPolicyConfig défini sur les valeurs appropriées.

Exemple :

$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

Modèle ARM

Le modèle ARM suivant montre comment mettre à jour un espace de noms existant (contosonamespace) pour ajouter des stratégies de limitation. L’identificateur du groupe d’applications est 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
			}
		]
      }
    }
  ]
}

Décider de la valeur de seuil pour les stratégies de limitation

Azure Event Hubs prend en charge la fonctionnalité Journaux des métriques d’application pour observer le débit habituel au sein de votre système et décider en conséquence de la valeur de seuil pour le groupe d’applications. Vous pouvez suivre ces étapes pour décider d’une valeur de seuil :

1. Dans Event Hubs, activez l’option Paramètres de diagnostic en sélectionnant la catégorie Journaux de métriques d’application, puis choisissez Log Analytics comme destination.

2. Créez un groupe d’applications vide sans stratégie de limitation.

3. Continuez à envoyer des messages/événements au hub d’événements à la fréquence habituelle.

4. Accédez à l’espace de travail Log Analytics et recherchez le nom d’activité approprié (basé sur le (resource-governance-overview.md#throttling-policy---threshold-limits)) dans la table AzureDiagnostics. L’exemple de requête suivant est défini pour suivre la valeur de seuil pour les messages entrants :

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

5. Sélectionnez la section Graphique sur l’espace de travail Log Analytics, puis tracez un graphique avec l’heure de génération en ordonnée (axe Y) et le nombre de messages envoyés en abscisse (axe X).

   

   Dans cet exemple, vous pouvez voir que le débit habituel n’a jamais dépassé 550 messages (débit courant attendu). Cette observation vous aide à définir la valeur de seuil réelle.

6. Une fois que vous avez choisi la valeur de seuil, ajoutez une nouvelle stratégie de limitation au sein du groupe d’applications.

Publier ou consommer des événements

Une fois que vous avez ajouté des stratégies de limitation au groupe d’applications, vous pouvez tester le comportement de limitation en publiant ou en consommant des événements à l’aide d’applications clientes qui font partie du groupe d’applications contosoAppGroup. Pour les tests, vous pouvez utiliser une application cliente AMQP ou cliente Kafka, et le même nom de stratégie SAS ou ID d’application Microsoft Entra utilisé pour créer le groupe d’applications.

Remarque

Quand vos applications clientes sont limitées, vous devez rencontrer un problème de lenteur lors de la publication ou de la consommation de données.

Valider la limitation avec des groupes d’applications

Comme pour Choisir des limites de seuil pour les stratégies de limitation, vous pouvez utiliser les journaux des métriques d’application pour valider la limitation et obtenir plus d’informations.

Vous pouvez utiliser l’exemple de requête ci-dessous pour connaître toutes les requêtes limitées dans un certain délai. Vous devez mettre à jour ActivityName pour qu’il corresponde à l’opération que vous prévoyez de limiter.

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

En raison des restrictions au niveau du protocole, les journaux des requêtes limitées ne sont pas générés pour les opérations de consommateur au sein du hub d’événements (OutgoingMessages ou OutgoingBytes). Lorsque les requêtes sont limitées côté consommateur, vous observez un débit de sortie lent.

Étapes suivantes

• Pour plus d’informations conceptuelles sur les groupes d’applications, consultez Gouvernance des ressources avec des groupes d’applications.
• Consultez les informations de référence sur Azure PowerShell pour Event Hubs.
• Consultez les informations de référence sur Azure CLI pour Event Hubs.