Verwalten von Application Insights-Ressourcen mithilfe von PowerShellManage Application Insights resources using PowerShell

Hinweis

Dieser Artikel wurde aktualisiert und beinhaltet jetzt das neue Az-Modul von Azure PowerShell.This article has been updated to use the new Azure PowerShell Az module. Sie können das AzureRM-Modul weiterhin verwenden, das bis mindestens Dezember 2020 weiterhin Fehlerbehebungen erhält.You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. Weitere Informationen zum neuen Az-Modul und zur Kompatibilität mit AzureRM finden Sie unter Introducing the new Azure PowerShell Az module (Einführung in das neue Az-Modul von Azure PowerShell).To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Anweisungen zur Installation des Az-Moduls finden Sie unter Install Azure PowerShell (Installieren von Azure PowerShell).For Az module installation instructions, see Install Azure PowerShell.

Dieser Artikel beschreibt, wie Sie die Erstellung und Aktualisierung von Application Insights-Ressourcen mit der Azure-Ressourcenverwaltung automatisieren können.This article shows you how to automate the creation and update of Application Insights resources automatically by using Azure Resource Management. Dies kann z. B. als Teil eines Buildvorgangs erfolgen.You might, for example, do so as part of a build process. Zusammen mit der grundlegenden Application Insights-Ressource können Sie Verfügbarkeitswebtests erstellen, Warnungen einrichten, das Preisschema festlegen und andere Azure-Ressourcen erstellen.Along with the basic Application Insights resource, you can create availability web tests, set up alerts, set the pricing scheme, and create other Azure resources.

Im Wesentlichen werden diese Ressourcen mit JSON-Vorlagen für den Azure Resource Manager erstellt.The key to creating these resources is JSON templates for Azure Resource Manager. 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.The basic procedure is: download the JSON definitions of existing resources; parameterize certain values such as names; and then run the template whenever you want to create a new resource. 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.You can package several resources together, to create them all in one go - for example, an app monitor with availability tests, alerts, and storage for continuous export. Einige Parametrisierungen weisen Besonderheiten auf, die hier erläutert werden.There are some subtleties to some of the parameterizations, which we'll explain here.

Einmalige KonfigurationOne-time setup

Wenn Sie PowerShell noch nicht mit Ihrem Azure-Abonnement verwendet haben:If you haven't used PowerShell with your Azure subscription before:

Installieren Sie das Azure PowerShell-Modul auf dem Computer, auf dem die Skripts ausgeführt werden sollen:Install the Azure Powershell module on the machine where you want to run the scripts:

  1. Installieren Sie Microsoft-Webplattform-Installer (Version 5 oder höher).Install Microsoft Web Platform Installer (v5 or higher).
  2. Installieren Sie hiermit Microsoft Azure PowerShell.Use it to install 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.In addition to using Resource Manager templates, there is a rich set of Application Insights PowerShell cmdlets, which make it easy to configure Application Insights resources programatically. Die mit Cmdlets ermöglichten Funktionen umfassen Folgendes:The capabilities enabled by the cmdlets include:

  • Erstellen und Löschen von Application Insights-RessourcenCreate and delete Application Insights resources
  • Abrufen von Listen mit Application Insights-Ressourcen und deren EigenschaftenGet lists of Application Insights resources and their properties
  • Erstellen und Verwalten von fortlaufendem ExportCreate and manage Continuous Export
  • Erstellen und Verwalten von AnwendungsschlüsselnCreate and manage Application Keys
  • Festlegen der täglichen ObergrenzeSet the Daily Cap
  • Festlegen des TarifsSet the Pricing Plan

Erstellen von Application Insights-Ressourcen mithilfe eines PowerShell-CmdletsCreate Application Insights resources using a PowerShell cmdlet

Hier wird gezeigt, wie Sie mithilfe des Cmdlets New-AzApplicationInsights eine neue Application Insights-Ressource im Azure-Rechenzentrum „USA, Osten“ erstellen:Here's how to create a new Application Insights resource in the Azure East US datacenter using the New-AzApplicationInsights cmdlet:

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

Erstellen von Application Insights-Ressourcen mithilfe einer Resource Manager-VorlageCreate Application Insights resources using a Resource Manager template

Nachfolgend wird beschrieben, wie Sie mithilfe einer Resource Manager-Vorlage eine neue Application Insights-Ressource erstellen.Here's how to create a new Application Insights resource using a Resource Manager template.

Erstellen der Azure Resource Manager-VorlageCreate the Azure Resource Manager template

