Programová správa sešitů

Článek
11/05/2024

Vlastníci prostředků můžou své sešity vytvářet a spravovat prostřednictvím kódu programu prostřednictvím šablon Azure Resource Manageru (šablon ARM).

Tato funkce může být užitečná ve scénářích, jako jsou:

Nasazení analytických sestav specifických pro organizaci nebo doménu spolu s nasazeními prostředků Můžete například nasadit sešity výkonu a selhání specifické pro organizaci pro nové aplikace nebo virtuální počítače.
Nasazení standardních sestav nebo řídicích panelů pomocí sešitů pro existující prostředky

Sešit se vytvoří v požadované podskupině nebo skupině prostředků a s obsahem zadaným v šablonách ARM.

Dva typy prostředků sešitu je možné spravovat prostřednictvím kódu programu:

Šablony sešitů
Instance sešitu

Šablona ARM pro nasazení šablony sešitu

Otevřete sešit, který chcete nasadit programově.
Výběrem možnosti Upravit přepněte sešit do režimu úprav.
Otevřete Rozšířený editor pomocí <tlačítka /> na panelu nástrojů.
Ujistěte se, že jste na kartě Šablona galerie.
Zkopírujte JSON v šabloně galerie do schránky.

Následující ukázková šablona ARM nasadí šablonu sešitu do galerie sešitů služby Azure Monitor. Vložte json, který jste zkopírovali místo <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>. Referenční šablonu ARM, která vytvoří šablonu sešitu, najdete v tomto úložišti GitHubu.

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

V objektu galleries vyplňte name hodnoty a category klíče. Další informace o parametrech najdete v další části.
Nasaďte tuto šablonu ARM pomocí webu Azure Portal, rozhraní příkazového řádku nebo PowerShellu.
Otevřete Web Azure Portal a přejděte do galerie sešitů zvolených v šabloně ARM. V ukázkové šabloně přejděte do galerie sešitů služby Azure Monitor:
1. Otevřete Azure Portal a přejděte do služby Azure Monitor.
2. Otevřete Workbooks obsah.
3. Najděte šablonu v galerii v kategorii Deployed Templates. (Bude to jedna z fialových položek.)

Parametry

Parametry	Vysvětlení
`name`	Název prostředku šablony sešitu v Azure Resource Manageru
`type`	Vždy microsoft.insights/workbooktemplates.
`location`	Umístění Azure, kde se sešit vytvoří.
`apiVersion`	Verze Preview z 10. 10. 2019
`type`	Vždy microsoft.insights/workbooktemplates.
`galleries`	Sada galerií, ve kterých se má zobrazit tato šablona sešitu.
`gallery.name`	Popisný název šablony sešitu v galerii
`gallery.category`	Skupina v galerii, do které chcete šablonu umístit.
`gallery.order`	Číslo, které rozhoduje o pořadí zobrazení šablony v kategorii v galerii. Nižší pořadí znamená vyšší prioritu.
`gallery.resourceType`	Typ prostředku odpovídající galerii. Tento typ je obvykle řetězec typu prostředku odpovídající prostředku (například microsoft.operationalinsights/workspaces).
`gallery.type`	Označuje se jako typ sešitu. Tento jedinečný klíč rozlišuje galerii v rámci typu prostředku. Application Insights má například typy `workbook` , `tsg` které odpovídají různým galeriím sešitů.

Galerie

Galerie	Typ prostředku	Typ sešitu
Sešity ve službě Azure Monitor	`Azure Monitor`	`workbook`
Přehledy virtuálních počítačů ve službě Azure Monitor	`Azure Monitor`	`vm-insights`
Sešity v pracovním prostoru služby Log Analytics	`microsoft.operationalinsights/workspaces`	`workbook`
Sešity v Application Insights	`microsoft.insights/components`	`workbook`
Průvodci odstraňováním potíží v Application Insights	`microsoft.insights/components`	`tsg`
Využití ve službě Application Insights	`microsoft.insights/components`	`usage`
Sešity ve službě Kubernetes	`Microsoft.ContainerService/managedClusters`	`workbook`
Sešity ve skupinách prostředků	`microsoft.resources/subscriptions/resourcegroups`	`workbook`
Sešity v Microsoft Entra ID	`microsoft.aadiam/tenant`	`workbook`
Přehledy virtuálních počítačů ve virtuálních počítačích	`microsoft.compute/virtualmachines`	`insights`
Přehledy virtuálních počítačů ve škálovacích sadách virtuálních počítačů	`microsoft.compute/virtualmachinescalesets`	`insights`

