使用應用程式群組控管用戶端應用程式的資源

發行項
03/22/2024

Azure 事件中樞可讓您使用應用程式群組，針對連線到事件中樞的用戶端應用程式，控管事件串流工作負載。如需詳細資訊，請參閱使用應用程式群組的資源控管。

本文章將說明如何執行下列工作：

建立應用程式群組。
啟用或停用應用程式群組
定義閾值限制，並將節流原則套用至應用程式群組
使用診斷記錄驗證節流

注意

應用程式群組僅適用於進階和專用層。

建立應用程式群組

本節說明如何使用 Azure 入口網站、CLI、PowerShell 和 Azure Resource Manager (ARM) 範本來建立應用程式群組。

您可以遵循下列步驟，使用 Azure 入口網站來建立應用程式群組。

瀏覽至事件中樞命名空間。
在左側功能表上，選取 [設定] 底下的 [應用程式群組]。
在 [應用程式群組] 頁面上，選取命令列上的 [+應用程式群組]。
在 [新增應用程式群組] 頁面上，按照下列步驟：
1. 指定應用程式群組的 [名稱]
2. 確認已選取 [啟用]。若要先讓應用程式群組處於停用狀態，請清除 [已啟用] 選項。該旗標可決定應用程式群組的用戶端是否可以存取事件中樞。
3. 針對 [安全性內容類型]，選取 [命名空間共用存取原則]、[事件中樞共用存取原則] 或 [Microsoft Entra 應用程式]。應用程式群組支援在命名空間或實體 (事件中樞) 層級選取 SAS 金鑰。建立應用程式群組時，應該為群組與用戶端應用程式所使用的共用存取簽章 (SAS) 或 Microsoft Entra 應用程式識別碼建立關聯。
4. 如果您選取 [命名空間共用存取原則]：
  1. 針對 SAS 金鑰名稱，選取可用來作為此應用程式群組安全性內容的 SAS 原則。您可以選取 [新增 SAS 原則] 來新增原則，然後與應用程式群組產生關聯。
5. 如果您選取 [事件中樞共用存取原則]：
  1. 針對 [SAS 金鑰名稱]，從事件中樞的 [共用存取原則] 頁面複製 SAS 原則名稱，然後貼到文字方塊中
6. 如果您選取 [Microsoft Entra 應用程式]：
  1. 針對 [Microsoft Entra 應用程式 (用戶端) 識別碼]，指定 Microsoft Entra 應用程式或用戶端識別碼。

支援的安全性內容類型

檢閱自動產生的用戶端群組識別碼，這是與應用程式群組相關聯的唯一識別碼。應用程式控管的範圍 (命名空間或實體層級) 取決於所使用 Microsoft Entra 應用程式識別碼的存取層級。下表顯示針對不同安全性內容類型自動產生的用戶端群組識別碼：

安全性內容類型	自動產生的用戶端群組識別碼
命名空間共用存取金鑰	`NamespaceSASKeyName=<NamespaceLevelKeyName>`
Microsoft Entra 應用程式	`AADAppID=<AppID>`
事件中樞共用存取金鑰	`EntitySASKeyName=<EntityLevelKeyName>`

注意

所有以命名空間共用存取金鑰建立的現有應用程式群組，皆會繼續使用開頭為 SASKeyName 的用戶端群組識別碼。不過，所有新的應用程式群組都會更新用戶端群組識別碼 (如上所示)。

若要新增原則，請遵循下列步驟：
1. 輸入原則的名稱。
2. 選取 [類型] 的 [節流原則]。
3. 針對 [計量識別碼]，選取下列其中一個選項：[傳入訊息]、[傳出訊息]、[傳入位元組]、[傳出位元組]。在下列範例中，已經選取 [傳入訊息]。
4. 輸入 [速率限制閾值] 的閾值。在下列範例中，10000 將受指定為傳入訊息數目的閾值。
  
  以下頁面的螢幕擷取畫面中，已經新增了另一項原則。
