Styra resurser för klientprogram med programgrupper

Artikel
10/18/2023

Med Azure Event Hubs kan du styra arbetsbelastningar för händelseströmning för klientprogram som ansluter till Event Hubs med hjälp av programgrupper. Mer information finns i Resursstyrning med programgrupper.

Den här artikeln visar hur man utför följande uppgifter:

Skapa en programgrupp.
Aktivera eller inaktivera en programgrupp
Definiera tröskelvärden och tillämpa begränsningsprinciper på en programgrupp
Verifiera begränsning med diagnostikloggar

Kommentar

Programgrupper är endast tillgängliga på premium - och dedikerade nivåer.

Skapa en programgrupp

Det här avsnittet visar hur du skapar en programgrupp med hjälp av mallen Azure Portal, CLI, PowerShell och Azure Resource Manager (ARM).

Du kan skapa en programgrupp med hjälp av Azure Portal genom att följa dessa steg.

Gå till Event Hubs-namnområdet.
På den vänstra menyn väljer du Programgrupper under Inställningar.
På sidan Programgrupper väljer du + Programgrupp i kommandofältet.
Följ dessa steg på sidan Lägg till programgrupp :
1. Ange ett namn för programgruppen.
2. Bekräfta att Aktiverad är markerat. Om du vill att programgruppen ska vara inaktiverad först avmarkerar du alternativet Aktiverad . Den här flaggan avgör om klienterna i en programgrupp kan komma åt Event Hubs eller inte.
3. Som Säkerhetskontexttyp väljer du Namnområdesprincip för delad åtkomst, princip för delad åtkomst för händelsehubb eller Microsoft Entra-program. Programgruppen stöder valet av SAS-nyckel på antingen namnrymd eller på entitetsnivå (händelsehubb). När du skapar programgruppen bör du associera med antingen en signatur för delad åtkomst (SAS) eller Microsoft Entra-program-ID som används av klientprogram.
4. Om du har valt namnområdesprincip för delad åtkomst:
  1. För SAS-nyckelnamn väljer du den SAS-princip som kan användas som säkerhetskontext för den här programgruppen. Du kan välja Lägg till SAS-princip för att lägga till en ny princip och sedan associera med programgruppen.
5. Om du har valt en princip för delad åtkomst i Event Hubs:
  1. För SAS-nyckelnamn kopierar du SAS-principnamnet från sidan Principer för delad åtkomst i Event Hubs och klistrar in i textrutan
6. Om du har valt Microsoft Entra-programmet:
  1. För Microsoft Entra-program-ID (klient)-ID anger du Microsoft Entra-programmet eller klient-ID:t.

Typ av säkerhetskontext som stöds

Granska det automatiskt genererade klientgrupps-ID :t, som är det unika ID som är associerat med programgruppen. Omfånget för programstyrning (namnområde eller entitetsnivå) beror på åtkomstnivån för det använda Microsoft Entra-program-ID:t. I följande tabell visas automatiskt genererat klientgrupps-ID för olika typer av säkerhetskontexter:

Typ av säkerhetskontext	Automatiskt genererat klientgrupps-ID
Nyckel för delad åtkomst för namnområde	`NamespaceSASKeyName=<NamespaceLevelKeyName>`
Microsoft Entra-program	`AADAppID=<AppID>`
Delad åtkomstnyckel för Event Hubs	`EntitySASKeyName=<EntityLevelKeyName>`

Kommentar

Alla befintliga programgrupper som skapats med den delade åtkomstnyckeln för namnområdet fortsätter att fungera med klientgrupps-ID som börjar med SASKeyName. Alla nya programgrupper skulle dock ha uppdaterat klientgrupps-ID enligt ovan.

Följ dessa steg för att lägga till en princip:
1. Ange ett namn för principen.
2. För Typ väljer du Begränsningsprincip.
3. För Mått-ID väljer du något av följande alternativ: Inkommande meddelanden, Utgående meddelanden, Inkommande byte, Utgående byte. I följande exempel är Inkommande meddelanden valt.
4. Ange tröskelvärdet för tröskelvärdet för Hastighetsgräns. I följande exempel anges 10000 som tröskelvärde för antalet inkommande meddelanden.
  
  Här är en skärmbild av sidan med en annan princip tillagd.
På sidan Lägg till programgrupp väljer du Lägg till.
Bekräfta att du ser programgruppen i listan över programgrupper.

Du kan ta bort programgruppen i listan genom att välja papperskorgsikonen bredvid den i listan.

