Gestire le cartelle di lavoro a livello di codice

Articolo
10/18/2023

I proprietari delle risorse possono creare e gestire le cartelle di lavoro a livello di codice tramite i modelli di Azure Resource Manager (modelli arm).

Questa funzionalità può essere utile in scenari come:

Distribuzione di report di analisi specifici del dominio o dell'organizzazione, insieme alle distribuzioni di risorse. Ad esempio, è possibile distribuire cartelle di lavoro di prestazioni e errori specifiche dell'organizzazione per le nuove app o le macchine virtuali.
Distribuzione di report o dashboard standard usando cartelle di lavoro per le risorse esistenti.

La cartella di lavoro verrà creata nel sottogruppo/gruppo di risorse desiderato e con il contenuto specificato nei modelli di Resource Manager.

È possibile gestire due tipi di risorse della cartella di lavoro a livello di codice:

Modelli di cartella di lavoro
Istanze di cartella di lavoro

Modello di Resource Manager per la distribuzione di un modello di cartella di lavoro

Aprire una cartella di lavoro che si vuole distribuire a livello di codice.
Passare alla modalità di modifica della cartella di lavoro selezionando Modifica.
Aprire il Editor avanzato usando il< pulsante />sulla barra degli strumenti.
Assicurarsi di essere nella scheda Modello raccolta.
Copiare negli Appunti il codice JSON del modello di raccolta.

Il modello di Resource Manager di esempio seguente distribuisce un modello di cartella di lavoro nella raccolta di cartelle di lavoro di Monitoraggio di Azure. Incollare il codice JSON copiato al posto di <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>. Per un modello di Resource Manager di riferimento che crea un modello di cartella di lavoro, vedere questo repository GitHub.

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

Nell'oggetto galleries compilare le chiavi e category con i name valori. Per altre informazioni sui parametri vedere la sezione successiva.
Distribuire questo modello di Resource Manager usando il portale di Azure, l'interfaccia della riga di comando o PowerShell.
Aprire il portale di Azure e passare alla raccolta di cartelle di lavoro scelta nel modello di Resource Manager. Nel modello di esempio passare alla raccolta di cartelle di lavoro di Monitoraggio di Azure:
1. Aprire il portale di Azure e passare a Monitoraggio di Azure.
2. Aprire Workbooks dal sommario.
3. Trovare il modello nella raccolta nella categoria Deployed Templates. (Sarà uno degli elementi viola.

Parametri

Parametri	Spiegazione
`name`	Nome della risorsa modello di cartella di lavoro in Azure Resource Manager.
`type`	Sempre microsoft.insights/workbooktemplates.
`location`	Posizione di Azure in cui verrà creata la cartella di lavoro.
`apiVersion`	Anteprima 2019-10-17.
`type`	Sempre microsoft.insights/workbooktemplates.
`galleries`	Set di raccolte in cui visualizzare questo modello di cartella di lavoro.
`gallery.name`	Nome descrittivo del modello di cartella di lavoro nella raccolta.
`gallery.category`	Gruppo nella raccolta in cui inserire il modello.
`gallery.order`	Numero che determina l'ordine di visualizzazione del modello all'interno di una categoria nella raccolta. Un valore inferiore dell'ordine implica una priorità più elevata.
`gallery.resourceType`	Tipo di risorsa corrispondente alla raccolta. Questo tipo è in genere la stringa del tipo di risorsa corrispondente alla risorsa, ad esempio microsoft.operationalinsights/workspaces.
`gallery.type`	Definito tipo di cartella di lavoro. Questa chiave univoca differenzia la raccolta all'interno di un tipo di risorsa. Application Insights, ad esempio, ha i tipi `workbook` e `tsg` che corrispondono a raccolte di cartelle di lavoro diverse.

Raccolte

Raccolta	Tipo di risorsa	Tipo di cartella di lavoro
Cartelle di lavoro in Monitoraggio di Azure	`Azure Monitor`	`workbook`
Informazioni dettagliate macchina virtuale in Monitoraggio di Azure	`Azure Monitor`	`vm-insights`
Cartelle di lavoro nell'area di lavoro Log Analytics	`microsoft.operationalinsights/workspaces`	`workbook`
Cartelle di lavoro in Application Insights	`microsoft.insights/components`	`workbook`
Guide alla risoluzione dei problemi in Application Insights	`microsoft.insights/components`	`tsg`
Utilizzo in Application Insights	`microsoft.insights/components`	`usage`
Cartelle di lavoro in Servizio Kubernetes	`Microsoft.ContainerService/managedClusters`	`workbook`
Cartelle di lavoro nei gruppi di risorse	`microsoft.resources/subscriptions/resourcegroups`	`workbook`
Cartelle di lavoro in Microsoft Entra ID	`microsoft.aadiam/tenant`	`workbook`
Informazioni dettagliate macchina virtuale nelle macchine virtuali	`microsoft.compute/virtualmachines`	`insights`
Informazioni dettagliate macchina virtuale in Set di scalabilità di macchine virtuali	`microsoft.compute/virtualmachinescalesets`	`insights`

Modello di Resource Manager per la distribuzione di un'istanza della cartella di lavoro

Aprire una cartella di lavoro che si vuole distribuire a livello di codice.
Passare alla modalità di modifica della cartella di lavoro selezionando Modifica.
Aprire il Editor avanzato selezionando </>.
Nell'editor impostare Il tipo di modello sul modello di Resource Manager.
Il modello arm per la creazione viene visualizzato nell'editor. Copiare il contenuto e usarlo così com'è o unirlo con un modello più ampio che consente anche la distribuzione della risorsa di destinazione.

Modello di Resource Manager di esempio

Questo modello illustra come distribuire una cartella di lavoro che visualizza 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'))]"
        }
    }
}