現在，在 [新增應用程式群組] 頁面上，選取 [新增]。
確認您在應用程式群組清單中有看到應用程式群組。

您可以選取清單旁的垃圾桶圖示按鈕，以此刪除清單中的應用程式群組。

使用 CLI 命令：az eventhubs namespace application-group create，以此在事件中樞命名空間或事件中樞層級建立應用程式群組。您必須根據您選擇的安全性內容類型來設定 --client-app-group-identifier。請檢閱上表以了解支援的安全性內容類型

下列範例會在 Azure 資源群組MyResourceGroup 的命名空間 mynamespace 中建立名為 myAppGroup 的應用程式群組。其會使用下列組態。

共用存取原則會用來作為安全性內容
用戶端應用程式群組識別碼會設定為 NamespaceSASKeyName=<NameOfTheSASkey>。
Incoming messages 計量的第一項節流原則，其閾值為 10000。
Incoming bytes 計量的第二項節流原則，其閾值為 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

若要深入了解 CLI 命令，請參閱 az eventhubs namespace application-group create。

使用 PowerShell 命令：New-AzEventHubApplicationGroup，以此在事件中樞命名空間或事件中樞層級建立應用程式群組。您必須根據您選擇的安全性內容類型來設定 -ClientAppGroupIdentifier。請檢閱上表以了解支援的安全性內容類型

下列範例會使用 New-AzEventHubThrottlingPolicyConfig 來建立與應用程式相關聯的兩個原則。

Incoming bytes 計量的第一項節流原則，其閾值為 12345。
Incoming messages 計量的第二項節流原則，其閾值為 23416。

然後，其會將節流原則和共用存取原則指定為安全性內容，以此在 Azure 資源群組 myresourcegroup 的命名空間 mynamespace 中建立名為 myappgroup 的應用程式群組。

$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

若要深入了解 PowerShell 命令，請參閱 New-AzEventHubApplicationGroup。

下列範例示範如何使用 ARM 範本建立應用程式群組。在此範例中，應用程式群組會藉由將用戶端 AppGroupIdentifier 設定為 NamespaceSASKeyName=contososaspolicy，與現有的 SAS 原則名稱 contososaspolicy 建立關聯。應用程式群組原則也定義於 ARM 範本中。您必須根據您選擇的安全性內容類型來設定 ClientAppGroupIdentifier。請檢閱上表以了解支援的安全性內容類型

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

啟用或停用應用程式群組

您可以停用包含這些應用程式的應用程式群組，以防止用戶端應用程式存取事件中樞命名空間。停用應用程式群組時，用戶端應用程式將無法發佈或取用資料。從該應用程式群組的用戶端應用程式建立的任何連線也會終止。

本節說明如何使用 Azure 入口網站、PowerShell、CLI 和 ARM 範本來啟用或停用應用程式群組。

在 [事件中樞命名空間] 頁面上，選取左側功能表上的 [應用程式群組]。
選取您要啟用或停用的應用程式群組。
在 [編輯應用程式群組] 頁面上，清除 [已啟用] 旁的核取方塊以停用應用程式群組，然後選取頁面底部的 [更新]。同樣地，選取核取方塊以啟用應用程式群組。

使用 az eventhubs namespace application-group update 命令，同時將 --is-enabled 設定 false，以此停用應用程式群組。同樣地，若要啟用應用程式群組，請將此屬性設定為 true，然後執行該命令。

下列範例命令會停用資源群組 myresourcegroup 中的事件中樞命名空間 mynamespace 中名為 myappgroup 的應用程式群組。

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

使用 Set-AzEventHubApplicationGroup 命令，同時將 -IsEnabled 設定為 false，以此停用應用程式群組。同樣地，若要啟用應用程式群組，請將此屬性設定為 true，然後執行該命令。

下列範例命令會停用資源群組 myresourcegroup 中的事件中樞命名空間 mynamespace 中名為 myappgroup 的應用程式群組。

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

下列 ARM 範本會示範如何更新現有命名空間 (contosonamespace)，以便藉由將屬性 isEnabled 設定為 false 來停用應用程式群組。該應用程式群組的識別碼為 SASKeyName=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": "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
			}
		]
      }
    }
  ]
}

套用節流原則

您可以在建立應用程式群組時新增零個或多個原則，或將這些原則新增至現有的應用程式群組。例如，您可以將與 IncomingMessages、IncomingBytes 或 OutgoingBytes 有關的節流原則新增至 contosoAppGroup。這些原則會套用至使用 SAS 原則 contososaspolicy 的用戶端應用程式所產生的事件串流工作負載。

若要了解如何在建立應用程式群組時新增原則，請參閱建立應用程式群組一節。

您也可以在建立應用程式群組之後新增原則。

在 [事件中樞命名空間] 頁面上，選取左側功能表上的 [應用程式群組]。
選取您要為哪一個應用程式群組新增、更新或刪除原則。
在 [編輯應用程式群組] 頁面上，您可以執行下列步驟：
1. 現有原則的更新設定 (包括閾值)
2. 新增原則

使用 az eventhubs namespace application-group policy add 將原則新增至現有的應用程式群組。

範例：

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

使用 Set-AzEventHubApplicationGroup 命令，同時將 -ThrottlingPolicyConfig 設定為適當的值。

範例：

$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

下列 ARM 範本會示範如何更新現有命名空間 (contosonamespace)，以便新增節流原則。該應用程式群組的識別碼為 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
			}
		]
      }
    }
  ]
}

決定節流原則的閾值

Azure 事件中樞支援應用程式計量記錄功能，可觀察您系統中的一般輸送量，並以此決定應用程式群組的閾值。您可以按照下列步驟來決定閾值：

在事件中樞開啟診斷設定，並選擇 [應用程式計量記錄] 作為選取的類別，然後選擇 [Log Analytics ] 作為目的地。
建立不含任何節流原則的空白應用程式群組。
繼續以一般輸送量將訊息/事件傳送至事件中樞。
移至 [Log Analytics 工作區]，並根據 (resource-governance-overview.md#throttling-policy---threshold-limits) 在 [AzureDiagnostics] 資料表中查詢正確的活動名稱。下列查詢範例的設定是追蹤傳入訊息的閾值：
```
AzureDiagnostics 
    | where ActivityName_s =="IncomingMessages" 
    | where Outcome_s =="Success"      
```
選取 [Log Analytics 工作區] 上的 [圖表 ] 區段，並在 Y 軸上產生的時間與 X 軸上的已傳送訊息數目之間繪製圖表。

在此範例中，您可以看到一般輸送量一律不超過 550 則訊息 (預期的目前輸送量)。此觀察結果可協助您定義實際的閾值。
決定閾值之後，請在應用程式群組內新增節流原則。

發佈或取用事件

將節流原則成功新增至應用程式群組之後，您可以使用 contosoAppGroup 應用程式群組的成員用戶端應用程式來發佈或取用事件，以測試節流行為。若要進行測試，您可以使用 AMQP 用戶端或 Kafka 用戶端應用程式，以及用來建立應用程式群組的相同 SAS 原則名稱或 Microsoft Entra 應用程式識別碼。

注意

當用戶端應用程式受到節流時，您應該會在發佈或取用資料時遇到速度緩慢的情況。

使用應用程式群組驗證節流

類似於決定節流原則的閾值限制，您可以使用應用程式計量記錄來驗證節流和尋找更多詳細資料。

您可以使用下列範例查詢來找出特定時間範圍內的所有節流要求。您必須更新 ActivityName，以符合您預期要節流的作業。


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

由於通訊協定層級的限制，不會針對事件中樞 (OutgoingMessages 或 OutgoingBytes) 內的取用者作業產生節流要求記錄。要求在取用者端進行節流時，您會觀察到輸出輸送量的速度緩慢。

下一步

如需應用程式群組的概念資訊，請參閱使用應用程式群組的資源控管。
請參閱事件中樞的 Azure PowerShell 參考
請參閱事件中樞的 Azure CLI 參考

共用方式為