Gerir os livros de forma programática

  • Artigo

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

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

  • Implantação de relatórios analíticos 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.
  • Implantação de 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:

Modelo 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çado usando o <botão /> na barra de ferramentas.

  4. Certifique-se de que está no separador Modelo de Galeria .

    Screenshot that shows the Gallery Template tab.

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

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

  8. Implante esse modelo 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 pastas 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á para o Azure Monitor.
    2. Abrir Workbooks a partir do índice.
    3. Encontre o seu modelo na galeria sob a 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 Gerenciador de Recursos do Azure.
type Sempre microsoft.insights/workbooktemplates.
location O local do Azure onde a pasta de trabalho será criada.
apiVersion Pré-visualização 2019-10-17.
type Sempre microsoft.insights/workbooktemplates.
galleries O conjunto de galerias nas quais mostrar este 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 colocar o modelo.
gallery.order Um número que decide a ordem para mostrar o modelo dentro de uma categoria na galeria. Ordem inferior implica maior prioridade.
gallery.resourceType O tipo de recurso correspondente à galeria. Esse tipo geralmente é a cadeia de caracteres do tipo de recurso correspondente ao recurso (por exemplo, microsoft.operationalinsights/workspaces).
gallery.type Conhecido 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 espaço de trabalho 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 Kubernetes Microsoft.ContainerService/managedClusters workbook
Pastas de trabalho em grupos de recursos microsoft.resources/subscriptions/resourcegroups workbook
Pastas de trabalho no Microsoft Entra ID microsoft.aadiam/tenant workbook
VM Insights em máquinas virtuais microsoft.compute/virtualmachines insights
VM Insights em conjuntos de dimensionamento de máquinas virtuais microsoft.compute/virtualmachinescalesets insights

Modelo ARM para implantar uma instância 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çado selecionando< />.
  4. No editor, alterne Tipo de modelo para modelo ARM.
  5. O modelo ARM para criação aparece no editor. Copie o conteúdo e use como está ou mescle-o com um modelo maior que também implante o recurso de destino. Screenshot that shows how to get the ARM template from within the workbook UI.

Modelo do Resource Manager de exemplo

Este modelo mostra como implantar uma pasta de trabalho que exibe Hello World!o .

{
    "$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 do modelo

Parâmetro Description
workbookDisplayName O nome amigável da pasta de trabalho usada na Galeria ou na Lista Salva. Precisa ser exclusivo no escopo do grupo de recursos e da fonte.
workbookType A galeria onde a pasta de trabalho aparece. Os valores suportados incluem pasta de trabalho tsge Azure Monitor.
workbookSourceId A ID da instância de recurso à qual a pasta de trabalho será associada. A nova pasta de trabalho aparecerá relacionada a essa instância de recurso, por exemplo, no sumário do recurso em Pasta de trabalho. Se pretender que o seu livro apareça na galeria Livros no Azure Monitor, utilize a cadeia de caracteres Azure Monitor em vez de um ID de recurso.
workbookId O guid exclusivo para esta 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 compartilhado.
location O local do 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 a carga a ser usada na pasta de trabalho. Use o modelo 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 do Azure Monitor.
tsg A galeria de Guias de Solução de Problemas no Application Insights.
usage A galeria Mais em Uso no Application Insights.

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

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

O exemplo a seguir demonstra a personalização de um modelo 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 exportados do portal do Azure. Também é uma prática recomendada mascarar quaisquer valores confidenciais incorporados quando você gerencia pastas de trabalho programaticamente. Por esse motivo, o ID da assinatura e o grupo de recursos foram mascarados aqui. Nenhuma outra modificação foi feita no valor bruto de entrada serializedData .

{
  "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 ARM exportado:

  1. Exporte a pasta de trabalho como um modelo ARM, conforme explicado na seção anterior.
  2. Na seção do variables modelo:
    1. Analise o serializedData valor 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. Crie novos objetos JSON que representem apenas os itens/propriedades a serem modificados.
    3. Projete um novo conjunto de itens de conteúdo JSON (updatedItems) usando a union() função para aplicar as modificações aos itens JSON originais.
    4. Crie um novo objeto de pasta de trabalho, , updatedWorkbookDataque contenha updatedItems e osisLockedversion/dados dos dados analisados originais e um conjunto corrigido de fallbackResourceIds.
    5. Serialize o novo conteúdo JSON de volta em uma nova variável de cadeia de caracteres, reserializedData.
  3. Use a nova reserializedData variável no lugar da propriedade original serializedData .
  4. Implante o novo recurso de pasta de trabalho usando o modelo ARM atualizado.

Próximos passos

Explore como as pastas de trabalho estão sendo usadas para potencializar a nova experiência de insights de armazenamento.