Hantera arbetsböcker programmässigt

Artikel
11/05/2024

Resursägare kan skapa och hantera sina arbetsböcker programmatiskt via Azure Resource Manager-mallar (ARM-mallar).

Den här funktionen kan vara användbar i scenarier som:

Distribuera organisations- eller domänspecifika analysrapporter tillsammans med resursdistributioner. Du kan till exempel distribuera organisationsspecifika arbetsböcker för prestanda och fel för dina nya appar eller virtuella datorer.
Distribuera standardrapporter eller instrumentpaneler med hjälp av arbetsböcker för befintliga resurser.

Arbetsboken skapas i önskad under-/resursgrupp och med det innehåll som anges i ARM-mallarna.

Två typer av arbetsboksresurser kan hanteras programmatiskt:

Arbetsboksmallar
Arbetsboksinstanser

ARM-mall för att distribuera en arbetsboksmall

Öppna en arbetsbok som du vill distribuera programmatiskt.
Växla arbetsboken till redigeringsläge genom att välja Redigera.
Öppna Avancerad redigerare med hjälp <av knappen />i verktygsfältet.
Kontrollera att du är på fliken Gallerimall .
Kopiera JSON i gallerimallen till Urklipp.

Följande ARM-exempelmall distribuerar en arbetsboksmall till Azure Monitor-arbetsboksgalleriet. Klistra in den JSON som du kopierade i stället för <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>. En ARM-referensmall som skapar en arbetsboksmall finns i den här GitHub-lagringsplatsen.

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

galleries I -objektet fyller du i name nycklarna och category med dina värden. Läs mer om parametrar i nästa avsnitt.
Distribuera den här ARM-mallen med hjälp av antingen Azure Portal, kommandoradsgränssnittet eller PowerShell.
Öppna Azure Portal och gå till arbetsboksgalleriet som valts i ARM-mallen. I exempelmallen går du till Azure Monitor-arbetsboksgalleriet:
1. Öppna Azure Portal och gå till Azure Monitor.
2. Öppna Workbooks från innehållsförteckningen.
3. Hitta mallen i galleriet under kategorin Deployed Templates. (Det blir ett av de lila objekten.)

Parameters

Parameters	Förklaring
`name`	Namnet på arbetsboksmallresursen i Azure Resource Manager.
`type`	Alltid microsoft.insights/workbooktemplates.
`location`	Den Azure-plats där arbetsboken ska skapas.
`apiVersion`	Förhandsversion 2019-10-17.
`type`	Alltid microsoft.insights/workbooktemplates.
`galleries`	Den uppsättning gallerier där arbetsboksmallen ska visas.
`gallery.name`	Det egna namnet på arbetsboksmallen i galleriet.
`gallery.category`	Gruppen i galleriet där mallen ska placeras.
`gallery.order`	Ett tal som bestämmer ordningen för att visa mallen i en kategori i galleriet. Lägre ordning innebär högre prioritet.
`gallery.resourceType`	Den resurstyp som motsvarar galleriet. Den här typen är vanligtvis den resurstypssträng som motsvarar resursen (till exempel microsoft.operationalinsights/workspaces).
`gallery.type`	Kallas för arbetsbokstyp. Den här unika nyckeln särskiljer galleriet inom en resurstyp. Application Insights har till exempel typerna `workbook` och `tsg` som motsvarar olika arbetsboksgallerier.

Gallerier

Galleri	Resurstyp	Arbetsbokstyp
Arbetsböcker i Azure Monitor	`Azure Monitor`	`workbook`
VM Insights i Azure Monitor	`Azure Monitor`	`vm-insights`
Arbetsböcker på Log Analytics-arbetsytan	`microsoft.operationalinsights/workspaces`	`workbook`
Arbetsböcker i Application Insights	`microsoft.insights/components`	`workbook`
Felsökningsguider i Application Insights	`microsoft.insights/components`	`tsg`
Användning i Application Insights	`microsoft.insights/components`	`usage`
Arbetsböcker i Kubernetes-tjänsten	`Microsoft.ContainerService/managedClusters`	`workbook`
Arbetsböcker i resursgrupper	`microsoft.resources/subscriptions/resourcegroups`	`workbook`
Arbetsböcker i Microsoft Entra-ID	`microsoft.aadiam/tenant`	`workbook`
VM Insights på virtuella datorer	`microsoft.compute/virtualmachines`	`insights`
VM Insights i VM-skalningsuppsättningar	`microsoft.compute/virtualmachinescalesets`	`insights`