Erstellen Sie eine neue JSON-Datei, in diesem Beispiel die Datei template1.json .Create a new .json file - let's call it template1.json in this example. Kopieren Sie den folgenden Inhalt in die Datei:Copy this content into it:

    {
        "$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": 24,
                "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-RessourceUse the Resource Manager template to create a new Application Insights resource

  1. Melden Sie sich in PowerShell mit $Connect-AzAccount bei Azure an.In PowerShell, sign in to Azure using $Connect-AzAccount

  2. Legen Sie mit Set-AzContext "<subscription ID>" den Kontext auf ein Abonnement fest.Set your context to a subscription with Set-AzContext "<subscription ID>"

  3. Führen Sie eine neue Bereitstellung aus, um eine neue Application Insights-Ressource zu erstellen:Run a new deployment to create a new Application Insights resource:

        New-AzResourceGroupDeployment -ResourceGroupName Fabrikam `
               -TemplateFile .\template1.json `
               -appName myNewApp
    
    
    • -ResourceGroupName ist die Gruppe, in der Sie die neuen Ressourcen erstellen möchten.-ResourceGroupName is the group where you want to create the new resources.
    • -TemplateFile muss vor den benutzerdefinierten Parametern angegeben werden.-TemplateFile must occur before the custom parameters.
    • -appName ist der Name der zu erstellenden Ressource.-appName The name of the resource to create.

Sie können noch weitere Parameter hinzufügen. Die entsprechenden Beschreibungen finden Sie im Abschnitt „Parameter“ der Vorlage.You can add other parameters - you'll find their descriptions in the parameters section of the template.

Abrufen des InstrumentierungsschlüsselsGet the instrumentation key

Nach dem Erstellen einer Anwendungsressource benötigen Sie den Instrumentierungsschlüssel:After creating an application resource, you'll want the instrumentation key:

  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:To see a list of many other properties of your Application Insights resource, use:

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

Zusätzliche Eigenschaften stehen über die folgenden Cmdlets zur Verfügung:Additional properties are available via the cmdlets:

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

Informationen zu den Parametern für diese Cmdlets finden Sie in der ausführlichen Dokumentation.Refer to the detailed documentation for the parameters for these cmdlets.

Festlegen der DatenaufbewahrungSet the data retention

Zum Abrufen der aktuelle Datenaufbewahrung für Ihre Application Insights Ressource können Sie das OSS-Tool ARMClient verwenden.To get the current data retention for your Application Insights resource, you can use the OSS tool ARMClient. (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:(Learn more about ARMClient from articles by David Ebbo and Daniel Bowbyes.) Here's an example using ARMClient, to get the current retention:

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:To set the retention, the command is a similar 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}}"

Führen Sie Folgendes aus, um die Datenaufbewahrung mithilfe der Vorlage oben auf 365 Tage festzulegen:To set the data retention to 365 days using the template above, run:

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

Das folgende Skript kann auch verwendet werden, um die Aufbewahrung zu ändern.The following script can also be used to change retention. Kopieren Sie dieses Skript, um es als Set-ApplicationInsightsRetention.ps1 zu speichern.Copy this script to save as 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

Dieses Skript kann dann für Folgendes verwendet werden:This script can then be used as:

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

Festlegen der täglichen ObergrenzeSet the daily cap

Verwenden Sie das Cmdlet Set-AzApplicationInsightsPricingPlan, um die Eigenschaften für die tägliche Obergrenze abzurufen:To get the daily cap properties, use the Set-AzApplicationInsightsPricingPlan cmdlet:

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.To set the daily cap properties, use same cmdlet. Führen Sie zum Festlegen der Obergrenze auf 300 GB/Tag beispielsweise Folgendes aus:For instance, to set the cap to 300 GB/day,

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

Festlegen des TarifsSet the pricing plan

Zum Abrufen des aktuellen Tarifs verwenden Sie das Cmdlet Set-AzApplicationInsightsPricingPlan:To get current pricing plan, use the Set-AzApplicationInsightsPricingPlan cmdlet:

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

