Programová správa sešitů

  • Článek

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:

Šablona ARM pro nasazení šablony sešitu

  1. Otevřete sešit, který chcete nasadit programově.

  2. Výběrem možnosti Upravit přepněte sešit do režimu úprav.

  3. Otevřete Rozšířený editor pomocí <tlačítka /> na panelu nástrojů.

  4. Ujistěte se, že jste na kartě Šablona galerie.

    Screenshot that shows the Gallery Template tab.

  5. Zkopírujte JSON v šabloně galerie do schránky.

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

  7. V objektu galleries vyplňte name hodnoty a category klíče. Další informace o parametrech najdete v další části.

  8. Nasaďte tuto šablonu ARM pomocí webu Azure Portal, rozhraní příkazového řádku nebo PowerShellu.

  9. 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. Aplikace Přehledy má například typyworkbook, 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ího počítače 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 Přehledy aplikace microsoft.insights/components workbook
Průvodci odstraňováním potíží v Přehledy aplikací microsoft.insights/components tsg
Využití v Přehledy aplikací 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čů 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

  1. Otevřete sešit, který chcete nasadit programově.
  2. Výběrem možnosti Upravit přepněte sešit do režimu úprav.
  3. Otevřete Rozšířený editor výběrem <příkazu />.
  4. V editoru přepněte typ šablony na šablonu ARM.
  5. Š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. Screenshot that shows how to get the ARM template from within the workbook UI.

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 tsga 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 služby Application Přehledy a Azure Monitoru.
tsg Galerie Průvodci odstraňováním potíží v Přehledy aplikace
usage The More gallery under Usage in Application Přehledy.

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:

  1. Exportujte sešit jako šablonu ARM, jak je vysvětleno v předchozí části.
  2. 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 aisLockedversion/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.
  3. Místo původní serializedData vlastnosti použijte novou reserializedData proměnnou.
  4. 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ě.