ARM-mall för att distribuera en arbetsboksinstans

Öppna en arbetsbok som du vill distribuera programmatiskt.
Växla arbetsboken till redigeringsläge genom att välja Redigera.
Öppna Avancerad redigerare genom att <välja />.
I redigeraren växlar du Malltyp till ARM-mall.
ARM-mallen för att skapa visas i redigeraren. Kopiera innehållet och använd som det är eller sammanfoga det med en större mall som även distribuerar målresursen.

ARM-exempelmall

Den här mallen visar hur du distribuerar en arbetsbok som visar 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'))]"
        }
    }
}

Mallparametrar

Parameter	Description
`workbookDisplayName`	Det egna namnet på arbetsboken som används i galleriet eller den sparade listan. Måste vara unikt i resursgruppens och källans omfång.
`workbookType`	Galleriet där arbetsboken visas. Värden som stöds är arbetsbok, `tsg`och Azure Monitor.
`workbookSourceId`	ID:t för resursinstansen som arbetsboken ska associeras till. Den nya arbetsboken visas relaterad till den här resursinstansen, till exempel i resursens innehållsförteckning under Arbetsbok. Om du vill att arbetsboken ska visas i galleriet Arbetsböcker i Azure Monitor använder du strängen Azure Monitor i stället för ett resurs-ID.
`workbookId`	Det unika guid för den här arbetsboksinstansen. Använd `[newGuid()]` för att automatiskt skapa ett nytt guid.
`kind`	Används för att ange om den skapade arbetsboken delas. Alla nya arbetsböcker använder det delade värdet.
`location`	Den Azure-plats där arbetsboken ska skapas. Använd `[resourceGroup().location]` för att skapa den på samma plats som resursgruppen.
`serializedData`	Innehåller det innehåll eller den nyttolast som ska användas i arbetsboken. Använd ARM-mallen från arbetsbokens användargränssnitt för att hämta värdet.

Arbetsbokstyper

Arbetsbokstyper anger den arbetsboksgallerityp där den nya arbetsboksinstansen visas. Alternativen inkluderar:

Typ	Galleriplats
`workbook`	Standardvärdet som används i de flesta rapporter, inklusive galleriet Arbetsböcker för Application Insights och Azure Monitor.
`tsg`	Galleriet Felsökningsguider i Application Insights.
`usage`	Galleriet Mer under Användning i Application Insights.

Arbeta med JSON-formaterade arbetsboksdata i parametern serializedData-mall

När du exporterar en ARM-mall för en Azure-arbetsbok finns det ofta fasta resurslänkar inbäddade i den exporterade serializedData mallparametern. De här länkarna innehåller potentiellt känsliga värden som prenumerations-ID och resursgruppsnamn och andra typer av resurs-ID:t.

I följande exempel visas anpassningen av en exporterad ARM-mall för arbetsboken, utan att använda strängmanipulering. Mönstret som visas i det här exemplet är avsett att fungera med oförändrade data som exporteras från Azure Portal. Det är också en bra idé att maskera alla inbäddade känsliga värden när du hanterar arbetsböcker programmatiskt. Därför har prenumerations-ID:t och resursgruppen maskerats här. Inga andra ändringar har gjorts i det råa inkommande serializedData värdet.

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

I det här exemplet underlättar följande steg anpassningen av en exporterad ARM-mall:

Exportera arbetsboken som en ARM-mall enligt beskrivningen i föregående avsnitt.
I mallens variables avsnitt:
1. Parsa serializedData värdet till en JSON-objektvariabel, som skapar en JSON-struktur, inklusive en matris med objekt som representerar innehållet i arbetsboken.
2. Skapa nya JSON-objekt som endast representerar de objekt/egenskaper som ska ändras.
3. Projicera en ny uppsättning JSON-innehållsobjekt (updatedItems) med hjälp union() av funktionen för att tillämpa ändringarna på de ursprungliga JSON-objekten.
4. Skapa ett nytt arbetsboksobjekt, updatedWorkbookData, som innehåller updatedItems och version/isLocked data från de ursprungliga tolkade data och en korrigerad uppsättning med fallbackResourceIds.
5. Serialisera det nya JSON-innehållet tillbaka till en ny strängvariabel, reserializedData.
Använd den nya reserializedData variabeln i stället för den ursprungliga serializedData egenskapen.
Distribuera den nya arbetsboksresursen med hjälp av den uppdaterade ARM-mallen.

Nästa steg

Utforska hur arbetsböcker används för att driva den nya storage insights-upplevelsen.

Dela via