Verwenden Sie zum Festlegen des Tarifs das gleiche Cmdlet mit angegebenem -PricingPlan:To set the pricing plan, use same cmdlet with the -PricingPlan specified:

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.You can also set the pricing plan on an existing Application Insights resource using the Resource Manager template above, omitting the "microsoft.insights/components" resource and the dependsOn node from the billing resource. Führen Sie z.B. Folgendes aus, um den Tarif auf „Pro GB“ (früher als Basic-Tarif bezeichnet) festzulegen:For instance, to set it to the Per GB plan (formerly called the Basic plan), run:

        New-AzResourceGroupDeployment -ResourceGroupName "<resource group>" `
               -TemplateFile .\template1.json `
               -priceCode 1 `
               -appName myApp
priceCodepriceCode Tarifplan
11 Pro GB (früher als Basic-Tarif bezeichnet)Per GB (formerly named the Basic plan)
22 Pro Knoten (früher als Enterprise-Tarif bezeichnet)Per Node (formerly name the Enterprise plan)

Hinzufügen einer MetrikwarnungAdd a metric alert

Informationen zum Automatisieren der Erstellung von Metrikwarnungen finden Sie im Artikel mit der Vorlage für eine Metrikwarnung.To automate the creation of metric alerts consult the metric alerts template article

Hinzufügen eines VerfügbarkeitstestsAdd an availability test

Informationen zum Automatisieren von Verfügbarkeitstests finden Sie im Artikel mit der Vorlage für eine Metrikwarnung.To automate availability tests consult the metric alerts template article.

Hinzufügen weiterer RessourcenAdd more resources

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.To automate the creation of any other resource of any kind, create an example manually, and then copy and parameterize its code from Azure Resource Manager.

  1. Öffnen Sie den Azure-Ressourcen-Manager.Open Azure Resource Manager. Navigieren Sie über subscriptions/resourceGroups/<your resource group>/providers/Microsoft.Insights/components nach unten zu Ihrer Anwendungsressource.Navigate down through subscriptions/resourceGroups/<your resource group>/providers/Microsoft.Insights/components, to your application resource.

    Navigation im Azure-Ressourcen-Explorer

    Komponenten sind die grundlegenden Application Insights-Ressourcen zum Anzeigen von Anwendungen.Components are the basic Application Insights resources for displaying applications. Für die zugeordneten Warnungsregeln und Verfügbarkeitswebtests liegen separate Ressourcen vor.There are separate resources for the associated alert rules and availability web tests.

  2. Kopieren Sie die JSON-Definition der Komponente an die entsprechende Stelle in der Datei template1.json.Copy the JSON of the component into the appropriate place in template1.json.

  3. Löschen Sie folgende Eigenschaften:Delete these properties:

    • 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.Open the webtests and alertrules sections and copy the JSON for individual items into your template. (Kopieren Sie die Definition nicht aus den Knoten webtests oder alertrules, sondern aus den Elementen unter diesen Knoten.)(Don't copy from the webtests or alertrules nodes: go into the items under them.)

    Jeder Webtest weist eine zugeordnete Warnungsregel auf, die Sie auch kopieren müssen.Each web test has an associated alert rule, so you have to copy both of them.

    Sie können auch Warnungen für Metriken hinzufügen.You can also include alerts on metrics. Metriknamen.Metric names.

  5. Fügen Sie diese Zeile in jede Ressource ein:Insert this line in each resource:

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

Parametrisieren der VorlageParameterize the template

Nun müssen Sie die Namen durch Parameter ersetzen.Now you have to replace the specific names with parameters. Zum Parametrisieren einer Vorlage schreiben Sie Ausdrücke mithilfe einer Reihe von Hilfsfunktionen.To parameterize a template, you write expressions using a set of helper functions.

Sie können nicht einen Teil einer Zeichenfolge parametrisieren. Verwenden Sie daher concat() zum Erstellen von Zeichenfolgen.You can't parameterize just part of a string, so use concat() to build strings.

Es folgen einige Beispiele der Ersetzungen, die Sie vornehmen können.Here are examples of the substitutions you'll want to make. Es gibt mehrere Vorkommen der einzelnen Ersetzungen.There are several occurrences of each substitution. In Ihrer Vorlage müssen Sie unter Umständen andere Ersetzungen vornehmen.You might need others in your template. In diesen Beispielen werden die Parameter und Variablen verwendet, die oben in der Vorlage definiert wurden.These examples use the parameters and variables we defined at the top of the template.

Suchenfind Ersetzen durchreplace 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" (Kleinbuchstaben)"myappname" (lower case) "[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 RessourcenSet dependencies between the resources

Die Ressourcen sollten in Azure in strikter Reihenfolge eingerichtet werden.Azure should set up the resources in strict order. Um sicherzustellen, dass eine Einrichtung abgeschlossen ist, bevor die nächste beginnt, fügen Sie Abhängigkeitszeilen hinzu:To make sure one setup completes before the next begins, add dependency lines:

  • In der Ressource für Verfügbarkeitstests:In the availability test resource:

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

  • In der Warnungsressource für einen Verfügbarkeitstest:In the alert resource for an availability test:

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

Nächste SchritteNext steps

Andere Artikel zu Automation:Other automation articles: