Gérer programmatiquement des classeurs

Article
06/21/2023

Les propriétaires de ressources peuvent créer et gérer leurs classeurs par programmation via des modèles Azure Resource Manager (modèles ARM).

Cette capacité peut être utile dans différents scénarios comme :

le déploiement de rapports d’analytique propres à l’organisation ou au domaine, ainsi que le déploiement de ressources Par exemple, vous pouvez déployer des classeurs de performances et de défaillances propres à l’organisation pour de nouvelles applications ou machines virtuelles.
Déployer des rapports ou de tableaux de bord standard à l’aide de classeurs pour des ressources existantes.

Le classeur sera créé dans le groupe ou sous-groupe de ressources souhaité et comportera le contenu spécifié dans les modèles ARM.

Deux types de ressources de classeur peuvent être gérés par programme :

Modèles de classeur
Instances de classeur

Modèle ARM pour le déploiement d’un modèle de classeur

Ouvrez un classeur que vous voulez déployer par programme.
Commutez le classeur en mode édition en sélectionnant Modifier.
Ouvrez l’Éditeur avancé avec le bouton </> de la barre d’outils.
Vérifiez que vous êtes sous l’onglet Modèles de galerie.
Copiez le JSON figurant dans le modèle de galerie dans le presse-papiers.

L’exemple de modèle ARM suivant déploie un modèle de classeur dans la galerie de classeurs Azure Monitor. Collez le JSON que vous avez copié à la place de <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>. Pour obtenir un modèle ARM de référence qui crée un modèle de classeur, consultez ce référentiel GitHub.

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "resourceName": {
            "type": "string",
            "defaultValue": "my-workbook-template",
            "metadata": {
                "description": "The unique name for this workbook template instance"
            }
        }
    },
    "resources": [
        {
            "name": "[parameters('resourceName')]",
            "type": "microsoft.insights/workbooktemplates",
            "location": "[resourceGroup().location]",
            "apiVersion": "2019-10-17-preview",
            "dependsOn": [],
            "properties": {
                "galleries": [
                    {
                        "name": "A Workbook Template",
                        "category": "Deployed Templates",
                        "order": 100,
                        "type": "workbook",
                        "resourceType": "Azure Monitor"
                    }
                ],
                "templateData": <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>
            }
        }
    ]
}

Dans l’objet galleries, renseignez les clés name et category avec vos valeurs. Apprenez-en davantage sur les paramètres dans la section suivante.
Déployez ce modèle ARM à l’aide de Portail Azure, de l’interface de ligne de commande ou de PowerShell.
Ouvrez le portail Azure et allez dans la galerie de classeurs choisie dans le modèle ARM. Dans l’exemple de modèle, accédez à la galerie de classeurs Azure Monitor :
1. Ouvrez le portail Azure et accédez à Azure Monitor.
2. Ouvrez Workbooks à partir de la table des matières.
3. Trouvez votre modèle dans la galerie sous la catégorie Deployed Templates. (Il s’agira de l’un des éléments violets.)

Paramètres

Paramètres	Explication
`name`	Nom de la ressource de modèle de classeur dans Azure Resource Manager.
`type`	Toujours microsoft.insights/workbooktemplates.
`location`	Emplacement Azure où sera créé le classeur.
`apiVersion`	2019-10-17-preview.
`type`	Toujours microsoft.insights/workbooktemplates.
`galleries`	Ensemble de galeries dans lequel afficher ce modèle de classeur.
`gallery.name`	Nom convivial du modèle de classeur dans la galerie.
`gallery.category`	Groupe dans la galerie dans lequel placer le modèle.
`gallery.order`	Nombre qui détermine l’ordre d’affichage du modèle dans une catégorie de la galerie. Un ordre inférieur implique une priorité supérieure.
`gallery.resourceType`	Type de ressource correspondant à la galerie. Ce type est généralement la chaîne de type de ressource correspondant à la ressource (par exemple, microsoft.operationalinsights/workspaces).
`gallery.type`	Appelé type de classeur. Cette clé unique permet de différencier la galerie au sein d’un type de ressource. Les Application Insights, par exemple, ont des types `workbook` et `tsg` correspondant à différentes galeries de classeurs.

