Programmgesteuertes Verwalten von Arbeitsmappen

Artikel
10/15/2024

Ressourcenbesitzer können Ihre Arbeitsmappen über Azure Resource Manager-Vorlagen (ARM-Vorlagen) programmgesteuert erstellen und verwalten.

Diese Funktion kann in den folgenden Szenarien hilfreich sein:

Bereitstellen von organisations- oder domänenspezifischen Analyseberichten zusammen mit Ressourcenbereitstellungen. Sie können beispielsweise organisationsspezifische Leistungs-und Fehlerarbeitsmappen für Ihre neuen Apps oder VMs bereitstellen.
Bereitstellen von Standardberichten oder Standarddashboards mithilfe von Arbeitsmappen für vorhandene Ressourcen.

Die Arbeitsmappe wird in der gewünschten Untergruppe/Ressourcengruppe und mit dem Inhalt erstellt, der in den ARM-Vorlagen angegeben ist.

Es gibt zwei Arten von Arbeitsmappenressourcen, die programmgesteuert verwaltet werden können:

Arbeitsmappenvorlagen
Arbeitsmappeninstanzen

ARM-Vorlage zum Erstellen einer Arbeitsmappenvorlage

Öffnen Sie eine Arbeitsmappe, die Sie programmgesteuert bereitstellen möchten.
Versetzen Sie die Arbeitsmappe in den Bearbeitungsmodus, indem Sie Bearbeiten auswählen.
Öffnen Sie den erweiterten Editor, indem Sie auf der Symbolleiste auf die Schaltfläche </> klicken.
Stellen Sie sicher, dass Sie sich auf der Registerkarte Katalogvorlage befinden.
Kopieren Sie den JSON-Code in der Katalogvorlage in die Zwischenablage.

Die folgende ARM-Beispielvorlage stellt eine Arbeitsmappenvorlage im Azure Monitor-Arbeitsmappenkatalog bereit. Fügen Sie den kopierten JSON-Code anstelle von <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE> ein. Eine ARM-Referenzvorlage zum Erstellen einer Arbeitsmappenvorlage finden Sie in diesem GitHub-Repository.

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

Geben Sie im galleries-Objekt für die Schlüssel name und category Ihre Werte ein. Im nächsten Abschnitt erfahren Sie mehr über Parameter.
Sie können diese ARM-Vorlage über das Azure-Portal, die Befehlszeilenschnittstelle oder PowerShell bereitstellen.
Öffnen Sie das Azure-Portal, und navigieren Sie zum Arbeitsmappenkatalog, der in der ARM-Vorlage ausgewählt wurde. Navigieren Sie in der Beispielvorlage zum Azure Monitor-Arbeitsmappenkatalog:
1. Öffnen Sie das Azure-Portal, navigieren Sie zu Azure Monitor.
2. Öffnen Sie Workbooks im Inhaltsverzeichnis.
3. Suchen Sie Ihre Vorlage im Katalog unter der Kategorie Deployed Templates. (Dabei handelt es sich um einen der lilafarbenen Einträge.)

Parameter

Parameter	Erklärung
`name`	Der Name der Arbeitsmappenvorlagen-Ressource in Azure Resource Manager.
`type`	Immer „microsoft.insights/workbooktemplates“.
`location`	Der Azure-Speicherort, an dem die Arbeitsmappe erstellt wird.
`apiVersion`	2019-10-17-preview
`type`	Immer „microsoft.insights/workbooktemplates“.
`galleries`	Die Gruppe von Galerien, in der diese Arbeitsmappenvorlage angezeigt wird.
`gallery.name`	Der Anzeigename der Arbeitsmappenvorlage im Katalog.
`gallery.category`	Die Gruppe im Katalog, in die die Vorlage eingefügt werden soll.
`gallery.order`	Eine Zahl, die die Rangordnung bestimmt, in der die Vorlage in einer Kategorie im Katalog angezeigt werden soll. Ein niedrigerer Rang impliziert eine höhere Priorität.
`gallery.resourceType`	Der Ressourcentyp, der dem Katalog entspricht. Dieser Typ ist normalerweise die Ressourcentyp-Zeichenfolge, die der Ressource entspricht (z. B. microsoft.operationalinsights/workspaces).
`gallery.type`	Wird als Arbeitsmappentyp bezeichnet. Dieser eindeutige Schlüssel kennzeichnet den Katalog in einem Ressourcentyp. Application Insights verfügt beispielsweise über die Typen `workbook` und `tsg`, die verschiedenen Arbeitsmappenkatalogen entsprechen.

