Поделиться через

Программное управление книгами

  • Статья

Владельцы ресурсов могут создавать книги и управлять ими программным способом с помощью шаблонов Azure Resource Manager (шаблонов ARM).

Эта возможность может быть полезна в таких сценариях:

  • Развертывание отчетов организационной или доменной аналитики вместе с развертываниями ресурсов. Например, вы можете развернуть книги производительности и сбоев для новых приложений или виртуальных машин, относящихся к организации.
  • Развертывание стандартных отчетов или панелей мониторинга с помощью книг для существующих ресурсов.

Книга будет создана в нужной подгруппе или группе ресурсов и содержимом, указанным в шаблонах ARM.

Два типа ресурсов книги можно управлять программным способом:

Шаблон ARM для развертывания шаблона книги

  1. Откройте книгу, которую требуется развернуть программно.

  2. Переведите книгу в режим правки, выбрав Изменить.

  3. Откройте Расширенный редактор с помощью кнопки </> на панели инструментов.

  4. Убедитесь, что вы находитесь на вкладке "Шаблон коллекции".

    Screenshot that shows the Gallery Template tab.

  5. Скопируйте JSON из шаблона коллекции в буфер обмена.

  6. Следующий пример шаблона ARM развертывает шаблон книги в коллекции книг Azure Monitor. Вставьте скопированный код JSON вместо <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>. Справочный шаблон ARM, создающий шаблон книги, см . в этом репозитории 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 заполните name значения и category ключи. Дополнительные сведения о параметрах приведены в следующем разделе.

  8. Разверните этот шаблон ARM с помощью портал Azure, интерфейса командной строки или PowerShell.

  9. Откройте портал Azure и перейдите в коллекцию книг, выбранную в шаблоне ARM. В примере шаблона перейдите в коллекцию книг Azure Monitor:

    1. Откройте портал Azure и перейдите в Azure Monitor.
    2. Откройте Workbooks из оглавление.
    3. Найдите шаблон в коллекции в категории Deployed Templates. (Это будет один из фиолетовых элементов.)

Параметры

Параметры Описание
name Имя ресурса шаблона книги в Azure Resource Manager.
type Всегда microsoft.insights/workbooktemplates.
location Расположение Azure, в котором будет создана книга.
apiVersion Предварительная версия 2019-10-17.
type Всегда microsoft.insights/workbooktemplates.
galleries Набор коллекций, в которых отображается этот шаблон книги.
gallery.name Понятное имя шаблона книги в коллекции.
gallery.category Группа в коллекции, в которой будет размещаться шаблон.
gallery.order Число, которое определяет порядок отображения шаблона в категории в коллекции. Более низкий порядок подразумевает более высокий приоритет.
gallery.resourceType Тип ресурса, соответствующий коллекции. Этот тип обычно представляет собой строку типа ресурса, соответствующую ресурсу (например, microsoft.operationalinsights/workspaces).
gallery.type Называется типом книги. Этот уникальный ключ отличает коллекцию в типе ресурса. Например, Аналитика приложения имеют типы workbook и tsg соответствующие разным коллекциям книг.

Коллекции

Галерея Тип ресурса Тип книги
Книги в Azure Monitor Azure Monitor workbook
Книги VM в Azure Monitor Azure Monitor vm-insights
Книги в рабочей области Log Analytics microsoft.operationalinsights/workspaces workbook
Книги в Application Insights microsoft.insights/components workbook
Руководства по устранению неполадок в Application Insights microsoft.insights/components tsg
Потребление в Application Insights microsoft.insights/components usage
Книги в службе Kubernetes Microsoft.ContainerService/managedClusters workbook
Книги в группах ресурсов microsoft.resources/subscriptions/resourcegroups workbook
Книги в идентификаторе Microsoft Entra microsoft.aadiam/tenant workbook
Аналитика виртуальной машины на виртуальных машинах microsoft.compute/virtualmachines insights
Аналитика VM в масштабируемых наборах виртуальных машин microsoft.compute/virtualmachinescalesets insights