Galeries

Galerie	Type de ressource	Type de classeur
Classeurs dans Azure Monitor	`Azure Monitor`	`workbook`
Insights de machine virtuelle dans Azure Monitor	`Azure Monitor`	`vm-insights`
Classeurs dans l’espace de travail Log Analytics	`microsoft.operationalinsights/workspaces`	`workbook`
Classeurs dans Application Insights	`microsoft.insights/components`	`workbook`
Guides de résolution des problèmes dans Application Insights	`microsoft.insights/components`	`tsg`
Utilisation dans Application Insights	`microsoft.insights/components`	`usage`
Classeurs dans le service Kubernetes	`Microsoft.ContainerService/managedClusters`	`workbook`
Classeurs dans des groupes de ressources	`microsoft.resources/subscriptions/resourcegroups`	`workbook`
Classeurs dans Microsoft Entra ID	`microsoft.aadiam/tenant`	`workbook`
Insights de machine virtuelle dans des machines virtuelles	`microsoft.compute/virtualmachines`	`insights`
Insights de machine virtuelle dans des groupes de machines virtuelles identiques	`microsoft.compute/virtualmachinescalesets`	`insights`

Modèle ARM pour le déploiement d’une instance de classeur

Ouvrez le classeur à déployer programmatiquement.
Commutez le classeur en mode édition en sélectionnant Modifier.
Ouvrez le Éditeur avancé en sélectionnant </>.
Dans l’éditeur, basculez Type de modèle sur Modèle ARM.
Le modèle ARM de création apparaît dans l’éditeur. Copiez le contenu et utilisez-le tel quel ou fusionnez-le avec un modèle plus vaste qui déploie également la ressource cible.

Exemple de modèle ARM

Ce modèle montre comment déployer un classeur qui affiche Hello World!.

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "workbookDisplayName":  {             
            "type":"string",
            "defaultValue": "My Workbook",
            "metadata": {
                "description": "The friendly name for the workbook that is used in the Gallery or Saved List. Needs to be unique in the scope of the resource group and source" 
            }
        },
        "workbookType":  {             
            "type":"string",
            "defaultValue": "tsg",
            "metadata": {
                "description": "The gallery that the workbook will be shown under. Supported values include workbook, `tsg`, Azure Monitor, etc." 
            }
        },
        "workbookSourceId":  {             
            "type":"string",
            "defaultValue": "<insert-your-resource-id-here>",
            "metadata": {
                "description": "The id of resource instance to which the workbook will be associated" 
            }
        },
        "workbookId": {
            "type":"string",
            "defaultValue": "[newGuid()]",
            "metadata": {
                "description": "The unique guid for this workbook instance" 
            }
        }
    },    
    "resources": [
        {
            "name": "[parameters('workbookId')]",
            "type": "Microsoft.Insights/workbooks",
            "location": "[resourceGroup().location]",
            "kind": "shared",
            "apiVersion": "2018-06-17-preview",
            "dependsOn": [],
            "properties": {
                "displayName": "[parameters('workbookDisplayName')]",
                "serializedData": "{\"version\":\"Notebook/1.0\",\"items\":[{\"type\":1,\"content\":\"{\\\"json\\\":\\\"Hello World!\\\"}\",\"conditionalVisibility\":null}],\"isLocked\":false}",
                "version": "1.0",
                "sourceId": "[parameters('workbookSourceId')]",
                "category": "[parameters('workbookType')]"
            }
        }
    ],
    "outputs": {
        "workbookId": {
            "type": "string",
            "value": "[resourceId( 'Microsoft.Insights/workbooks', parameters('workbookId'))]"
        }
    }
}

Paramètres de modèle

