以程式設計方式管理活頁簿

發行項
03/11/2024

資源擁有者可以透過 Resource Manager 範本 (ARM 範本)，以程式設計方式建立和管理其活頁簿。

這功能在下列情況下會很有用：

與資源部署一起部署組織或領域特定的分析報表。例如，您可為新的應用程式或虛擬機器，部署組織特定的效能和失敗活頁簿。
針對現有資源，藉由活頁簿來部署標準報表或儀表板。

活頁簿會在所需的子資源群組/資源群組中建立，其中包含在 ARM 範本中指定的內容。

可透過程式設計方式管理兩種類型的活頁簿資源：

活頁簿範本
活頁簿執行個體

部署活頁簿範本的 ARM 範例

開啟您想要以程式設計方式部署的活頁簿。
選取 [編輯] 以將活頁簿切換為編輯模式。
透過工具列上的 </> 按鈕開啟「進階編輯器」。
確定位於 [資源庫範本] 索引標籤上。
將資源庫範本中的 JSON 複製到剪貼簿。

下列範例 ARM 範本會將活頁簿範本部署至 Azure 監視器活頁簿資源庫。貼上您複製的 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>
            }
        }
    ]
}

在 galleries 物件中，以您的值填入 name 和 category 索引鍵。若要深入了解參數，請參閱下一節。
使用 Azure 入口網站、命令列介面或是PowerShell 等來部署此 ARM 範本。
開啟 Azure 入口網站，然後前往至在 ARM 範本中選擇的活頁簿資源庫。在範例範本中，前往至 Azure 監視器活頁簿資源庫：
1. 開啟 Azure 入口網站並前往至 Azure 監視器。
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`	稱為活頁簿類型。此唯一索引鍵可區分資源類型內的資源庫。例如，Application Insights 具有類型 `workbook` 和 `tsg`，對應至不同的活頁簿資源庫。

資源庫

資源庫	資源類型	活頁簿類型
Azure 監視器中的活頁簿	`Azure Monitor`	`workbook`
Azure 監視器中的 VM 深入解析	`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 ID 中的活頁簿	`microsoft.aadiam/tenant`	`workbook`
虛擬機器中的 VM 深入解析	`microsoft.compute/virtualmachines`	`insights`
虛擬機器擴展集中的 VM 深入解析	`microsoft.compute/virtualmachinescalesets`	`insights`

用於部署活頁簿執行個體的 ARM 執行個體

開啟您想要以程式設計方式部署的活頁簿。
選取 [編輯] 以將活頁簿切換為編輯模式。
選取 </> 開啟 [進階編輯器]。
在編輯器中，將 [範本類型] 切換為 [ARM 範本]。
用於建立的 ARM 範本會顯示在編輯器中。複製內容並依原樣使用，或將其與也會部署目標資源的較大型範本合併。

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`	活頁簿所在的資源庫。支援的值包括活頁簿、`tsg`，以及 Azure 監視器。
`workbookSourceId`	將與活頁簿建立關聯的資源執行個體識別碼。新的活頁簿會顯示與這個資源執行個體相關，例如，在 [活頁簿] 下的資源目錄中。如果您想要讓活頁簿顯示在 Azure 監視器的活頁簿資源庫中，請使用「Azure 監視器」字串，而不是資源識別碼。
`workbookId`	此活頁簿執行個體的唯一 GUID。使用 `[newGuid()]` 自動建立新的 GUID。
`kind`	用來指定是否共用已建立的活頁簿。所有新的活頁簿都會使用值 shared。
`location`	將建立活頁簿的 Azure 位置。使用 `[resourceGroup().location]` 可在與資源群組相同的位置建立活頁簿。
`serializedData`	包含要在活頁簿中使用的內容或承載。使用活頁簿 UI 中的 ARM 範本來取得值。

活頁簿類型

活頁簿類型會指定新的活頁簿執行個體將在哪一種活頁簿資源庫類型下出現。這些選項包括：

類型	資源庫位置
`workbook`	大部分報表中使用的預設值，包括 Application Insights 以及 Azure 監視器的活頁簿資源庫。
`tsg`	Application Insights 中的疑難排解指南資源庫。
`usage`	Application Insights 中 [使用量] 下的 [其他] 資源庫。

於 serializedData 範本參數中使用 JSON 格式的活頁簿資料

當您匯出 Azure 活頁簿的 ARM 範本時，通常會在匯出的 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 範本：

如上一節所述，將活頁簿匯出為 ARM 範本。
在範本的 variables 區段中：
1. 將 serializedData 值剖析為 JSON 物件變數，這會建立 JSON 結構，包括代表活頁簿內容的項目陣列。
2. 建立新的 JSON 物件，只代表要修改的項目/屬性。
3. 投影一組新的 JSON 內容項目 (updatedItems)，透過使用 union() 函式將修改套用至原始 JSON 項目。
4. 建立新的活頁簿物件 updatedWorkbookData，其中包含 updatedItems 和來自原始剖析資料的 version/isLocked 資料，以及一組修正的 fallbackResourceIds。
5. 將新的 JSON 內容序列化回到新的字串變數 reserializedData。
使用新的 reserializedData 變數取代原始 serializedData 屬性。
使用更新的 ARM 範本來部署新的活頁簿資源。

下一步

探索如何使用活頁簿來支援新的儲存體深入解析體驗。

共用方式為