Gestire le cartelle di lavoro a livello di codice

Articolo
10/15/2024

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 relative a prestazioni ed errori specifici dell'organizzazione per le nuove app o macchine virtuali.
Distribuzione di report o dashboard standard tramite cartelle di lavoro per le risorse esistenti.

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

È possibile gestire due tipi di risorse di cartelle 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 l'Editor avanzato usando il pulsante </> sulla barra degli strumenti.
Verificare che venga visualizzata la scheda Modello raccolta.
Copiare negli Appunti il codice JSON del modello di raccolta.

Il modello di Azure 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 Azure 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 inserire i propri valori per le chiavi name e category. Per altre informazioni sui parametri vedere la sezione successiva.
Distribuire questo modello di Azure 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 Azure 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`	2019-10-17 (anteprima).
`type`	Sempre microsoft.insights/workbooktemplates.
`galleries`	Set di raccolte in cui visualizzare il 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. Si tratta in genere della 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, include i tipi `workbook` e `tsg` corrispondenti a raccolte di cartelle di lavoro diverse.

Raccolte

Gallery	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 in Gruppi di risorse	`microsoft.resources/subscriptions/resourcegroups`	`workbook`
Cartelle di lavoro in Microsoft Entra ID	`microsoft.aadiam/tenant`	`workbook`
Informazioni dettagliate sulla macchina virtuale in Macchine virtuali	`microsoft.compute/virtualmachines`	`insights`
Informazioni dettagliate macchina virtuale in Set di scalabilità di macchine virtuali	`microsoft.compute/virtualmachinescalesets`	`insights`

Modello di Azure 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 l'Editor avanzato selezionando </>.
Nell'editor impostare Tipo di modello su Modello di Azure Resource Manager.
Il modello di Azure Resource Manager 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 mostra 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 per la cartella di lavoro usato nella raccolta o nell'elenco do elementi salvati. Il nome 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 cartella di lavoro, `tsg`, Monitoraggio di Azure e così via.
`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. Per visualizzare la cartella di lavoro nella raccolta Cartelle di lavoro in Monitoraggio di Azure, usare la stringa Azure Monitor invece di un ID della risorsa.
`workbookId`	GUID univoco per l'istanza della cartella di lavoro. Usare `[newGuid()]` per creare automaticamente un nuovo GUID.
`kind`	Usato per 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 Azure 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 di cartelle di lavoro in cui viene visualizzata la nuova istanza della cartella di lavoro. Le opzioni includono:

Type	Posizione della raccolta
`workbook`	Posizione predefinita usata nella maggior parte dei report, tra cui la raccolta Cartelle di lavoro di Application Insights e Monitoraggio di Azure.
`tsg`	Raccolta Guide alla risoluzione dei problemi in Application Insights.
`usage`	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 Azure Resource Manager per una cartella di lavoro di Azure, sono spesso presenti collegamenti a 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 di Azure Resource Manager della cartella di lavoro esportata, senza ricorrere alla modifica delle stringhe. Il modello illustrato in questo esempio è pensato per essere usato con i dati non alterati come quelli 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 Azure Resource Manager esportato:

Esportare la cartella di lavoro come modello di Azure Resource Manager, come illustrato nella sezione precedente.
Nella sezione variables del modello:
1. Analizzare il valore serializedData 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 funzione union() per applicare le modifiche agli elementi JSON originali.
4. Creare un nuovo oggetto cartella di lavoro, updatedWorkbookData, che contiene updatedItems e i dati isLockedversion/ dai 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 variabile reserializedData invece della proprietà originale serializedData.
Distribuire la nuova risorsa della cartella di lavoro usando il modello di Azure Resource Manager aggiornato.

Passaggi successivi

Esplorare il modo in cui le cartelle di lavoro vengono usate per potenziare la nuova esperienza di Insights per l'archiviazione.

Condividi tramite