Gerenciar pastas de trabalho de modo programático

Os proprietários de recursos podem criar e gerenciar suas pastas de trabalho programaticamente por meio de modelos do ARM (modelos do Azure Resource Manager).

Esse recurso pode ser útil em cenários como:

• Implantar relatórios de análise específicos da organização ou do domínio juntamente com implantações de recursos. Por exemplo, você pode implantar pastas de trabalho de desempenho e falha específicas da organização para seus novos aplicativos ou máquinas virtuais.
• Implantar relatórios ou painéis padrão usando pastas de trabalho para recursos existentes.

A pasta de trabalho será criada no sub/grupo de recursos desejado e com o conteúdo especificado nos modelos ARM.

Dois tipos de recursos de pasta de trabalho podem ser gerenciados programaticamente:

• Modelos de pasta de trabalho
• Instâncias de pasta de trabalho

Modelo do ARM para implantar um modelo de pasta de trabalho

1. Abra uma pasta de trabalho que você deseja implantar programaticamente.

2. Alterne a pasta de trabalho para o modo de edição selecionando Editar.

3. Abra o Editor Avançadousando o botão </> na barra de ferramentas.

4. Verifique se você está na guia Modelo de Galeria.

   

5. Copie o JSON no modelo da galeria para a área de transferência.

6. O exemplo de modelo do ARM a seguir implanta um modelo de pasta de trabalho na galeria de pastas de trabalho do Azure Monitor. Cole o JSON que você copiou no lugar de <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>. Para obter um modelo do ARM de referência que cria um modelo de pasta de trabalho, confira este repositório 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. No objeto galleries, preencha as chaves name e category com seus valores. Saiba mais sobre parâmetros na próxima seção.

8. Implante esse modelo do ARM usando o portal do Azure, a interface de linha de comando ou o PowerShell.

9. Abra o portal do Azure e vá para a galeria de pasta de trabalho escolhida no modelo ARM. No modelo de exemplo, vá para a galeria de pastas de trabalho do Azure Monitor:

   1. Abra o portal do Azure e vá até o Azure Monitor.
   2. Abra Workbooks no índice.
   3. Encontre seu modelo na galeria na categoria Deployed Templates. (Será um dos itens roxos.)

Parâmetros

Galerias

Modelo do ARM para implantar uma instância da pasta de trabalho

1. Abra uma pasta de trabalho que você deseja implantar programaticamente.
2. Alterne a pasta de trabalho para o modo de edição selecionando Editar.
3. Abra o Editor Avançado selecionando </>.
4. No editor, alterne Tipo de Modelo para Modelo do ARM.
5. O modelo do ARM para a criação é mostrado no editor. Copie o conteúdo e use-o no estado em que se encontra ou mescle-o com um modelo maior que também implante o recurso de destino.

Modelo ARM de exemplo

Este modelo mostra como implantar uma pasta de trabalho que exibe 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'))]"
        }
    }
}

Parâmetros de modelo

Tipos de pasta de trabalho

Os tipos de pasta de trabalho especificam o tipo de galeria de pasta de trabalho onde a nova instância da pasta de trabalho aparece. As opções incluem:

Trabalhe com dados de pasta de trabalho formatados em JSON no parâmetro de modelo serializedData

Quando você exporta um modelo do ARM para uma pasta de trabalho do Azure, geralmente há links de recursos fixos inseridos no parâmetro do modelo serializedData exportado. Esses links incluem valores potencialmente confidenciais, como ID de assinatura e nome do grupo de recursos e outros tipos de IDs de recursos.

O exemplo a seguir demonstra a personalização de um modelo do ARM de pasta de trabalho exportado, sem recorrer à manipulação de cadeia de caracteres. O padrão mostrado neste exemplo destina-se a trabalhar com os dados inalterados conforme exportados do portal do Azure. Também é uma prática recomendada mascarar quaisquer valores confidenciais inseridos ao gerenciar pastas de trabalho programaticamente. Por esse motivo, a ID da assinatura e o grupo de recursos foram mascarados aqui. Nenhuma outra modificação foi feita no valor de entrada serializedData bruto.

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

Neste exemplo, as etapas a seguir facilitam a personalização de um modelo do ARM exportado:

1. Exporte a pasta de trabalho como um modelo do ARM, conforme explicado na seção anterior.
2. Na seção do modelo variables:
   1. Analise o valor serializedData em uma variável de objeto JSON, que cria uma estrutura JSON, incluindo uma matriz de itens que representam o conteúdo da pasta de trabalho.
   2. Criar novos objetos JSON que representam apenas os itens/propriedades a serem modificados.
   3. Projete um novo conjunto de itens de conteúdo JSON (updatedItems) usando a função union() para aplicar as modificações aos itens JSON originais.
   4. Crie um objeto de pasta de trabalho, updatedWorkbookData, que contém updatedItems e os dados version/isLocked dos dados originais analisados e um conjunto corrigido de fallbackResourceIds.
   5. Serializar o novo conteúdo JSON de volta em uma nova variável de cadeia de caracteres, reserializedData.
3. Usar a nova variável reserializedData no lugar da propriedade original serializedData.
4. Implante o novo recurso de pasta de trabalho usando o modelo do ARM atualizado.

Próximas etapas

Saiba como as pastas de trabalho estão sendo usadas para capacitar a nova Experiência de insights de armazenamento.