Gestire le cartelle di lavoro a livello di codice

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

1. Aprire una cartella di lavoro che si vuole distribuire a livello di codice.

2. Passare alla modalità di modifica della cartella di lavoro selezionando Modifica.

3. Aprire l'Editor avanzato usando il pulsante </> sulla barra degli strumenti.

4. Verificare che venga visualizzata la scheda Modello raccolta.

   

5. Copiare negli Appunti il codice JSON del modello di raccolta.

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

7. Nell'oggetto galleries inserire i propri valori per le chiavi name e category. Per altre informazioni sui parametri vedere la sezione successiva.

8. Distribuire questo modello di Azure Resource Manager usando il portale di Azure, l'interfaccia della riga di comando o PowerShell.

9. 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

Raccolte

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

1. Aprire una cartella di lavoro che si vuole distribuire a livello di codice.
2. Passare alla modalità di modifica della cartella di lavoro selezionando Modifica.
3. Aprire l'Editor avanzato selezionando </>.
4. Nell'editor impostare Tipo di modello su Modello di Azure Resource Manager.
5. 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

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:

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:

1. Esportare la cartella di lavoro come modello di Azure Resource Manager, come illustrato nella sezione precedente.
2. 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.
3. Usare la nuova variabile reserializedData invece della proprietà originale serializedData.
4. 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.