Paramètre	Description
`workbookDisplayName`	Nom convivial du classeur utilisé dans la Galerie ou la liste enregistrée. Doit être unique dans l’étendue du groupe de ressources et de la source.
`workbookType`	Galerie dans laquelle le classeur apparaît. Valeurs prises en charge : classeur, `tsg`, et Azure Monitor.
`workbookSourceId`	ID de l’instance de ressource à laquelle le classeur sera associé. Le nouveau classeur s’affichera en rapport avec cette instance de ressource, par exemple dans le sommaire de la ressource sous Classeur. Si vous souhaitez que votre classeur apparaisse dans la galerie de classeurs d’Azure Monitor, utilisez la chaîne Azure Monitor au lieu d’un ID de ressource.
`workbookId`	GUID unique de cette instance de classeur. Utilisez `[newGuid()]` pour créer automatiquement un nouveau GUID.
`kind`	Permet de spécifier si le classeur créé est partagé ou privé. Tous les nouveaux classeurs utilisent la valeur partagé.
`location`	Emplacement Azure où sera créé le classeur. Utilisez `[resourceGroup().location]` pour le créer dans le même emplacement que le groupe de ressources.
`serializedData`	Contient le contenu ou la charge utile à utiliser dans le classeur. Utilisez le modèle ARM de l’interface utilisateur des classeurs pour récupérer la valeur.

Types de classeurs

Les types de classeurs spécifient le type de galerie de classeurs où la nouvelle instance de classeur s’affichera. Options disponibles :

Type	Emplacement de la galerie
`workbook`	Valeur par défaut utilisée dans la plupart des rapports, qui comprend la galerie de classeurs d’Application Insights et d’Azure Monitor.
`tsg`	Galerie de guides de dépannage dans Application Insights.
`usage`	Galerie Plus sous Utilisation dans Application Insights.

Utiliser des données de classeur au format JSON dans le paramètre de modèle serializedData

Lorsque vous exportez un modèle ARM pour un classeur Azure, il y a souvent des liens de ressources fixes intégrés dans le paramètre du modèle serializedDataexporté. Ces liens incluent des valeurs potentiellement sensibles, telles que l’ID d’abonnement et le nom du groupe de ressources, ainsi que d’autres types d’ID de ressource.

L'exemple suivant démontre la personnalisation d’un modèle ARM de classeur exporté, sans avoir recours à la manipulation de chaînes de caractères. Le modèle présenté dans cet exemple est conçu pour utiliser les données non modifiées telles qu’elles sont exportées depuis le portail Azure. Il est également recommandé de masquer toutes les valeurs sensibles incorporées lorsque vous gérez des classeurs par programmation. Pour cette raison, l’ID d’abonnement et le groupe de ressources ont été masqués ici. Aucune autre modification n’a été apportée à la valeur serializedData entrante brute.

