Verwalten von Application Insights-Ressourcen mithilfe von PowerShell

Dieser Artikel beschreibt, wie Sie die Erstellung und Aktualisierung von Application Insights-Ressourcen mit dem Azure Resource Manager automatisieren können. Dies kann z. B. als Teil eines Buildvorgangs erfolgen. Zusammen mit der grundlegenden Application Insights-Ressource können Sie Verfügbarkeitswebtests erstellen, Warnungen einrichten, das Preisschema festlegen und andere Azure-Ressourcen erstellen.

Im Wesentlichen werden diese Ressourcen mit JSON-Vorlagen für den Azure Resource Manager erstellt. Die grundlegende Prozedur lautet wie folgt:

• Laden Sie die JSON-Definitionen vorhandener Ressourcen herunter.
• Parametrisieren Sie bestimmte Werte, z. B. Namen.
• Führen Sie die Vorlage immer dann aus, wenn Sie eine neue Ressource erstellen möchten.

Sie können mehrere Ressourcen zusammen packen, um sie alle auf einmal zu erstellen. Sie können beispielsweise einen App-Monitor mit Verfügbarkeitstests, Warnungen und Speicher für den fortlaufenden Export erstellen. Einige Parametrisierungen weisen Besonderheiten auf, die hier erläutert werden.

Einmalige Konfiguration

Wenn Sie PowerShell noch nicht mit Ihrem Azure-Abonnement verwendet haben, installieren Sie das Azure PowerShell-Modul auf dem Computer, auf dem Sie die Skripts ausführen möchten:

1. Installieren Sie Microsoft-Webplattform-Installer (Version 5 oder höher).
2. Verwenden Sie es, um Azure PowerShell zu installieren.

Zusätzlich zur Verwendung von Azure Resource Manager-Vorlagen (ARM-Vorlagen) gibt es eine Vielzahl von PowerShell-Cmdlets für Application Insights. Diese Cmdlets erleichtern die programmgesteuerte Konfiguration von Application Insights-Ressourcen. Die mit Cmdlets ermöglichten Funktionen umfassen Folgendes:

• Erstellen und Löschen von Application Insights-Ressourcen
• Abrufen von Listen mit Application Insights-Ressourcen und deren Eigenschaften
• Erstellen und Verwalten von fortlaufendem Export
• Erstellen und Verwalten von Anwendungsschlüsseln
• Festlegen der täglichen Obergrenze
• Festlegen des Tarifs

Erstellen von Application Insights-Ressourcen mithilfe eines PowerShell-Cmdlets

Hier wird gezeigt, wie Sie mithilfe des Cmdlets New-AzApplicationInsights eine neue Application Insights-Ressource im Azure-Rechenzentrum „USA, Osten“ erstellen:

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

Erstellen von Application Insights-Ressourcen mithilfe einer ARM-Vorlage

Nachfolgend wird beschrieben, wie Sie mithilfe einer ARM-Vorlage eine neue Application Insights-Ressource erstellen.

Erstellen der ARM-Vorlage

Erstellen Sie eine neue JSON-Datei. In diesem Beispiel nennen wir sie template1.json. Kopieren Sie den folgenden Inhalt in die Datei:

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

Verwenden der ARM-Vorlage zum Erstellen einer neuen Application Insights-Ressource

1. Melden Sie sich in PowerShell mit $Connect-AzAccount bei Azure an.

2. Legen Sie mit Set-AzContext "<subscription ID>" den Kontext auf ein Abonnement fest.

3. Führen Sie eine neue Bereitstellung aus, um eine neue Application Insights-Ressource zu erstellen:

       New-AzResourceGroupDeployment -ResourceGroupName Fabrikam `
              -TemplateFile .\template1.json `
              -appName myNewApp
   
   

   • -ResourceGroupName ist die Gruppe, in der Sie die neuen Ressourcen erstellen möchten.
   • -TemplateFile muss vor den benutzerdefinierten Parametern angegeben werden.
   • -appName ist der Name der zu erstellenden Ressource.

Sie können weitere Parameter hinzufügen. Die entsprechenden Beschreibungen finden Sie im Abschnitt „Parameter“ der Vorlage.

