Share via

Workbooks programmatisch beheren

  • Artikel

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:

ARM-sjabloon voor het implementeren van een werkmapsjabloon

  1. Open een werkmap die u programmatisch wilt implementeren.

  2. Schakel de werkmap over naar de bewerkingsmodus door Bewerken te selecteren.

  3. Open de Geavanceerde editor met behulp van de< knop />op de werkbalk.

  4. Zorg ervoor dat u zich op het tabblad Galeriesjabloon .

    Screenshot that shows the Gallery Template tab.

  5. Kopieer de JSON in de galeriesjabloon naar het klembord.

  6. 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>
            }
        }
    ]
}

  7. Vul in het galleries object de name en category sleutels in met uw waarden. Meer informatie over parameters in de volgende sectie.

  8. Implementeer deze ARM-sjabloon met behulp van Azure Portal, de opdrachtregelinterface of PowerShell.

  9. 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 Resourcetype 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

  1. Open een werkmap die u programmatisch wilt implementeren.
  2. Schakel de werkmap over naar de bewerkingsmodus door Bewerken te selecteren.
  3. Open de Geavanceerde editor door </>.
  4. Schakel in de editor het sjabloontype over naar een ARM-sjabloon.
  5. 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. Screenshot that shows how to get the ARM template from within the workbook UI.

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, tsgen 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:

  1. Exporteer de werkmap als een ARM-sjabloon, zoals wordt uitgelegd in de vorige sectie.
  2. 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 deisLockedversion/gegevens uit updatedItems de oorspronkelijke geparseerde gegevens en een gecorrigeerde set fallbackResourceIdsbevat.
    5. Serialiseer de nieuwe JSON-inhoud weer in een nieuwe tekenreeksvariabele. reserializedData
  3. Gebruik de nieuwe reserializedData variabele in plaats van de oorspronkelijke serializedData eigenschap.
  4. Implementeer de nieuwe werkmapresource met behulp van de bijgewerkte ARM-sjabloon.

Volgende stappen

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