{
  "contentVersion": "1.0.0.0",
  "parameters": {
    "workbookDisplayName": {
      "type": "string"
    },
    "workbookSourceId": {
      "type": "string",
      "defaultValue": "[resourceGroup().id]"
    },
    "workbookId": {
      "type": "string",
      "defaultValue": "[newGuid()]"
    }
  },
  "variables": {
    // serializedData from original exported Azure Resource Manager template
    "serializedData": "{\"version\":\"Notebook/1.0\",\"items\":[{\"type\":1,\"content\":{\"json\":\"Replace with Title\"},\"name\":\"text - 0\"},{\"type\":3,\"content\":{\"version\":\"KqlItem/1.0\",\"query\":\"{\\\"version\\\":\\\"ARMEndpoint/1.0\\\",\\\"data\\\":null,\\\"headers\\\":[],\\\"method\\\":\\\"GET\\\",\\\"path\\\":\\\"/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/resourceGroups\\\",\\\"urlParams\\\":[{\\\"key\\\":\\\"api-version\\\",\\\"value\\\":\\\"2019-06-01\\\"}],\\\"batchDisabled\\\":false,\\\"transformers\\\":[{\\\"type\\\":\\\"jsonpath\\\",\\\"settings\\\":{\\\"tablePath\\\":\\\"$..*\\\",\\\"columns\\\":[]}}]}\",\"size\":0,\"queryType\":12,\"visualization\":\"map\",\"tileSettings\":{\"showBorder\":false},\"graphSettings\":{\"type\":0},\"mapSettings\":{\"locInfo\":\"AzureLoc\",\"locInfoColumn\":\"location\",\"sizeSettings\":\"location\",\"sizeAggregation\":\"Count\",\"opacity\":0.5,\"legendAggregation\":\"Count\",\"itemColorSettings\":null}},\"name\":\"query - 1\"}],\"isLocked\":false,\"fallbackResourceIds\":[\"/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/resourceGroups/XXXXXXX\"]}",

    // parse the original into a JSON object, so that it can be manipulated
    "parsedData": "[json(variables('serializedData'))]",

    // create new JSON objects that represent only the items/properties to be modified
    "updatedTitle": {
      "content":{
        "json": "[concat('Resource Group Regions in subscription \"', subscription().displayName, '\"')]"
      }
    },
    "updatedMap": {
      "content": {
        "path": "[concat('/subscriptions/', subscription().subscriptionId, '/resourceGroups')]"
      }
    },

    // the union function applies the updates to the original data
    "updatedItems": [
      "[union(variables('parsedData')['items'][0], variables('updatedTitle'))]",
      "[union(variables('parsedData')['items'][1], variables('updatedMap'))]"
    ],

    // copy to a new workbook object, with the updated items
    "updatedWorkbookData": {
      "version": "[variables('parsedData')['version']]",
      "items": "[variables('updatedItems')]",
      "isLocked": "[variables('parsedData')['isLocked']]",
      "fallbackResourceIds": ["[parameters('workbookSourceId')]"]
    },

    // convert back to an encoded string
    "reserializedData": "[string(variables('updatedWorkbookData'))]"
  },
  "resources": [
    {
      "name": "[parameters('workbookId')]",
      "type": "microsoft.insights/workbooks",
      "location": "[resourceGroup().location]",
      "apiVersion": "2018-06-17-preview",
      "dependsOn": [],
      "kind": "shared",
      "properties": {
        "displayName": "[parameters('workbookDisplayName')]",
        "serializedData": "[variables('reserializedData')]",
        "version": "1.0",
        "sourceId": "[parameters('workbookSourceId')]",
        "category": "workbook"
      }
    }
  ],
  "outputs": {
    "workbookId": {
      "type": "string",
      "value": "[resourceId( 'microsoft.insights/workbooks', parameters('workbookId'))]"
    }
  },
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#"
}

Dans cet exemple, les étapes suivantes facilitent la personnalisation d’un modèle ARM exporté :

Exportez le classeur en tant que modèle ARM, comme expliqué dans la section précédente.
Dans la section variables du modèle :
1. Analysez la valeur serializedData dans une variable objet JSON, qui crée une structure JSON comprenant un tableau d’éléments qui représentent le contenu du classeur.
2. Créez de nouveaux objets JSON qui représentent uniquement les éléments/propriétés à modifier.
3. Projetez un nouvel ensemble d’éléments de contenu JSON (updatedItems) en utilisant la fonction union() pour appliquer les modifications aux éléments JSON d’origine.
4. Créez un nouvel objet de classeur, updatedWorkbookData, qui contient updatedItems les données version/isLocked des données analysées d’origine, et un ensemble corrigé de fallbackResourceIds.
5. Sérialisez le nouveau contenu JSON dans une nouvelle variable de chaîne, reserializedData.
Utilisez la nouvelle variable reserializedData à la place de la propriété serializedData d’origine.
Déployez la nouvelle ressource de classeur à l’aide du modèle ARM mis à jour.

Étapes suivantes

Découvrez comment les classeurs sont utilisés dans la nouvelle expérience d’insights pour le stockage.