Parametri del modello

Parametro	Descrizione
`workbookDisplayName`	Nome descrittivo della cartella di lavoro utilizzata nella raccolta o nell'elenco salvato. Deve essere univoco nell'ambito del gruppo di risorse e dell'origine.
`workbookType`	Raccolta in cui viene visualizzata la cartella di lavoro. I valori supportati includono cartelle di lavoro, `tsg`e Monitoraggio di Azure.
`workbookSourceId`	ID dell'istanza della risorsa a cui verrà associata la cartella di lavoro. La nuova cartella di lavoro verrà visualizzata in relazione a questa istanza di risorsa, ad esempio, nel sommario della risorsa in Cartella di lavoro. Se si vuole che la cartella di lavoro venga visualizzata nella raccolta Cartelle di lavoro in Monitoraggio di Azure, usare la stringa Monitoraggio di Azure anziché un ID risorsa.
`workbookId`	GUID univoco per l'istanza della cartella di lavoro. Usare `[newGuid()]` per creare automaticamente un nuovo GUID.
`kind`	Consente di specificare se la cartella di lavoro creata è condivisa. Tutte le nuove cartelle di lavoro useranno il valore condiviso.
`location`	Posizione di Azure in cui verrà creata la cartella di lavoro. Usare `[resourceGroup().location]` per crearlo nella stessa posizione del gruppo di risorse.
`serializedData`	Contiene il contenuto o il payload da usare nella cartella di lavoro. Usare il modello di Resource Manager dall'interfaccia utente delle cartelle di lavoro per ottenere il valore.

Tipi di cartella di lavoro

I tipi di cartella di lavoro specificano il tipo di raccolta cartelle di lavoro in cui viene visualizzata la nuova istanza della cartella di lavoro. Le opzioni includono:

Tipo	Posizione della raccolta
`workbook`	Impostazione predefinita usata nella maggior parte dei report, inclusa la raccolta Cartelle di lavoro di Application Insights e Monitoraggio di Azure.
`tsg`	Raccolta guide alla risoluzione dei problemi in Application Insights.
`usage`	La raccolta Altro in Utilizzo in Application Insights.

Usare i dati della cartella di lavoro in formato JSON nel parametro del modello serializedData

Quando si esporta un modello di Resource Manager per una cartella di lavoro di Azure, sono spesso presenti collegamenti di risorse fissi incorporati nel parametro del modello esportato serializedData . Questi collegamenti includono valori potenzialmente sensibili, ad esempio l'ID sottoscrizione e il nome del gruppo di risorse e altri tipi di ID risorsa.

Nell'esempio seguente viene illustrata la personalizzazione di un modello arm della cartella di lavoro esportata, senza ricorrere alla modifica delle stringhe. Il modello illustrato in questo esempio è destinato a funzionare con i dati non alterati come esportati dal portale di Azure. È anche consigliabile mascherare tutti i valori sensibili incorporati quando si gestiscono cartelle di lavoro a livello di codice. Per questo motivo, l'ID sottoscrizione e il gruppo di risorse sono stati mascherati qui. Non sono state apportate altre modifiche al valore in ingresso serializedData non elaborato.

{
  "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 questo esempio, i passaggi seguenti semplificano la personalizzazione di un modello di Resource Manager esportato:

Esportare la cartella di lavoro come modello di Resource Manager, come illustrato nella sezione precedente.
Nella sezione del variables modello:
1. Analizzare il serializedData valore in una variabile oggetto JSON, che crea una struttura JSON che include una matrice di elementi che rappresentano il contenuto della cartella di lavoro.
2. Creare nuovi oggetti JSON che rappresentano solo gli elementi o le proprietà da modificare.
3. Proiettare un nuovo set di elementi di contenuto JSON (updatedItems) usando la union() funzione per applicare le modifiche agli elementi JSON originali.
4. Creare un nuovo oggetto cartella di lavoro, updatedWorkbookData, che contiene updatedItems e iisLockedversion/dati dei dati analizzati originali e un set corretto di .fallbackResourceIds
5. Serializzare di nuovo il nuovo contenuto JSON in una nuova variabile stringa, reserializedData.
Usare la nuova reserializedData variabile al posto della proprietà originale serializedData .
Distribuire la nuova risorsa della cartella di lavoro usando il modello di Resource Manager aggiornato.

Passaggi successivi

Esplorare il modo in cui le cartelle di lavoro vengono usate per potenziare la nuova esperienza di informazioni dettagliate Archiviazione.

Condividi tramite