Använd CLI-kommandot: az eventhubs namespace application-group create för att skapa en programgrupp på Event Hubs-namnrymd eller händelsehubbnivå. Du måste ange --client-app-group-identifier baserat på den typ av säkerhetskontext som du väljer. Granska tabellen ovan om du vill veta vilken typ av säkerhetskontext som stöds

I följande exempel skapas en programgrupp med namnet myAppGroup i namnområdet mynamespace i Azure-resursgruppen MyResourceGroup. Den använder följande konfigurationer.

Principen för delad åtkomst används som säkerhetskontext
Klientappens grupp-ID är inställt på NamespaceSASKeyName=<NameOfTheSASkey>.
Första begränsningsprincipen för måttet Incoming messages med 10000 som tröskelvärde.
Den andra begränsningsprincipen för måttet Incoming bytes med 20000 som tröskelvärde.

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

Mer information om CLI-kommandot az eventhubs namespace application-group createfinns i .

Använd PowerShell-kommandot: New-AzEventHubApplicationGroup för att skapa en programgrupp på Event Hubs-namnrymd eller händelsehubbnivå. Du måste ange -ClientAppGroupIdentifier baserat på den typ av säkerhetskontext som du väljer. Granska tabellen ovan om du vill veta vilken typ av säkerhetskontext som stöds

I följande exempel används New-AzEventHubThrottlingPolicyConfig för att skapa två principer som ska associeras med programmet.

Första begränsningsprincipen för måttet Incoming bytes med 12345 som tröskelvärde.
Den andra begränsningsprincipen för måttet Incoming messages med 23416 som tröskelvärde.

Sedan skapas en programgrupp med namnet myappgroup i namnområdet mynamespace i Azure-resursgruppen myresourcegroup genom att ange begränsningsprinciperna och principen för delad åtkomst som säkerhetskontext.

$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

Mer information om PowerShell-kommandot finns i New-AzEventHubApplicationGroup.

I följande exempel visas hur du skapar en programgrupp med hjälp av en ARM-mall. I det här exemplet associeras programgruppen med ett befintligt SAS-principnamn contososaspolicy genom att klienten AppGroupIdentifier anges som NamespaceSASKeyName=contososaspolicy. Programgruppsprinciperna definieras också i ARM-mallen. Du måste ange ClientAppGroupIdentifier baserat på den typ av säkerhetskontext som du väljer. Granska tabellen ovan om du vill veta vilken typ av säkerhetskontext som stöds

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

Aktivera eller inaktivera en programgrupp

Du kan förhindra att klientprogram kommer åt event hubs-namnområdet genom att inaktivera programgruppen som innehåller dessa program. När programgruppen är inaktiverad kan klientprogram inte publicera eller använda data. Alla etablerade anslutningar från klientprogram i den programgruppen avslutas också.

Det här avsnittet visar hur du aktiverar eller inaktiverar en programgrupp med hjälp av mallen Azure Portal, PowerShell, CLI och ARM.

På sidan Event Hubs-namnområde väljer du Programgrupper på den vänstra menyn.
Välj den programgrupp som du vill aktivera eller inaktivera.
På sidan Redigera programgrupp avmarkerar du kryssrutan bredvid Aktiverad för att inaktivera en programgrupp och väljer sedan Uppdatera längst ned på sidan. På samma sätt markerar du kryssrutan för att aktivera en programgrupp.

az eventhubs namespace application-group update Använd kommandot med --is-enabled inställt på för att false inaktivera en programgrupp. Om du vill aktivera en programgrupp anger du på samma sätt den här egenskapen till true och kör kommandot.

Följande exempelkommando inaktiverar programgruppen med namnet myappgroup i Event Hubs-namnområdet mynamespace som finns i resursgruppen myresourcegroup.

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

Använd kommandot Set-AzEventHubApplicationGroup med -IsEnabled inställt på för att false inaktivera en programgrupp. Om du vill aktivera en programgrupp anger du på samma sätt den här egenskapen till true och kör kommandot.

Följande exempelkommando inaktiverar programgruppen med namnet myappgroup i Event Hubs-namnområdet mynamespace som finns i resursgruppen myresourcegroup.

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

Följande ARM-mall visar hur du uppdaterar ett befintligt namnområde (contosonamespace) för att inaktivera en programgrupp genom att ange isEnabled egenskapen till false. Identifieraren för appgruppen är SASKeyName=RootManageSharedAccessKey.

Kommentar

Följande exempel lägger också till två begränsningsprinciper

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

Tillämpa begränsningsprinciper

