Gestire le risorse Application Insights con PowerShell

Articolo
10/15/2024

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 descrive come automatizzare la creazione e l'aggiornamento di risorse 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 la creazione di queste risorse è rappresentata dai 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 combinare diverse risorse in un pacchetto 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 non si è ancora 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 di ARM), è disponibile un set completo di cmdlet di PowerShell per Application Insights. Questi cmdlet semplificano la configurazione delle risorse Application Insights a livello di codice. È possibile usare le funzionalità abilitate dai cmdlet per:

Creare ed eliminare risorse Application Insights.
Ottenere elenchi di risorse 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 Application Insights usando un cmdlet di PowerShell

Di seguito viene illustrato come creare una nuova risorsa Application Insights nel data center dell'area di Azure Stati Uniti orientali usando il cmdlet New-AzApplicationInsights:

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

Creare risorse di Application Insights usando un modello di ARM

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

Creare il modello di Resource Manager

Creare un nuovo file JSON. In questo esempio gli verrà assegnato il nome template1.json. 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 ARM per creare una nuova risorsa 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 del modello dedicata ai parametri.

Ottenere la chiave di strumentazione

Dopo la creazione di una risorsa applicazione, è necessaria 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

Ulteriori proprietà sono disponibili 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 delle chiavi di strumentazione continuerà a funzionare, ma non saranno più garantiti aggiornamenti o supporto per la funzionalità. Eseguire la transizione alle stringhe 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 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 tramite 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, in questo esempio 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 specificando -PricingPlan:

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

È anche possibile impostare il piano tariffario su una risorsa Application Insights esistente usando il modello di ARM precedente, omettendo la risorsa "microsoft.insights/components" e il nodo dependsOn 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 imposterà il limite giornaliero su 200 GB/giorno, configurerà l'ora di ripristino del limite di uso giornaliero su 12:00 UTC, invierà messaggi di posta elettronica quando viene raggiunto il limite e il livello di avviso e imposterà la soglia di avviso sul 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 qualunque tipo, creare un esempio manualmente e quindi copiare e parametrizzare il codice da Azure Resource Manager.

Aprire Gestione risorse di Azure. Scorrere verso il basso in subscriptions/resourceGroups/<your resource group>/providers/Microsoft.Insights/components fino alla risorsa 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 nodi webtests 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 impostare i parametri per una sola parte di una stringa, quindi usare concat() per creare le 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 sull'automazione:

Condividi tramite