Abrufen des Instrumentierungsschlüssels

Nach dem Erstellen einer Anwendungsressource benötigen Sie den Instrumentierungsschlüssel:

1. Anmelden bei Azure mithilfe von $Connect-AzAccount.
2. Legen Sie mit Set-AzContext "<subscription ID>" den Kontext auf ein Abonnement fest.
3. Verwenden Sie anschließend Folgendes:
   1. $resource = Get-AzResource -Name "<resource name>" -ResourceType "Microsoft.Insights/components"
   2. $details = Get-AzResource -ResourceId $resource.ResourceId
   3. $details.Properties.InstrumentationKey

Verwenden Sie Folgendes, um eine Liste vieler anderer Eigenschaften Ihrer Application Insights-Ressource anzuzeigen:

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

Zusätzliche Eigenschaften stehen über die folgenden Cmdlets zur Verfügung:

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

Informationen zu den Parametern für diese Cmdlets finden Sie in der ausführlichen Dokumentation.

Festlegen der Datenaufbewahrung

Im Folgenden finden Sie drei Methoden, um die Datenaufbewahrung für eine Application Insights-Ressource programmgesteuert festzulegen.

Festlegen der Datenaufbewahrung mithilfe von PowerShell-Befehlen

Hier finden Sie eine einfache Gruppe von PowerShell-Befehlen, um die Datenaufbewahrung für Ihre Application Insights Ressource festzulegen:

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

Festlegen der Datenaufbewahrung mithilfe von REST

Zum Abrufen der aktuelle Datenaufbewahrung für Ihre Application Insights Ressource können Sie das OSS-Tool ARMClient verwenden. Weitere Informationen zu ARMClient finden Sie in den Artikeln von David Ebbo und Daniel Bowbyes. Es folgt ein Beispiel für die Verwendung von ARMClient zum Abrufen der aktuellen Aufbewahrung:

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

Zum Festlegen der Aufbewahrung dient ein ähnlicher PUT-Befehl:

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

Führen Sie Folgendes aus, um die Datenaufbewahrung mithilfe der vorangegangenen Vorlage auf 365 Tage festzulegen:

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

Festlegen der Datenaufbewahrung mithilfe eines PowerShell-Skripts

Das folgende Skript kann auch verwendet werden, um die Aufbewahrung zu ändern. Kopieren Sie dieses Skript, um es als Set-ApplicationInsightsRetention.ps1 zu speichern.

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

Dieses Skript kann dann für Folgendes verwendet werden:

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

Festlegen der täglichen Obergrenze

Verwenden Sie das Cmdlet Set-AzApplicationInsightsPricingPlan, um die Eigenschaften für die tägliche Obergrenze abzurufen:

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

Zum Festlegen der Eigenschaften für die tägliche Obergrenze verwenden Sie das gleiche Cmdlet. Führen Sie zum Festlegen der Obergrenze auf 300 GB pro Tag beispielsweise Folgendes aus:

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

Sie können ARMClient auch verwenden, um Parameter für das Obergrenze pro Tag abzurufen und festzulegen. Verwenden Sie Folgendes, um die aktuellen Werte zu erhalten:

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

Festlegen der Zeit der Zurücksetzung der Obergrenze pro Tag

Mit ARMClient können Sie die Zeit der Zurücksetzung der Obergrenze pro Tag festlegen. Hier ist ein Beispiel mit ARMClient, um die Zeit der Zurücksetzung auf eine neue Stunde festzulegen. In diesem Beispiel wird 12:00 UTC angezeigt:

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':100,'WarningThreshold':80,'ResetTime':12}}"

Festlegen des Tarifs

Zum Abrufen des aktuellen Tarifs verwenden Sie das Cmdlet Set-AzApplicationInsightsPricingPlan:

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

Verwenden Sie zum Festlegen des Tarifs das gleiche Cmdlet mit angegebenem -PricingPlan:

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

Sie können auch den Tarif für eine vorhandene Application Insights-Ressource mithilfe der vorangegangenen ARM-Vorlage festlegen, wobei Sie die Ressource „microsoft.insights/components“ und den Knoten dependsOn aus der Abrechnungsressource auslassen. Führen Sie z.B. Folgendes aus, um den Tarif auf „Pro GB“ (früher als Basic-Tarif bezeichnet) festzulegen:

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

