Workbooks programmatisch beheren

Artikel
11/05/2024

Resource-eigenaren kunnen hun werkmappen programmatisch maken en beheren via ARM-sjablonen (Azure Resource Manager).

Deze mogelijkheid kan nuttig zijn in scenario's zoals:

Organisatie- of domeinspecifieke analyserapporten implementeren, samen met resourcesimplementaties. U kunt bijvoorbeeld organisatiespecifieke werkmappen voor prestaties en fouten implementeren voor uw nieuwe apps of virtuele machines.
Standaardrapporten of dashboards implementeren met behulp van werkmappen voor bestaande resources.

De werkmap wordt gemaakt in de gewenste sub-/resourcegroep en met de inhoud die is opgegeven in de ARM-sjablonen.

Er kunnen twee typen werkmapbronnen programmatisch worden beheerd:

Werkmapsjablonen
Werkmapexemplaren

ARM-sjabloon voor het implementeren van een werkmapsjabloon

Open een werkmap die u programmatisch wilt implementeren.
Schakel de werkmap over naar de bewerkingsmodus door Bewerken te selecteren.
Open de Geavanceerde editor met behulp van de< knop />op de werkbalk.
Zorg ervoor dat u zich op het tabblad Galeriesjabloon .
Kopieer de JSON in de galeriesjabloon naar het klembord.

Met de volgende ARM-voorbeeldsjabloon wordt een werkmapsjabloon geïmplementeerd in de Galerie met Azure Monitor-werkmappen. Plak de JSON die u hebt gekopieerd in plaats van <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>. Zie deze GitHub-opslagplaats voor een referentie-ARM-sjabloon waarmee een werkmapsjabloon wordt gemaakt.

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

Vul in het galleries object de name en category sleutels in met uw waarden. Meer informatie over parameters in de volgende sectie.
Implementeer deze ARM-sjabloon met behulp van Azure Portal, de opdrachtregelinterface of PowerShell.
Open Azure Portal en ga naar de werkmapgalerie die u hebt gekozen in de ARM-sjabloon. Ga in de voorbeeldsjabloon naar de galerie met Azure Monitor-werkmappen:
1. Open Azure Portal en ga naar Azure Monitor.
2. Openen Workbooks vanuit de inhoudsopgave.
3. Zoek uw sjabloon in de galerie onder de categorie Deployed Templates. (Dit is een van de paarse items.)

Parameters

Parameters	Uitleg
`name`	De naam van de werkmapsjabloonresource in Azure Resource Manager.
`type`	Altijd microsoft.insights/workbooktemplates.
`location`	De Azure-locatie waar de werkmap wordt gemaakt.
`apiVersion`	2019-10-17 preview.
`type`	Altijd microsoft.insights/workbooktemplates.
`galleries`	De set galerieën waarin deze werkmapsjabloon wordt weergegeven.
`gallery.name`	De beschrijvende naam van de werkmapsjabloon in de galerie.
`gallery.category`	De groep in de galerie waarin u de sjabloon wilt plaatsen.
`gallery.order`	Een getal waarmee de volgorde wordt bepaald om de sjabloon weer te geven binnen een categorie in de galerie. Lagere volgorde impliceert een hogere prioriteit.
`gallery.resourceType`	Het resourcetype dat overeenkomt met de galerie. Dit type is meestal de tekenreeks van het resourcetype die overeenkomt met de resource (bijvoorbeeld microsoft.operationalinsights/workspaces).
`gallery.type`	Aangeduid als werkmaptype. Deze unieke sleutel onderscheidt de galerie binnen een resourcetype. Application Insights heeft bijvoorbeeld de typen `workbook` en `tsg` die overeenkomen met verschillende werkmapgalerieën.

Galerieën

Galerij	Brontype	Werkmaptype
Werkmappen in Azure Monitor	`Azure Monitor`	`workbook`
VM-inzichten in Azure Monitor	`Azure Monitor`	`vm-insights`
Werkmappen in Log Analytics-werkruimte	`microsoft.operationalinsights/workspaces`	`workbook`
Werkmappen in Application Insights	`microsoft.insights/components`	`workbook`
Handleidingen voor probleemoplossing in Application Insights	`microsoft.insights/components`	`tsg`
Gebruik in Application Insights	`microsoft.insights/components`	`usage`
Werkmappen in Kubernetes-service	`Microsoft.ContainerService/managedClusters`	`workbook`
Werkmappen in resourcegroepen	`microsoft.resources/subscriptions/resourcegroups`	`workbook`
Werkmappen in Microsoft Entra-id	`microsoft.aadiam/tenant`	`workbook`
VM-inzichten in virtuele machines	`microsoft.compute/virtualmachines`	`insights`
VM-inzichten in virtuele-machineschaalsets	`microsoft.compute/virtualmachinescalesets`	`insights`

ARM-sjabloon voor het implementeren van een werkmapexemplaren

