使用 PowerShell 管理 Application Insights 資源

發行項
10/15/2024

注意

建議您使用 Azure Az PowerShell 模組來與 Azure 互動。若要開始使用，請參閱安裝 Azure PowerShell (部分機器翻譯)。若要了解如何移轉至 Az PowerShell 模組，請參閱將 Azure PowerShell 從 AzureRM 移轉至 Az。

本文說明如何使用 Azure Resource Manager，自動將 Application Insights 資源的建立和更新自動化。例如，您可能建置程序中這麼做。除了基本的 Application Insights 資源外，您可以建立可用性 Web 測試、設定警示、設定價格配置和建立其他 Azure 資源。

建立這些資源的關鍵是 Resource Manager 適用的 JSON 範本。基本程序如下：

下載現有資源的 JSON 定義。
參數化某些值 (例如名稱)。
每當想要建立新的資源時再執行範本。

您可以一起封裝幾項資源一次全部建立。例如一個包含可用性測試、警示和連續匯出儲存體的應用程式監視器。有些參數化有一些微妙之處，我們會在這裡加以說明。

單次設定

如果您未曾將 PowerShell 與 Azure 訂用帳戶搭配使用，請在您要執行指令碼的電腦上安裝 Azure Powershell 模組：

安裝 Microsoft Web Platform Installer (v5 或更高版本)。
用來安裝 Azure PowerShell。

除了使用 Azure Resource Manager 範本 (ARM 範本) 以外，還有一組豐富的 Application Insights PowerShell Cmdlet。這些 Cmdlet 可供以程式設計方式輕鬆設定 Application Insights 資源。您可以使用 Cmdlet 啟用的功能：

建立和刪除 Application Insights 資源。
取得 Application Insights 資源及其屬性的清單。
建立和管理連續匯出。
建立和管理應用程式金鑰。
設定每日上限。
設定定價方案。

使用 PowerShell Cmdlet 建立 Application Insights 資源

以下說明如何使用 New-AzApplicationInsights Cmdlet 在 Azure 美國東部資料中心建立新的 Application Insights 資源：

New-AzApplicationInsights -ResourceGroupName <resource group> -Name <resource name> -location eastus

使用 ARM 範本建立 Application Insights 資源

以下說明如何使用 ARM 範本建立新的 Application Insights 資源。

建立 ARM 範本

建立新的 .json 檔案。在此範例中稱為 template1.json。將此內容複製到其中：

    {
        "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
        "contentVersion": "1.0.0.0",
        "parameters": {
            "appName": {
                "type": "string",
                "metadata": {
                    "description": "Enter the name of your Application Insights resource."
                }
            },
            "appType": {
                "type": "string",
                "defaultValue": "web",
                "allowedValues": [
                    "web",
                    "java",
                    "other"
                ],
                "metadata": {
                    "description": "Enter the type of the monitored application."
                }
            },
            "appLocation": {
                "type": "string",
                "defaultValue": "eastus",
                "metadata": {
                    "description": "Enter the location of your Application Insights resource."
                }
            },
            "retentionInDays": {
                "type": "int",
                "defaultValue": 90,
                "allowedValues": [
                    30,
                    60,
                    90,
                    120,
                    180,
                    270,
                    365,
                    550,
                    730
                ],
                "metadata": {
                    "description": "Data retention in days"
                }
            },
            "ImmediatePurgeDataOn30Days": {
                "type": "bool",
                "defaultValue": false,
                "metadata": {
                    "description": "If set to true when changing retention to 30 days, older data will be immediately deleted. Use this with extreme caution. This only applies when retention is being set to 30 days."
                }
            },
            "priceCode": {
                "type": "int",
                "defaultValue": 1,
                "allowedValues": [
                    1,
                    2
                ],
                "metadata": {
                    "description": "Pricing plan: 1 = Per GB (or legacy Basic plan), 2 = Per Node (legacy Enterprise plan)"
                }
            },
            "dailyQuota": {
                "type": "int",
                "defaultValue": 100,
                "minValue": 1,
                "metadata": {
                    "description": "Enter daily quota in GB."
                }
            },
            "dailyQuotaResetTime": {
                "type": "int",
                "defaultValue": 0,
                "metadata": {
                    "description": "Enter daily quota reset hour in UTC (0 to 23). Values outside the range will get a random reset hour."
                }
            },
            "warningThreshold": {
                "type": "int",
                "defaultValue": 90,
                "minValue": 1,
                "maxValue": 100,
                "metadata": {
                    "description": "Enter the % value of daily quota after which warning mail to be sent. "
                }
            }
        },
        "variables": {
            "priceArray": [
                "Basic",
                "Application Insights Enterprise"
            ],
            "pricePlan": "[take(variables('priceArray'),parameters('priceCode'))]",
            "billingplan": "[concat(parameters('appName'),'/', variables('pricePlan')[0])]"
        },
        "resources": [
            {
                "type": "microsoft.insights/components",
                "kind": "[parameters('appType')]",
                "name": "[parameters('appName')]",
                "apiVersion": "2014-04-01",
                "location": "[parameters('appLocation')]",
                "tags": {},
                "properties": {
                    "ApplicationId": "[parameters('appName')]",
                    "retentionInDays": "[parameters('retentionInDays')]",
                    "ImmediatePurgeDataOn30Days": "[parameters('ImmediatePurgeDataOn30Days')]"
                },
                "dependsOn": []
            },
            {
                "name": "[variables('billingplan')]",
                "type": "microsoft.insights/components/CurrentBillingFeatures",
                "location": "[parameters('appLocation')]",
                "apiVersion": "2015-05-01",
                "dependsOn": [
                    "[resourceId('microsoft.insights/components', parameters('appName'))]"
                ],
                "properties": {
                    "CurrentBillingFeatures": "[variables('pricePlan')]",
                    "DataVolumeCap": {
                        "Cap": "[parameters('dailyQuota')]",
                        "WarningThreshold": "[parameters('warningThreshold')]",
                        "ResetTime": "[parameters('dailyQuotaResetTime')]"
                    }
                }
            }
        ]
    }