Kataloge

Galerie	Ressourcentyp	Arbeitsmappentyp
Arbeitsmappen in Azure Monitor	`Azure Monitor`	`workbook`
VM Insights in Azure Monitor	`Azure Monitor`	`vm-insights`
Arbeitsmappen im Log Analytics-Arbeitsbereich	`microsoft.operationalinsights/workspaces`	`workbook`
Arbeitsmappen in Application Insights	`microsoft.insights/components`	`workbook`
Leitfäden zur Problembehandlung in Application Insights	`microsoft.insights/components`	`tsg`
Nutzung in Application Insights	`microsoft.insights/components`	`usage`
Arbeitsmappen in Kubernetes Service	`Microsoft.ContainerService/managedClusters`	`workbook`
Arbeitsmappen in Ressourcengruppen	`microsoft.resources/subscriptions/resourcegroups`	`workbook`
Workbooks in Microsoft Entra ID	`microsoft.aadiam/tenant`	`workbook`
VM Insights in virtuellen Computern	`microsoft.compute/virtualmachines`	`insights`
VM Insights in VM-Skalierungsgruppen	`microsoft.compute/virtualmachinescalesets`	`insights`

ARM-Vorlage zum Erstellen einer Arbeitsmappeninstanz

Öffnen Sie eine Arbeitsmappe, die Sie programmgesteuert bereitstellen möchten.
Versetzen Sie die Arbeitsmappe in den Bearbeitungsmodus, indem Sie Bearbeiten auswählen.
Öffnen Sie den erweiterten Editor, indem Sie </> auswählen.
Ändern Sie im Editor Vorlagentyp in ARM-Vorlage.
Die ARM-Vorlage zum Erstellen wird im Editor angezeigt. Kopieren Sie den Inhalt, und übernehmen Sie ihn unverändert, oder führen Sie ihn mit einer größeren Vorlage zusammen, mit der ebenfalls die Zielressource bereitgestellt wird.

ARM-Beispielvorlage

Diese Vorlage zeigt, wie Sie eine Arbeitsmappe bereitstellen, in der Hello World! angezeigt wird.

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

Vorlagenparameter

Parameter	BESCHREIBUNG
`workbookDisplayName`	Der Anzeigename für die Arbeitsmappe, der im Katalog oder in der Liste gespeicherter Elemente verwendet wird. Muss im Bereich der Ressourcengruppe und der Quelle eindeutig sein.
`workbookType`	Der Katalog, in dem die Arbeitsmappe angezeigt wird. Zu den unterstützten Werten zählen Arbeitsmappe, `tsg` und Azure Monitor.
`workbookSourceId`	Die ID der Ressourceninstanz, der die Arbeitsmappe zugeordnet wird. Die neue Arbeitsmappe wird im Zusammenhang mit dieser Ressourceninstanz angezeigt, z. B. im Inhaltsverzeichnis der Ressource unter Arbeitsmappe. Wenn die Arbeitsmappe im Katalog Arbeitsmappen in Azure Monitor angezeigt werden soll, verwenden Sie anstelle einer Ressourcen-ID die Zeichenfolge Azure Monitor.
`workbookId`	Die eindeutige GUID für diese Arbeitsmappeninstanz. Verwenden Sie `[newGuid()]` , um automatisch eine neue GUID zu erstellen.
`kind`	Hiermit wird angegeben, ob die erstellte Arbeitsmappe freigegeben ist. Alle neuen Arbeitsmappen verwenden den Wert shared.
`location`	Der Azure-Speicherort, an dem die Arbeitsmappe erstellt wird. Verwenden Sie `[resourceGroup().location]`, um sie im selben Speicherort wie die Ressourcengruppe zu erstellen.
`serializedData`	Enthält den Inhalt oder die Nutzlast, der bzw. die in der Arbeitsmappe verwendet werden soll. Rufen Sie den Wert mithilfe der ARM-Vorlage in der Arbeitsmappen-Benutzeroberfläche ab.