Шаблон ARM для развертывания экземпляра книги

  1. Откройте книгу, которую требуется развернуть программно.
  2. Переведите книгу в режим правки, выбрав Изменить.
  3. Откройте Расширенный редактор, выбрав< />.
  4. В редакторе переключите тип шаблона на шаблон ARM.
  5. Шаблон ARM для создания отображается в редакторе. Скопируйте содержимое и используйте "как есть" или объедините его с шаблоном большего размера, который также развертывает целевой ресурс. Screenshot that shows how to get the ARM template from within the workbook UI.

Образец шаблона ARM

В этом шаблоне показано, как развернуть книгу, которая отображается 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'))]"
        }
    }
}

Параметры шаблона

Параметр Описание
workbookDisplayName Понятное имя книги, используемой в коллекции или сохраненном списке. Необходимо быть уникальным в область группы ресурсов и источника.
workbookType Коллекция, в которой появится книга. Поддерживаемые значения включают книгу и tsgAzure Monitor.
workbookSourceId Идентификатор экземпляра ресурса, с которым будет связана книга. Новая книга будет отображаться, связанная с этим экземпляром ресурса, например, в оглавлении ресурса в книге. Если вы хотите, чтобы книга отображалась в коллекции книг в Azure Monitor, используйте строку Azure Monitor вместо идентификатора ресурса.
workbookId Уникальный GUID этого экземпляра книги. Используется [newGuid()] для автоматического создания нового guid.
kind Указывает, является созданная книга общей. Для всех новых книг задается общий режим доступа.
location Расположение Azure, в котором будет создана книга. Используется [resourceGroup().location] для его создания в том же расположении, что и группа ресурсов.
serializedData Имеет содержимое или полезные данные для использования в книге. Используйте шаблон ARM из пользовательского интерфейса книг, чтобы получить это значение.

Типы книг

Типы книг указывают тип коллекции книг, в которой отображается новый экземпляр книги. Возможные варианты:

Тип Расположение коллекции
workbook Значение по умолчанию используется в большинстве отчетов, включая коллекцию книг приложений Аналитика и Azure Monitor.
tsg Коллекция "Руководства по устранению неполадок" в Application Аналитика.
usage Коллекция More в разделе Usage in Application Аналитика.

Работа с данными книги в формате JSON в параметре шаблона serializedData

При экспорте шаблона ARM для книги Azure часто существуют фиксированные ссылки на ресурсы, внедренные в экспортируемый serializedData параметр шаблона. Эти ссылки включают потенциально конфиденциальные значения, такие как идентификатор подписки и имя группы ресурсов, а также другие типы идентификаторов ресурсов.

В следующем примере демонстрируется настройка экспортированного шаблона ARM книги, не прибегая к обработке строк. Шаблон, показанный в этом примере, предназначен для работы с неизмененными данными, экспортированными из портала Azure. Рекомендуется также маскировать все внедренные конфиденциальные значения при программном управлении книгами. По этой причине идентификатор подписки и группа ресурсов были маскированы здесь. Никакие другие изменения не были внесены в необработанное входящее значение 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#"
}

В этом примере следующие действия упрощают настройку экспортированного шаблона ARM:

  1. Экспорт книги в виде шаблона ARM, как описано в предыдущем разделе.
  2. В разделе шаблона variables :
    1. serializedData Анализ значения в переменную объекта JSON, которая создает структуру JSON, включая массив элементов, представляющих содержимое книги.
    2. Создайте новые объекты JSON, представляющие только изменяемые элементы и свойства.
    3. Проект нового набора элементов содержимого JSON (updatedItems) с помощью union() функции для применения изменений к исходным элементам JSON.
    4. Создайте объект книги, updatedWorkbookDataсодержащий updatedItems иisLockedversion/данные из исходных проанализированных данных и исправленный набор.fallbackResourceIds
    5. Сериализируйте новое содержимое JSON обратно в новую строковую переменную reserializedData.
  3. Используйте новую переменную reserializedData вместо исходного свойства serializedData.
  4. Разверните новый ресурс книги с помощью обновленного шаблона ARM.

Следующие шаги

Узнайте, как использовать книги для нового интерфейса Storage Insights.