Open een werkmap die u programmatisch wilt implementeren.
Schakel de werkmap over naar de bewerkingsmodus door Bewerken te selecteren.
Open de Geavanceerde editor door </>.
Schakel in de editor het sjabloontype over naar een ARM-sjabloon.
De ARM-sjabloon voor het maken wordt weergegeven in de editor. Kopieer de inhoud en gebruik deze als zodanig of voeg deze samen met een grotere sjabloon die ook de doelresource implementeert.

Voorbeeld van een ARM-sjabloon

Deze sjabloon laat zien hoe u een werkmap implementeert die wordt weergegeven 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'))]"
        }
    }
}

Sjabloonparameters

Parameter	Description
`workbookDisplayName`	De beschrijvende naam voor de werkmap die wordt gebruikt in de galerie of opgeslagen lijst. Moet uniek zijn binnen het bereik van de resourcegroep en de bron.
`workbookType`	De galerie waarin de werkmap wordt weergegeven. Ondersteunde waarden zijn werkmap, `tsg`en Azure Monitor.
`workbookSourceId`	De id van het resource-exemplaar waaraan de werkmap wordt gekoppeld. De nieuwe werkmap wordt weergegeven met betrekking tot dit resource-exemplaar, bijvoorbeeld in de inhoudsopgave van de resource onder Werkmap. Als u wilt dat uw werkmap wordt weergegeven in de galerie Werkmappen in Azure Monitor, gebruikt u de tekenreeks Azure Monitor in plaats van een resource-id.
`workbookId`	De unieke guid voor dit werkmapexemplaren. Hiermee `[newGuid()]` maakt u automatisch een nieuwe guid.
`kind`	Wordt gebruikt om op te geven of de gemaakte werkmap wordt gedeeld. Alle nieuwe werkmappen gebruiken de gedeelde waarde.
`location`	De Azure-locatie waar de werkmap wordt gemaakt. Gebruik `[resourceGroup().location]` deze om deze te maken op dezelfde locatie als de resourcegroep.
`serializedData`	Bevat de inhoud of nettolading die in de werkmap moet worden gebruikt. Gebruik de ARM-sjabloon uit de gebruikersinterface van werkmappen om de waarde op te halen.

Werkmaptypen

Met werkmaptypen geeft u het type werkmapgalerie op waar het nieuwe werkmapexemplaren worden weergegeven. De volgende opties zijn beschikbaar:

Type	Galerielocatie
`workbook`	De standaardinstelling die wordt gebruikt in de meeste rapporten, waaronder de werkmapgalerie van Application Insights en Azure Monitor.
`tsg`	De galerie Probleemoplossingsgidsen in Application Insights.
`usage`	De galerie Meer onder Gebruik in Application Insights.

Werken met met JSON-indeling opgemaakte werkmapgegevens in de parameter serializedData-sjabloon

Wanneer u een ARM-sjabloon voor een Azure-werkmap exporteert, zijn er vaak vaste resourcekoppelingen ingesloten in de geëxporteerde serializedData sjabloonparameter. Deze koppelingen bevatten mogelijk gevoelige waarden, zoals abonnements-id en resourcegroepnaam en andere typen resource-id's.

In het volgende voorbeeld ziet u de aanpassing van een geëxporteerde ARM-werkmapsjabloon, zonder gebruik te maken van tekenreeksmanipulatie. Het patroon dat in dit voorbeeld wordt weergegeven, is bedoeld om te werken met de ongewijzigde gegevens, zoals geëxporteerd vanuit Azure Portal. Het is ook een best practice om ingesloten gevoelige waarden te maskeren wanneer u werkmappen programmatisch beheert. Daarom zijn de abonnements-id en resourcegroep hier gemaskeerd. Er zijn geen andere wijzigingen aangebracht in de onbewerkte binnenkomende serializedData waarde.

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

In dit voorbeeld vergemakkelijken de volgende stappen de aanpassing van een geëxporteerde ARM-sjabloon:

Exporteer de werkmap als een ARM-sjabloon, zoals wordt uitgelegd in de vorige sectie.
In de sectie van variables de sjabloon:
1. Parseert de serializedData waarde in een JSON-objectvariabele, waarmee een JSON-structuur wordt gemaakt, inclusief een matrix met items die de inhoud van de werkmap vertegenwoordigen.
2. Maak nieuwe JSON-objecten die alleen de items/eigenschappen vertegenwoordigen die moeten worden gewijzigd.
3. Projecter een nieuwe set JSON-inhoudsitems (updatedItems) met behulp van de union() functie om de wijzigingen toe te passen op de oorspronkelijke JSON-items.
4. Maak een nieuw werkmapobject, updatedWorkbookDatadat deisLocked version/gegevens uit updatedItems de oorspronkelijke geparseerde gegevens en een gecorrigeerde set fallbackResourceIdsbevat.
5. Serialiseer de nieuwe JSON-inhoud weer in een nieuwe tekenreeksvariabele. reserializedData
Gebruik de nieuwe reserializedData variabele in plaats van de oorspronkelijke serializedData eigenschap.
Implementeer de nieuwe werkmapresource met behulp van de bijgewerkte ARM-sjabloon.

Volgende stappen

Ontdek hoe werkmappen worden gebruikt om de nieuwe opslaginzichtervaring te verbeteren.

Delen via