Arbeitsmappentypen

Arbeitsmappentypen geben an, unter welchem Arbeitsmappenkatalogtyp die neue Arbeitsmappeninstanz angezeigt wird. Beispiele für Optionen:

type	Position im Katalog
`workbook`	Der in den meisten Berichten verwendete Standardwert, einschließlich des Katalogs Arbeitsmappen von Application Insights und Azure Monitor.
`tsg`	Der Katalog Leitfäden zur Problembehandlung in Application Insights.
`usage`	Der Katalog Mehr unter Nutzung in Application Insights.

Verwenden von Arbeitsmappendaten im JSON-Format im Vorlagenparameter „serializedData“

Beim Exportieren einer ARM-Vorlage für eine Azure-Arbeitsmappe sind häufig feste Ressourcenlinks in den exportierten Vorlagenparameter serializedData eingebettet. Diese Links enthalten potenziell vertrauliche Werte wie Abonnement-ID und Ressourcengruppenname sowie andersartige Ressourcen-IDs.

Das folgende Beispiel veranschaulicht die Anpassung einer exportierten ARM-Vorlage für Arbeitsmappen ohne Zeichenfolgenbearbeitung. Das in diesem Beispiel gezeigte Muster ist für die Verwendung mit den unveränderten Daten vorgesehen, die aus dem Azure-Portal exportiert wurden. Es hat sich außerdem bewährt, alle eingebetteten vertraulichen Werte zu maskieren, wenn Sie Arbeitsmappen programmgesteuert verwalten. Aus diesem Grund wurden die Abonnement-ID und die Ressourcengruppe hier maskiert. Es wurden keine weiteren Änderungen am eingehenden serializedData-Rohwert vorgenommen.

{
  "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 diesem Beispiel erleichterten die folgenden Schritte die Anpassung einer exportierten ARM-Vorlage:

Exportieren Sie die Arbeitsmappe als ARM-Vorlage, wie im vorherigen Abschnitt erläutert.
Gehen Sie im Abschnitt variables der Vorlage wie folgt vor:
1. Parsen Sie den Wert serializedData in einer JSON-Objektvariablen, die eine JSON-Struktur mit einem Array von Elementen erstellt, die den Inhalt der Arbeitsmappe darstellen.
2. Erstellen Sie neue JSON-Objekte, die nur die Elemente/Eigenschaften darstellen, die geändert werden sollen.
3. Projektieren Sie mithilfe der Funktion union() einen neuen Satz von JSON-Inhaltselementen (updatedItems), um die Änderungen auf die ursprünglichen JSON-Elemente anzuwenden.
4. Erstellen Sie ein neues Arbeitsmappenobjekt (updatedWorkbookData), das updatedItems und die Daten vom Typ version/isLocked aus den ursprünglichen analysierten Daten und einen korrigierten Satz von fallbackResourceIds enthält.
5. Serialisieren Sie den neuen JSON-Inhalt wieder in eine neue Zeichenfolgenvariable (reserializedData).
Verwenden Sie die neue Variable reserializedData anstelle der ursprünglichen Eigenschaft serializedData.
Stellen Sie die neue Arbeitsmappenressource mithilfe der aktualisierten ARM-Vorlage bereit.

Nächste Schritte

Erfahren Sie, wie Arbeitsmappen die neue Storage Insights-Funktion fördern.

Freigeben über