Gérer les ressources Application Insights à l’aide de PowerShell

  • Article

Notes

Nous vous recommandons d’utiliser le module Azure Az PowerShell pour interagir avec Azure. Pour commencer, consultez Installer Azure PowerShell. Pour savoir comment migrer vers le module Az PowerShell, consultez Migrer Azure PowerShell depuis AzureRM vers Az.

Cet article explique comment automatiser la création et la mise à jour de ressources Application Insights à l’aide du service Azure Resource Manager. Cette opération peut par exemple avoir lieu dans le cadre du processus de génération. Avec la ressource Application Insights de base, vous pouvez créer des tests web de disponibilité, configurer des alertes et un mécanisme de tarification, mais aussi créer d’autres ressources Azure.

Les éléments importants pour la création de ces ressources sont les modèles JSON pour Resource Manager. La procédure de base est la suivante :

  • Téléchargez les définitions JSON des ressources existantes.
  • Paramétrez certaines valeurs, telles que les noms.
  • Exécutez le modèle chaque fois que vous souhaitez créer une ressource.

Vous pouvez empaqueter plusieurs ressources pour les créer toutes en une seule fois. Par exemple, vous pouvez créer un moniteur d’application avec des tests de disponibilité, des alertes et un stockage pour l’exportation continue. Certains paramètres ont des particularités que nous aborderons ici.

Installation unique

Si vous n’avez pas encore utilisé PowerShell avec votre abonnement Azure, installez le module Azure PowerShell sur l’ordinateur sur lequel vous souhaitez exécuter les scripts :

  1. Installez le programme Microsoft Web Platform Installer (v5 ou version ultérieure).
  2. Utilisez-le pour installer le module Azure PowerShell.

Outre l’utilisation de modèles Azure Resource Manager (modèles ARM), il existe un ensemble complet d’applets de commande PowerShell Application Insights. Ces applets de commande facilitent la configuration programmatique des ressources Application Insights. Vous pouvez utiliser les fonctionnalités activées par les applets de commande pour :

  • Créer et supprimer des ressources Application Insights.
  • Obtenir les listes de ressources Application Insights et leurs propriétés.
  • Créer et gérer une exportation continue.
  • Créer et gérer des clés d’application.
  • Définir le plafond quotidien.
  • Définir le plan de tarification.

Créer des ressources Application Insights à l’aide d’une applet de commande PowerShell

Voici comment créer une ressource Application Insights dans le centre de données Azure USA Est à l’aide de l’applet de commande New-AzApplicationInsights :

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

Créer des ressources Application Insights à l’aide d’un modèle ARM

Voici comment créer une nouvelle ressource Application Insights à l’aide d’un modèle ARM.

Créer le modèle ARM

Créez un fichier .json. Appelons-le template1.json dans cet exemple. Copiez-y ce contenu :

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

Utiliser le modèle ARM pour créer une ressource Application Insights

  1. Dans PowerShell, connectez-vous à Azure en utilisant $Connect-AzAccount.

  2. Affectez un abonnement à votre contexte avec Set-AzContext "<subscription ID>".

  3. Exécutez un nouveau déploiement pour créer une ressource Application Insights :

        New-AzResourceGroupDeployment -ResourceGroupName Fabrikam `
           -TemplateFile .\template1.json `
           -appName myNewApp
    • -ResourceGroupName est le groupe dans lequel vous souhaitez créer les nouvelles ressources.
    • -TemplateFile doit se produire avant les paramètres personnalisés.
    • -appName est le nom de la ressource à créer.

Vous pouvez ajouter d'autres paramètres. Vous trouverez leurs descriptions dans la section Paramètres du modèle.

Obtenir la clé d’instrumentation

Après avoir créé une ressource d’application, vous voulez obtenir la clé d’instrumentation :

  1. Connexion à Azure avec $Connect-AzAccount.
  2. Affectez un abonnement à votre contexte avec Set-AzContext "<subscription ID>".
  3. Ensuite, utilisez :
    1. $resource = Get-AzResource -Name "<resource name>" -ResourceType "Microsoft.Insights/components"
    2. $details = Get-AzResource -ResourceId $resource.ResourceId
    3. $details.Properties.InstrumentationKey

Pour voir la liste des nombreuses autres propriétés de votre ressource Application Insights, utilisez :

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

Des propriétés supplémentaires sont disponibles via les applets de commande :

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

Consultez la documentation détaillée pour connaître les paramètres de ces applets de commande.

Notes

Le support de l’ingestion de clé d’instrumentation prendra fin le 31 mars 2025. L’ingestion de clé d’instrumentation continuera de fonctionner, mais nous ne fournirons plus de mises à jour ni de support pour la fonctionnalité. Passez aux chaînes de connexion pour tirer parti des nouvelles fonctionnalités.

Définir la conservation des données

Vous pouvez utiliser les trois méthodes suivantes pour définir programmatiquement la conservation des données sur une ressource Application Insights.

Définir la conservation des données à l’aide de commandes PowerShell

Voici un ensemble simple de commandes PowerShell permettant de définir la conservation des données pour votre ressource Application Insights :

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

Définir la conservation des données à l’aide de REST