Du kan lägga till noll eller fler principer när du skapar en programgrupp eller till en befintlig programgrupp. Du kan till exempel lägga till begränsningsprinciper relaterade till IncomingMessageseller IncomingBytes OutgoingBytes till contosoAppGroup. Dessa principer tillämpas på händelseströmningsarbetsbelastningar för klientprogram som använder SAS-principen contososaspolicy.

Mer information om hur du lägger till principer när du skapar en programgrupp finns i avsnittet Skapa en programgrupp .

Du kan också lägga till principer när en programgrupp har skapats.

På sidan Event Hubs-namnområde väljer du Programgrupper på den vänstra menyn.
Välj den programgrupp som du vill lägga till, uppdatera eller ta bort en princip.
På sidan Redigera programgrupp kan du göra följande:
1. Uppdatera inställningar (inklusive tröskelvärden) för befintliga principer
2. Lägga till en ny princip

az eventhubs namespace application-group policy add Använd för att lägga till en princip i en befintlig programgrupp.

Exempel:

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

Använd kommandot Set-AzEventHubApplicationGroup med -ThrottingPolicyConfig inställt på lämpliga värden.

Exempel:

$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

Följande ARM-mall visar hur du uppdaterar ett befintligt namnområde (contosonamespace) för att lägga till begränsningsprinciper. Identifieraren för appgruppen är 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
			}
		]
      }
    }
  ]
}

Bestämma tröskelvärde för begränsningsprinciper

Azure Event Hubs har stöd för funktioner för programmåttloggar för att observera vanligt dataflöde i systemet och därmed bestämma tröskelvärdet för programgruppen. Du kan följa de här stegen för att bestämma ett tröskelvärde:

Aktivera diagnostikinställningar i Event Hubs med Application Metric-loggar som vald kategori och välj Log Analytics som mål.
Skapa en tom programgrupp utan någon begränsningsprincip.
Fortsätt att skicka meddelanden/händelser till händelsehubben vid vanligt dataflöde.
Gå till Log Analytics-arbetsytan och fråga efter rätt aktivitetsnamn (baserat på tabellen (resource-governance-overview.md#throttling-policy---threshold-limits)) i AzureDiagnostics . Följande exempelfråga är inställd på att spåra tröskelvärdet för inkommande meddelanden:
```
AzureDiagnostics 
    | where ActivityName_s =="IncomingMessages" 
    | where Outcome_s =="Success"      
```
Välj avsnittet Diagram på Log Analytics-arbetsytan och rita ett diagram mellan tiden som genereras på Y-axeln och antalet meddelanden som skickas på x-axeln.

I det här exemplet kan du se att det vanliga dataflödet aldrig passerade fler än 550 meddelanden (förväntat aktuellt dataflöde). Den här observationen hjälper dig att definiera det faktiska tröskelvärdet.
När du har bestämt tröskelvärdet lägger du till en ny begränsningsprincip i programgruppen.

Publicera eller använda händelser

När du har lagt till begränsningsprinciper i programgruppen kan du testa begränsningsbeteendet genom att antingen publicera eller använda händelser med klientprogram som ingår i contosoAppGroup programgruppen. För att testa kan du använda antingen en AMQP-klient eller ett Kafka-klientprogram och samma SAS-principnamn eller Microsoft Entra-program-ID som används för att skapa programgruppen.

Kommentar

När dina klientprogram begränsas bör du uppleva en långsam publicering eller användning av data.

Verifiera begränsning med programgrupper

På samma sätt som när du bestämmer tröskelvärden för begränsningsprinciper kan du använda programmåttloggar för att verifiera begränsning och hitta mer information.

Du kan använda exempelfrågan nedan för att ta reda på alla begränsade begäranden inom en viss tidsram. Du måste uppdatera ActivityName så att det matchar den åtgärd som du förväntar dig ska begränsas.


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

På grund av begränsningar på protokollnivå genereras inte begränsade begärandeloggar för konsumentåtgärder i händelsehubben ( OutgoingMessages eller OutgoingBytes). När begäranden begränsas på konsumentsidan observerar du långsamt utgående dataflöde.

Nästa steg

Konceptuell information om programgrupper finns i Resursstyrning med programgrupper.
Se Azure PowerShell-referens för Event Hubs
Se Azure CLI-referens för Event Hubs

Dela via

Styra resurser för klientprogram med programgrupper

Skapa en programgrupp

Typ av säkerhetskontext som stöds

Aktivera eller inaktivera en programgrupp

Tillämpa begränsningsprinciper

Bestämma tröskelvärde för begränsningsprinciper

Publicera eller använda händelser

Verifiera begränsning med programgrupper

Nästa steg

Feedback

Ytterligare resurser