priceCode ist wie folgt definiert:

Schließlich können Sie ARMClient verwenden, um Preispläne und Parameter für das Obergrenze pro Tag abzurufen und festzulegen. Verwenden Sie Folgendes, um die aktuellen Werte zu erhalten:

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

Sie können alle diese Einstellungen mit folgenden Parametern festlegen:

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

Durch diesen Code wird die Obergrenze pro Tag auf 200 GB pro Tag und die Zeit der Zurücksetzung der Obergrenze pro Tag auf 12:00 UTC festgelegt. Außerdem werden E-Mails bei Erreichen sowohl der Obergrenze als auch der Warnstufe gesendet, und die Warnschwelle wird auf 90 % der Obergrenze festgelegt.

Hinzufügen einer Metrikwarnung

Informationen zum Automatisieren der Erstellung von Metrikwarnungen finden Sie im Artikel Vorlage für eine Metrikwarnung.

Hinzufügen eines Verfügbarkeitstests

Informationen zum Automatisieren von Verfügbarkeitstests finden Sie im Artikel Vorlage für eine Metrikwarnung.

Hinzufügen weiterer Ressourcen

Um die Erstellung von beliebigen anderen Ressourcen zu automatisieren, erstellen Sie manuell ein Beispiel und kopieren und parametrisieren den Code dann über Azure Resource Manager.

1. Öffnen Sie den Azure-Ressourcen-Manager. Navigieren Sie über subscriptions/resourceGroups/<your resource group>/providers/Microsoft.Insights/components nach unten zu Ihrer Anwendungsressource.

   

   Komponenten sind die grundlegenden Application Insights-Ressourcen zum Anzeigen von Anwendungen. Für die zugeordneten Warnungsregeln und Verfügbarkeitswebtests liegen separate Ressourcen vor.

2. Kopieren Sie die JSON-Definition der Komponente an die entsprechende Stelle in der Datei template1.json.

3. Löschen Sie folgende Eigenschaften:

   • id
   • InstrumentationKey
   • CreationDate
   • TenantId

4. Öffnen Sie die Abschnitte webtests und alertrules, und kopieren Sie die JSON-Definition für einzelne Elemente in die Vorlage. Kopieren Sie nicht aus den Knoten webtests oder alertrules. Wechseln Sie zu den Elementen unter ihnen.

   Jeder Webtest weist eine zugeordnete Warnungsregel auf, die Sie auch kopieren müssen.

5. Fügen Sie diese Zeile in jede Ressource ein:

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

Parametrisieren der Vorlage

Nun müssen Sie die Namen durch Parameter ersetzen. Zum Parametrisieren einer Vorlage schreiben Sie Ausdrücke mithilfe einer Reihe von Hilfsfunktionen.

Sie können nicht nur einen Teil einer Zeichenfolge parametrisieren. Verwenden Sie daher concat() zum Erstellen von Zeichenfolgen.

Es folgen einige Beispiele der Ersetzungen, die Sie vornehmen können. Es gibt mehrere Vorkommen der einzelnen Ersetzungen. In Ihrer Vorlage müssen Sie unter Umständen andere Ersetzungen vornehmen. In diesen Beispielen werden die Parameter und Variablen verwendet, die oben in der Vorlage definiert wurden.

Festlegen von Abhängigkeiten zwischen den Ressourcen

Die Ressourcen sollten in Azure in strikter Reihenfolge eingerichtet werden. Um sicherzustellen, dass eine Einrichtung abgeschlossen ist, bevor die nächste beginnt, fügen Sie Abhängigkeitszeilen hinzu:

• In der Ressource für Verfügbarkeitstests:

  "dependsOn": ["[resourceId('Microsoft.Insights/components', parameters('appName'))]"],

• In der Warnungsressource für einen Verfügbarkeitstest:

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

Nächste Schritte

Andere Artikel zu Automation:

• Erstellen Sie eine Application Insights-Ressource.
• Erstellen von Webtests
• Senden von Azure-Diagnosedaten an Application Insights
• Erstellen von Versionsanmerkungen