Verwalten von Application Insights-Ressourcen mithilfe von PowerShell

Hinweis

Dieser Artikel wurde mit der Verwendung des Azure Az PowerShell-Moduls aktualisiert. Das Azure Az PowerShell-Modul wird für die Interaktion mit Azure empfohlen. Informationen zu den ersten Schritten mit dem Az PowerShell-Modul finden Sie unter Installieren von Azure PowerShell. Informationen zum Migrieren zum Az PowerShell-Modul finden Sie unter Migrieren von Azure PowerShell von AzureRM zum Az-Modul.

Dieser Artikel beschreibt, wie Sie die Erstellung und Aktualisierung von Application Insights-Ressourcen mit der Azure-Ressourcenverwaltung 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 Vorgehensweise ist wie folgt: Sie laden die JSON-Definitionen vorhandener Ressourcen herunter, parametrisieren bestimmte Werte, z. B. Namen, und führen dann die Vorlage immer aus, wenn Sie eine neue Ressource erstellen möchten. Sie können mehrere Ressourcen zusammenfassen und in einem Durchgang erstellen, z. B. einen App-Monitor mit Verfügbarkeitstests, Warnungen und Speicher für fortlaufenden Export. 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 die Skripts ausgeführt werden sollen:

  1. Installieren Sie Microsoft-Webplattform-Installer (Version 5 oder höher).
  2. Installieren Sie hiermit Microsoft Azure PowerShell.

Zusätzlich zur Verwendung von Resource Manager-Vorlagen gibt es einen umfangreichen Satz von PowerShell-Cmdlets für Application Insights, die das programmgesteuerte Konfigurieren von Application Insights-Ressourcen erleichtern. 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 Resource Manager-Vorlage

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

Erstellen der Azure Resource Manager-Vorlage

Erstellen Sie eine neue JSON-Datei, in diesem Beispiel die Datei 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')]"
                },
                "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 Resource Manager-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 noch 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. $Connect-AzAccount
  2. Set-AzContext "<subscription ID>"
  3. $resource = Get-AzResource -Name "<resource name>" -ResourceType "Microsoft.Insights/components"
  4. $details = Get-AzResource -ResourceId $resource.ResourceId
  5. $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 eines PowerShell-Befehls

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 Vorlage oben 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/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 12:00 UTC):

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':{'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 oben genannten Resource Manager-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:

priceCode Tarif
1 Pro GB (früher als Basic-Tarif bezeichnet)
2 Pro Knoten (früher als Enterprise-Tarif bezeichnet)

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

Dadurch wird die Obergrenze pro Tag auf 200 GB/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 mit der Vorlage für eine Metrikwarnung.

Hinzufügen eines Verfügbarkeitstests

Informationen zum Automatisieren von Verfügbarkeitstests finden Sie im Artikel mit der 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.

    Navigation im Azure-Ressourcen-Explorer

    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 die Definition nicht aus den Knoten webtests oder alertrules, sondern aus den Elementen unter diesen Knoten.)

    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 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.

Suchen Ersetzen durch
"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" (Kleinbuchstaben) "[toLower(parameters('appName'))]"
"<WebTest Name=\"myWebTest\" ...
Url=\"http://fabrikam.com/home\" ...>"
[concat('<WebTest Name=\"',
parameters('webTestName'),
'\" ... Url=\"', parameters('Url'),
'\"...>')]"

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: