Gestire le risorse di Application Insights con PowerShell

Articolo
09/12/2023

Nota

È consigliabile usare il modulo Azure Az PowerShell per interagire con Azure. Per iniziare, vedere Installare Azure PowerShell. Per informazioni su come eseguire la migrazione al modulo AZ PowerShell, vedere Eseguire la migrazione di Azure PowerShell da AzureRM ad Az.

Questo articolo illustra come automatizzare automaticamente la creazione e l'aggiornamento delle risorse di Application Insights usando Azure Resource Manager. Questo procedimento potrebbe, ad esempio, essere utilizzato come parte di un processo di compilazione. Insieme alla risorsa di base di Application Insights, è possibile creare test Web di disponibilità, configurare avvisi, impostare lo schema dei prezzi e creare altre risorse di Azure.

La chiave per creare queste risorse è i modelli JSON per Resource Manager. La procedura di base è la seguente:

Scaricare le definizioni JSON delle risorse esistenti.
Parametrizzare determinati valori, ad esempio i nomi.
Eseguire il modello ogni volta che si vuole creare una nuova risorsa.

È possibile creare insieme diverse risorse per crearle tutte in un'unica operazione. Ad esempio, è possibile creare un monitoraggio app con test di disponibilità, avvisi e archiviazione per l'esportazione continua. Esistono alcune sottigliezze di alcuni parametri, che verranno illustrate di seguito.

Installazione singola

Se in precedenza non è stato usato PowerShell con la sottoscrizione di Azure, installare il modulo Azure PowerShell nel computer in cui si vogliono eseguire gli script:

Installare Installazione guidata piattaforma Web Microsoft (v5 o versione successiva).
Usarlo per installare Azure PowerShell.

Oltre a usare i modelli di Azure Resource Manager (modelli arm), è disponibile un set completo di cmdlet di PowerShell per Application Insights. Questi cmdlet semplificano la configurazione delle risorse di Application Insights a livello di codice. È possibile usare le funzionalità abilitate dai cmdlet per:

Creare ed eliminare le risorse di Application Insights.
Ottenere elenchi di risorse di Application Insights e le relative proprietà.
Creare e gestire l'esportazione continua.
Creare e gestire le chiavi dell'applicazione.
Impostare il limite giornaliero.
Impostare il piano tariffario.

Creare risorse di Application Insights usando un cmdlet di PowerShell

Ecco come creare una nuova risorsa di Application Insights nel data center degli Stati Uniti orientali di Azure usando il cmdlet New-AzApplicationInsights :

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

Creare risorse di Application Insights usando un modello di Resource Manager

Ecco come creare una nuova risorsa di Application Insights usando un modello di Resource Manager.

Creare il modello di Resource Manager

Creare un nuovo file json. In questo esempio viene template1.json chiamato . Copiare questo contenuto al suo interno:

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

Usare il modello di Resource Manager per creare una nuova risorsa di Application Insights

In PowerShell accedere ad Azure usando $Connect-AzAccount.
Impostare il contesto su una sottoscrizione con Set-AzContext "<subscription ID>".
Eseguire una nuova distribuzione per creare una nuova risorsa di Application Insights:
```
    New-AzResourceGroupDeployment -ResourceGroupName Fabrikam `
           -TemplateFile .\template1.json `
           -appName myNewApp
```
- -ResourceGroupName è il gruppo in cui si vogliono creare le nuove risorse.
- -TemplateFile deve precedere i parametri personalizzati.
- -appName è il nome della risorsa da creare.

È possibile aggiungere altri parametri. Le descrizioni sono disponibili nella sezione parametri del modello.

Ottenere la chiave di strumentazione

Dopo aver creato una risorsa dell'applicazione, è necessario usare la chiave di strumentazione:

Accedere ad Azure usando $Connect-AzAccount.
Impostare il contesto su una sottoscrizione con Set-AzContext "<subscription ID>".
Usare quindi:
1. $resource = Get-AzResource -Name "<resource name>" -ResourceType "Microsoft.Insights/components"
2. $details = Get-AzResource -ResourceId $resource.ResourceId
3. $details.Properties.InstrumentationKey

Per visualizzare un elenco di molte altre proprietà della risorsa di Application Insights, usare:

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

Sono disponibili altre proprietà tramite i cmdlet:

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

Vedere la documentazione dettagliata per i parametri per questi cmdlet.

Nota

Il 31 marzo 2025, il supporto per l'inserimento delle chiavi di strumentazione terminerà. L'inserimento di chiavi di strumentazione continuerà a funzionare, ma non forniamo più aggiornamenti o supporto per la funzionalità. Passare alle stringa di connessione per sfruttare le nuove funzionalità.

Impostare la conservazione dei dati

È possibile usare i tre metodi seguenti per impostare a livello di codice la conservazione dei dati in una risorsa di Application Insights.

Impostare la conservazione dei dati usando i comandi di PowerShell

Ecco un semplice set di comandi di PowerShell per impostare la conservazione dei dati per la risorsa di Application Insights:

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

Impostare la conservazione dei dati usando REST

Per ottenere la conservazione dei dati corrente per la risorsa di Application Insights, è possibile usare lo strumento OSS ARMClient. Altre informazioni su ARMClient sono disponibili negli articoli di David Ebbo e Daniel Bowbyes. Ecco un esempio che usa ARMClient per ottenere la conservazione corrente:

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

Per impostare la conservazione, il comando è un PUT simile:

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

Per impostare la conservazione dei dati su 365 giorni usando il modello precedente, eseguire:

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

Impostare la conservazione dei dati usando uno script di PowerShell

Lo script seguente può essere usato anche per modificare la conservazione. Copiare questo script per salvarlo come 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

Questo script può quindi essere usato come:

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

Impostare il limite giornaliero

Per ottenere le proprietà del limite giornaliero, usare il cmdlet set-AzApplicationInsightsPricingPlan:

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

Per impostare le proprietà del limite giornaliero, usare lo stesso cmdlet. Ad esempio, per impostare il limite su 300 GB al giorno:

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

È anche possibile usare ARMClient per ottenere e impostare parametri del limite giornaliero. Per ottenere i valori correnti, usare:

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

Impostare l'ora di reimpostazione del limite di uso giornaliero

Per impostare l'ora di reimpostazione del limite di uso giornaliero, è possibile usare ARMClient. Ecco un esempio che usa ARMClient per impostare l'ora di reimpostazione su una nuova ora. Questo esempio mostra le 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':{'Cap':100,'WarningThreshold':80,'ResetTime':12}}"

Impostare il piano tariffario

Per ottenere il piano tariffario corrente, usare il cmdlet Set-AzApplicationInsightsPricingPlan :

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

Per impostare il piano tariffario, usare lo stesso cmdlet con il -PricingPlan valore specificato:

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

È anche possibile impostare il piano tariffario in una risorsa di Application Insights esistente usando il modello di Resource Manager precedente, omettendo la risorsa "microsoft.insights/components" e il dependsOn nodo dalla risorsa di fatturazione. Ad esempio, per impostarlo sul piano Per GB (denominato in precedenza piano Basic), eseguire:

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

priceCode viene definito come:

priceCode	Piano
1	Per GB (in precedenza denominato piano Basic)
2	Per nodo (denominato in precedenza il piano Enterprise)

Infine, è possibile usare ARMClient per ottenere e impostare piani tariffari e i parametri del limite giornaliero. Per ottenere i valori correnti, usare:

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

È possibile impostare tutti questi parametri usando:

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

Questo codice imposta il limite giornaliero su 200 GB al giorno, configura il tempo di reimpostazione del limite giornaliero su 12:00 UTC, invia messaggi di posta elettronica sia quando viene raggiunto il limite che il livello di avviso viene soddisfatto e imposta la soglia di avviso su 90% del limite.

Aggiungere un avviso per la metrica

Per automatizzare la creazione di avvisi delle metriche, vedere l'articolo Modello di avvisi delle metriche.

Aggiungere un test di disponibilità

Per automatizzare i test di disponibilità, vedere l'articolo Modello di avvisi delle metriche.

Aggiungere altre risorse

Per automatizzare la creazione di qualsiasi altra risorsa di qualsiasi tipo, creare un esempio manualmente e quindi copiare e parametrizzare il codice da Azure Resource Manager.

Aprire Gestione risorse di Azure. Passare alla subscriptions/resourceGroups/<your resource group>/providers/Microsoft.Insights/components risorsa dell'applicazione.

Componenti sono le risorse base di Application Insights per la visualizzazione di applicazioni. Sono disponibili risorse separate per le regole di avviso associate e i test web di disponibilità.
Copiare i JSON del componente nella posizione appropriata in template1.json.
Eliminare queste proprietà:
- id
- InstrumentationKey
- CreationDate
- TenantId
Aprire le sezioni webtests e alertrules e copiare i JSON per i singoli elementi nel modello. Non copiare dai webtests nodi o alertrules . Passare agli elementi sotto di essi.

Ciascun test web dispone di una regola di avviso associata, perciò è necessario copiarli entrambi.
Inserire questa riga in ciascuna risorsa:

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

Impostazione dei parametri per il modello

È necessario sostituire i nomi specifici con i parametri. Per impostare i parametri di un modello, si scrivono espressioni mediante un set di funzioni di supporto.

Non è possibile parametrizzare solo parte di una stringa, quindi usare concat() per compilare stringhe.

Di seguito sono riportati esempi delle sostituzioni che si possono apportare. Sono presenti più occorrenze di ogni sostituzione. Potrebbero esserne necessarie altre nel modello. Questi esempi utilizzano i parametri e le variabili definite nella parte superiore del modello.

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

Impostazione di dipendenze tra le risorse

Azure deve configurare le risorse in ordine fisso. Per assicurarsi che un programma di installazione venga completato prima che inizi il successivo, aggiungere le righe delle dipendenze:

Nella risorsa del test di disponibilità:

"dependsOn": ["[resourceId('Microsoft.Insights/components', parameters('appName'))]"],
Nella risorsa avviso per un test di disponibilità:

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

Passaggi successivi

Vedere questi altri articoli di automazione:

Creare una risorsa di Application Insights
Creare test Web.
Inviare Diagnostica di Azure ad Application Insights.
Creare annotazioni di versione.