使用 ARM 範本建立新的 Application Insights 資源

在 PowerShell 中，使用 $Connect-AzAccount 登入至 Azure。
使用 Set-AzContext "<subscription ID>" 將內容設定至訂用帳戶。
執行新部署來建立新的 Application Insights 資源：
```
    New-AzResourceGroupDeployment -ResourceGroupName Fabrikam `
           -TemplateFile .\template1.json `
           -appName myNewApp
```
- -ResourceGroupName 是您要在其中建立新資源的群組。
- -TemplateFile 必須出現在自訂參數之前。
- -appName 是要建立的資源名稱。

您可以新增其他參數。您可以在樣本的參數區段中找到其描述。

取得檢測金鑰

建立應用程式資源之後，您會想要檢測金鑰：

使用 $Connect-AzAccount 登入 Azure。
使用 Set-AzContext "<subscription ID>" 將內容設定至訂用帳戶。
然後使用︰
1. $resource = Get-AzResource -Name "<resource name>" -ResourceType "Microsoft.Insights/components"
2. $details = Get-AzResource -ResourceId $resource.ResourceId
3. $details.Properties.InstrumentationKey

若要查看 Application Insights 資源其他許多屬性的清單，請使用：

Get-AzApplicationInsights -ResourceGroupName Fabrikam -Name FabrikamProd | Format-List

您可透過下列 Cmdlet 取得更多屬性：

Set-AzApplicationInsightsDailyCap
Set-AzApplicationInsightsPricingPlan
Get-AzApplicationInsightsApiKey
Get-AzApplicationInsightsContinuousExport

如需這些 Cmdlet 的參數，請參閱詳細文件。

注意

針對檢測金鑰擷取的支援將在 2025 年 3 月 31 日結束。檢測金鑰擷取將會繼續運作，但我們不再提供該功能的更新或支援。轉換至連接字串以利用新功能。

設定資料保留

可以使用下列三種方法透過程式設計方式設定 Application Insights 資源的資料保留。

使用 PowerShell 命令設定資料保留

以下是可用來設定 Application Insights 資源資料保留的一組簡單 PowerShell 命令：

$Resource = Get-AzResource -ResourceType Microsoft.Insights/components -ResourceGroupName MyResourceGroupName -ResourceName MyResourceName
$Resource.Properties.RetentionInDays = 365
$Resource | Set-AzResource -Force

使用 REST 設定資料保留

若要取得 Application Insights 資源目前的資料保留，您可使用 OSS 工具 ARMClient。請透過 David Ebbo 和 Daniel Bowbyes 的文章來深入了解 ARMClient。以下是使用 ARMClient 取得目前保留的範例：

armclient GET /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName?api-version=2018-05-01-preview

若要設定保留，該命令是類似的 PUT：

armclient PUT /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName?api-version=2018-05-01-preview "{location: 'eastus', properties: {'retentionInDays': 365}}"

若要使用上述範本將資料保留設為 365 天，請執行：

New-AzResourceGroupDeployment -ResourceGroupName "<resource group>" `
       -TemplateFile .\template1.json `
       -retentionInDays 365 `
       -appName myApp

使用 PowerShell 指令碼來設定資料保留

下列指令碼也可用來變更保留。複製此指令碼以另存新檔為 Set-ApplicationInsightsRetention.ps1。

Param(
    [Parameter(Mandatory = $True)]
    [string]$SubscriptionId,

    [Parameter(Mandatory = $True)]
    [string]$ResourceGroupName,

    [Parameter(Mandatory = $True)]
    [string]$Name,

    [Parameter(Mandatory = $True)]
    [string]$RetentionInDays
)
$ErrorActionPreference = 'Stop'
if (-not (Get-Module Az.Accounts)) {
    Import-Module Az.Accounts
}
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
if (-not $azProfile.Accounts.Count) {
    Write-Error "Ensure you have logged in before calling this function."    
}
$currentAzureContext = Get-AzContext
$profileClient = New-Object Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient($azProfile)
$token = $profileClient.AcquireAccessToken($currentAzureContext.Tenant.TenantId)
$UserToken = $token.AccessToken
$RequestUri = "https://management.azure.com/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.Insights/components/$($Name)?api-version=2015-05-01"
$Headers = @{
    "Authorization"         = "Bearer $UserToken"
    "x-ms-client-tenant-id" = $currentAzureContext.Tenant.TenantId
}
## Get Component object via ARM
$GetResponse = Invoke-RestMethod -Method "GET" -Uri $RequestUri -Headers $Headers 

## Update RetentionInDays property
if($($GetResponse.properties | Get-Member "RetentionInDays"))
{
    $GetResponse.properties.RetentionInDays = $RetentionInDays
}
else
{
    $GetResponse.properties | Add-Member -Type NoteProperty -Name "RetentionInDays" -Value $RetentionInDays
}
## Upsert Component object via ARM
$PutResponse = Invoke-RestMethod -Method "PUT" -Uri "$($RequestUri)" -Headers $Headers -Body $($GetResponse | ConvertTo-Json) -ContentType "application/json"
$PutResponse

然後，此指令碼可用為：

Set-ApplicationInsightsRetention `
        [-SubscriptionId] <String> `
        [-ResourceGroupName] <String> `
        [-Name] <String> `
        [-RetentionInDays <Int>]

設定每日上限

若要取得每日上限屬性，請使用 Set-AzApplicationInsightsPricingPlan Cmdlet：

Set-AzApplicationInsightsDailyCap -ResourceGroupName <resource group> -Name <resource name> | Format-List

若要設定每日上限屬性，請使用相同的 Cmdlet。例如，若要將上限設為每天 300 GB：

Set-AzApplicationInsightsDailyCap -ResourceGroupName <resource group> -Name <resource name> -DailyCapGB 300

您也可以使用 ARMClient 以取得及設定每日上限參數。若要取得目前的值，請使用：

armclient GET /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName/CurrentBillingFeatures?api-version=2018-05-01-preview

設定每日上限重設時間

重要

您無法再使用 ResetTime 屬性來自定義每日上限重設時間。

設定定價方案

若要取得目前的定價方案，請使用 Set-AzApplicationInsightsPricingPlan Cmdlet：

Set-AzApplicationInsightsPricingPlan -ResourceGroupName <resource group> -Name <resource name> | Format-List

若要設定定價方案，請使用相同的 Cmdlet 並指定 -PricingPlan：

Set-AzApplicationInsightsPricingPlan -ResourceGroupName <resource group> -Name <resource name> -PricingPlan Basic

您也可以使用上述 ARM 範本，在現有的 Application Insights 資源上設定定價方案，從計費資源省略 "microsoft.insights/components" 資源和 dependsOn 節點。例如，若要將其設為每 GB 方案 (先前稱為基本方案)，請執行：

        New-AzResourceGroupDeployment -ResourceGroupName "<resource group>" `
               -TemplateFile .\template1.json `
               -priceCode 1 `
               -appName myApp

priceCode 定義為：

priceCode	計畫
1	每 GB (先前名為基本方案)
2	每節點 (先前名為企業方案)

最後，您可使用 ARMClient 來取得及設定定價方案與每日上限參數。若要取得目前的值，請使用：

armclient GET /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName/CurrentBillingFeatures?api-version=2018-05-01-preview

您可使用下列項目設定這些參數：

armclient PUT /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName/CurrentBillingFeatures?api-version=2018-05-01-preview
"{'CurrentBillingFeatures':['Basic'],'DataVolumeCap':{'Cap':200,'ResetTime':12,'StopSendNotificationWhenHitCap':true,'WarningThreshold':90,'StopSendNotificationWhenHitThreshold':true}}"

此程式代碼會將每日上限設定為每天 200 GB、將每日上限重設時間設定為 12：00 UTC、在達到上限時傳送電子郵件，並將警告閾值設定為上限的 90%。

新增度量警示

若要自動建立計量警示，請參閱計量警示範本文章。

新增可用性測試

若要將可用性測試自動化，請參閱計量警示範本文章。

新增其他資源

若要自動建立任何類型的其他任何資源，手動建立範例，然後從 Azure Resource Manager 複製並參數化其程式碼。

開啟 Azure 資源管理員。向下導覽 subscriptions/resourceGroups/<your resource group>/providers/Microsoft.Insights/components 直到應用程式資源。

元件是用來顯示應用程式的基本 Application Insights 資源。相關聯的警示規則和可用性 Web 測試有個別的資源。
將元件的 JSON 複製到 template1.json的適當位置。
刪除這些屬性：
- id
- InstrumentationKey
- CreationDate
- TenantId
開啟 webtests 和 alertrules 區段，並將個別項目的 JSON 複製到範本。請勿從 webtests 或 alertrules 節點複製。移到其下的項目。

每個 Web 測試都有一個關聯的警示規則，您必須同時複製這兩者。
在每個資源中插入下面這行：

"apiVersion": "2015-05-01",

參數化範本

現在您必須以參數取代特定的名稱。若要參數化範本，您要使用一組協助程式函式撰寫表示式。

您無法將參數化字串的一部分，因此請使用 concat() 建置字串。

以下是您想要進行之替代的範例。每個替換各出現數次。您的範本中可能需要其他替換。這些範例使用我們在範本頂端定義的參數和變數。

Find	Replace with
`"hidden-link:/subscriptions/.../../components/MyAppName"`	`"[concat('hidden-link:',` `resourceId('microsoft.insights/components',` `parameters('appName')))]"`
`"/subscriptions/.../../alertrules/myAlertName-myAppName-subsId",`	`"[resourceId('Microsoft.Insights/alertrules', variables('alertRuleName'))]",`
`"/subscriptions/.../../webtests/myTestName-myAppName",`	`"[resourceId('Microsoft.Insights/webtests', parameters('webTestName'))]",`
`"myWebTest-myAppName"`	`"[variables(testName)]"'`
`"myTestName-myAppName-subsId"`	`"[variables('alertRuleName')]"`
`"myAppName"`	`"[parameters('appName')]"`
`"myappname"` (小寫)	`"[toLower(parameters('appName'))]"`
`"<WebTest Name=\"myWebTest\" ...` `Url=\"http://fabrikam.com/home\" ...>"`	`[concat('<WebTest Name=\"',` `parameters('webTestName'),` `'\" ... Url=\"', parameters('Url'),` `'\"...>')]"`

設定資源間的相依性

Azure 應以嚴格的順序設定資源。為確保一項設定完成後再開始下一項設定，請加入相依性命令行：

在可用性測試資源中︰

"dependsOn": ["[resourceId('Microsoft.Insights/components', parameters('appName'))]"],
可用性測試的警示資源中︰

"dependsOn": ["[resourceId('Microsoft.Insights/webtests', variables('testName'))]"],

下一步

請參閱下列其他自動化文章：

共用方式為