Pour obtenir la conservation des données actuelle de votre ressource Application Insights, vous pouvez utiliser l’outil OSS ARMClient. Découvrez plus en détail ARMClient dans les articles de David Ebbo et Daniel Bowbyes. Voici un exemple qui utilise ARMClient pour obtenir la conservation actuelle :

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

Pour définir la conservation, la commande est un PUT similaire :

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

Pour définir la conservation des données sur 365 jours à l’aide du modèle précédent, exécutez :

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

Définir la conservation des données au moyen d’un script PowerShell

Le script suivant peut également être utilisé pour modifier la rétention. Copiez ce script pour l’enregistrer en tant que 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

Ce script peut être alors utilisé comme suit  :

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

Définir le plafond quotidien

Pour accéder aux propriétés du plafond quotidien, utilisez l’applet de commande Set-AzApplicationInsightsPricingPlan :

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

Pour définir les propriétés du plafond quotidien, utilisez la même applet de commande. Par exemple, pour définir le plafond à 300 Go par jour :

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

Vous pouvez également utiliser ARMClient pour récupérer et définir des paramètres de limite quotidienne. Pour obtenir les valeurs actuelles, utilisez la commande suivante :

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

Définir l’heure de réinitialisation de la limite quotidienne

Pour définir l’heure de réinitialisation de la limite quotidienne, vous pouvez utiliser ARMClient. Voici un exemple d’utilisation de ARMClient pour définir l’heure de réinitialisation sur une nouvelle heure. Cet exemple montre 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}}"

Définir le plan tarifaire

Pour obtenir le plan tarifaire actuel, utilisez l’applet de commande Set-AzApplicationInsightsPricingPlan :

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

Pour définir le plan tarifaire, utilisez la même applet de commande avec le -PricingPlan spécifié :

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

Vous pouvez également définir le plan tarifaire en fonction d’une ressource Application Insights existante à l’aide du modèle ARM précédent, en omettant la ressource « microsoft.insights/components » et le nœud dependsOn dans la ressource de facturation. Par exemple, pour définir le plan tarifaire en fonction du plan Par Go (anciennement appelé Plan de base), exécutez :

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

Le priceCode est défini comme :

priceCode Plan
1 Par Go (anciennement appelé Plan de base)
2 Par nœud (anciennement appelé Plan Entreprise)

Enfin, vous pouvez utiliser ARMClient pour récupérer et définir des plans de tarification et des paramètres de limite quotidienne. Pour obtenir les valeurs actuelles, utilisez la commande suivante :

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

Vous pouvez définir tous ces paramètres à l’aide de la commande suivante :

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

Ce code définit la limite quotidienne sur 200 Go par jour, configure l’heure de réinitialisation de la limite quotidienne sur 12:00 UTC, envoie des e-mails lorsque la limite et le niveau d’avertissement sont atteints, et définit le seuil d’avertissement sur 90 % de la limite.

Ajouter une alerte métrique

Pour automatiser la création d’alertes de métrique, consultez l’article Modèle d’alertes de métrique.

Ajouter un test de disponibilité

Pour automatiser les tests de disponibilité, voir l’article Modèle d’alertes de métrique.

Ajouter des ressources

Pour automatiser la création de toute autre ressource de tout type, créez un exemple manuellement, puis copiez-le et paramétrez son code à partir d’Azure Resource Manager.

  1. Ouvrez Azure Resource Manager. Accédez à votre ressource d’application qui se trouve après subscriptions/resourceGroups/<your resource group>/providers/Microsoft.Insights/components.

    Screenshot that shows navigation in Azure Resource Explorer.

    composants sont les ressources Application Insights de base pour l’affichage des applications. Il existe des ressources distinctes pour les règles d’alertes et les tests web de disponibilité associés.

  2. Copiez le JSON du composant dans l’emplacement approprié dans template1.json.

  3. Supprimez les propriétés suivantes :

    • id
    • InstrumentationKey
    • CreationDate
    • TenantId

  4. Ouvrez les sections webtests et alertrules, puis copiez le contenu JSON des éléments individuels dans votre modèle. Ne copiez pas à partir des webtests nœuds ou alertrules . Accédez aux éléments en dessous.

    Chaque test web étant associé à une règle d’alerte, vous devez copier les deux.

  5. Insérez cette ligne dans chaque ressource :

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

Définir les paramètres du modèle

Vous devez à présent remplacer les noms spécifiques par des paramètres. Pour définir les paramètres d’un modèle, écrivez des expressions utilisant un ensemble de fonctions d’assistance.

Comme vous ne pouvez pas définir uniquement les paramètres d’une portion de chaîne, utilisez concat() pour générer les chaînes.

Voici des exemples de substitutions que vous allez effectuer. Il existe plusieurs occurrences de chaque substitution. Il vous en faudra peut-être d’autres dans votre modèle. Ces exemples utilisent les paramètres et les variables que nous avons définis en haut du modèle.

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

Définir les dépendances entre les ressources

Azure doit configurer les ressources dans un ordre strict. Pour vous assurer de l’achèvement d’une installation avant que la suivante ne commence, ajoutez les lignes de dépendance :

  • Dans la ressource du test de disponibilité :

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

  • Dans la ressource d’alerte pour un test de disponibilité :

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

Étapes suivantes

Consultez ces autres articles sur l’automatisation :