Šablona ARM pro nasazení instance sešitu

Otevřete sešit, který chcete nasadit programově.
Výběrem možnosti Upravit přepněte sešit do režimu úprav.
Otevřete Rozšířený editor výběrem <příkazu />.
V editoru přepněte typ šablony na šablonu ARM.
Šablona ARM pro vytváření se zobrazí v editoru. Zkopírujte obsah a použijte ho tak, jak je, nebo ho sloučíte s větší šablonou, která také nasadí cílový prostředek.

Ukázková šablona ARM

Tato šablona ukazuje, jak nasadit sešit, který se zobrazí 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'))]"
        }
    }
}

Parametry šablony

Parametr	Popis
`workbookDisplayName`	Popisný název sešitu, který se používá v galerii nebo uloženém seznamu. Musí být jedinečný v oboru skupiny prostředků a zdroje.
`workbookType`	Galerie, kde se sešit zobrazuje. Mezi podporované hodnoty patří sešit `tsg`a Azure Monitor.
`workbookSourceId`	ID instance prostředku, ke které bude sešit přidružen. Nový sešit se zobrazí v souvislosti s tímto příkladem prostředku, například v obsahu prostředku v části Sešit. Pokud chcete, aby se sešit zobrazoval v galerii Sešity ve službě Azure Monitor, použijte místo ID prostředku řetězec služby Azure Monitor.
`workbookId`	Jedinečný identifikátor GUID pro tuto instanci sešitu. Slouží `[newGuid()]` k automatickému vytvoření nového identifikátoru GUID.
`kind`	Slouží k určení, zda je vytvořený sešit sdílený. Všechny nové sešity budou používat sdílenou hodnotu.
`location`	Umístění Azure, kde se sešit vytvoří. Slouží `[resourceGroup().location]` k jeho vytvoření ve stejném umístění jako skupina prostředků.
`serializedData`	Obsahuje obsah nebo datovou část, která se má použít v sešitu. K získání hodnoty použijte šablonu ARM z uživatelského rozhraní sešitů.

Typy sešitů

Typy sešitů určují typ galerie sešitů, kde se zobrazí nová instance sešitu. K dispozici jsou následující možnosti:

Typ	Umístění galerie
`workbook`	Výchozí hodnota použitá ve většině sestav, včetně galerie Sešity Application Insights a Azure Monitoru.
`tsg`	Galerie Průvodci odstraňováním potíží v Application Insights
`usage`	Galerie Další v části Využití v Application Insights

Práce s daty sešitu ve formátu JSON v parametru šablony serializedData

Když exportujete šablonu ARM pro sešit Azure, často jsou v rámci exportovaného serializedData parametru šablony vložené odkazy na prostředky s pevnými prostředky. Mezi tyto odkazy patří potenciálně citlivé hodnoty, jako je ID předplatného a název skupiny prostředků a další typy ID prostředků.

Následující příklad ukazuje přizpůsobení exportované šablony ARM sešitu bez použití manipulace s řetězci. Vzor zobrazený v tomto příkladu je určený k práci s nealterovanými daty, která se exportují z webu Azure Portal. Osvědčeným postupem je také maskovat všechny vložené citlivé hodnoty při správě sešitů prostřednictvím kódu programu. Z tohoto důvodu se zde maskovalo ID předplatného a skupina prostředků. Nezpracované příchozí serializedData hodnoty nebyly provedeny žádné další změny.

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

V tomto příkladu následující kroky usnadňují přizpůsobení exportované šablony ARM:

Exportujte sešit jako šablonu ARM, jak je vysvětleno v předchozí části.
V části šablony variables :
1. Parsujte serializedData hodnotu do proměnné objektu JSON, která vytvoří strukturu JSON včetně pole položek, které představují obsah sešitu.
2. Vytvořte nové objekty JSON, které představují pouze položky/vlastnosti, které se mají upravit.
3. Promítejte novou sadu položek obsahu JSON (updatedItems) pomocí union() funkce, aby se změny použily u původních položek JSON.
4. Vytvořte nový objekt sešitu , updatedWorkbookDatakterý obsahuje updatedItems aisLocked version/data z původních parsovaných dat a opravenou sadu .fallbackResourceIds
5. Serializace nového obsahu JSON zpět do nové řetězcové proměnné, reserializedData.
Místo původní serializedData vlastnosti použijte novou reserializedData proměnnou.
Nasaďte nový prostředek sešitu pomocí aktualizované šablony ARM.

Další kroky

Prozkoumejte, jak se sešity používají k výkonu nového prostředí pro přehledy úložiště.

Sdílet prostřednictvím