以编程方式管理工作簿Programmatically manage workbooks

资源所有者可以选择通过资源管理器模板以编程方式创建和管理其工作簿。Resource owners have the option to create and manage their workbooks programmatically via Resource Manager templates.

在如下所述的场景中,此方法可能很有用:This can be useful in scenarios like:

  • 连同资源部署一起部署特定于组织或域的分析报表。Deploying org- or domain-specific analytics reports along with resources deployments. 例如,可为新的应用或虚拟机部署特定于组织的性能和故障工作簿。For instance, you may deploy org-specific performance and failure workbooks for your new apps or virtual machines.
  • 使用工作簿为现有资源部署标准报表或仪表板。Deploying standard reports or dashboards using workbooks for existing resources.

将使用资源管理器模板中指定的内容,在所需的子组/资源组中创建工作簿。The workbook will be created in the desired sub/resource-group and with the content specified in the Resource Manager templates.

可通过编程方式管理两种类型的工作簿资源:There are two types of workbook resources that can be managed programmatically:

用于部署工作簿模板的 Azure 资源管理器模板Azure Resource Manager template for deploying a workbook template

  1. 打开要以编程方式部署的工作簿。Open a workbook you want to deploy programmatically.

  2. 单击“编辑”工具栏项,将工作簿切换到编辑模式。Switch the workbook to edit mode by clicking on the Edit toolbar item.

  3. 使用工具栏上的 </> 按钮打开“高级编辑器”。Open the Advanced Editor using the </> button on the toolbar.

  4. 确保位于“库模板”选项卡上。Ensure you are on the Gallery Template tab.

    “库模板”选项卡

  5. 将库模板中的 JSON 复制到剪贴板。Copy the JSON in the gallery template to the clipboard.

  6. 下面是一个示例 Azure 资源管理器模板,它将一个工作簿模板部署到 Azure Monitor 工作簿库。Below is a sample Azure Resource Manager template that deploys a workbook template to Azure Monitor workbook gallery. 粘贴复制的 JSON 并替代 <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>Paste the JSON you copied in place of <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>. 可在此处找到用于创建工作簿模板的 Azure 资源管理器参考模板。A reference Azure Resource Manager template that creates a workbook template can be found here.

    {
        "$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 对象中,使用你自己的值填充 namecategory 键。In the galleries object fill in the name and category keys with your values. 在下一部分详细了解参数Learn more about parameters in the next section.

  8. 使用 Azure 门户命令行界面PowerShell 等部署此 Azure 资源管理器模板。Deploy this Azure Resource Manager template using either the Azure portal, command line interface, PowerShell, etc.

  9. 打开 Azure 门户,导航到在 Azure 资源管理器模板中选择的工作簿库。Open the Azure portal and navigate to the workbook gallery chosen in the Azure Resource Manager template. 在示例模板中,导航到 Azure Monitor 工作簿库:In the example template, navigate to the Azure Monitor workbook gallery:

    1. 打开 Azure 门户并导航到 Azure MonitorOpen the Azure portal and navigate to Azure Monitor
    2. 从目录中打开 WorkbooksOpen Workbooks from the table of contents
    3. Deployed Templates 类别下的库中找到你的模板(一个紫色的项)。Find your template in the gallery under category Deployed Templates (will be one of the purple items).

parametersParameters

parametersParameters 说明Explanation
name Azure 资源管理器中的工作簿模板资源的名称。The name of the workbook template resource in Azure Resource Manager.
type 始终是 microsoft.insights/workbooktemplatesAlways microsoft.insights/workbooktemplates
location 要在其中创建工作簿的 Azure 位置。The Azure location that the workbook will be created in.
apiVersion 2019-10-17 预览版2019-10-17 preview
type 始终是 microsoft.insights/workbooktemplatesAlways microsoft.insights/workbooktemplates
galleries 要在其中显示此工作簿模板的库集。The set of galleries to show this workbook template in.
gallery.name 库中工作簿模板的易记名称。The friendly name of the workbook template in the gallery.
gallery.category 库中的要将该模板放入到其中的组。The group in the gallery to place the template in.
gallery.order 一个编号,用于确定模板在库中某个类别中的显示顺序。A number that decides the order to show the template within a category in the gallery. 顺序越低,优先级越高。Lower order implies higher priority.
gallery.resourceType 与库对应的资源类型。The resource type corresponding to the gallery. 这通常是一个对应于资源的资源类型字符串(例如 microsoft.operationalinsights/workspaces)。This is usually the resource type string corresponding to the resource (for example, microsoft.operationalinsights/workspaces ).
gallery.type 称作工作簿类型,它是用于在资源类型中区分库的唯一键。Referred to as workbook type, this is a unique key that differentiates the gallery within a resource type. 例如,Application Insights 具有对应于不同工作簿库的类型 workbooktsgApplication Insights, for example, have types workbook and tsg corresponding to different workbook galleries.

Galleries

Gallery 资源类型Resource type 工作簿类型Workbook type
Azure Monitor 中的工作簿Workbooks in Azure Monitor Azure Monitor workbook
Azure Monitor 中的 VM InsightsVM Insights in Azure Monitor Azure Monitor vm-insights
Log Analytics 工作区中的工作簿Workbooks in Log analytics workspace microsoft.operationalinsights/workspaces workbook
Application Insights 中的工作簿Workbooks in Application Insights microsoft.insights/components workbook
Application Insights 中的故障排除指南Troubleshooting guides in Application Insights microsoft.insights/components tsg
Application Insights 中的使用情况Usage in Application Insights microsoft.insights/components usage
Kubernetes 服务中的工作簿Workbooks in Kubernetes service Microsoft.ContainerService/managedClusters workbook
资源组中的工作簿Workbooks in Resource groups microsoft.resources/subscriptions/resourcegroups workbook
Azure Active Directory 中的工作簿Workbooks in Azure Active Directory microsoft.aadiam/tenant workbook
虚拟机中的 VM InsightsVM Insights in Virtual machines microsoft.compute/virtualmachines insights
虚拟机规模集中的 VM InsightsVM Insights in virtual machine scale sets microsoft.compute/virtualmachinescalesets insights

用于部署工作簿实例的 Azure 资源管理器模板Azure Resource Manager template for deploying a workbook instance

  1. 打开要以编程方式部署的工作簿。Open a workbook that you want to deploy programmatically.

  2. 单击“编辑”工具栏项,将工作簿切换到编辑模式。Switch the workbook to edit mode by clicking on the Edit toolbar item.

  3. 使用工具栏上的 </> 按钮打开“高级编辑器”。Open the Advanced Editor using the </> button on the toolbar.

  4. 在编辑器中,将“模板类型”切换为“资源管理器模板”。 In the editor, switch Template Type to Resource Manager template.

  5. 该资源管理器模板会显示在编辑器中。The Resource Manager template for creating shows up in the editor. 复制内容并按原样使用,或将其与一个更大的也用于部署目标资源的模板合并。Copy the content and use as-is or merge it with a larger template that also deploys the target resource.

    插图,显示如何从工作簿 UI 内部获取资源管理器模板

示例 Azure 资源管理器模板Sample Azure Resource Manager template

此模板演示如何部署一个显示“Hello World!”的简单工作簿This template shows how to deploy a simple workbook that displays a '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 been 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'))]"
        }
    }
}

模板参数Template parameters

参数Parameter 说明Explanation
workbookDisplayName 在“库”或“保存的列表”中使用的工作簿的易记名称。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 工作簿将在其下显示的库。The gallery that the workbook will be shown under. 支持的值包括 workbook、tsg、Azure Monitor 等。Supported values include workbook, tsg, Azure Monitor, etc.
workbookSourceId 将要与该工作簿关联的资源实例的 ID。The ID of the resource instance to which the workbook will be associated. 新工作簿会显示它与此资源实例相关 - 例如,它会显示在资源目录中的“工作簿”下。The new workbook will show up related to this resource instance - for example in the resource's table of content under Workbook. 如果你希望工作簿在 Azure Monitor 中的工作簿库内显示,请使用字符串 Azure Monitor 而不是资源 ID。If you want your workbook to show up in the workbook gallery in Azure Monitor, use the string Azure Monitor instead of a resource ID.
workbookId 此工作簿实例的唯一 GUID。The unique guid for this workbook instance. 使用 [newGuid()] 自动创建新的 GUID。Use [newGuid()] to automatically create a new guid.
kind 用于指定创建的工作簿是共享的还是专用的。Used to specify if the created workbook is shared or private. 对于共享的工作簿,请使用值 shared;对于专用的工作簿,请使用 userUse value shared for shared workbooks and user for private ones.
location 要在其中创建工作簿的 Azure 位置。The Azure location where the workbook will be created. 使用 [resourceGroup().location] 在资源组所在的位置创建工作簿Use [resourceGroup().location] to create it in the same location as the resource group
serializedData 包含要在工作簿中使用的内容或有效负载。Contains the content or payload to be used in the workbook. 从工作簿 UI 使用资源管理器模板来获取值Use the Resource Manager template from the workbooks UI to get the value

工作簿类型Workbook types

工作簿类型指定新工作簿实例会在其下显示的工作簿库类型。Workbook types specify which workbook gallery type the new workbook instance will show up under. 选项包括:Options include:

类型Type 库位置Gallery location
workbook 大多数报表中使用的默认值,包括 Application Insights 的工作簿库、Azure Monitor 等。The default used in most reports, including the Workbooks gallery of Application Insights, Azure Monitor, etc.
tsg Application Insights 中的故障排除指南库The Troubleshooting Guides gallery in Application Insights
usage Application Insights 中“使用情况”下的“更多”库 The More gallery under Usage in Application Insights

限制Limitations

出于技术原因,此机制无法用于在 Application Insights 的“工作簿”库中创建工作簿实例。For a technical reason, this mechanism cannot be used to create workbook instances in the Workbooks gallery of Application Insights. 我们正在努力解决此限制。We are working on addressing this limitation. 在此同时,我们建议使用故障排除指南库(workbookType:tsg)来部署与 Application Insights 相关的工作簿。In the meanwhile, we recommend that you use the Troubleshooting Guide gallery (workbookType: tsg) to deploy Application Insights related workbooks.

后续步骤Next steps

了解如何使用工作簿来提供新的用于存储的 Azure Monitor 体验Explore how workbooks are being used to power the new Azure Monitor for Storage experience.