Gerenciar pastas de trabalho de modo programático

Artigo
11/05/2024

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

Abra uma pasta de trabalho que você deseja implantar programaticamente.
Alterne a pasta de trabalho para o modo de edição selecionando Editar.
Abra o Editor Avançadousando o botão </> na barra de ferramentas.
Verifique se você está na guia Modelo de Galeria.
Copie o JSON no modelo da galeria para a área de transferência.

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

No objeto galleries, preencha as chaves name e category com seus valores. Saiba mais sobre parâmetros na próxima seção.
Implante esse modelo do ARM usando o portal do Azure, a interface de linha de comando ou o PowerShell.
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

Parâmetros	Explicação
`name`	O nome do recurso de modelo de pasta de trabalho no Azure Resource Manager.
`type`	Sempre microsoft.insights/workbooktemplates.
`location`	A localização no Azure onde a pasta de trabalho será criada.
`apiVersion`	Versão prévia de 17/10/2019
`type`	Sempre microsoft.insights/workbooktemplates.
`galleries`	O conjunto de galerias na quais mostrar esse modelo de pasta de trabalho.
`gallery.name`	O nome amigável do modelo de pasta de trabalho na galeria.
`gallery.category`	O grupo na galeria no qual o modelo será colocado.
`gallery.order`	Um número que decide a ordem para mostrar o modelo dentro de uma categoria na galeria. Uma ordem inferior implica em uma prioridade mais alta.
`gallery.resourceType`	O tipo de recurso correspondente à galeria. Este tipo é geralmente a cadeia de caracteres do tipo de recurso correspondente ao recurso (por exemplo, microsoft.operationalinsights/workspaces).
`gallery.type`	Referido como tipo de pasta de trabalho. Essa chave exclusiva diferencia a galeria dentro de um tipo de recurso. O Application Insights, por exemplo, tem os tipos `workbook` e `tsg` que correspondem a diferentes galerias de pastas de trabalho.

Galerias

Galeria	Tipo de recurso	Tipo de pasta de trabalho
Pastas de trabalho no Azure Monitor	`Azure Monitor`	`workbook`
Insights de VM no Azure Monitor	`Azure Monitor`	`vm-insights`
Pastas de Trabalho no workspace do Log Analytics	`microsoft.operationalinsights/workspaces`	`workbook`
Pastas de trabalho no Application Insights	`microsoft.insights/components`	`workbook`
Guias de solução de problemas no Application Insights	`microsoft.insights/components`	`tsg`
Uso no Application Insights	`microsoft.insights/components`	`usage`
Pastas de trabalho no serviço do Kubernetes	`Microsoft.ContainerService/managedClusters`	`workbook`
Pastas de Trabalho em Grupos de recursos	`microsoft.resources/subscriptions/resourcegroups`	`workbook`
Workbooks no Microsoft Entra ID	`microsoft.aadiam/tenant`	`workbook`
Insights de VM em Máquinas virtuais	`microsoft.compute/virtualmachines`	`insights`
Insights de VM em conjuntos de dimensionamento de máquinas virtuais	`microsoft.compute/virtualmachinescalesets`	`insights`

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

Abra uma pasta de trabalho que você deseja implantar programaticamente.
Alterne a pasta de trabalho para o modo de edição selecionando Editar.
Abra o Editor Avançado selecionando </>.
No editor, alterne Tipo de Modelo para Modelo do ARM.
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

Parâmetro	Descrição
`workbookDisplayName`	O nome amigável da pasta de trabalho usada no Galeria ou Lista salva. Precisa ser exclusivo no escopo do grupo de recursos e da origem.
`workbookType`	A galeria em que a pasta de trabalho é exibida. Os valores com suporte incluem pasta de trabalho, `tsg` e Azure Monitor.
`workbookSourceId`	A ID da instância de recurso com a qual a pasta de trabalho será associada. A nova pasta de trabalho aparecerá relacionada a esta instância do recurso, por exemplo, no sumário do recurso em Pasta de Trabalho. Se você deseja que sua pasta de trabalho apareça na galeria Pastas de Trabalho no Azure Monitor, use a cadeia de caracteres Azure Monitor em vez de uma ID de recurso.
`workbookId`	O GUID exclusivo para essa instância de pasta de trabalho. Use `[newGuid()]` para criar automaticamente um novo GUID.
`kind`	Usado para especificar se a pasta de trabalho criada é compartilhada. Todas as novas pastas de trabalho usarão o valor compartilhada.
`location`	A localização no Azure onde a pasta de trabalho será criada. Use `[resourceGroup().location]` para criá-lo no mesmo local que o grupo de recursos.
`serializedData`	Contém o conteúdo ou o payload a ser usado na pasta de trabalho. Use o modelo do ARM da interface do usuário das pastas de trabalho para obter o valor.

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:

Tipo	Localização da galeria
`workbook`	O padrão usado na maioria dos relatórios, incluindo a galeria Pastas de trabalho do Application Insights e Azure Monitor.
`tsg`	A galeria Guias de Resolução de problemas no Application Insights.
`usage`	A galeria Mais em Uso no Application Insights.

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:

Exporte a pasta de trabalho como um modelo do ARM, conforme explicado na seção anterior.
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.
Usar a nova variável reserializedData no lugar da propriedade original serializedData.
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.

Compartilhar via