プログラムでブックを管理する

[アーティクル]
10/15/2024

リソース所有者は、Azure Resource Manager テンプレート (ARM テンプレート) を使用して、プログラムでブックを作成および管理できます。

この機能は、次のようなシナリオで役に立ちます。

リソースのデプロイと共に、組織またはドメインに固有の分析レポートをデプロイする。たとえば、組織に固有のパフォーマンスおよび障害ブックを新しいアプリまたは仮想マシン用にデプロイできます。
既存のリソース用のブックを使用して、標準レポートまたはダッシュボードをデプロイする。

ブックは、ARM テンプレートで指定されたコンテンツと共に、ご希望のサブまたはリソースグループに作成されます。

次の 2 種類のブックリソースをプログラムで管理できます。

ブックテンプレート
ブックインスタンス

ブックテンプレートをデプロイするための ARM テンプレート

プログラムでデプロイするブックを開きます。
[編集] を選択して、ブックを編集モードに切り替えます。
ツールバーの </> ボタンを使用して [詳細エディター] を開きます。
[ギャラリーテンプレート] タブが確実に表示されている状態にします。
ギャラリーテンプレート内の JSON をクリップボードにコピーします。

次のサンプル ARM テンプレートでは、ブックテンプレートが Azure Monitor ブックギャラリーにデプロイされます。 <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE> の代わりにコピーした JSON を貼り付けます。ブックテンプレートを作成する参照 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 portal、コマンドラインインターフェイス、または PowerShell のいずれかを使用して、この ARM テンプレートをデプロイします。
Azure portal を開き、ARM テンプレートで選択したブックギャラリーに移動します。サンプルテンプレートで、Azure Monitor ブックギャラリーに移動します。
1. Azure portal を開き、Azure Monitor に移動します。
2. 目次から Workbooks を開きます。
3. ギャラリー (カテゴリ Deployed Templates) で、使用するテンプレートを見つけます。 (紫色の項目の 1 つです。)

パラメーター

パラメーター	説明
`name`	Azure Resource Manager 内のブックテンプレートリソースの名前。
`type`	常に microsoft.insights/workbooktemplates です。
`location`	ブックの作成先となる Azure の場所。
`apiVersion`	2019-10-17 preview。
`type`	常に microsoft.insights/workbooktemplates です。
`galleries`	このブックテンプレートが表示されるギャラリーセット。
`gallery.name`	ギャラリー内のブックテンプレートのフレンドリ名。
`gallery.category`	テンプレートを配置するギャラリー内のグループ。
`gallery.order`	ギャラリー内のカテゴリにおいてテンプレートの表示順序を決定する数値。順位が低いほど優先順位が高くなります。
`gallery.resourceType`	ギャラリーに対応するリソースの種類。この種類は、通常、リソースに対応するリソースの種類の文字列です (例: microsoft.operationalinsights/workspaces)。
`gallery.type`	ブックの種類と呼ばれます。この一意のキーにより、リソースの種類の中でギャラリーが区別されます。たとえば、Application Insights には、異なるブックギャラリーに対応する種類として `workbook` と `tsg` があります。

ギャラリー

[ギャラリー]	リソースの種類	ブックの種類
Azure Monitor での Workbooks	`Azure Monitor`	`workbook`
Azure Monitor での VM Insights	`Azure Monitor`	`vm-insights`
Log Analytics ワークスペースでの Workbooks	`microsoft.operationalinsights/workspaces`	`workbook`
Application Insights での Workbooks	`microsoft.insights/components`	`workbook`
Application Insights のトラブルシューティングガイド	`microsoft.insights/components`	`tsg`
Application Insights の使用	`microsoft.insights/components`	`usage`
Kubernetes サービスでの Workbooks	`Microsoft.ContainerService/managedClusters`	`workbook`
リソースグループでの Workbooks	`microsoft.resources/subscriptions/resourcegroups`	`workbook`
Microsoft Entra ID のブック	`microsoft.aadiam/tenant`	`workbook`
Virtual Machines での VM Insights	`microsoft.compute/virtualmachines`	`insights`
仮想マシンスケールセット内の VM Insights	`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'))]"
        }
    }
}

Template parameters

パラメーター	説明
`workbookDisplayName`	ギャラリーまたは保存リストで使用されているブックのフレンドリ名。リソースグループとソースのスコープ内で一意である必要があります。
`workbookType`	ブックが表示されるギャラリー。サポートされる値としては、workbook、`tsg`、Azure Monitor があります。
`workbookSourceId`	ブックを関連付けるリソースインスタンスの ID。新しいブックは、このリソースインスタンスに関連して表示されます (たとえば、リソース目次の [ブック] の下)。ブックを Azure Monitor のブックギャラリーに表示したい場合は、リソース ID ではなく文字列 Azure Monitor を使用します。
`workbookId`	このブックインスタンスの一意の GUID。新しい GUID を自動的に作成するには、 `[newGuid()]` を使用します。
`kind`	作成されるブックを共有するかどうかの指定に使用します。すべての新しいブックで、値 shared が使用されます。
`location`	ブックの作成先となる Azure の場所。リソースグループと同じ場所に作成するには、`[resourceGroup().location]` を使用します。
`serializedData`	ブックで使用されるコンテンツまたはペイロードが格納されます。ブック UI で ARM テンプレートを使用して値を取得します。

ブックの種類

ブックの種類では、新しいブックインスタンスが表示されるブックギャラリーの種類を指定します。次のオプションがあります。

Type	ギャラリーの場所
`workbook`	Application Insights および Azure Monitor の [ブック] ギャラリーを含む、ほとんどのレポートで使用される既定値です。
`tsg`	Application Insights の [トラブルシューティングガイド] ギャラリー。
`usage`	Application Insights の [使用法] の下にある [その他] ギャラリー。

serializedData テンプレートパラメーターの JSON 形式ブックデータを操作する

Azure ブック用に ARM テンプレートをエクスポートするときに、エクスポートされた serializedData テンプレートパラメーターの内部に固定のリソースリンクが埋め込まれていることがよくあります。これらのリンクには、サブスクリプション ID やリソースグループ名、およびその他の種類のリソース ID など、機密である可能性がある値が含まれています。

次の例では、文字列操作を行わずに、エクスポートしたブック ARM テンプレートをカスタマイズする方法を示しています。この例で示しているパターンの意図は、Azure portal からエクスポートした未変更のデータを処理することです。また、プログラムでブックを管理する場合は、埋め込まれている機密値をマスクすることをお勧めします。このため、ここではサブスクリプション ID とリソースグループはマスクされています。生の受信値 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. union() 関数を使用して、JSON コンテンツ項目の新しいセット (updatedItems) を投影し、元の JSON 項目に変更を適用します。
4. 新しいブックオブジェクト updatedWorkbookData を作成します。これには、元の解析済みデータからの updatedItems および version/isLocked データと、fallbackResourceIds の訂正されたセットが含まれます。
5. 新しい JSON コンテンツをシリアル化して、新しい文字列変数 reserializedData に戻します。
元の serializedData プロパティの代わりに新しい reserializedData 変数を使用します。
更新された ARM テンプレートを使用して、新しいブックリソースをデプロイします。

次のステップ

新しいストレージ分析情報エクスペリエンスを強化するためにブックがどのように使用されているかを確認してください。

次の方法で共有

プログラムでブックを管理する

ブックテンプレートをデプロイするための ARM テンプレート

パラメーター

ギャラリー

ブックインスタンスをデプロイするための ARM テンプレート

サンプル ARM テンプレート

Template parameters

ブックの種類

serializedData テンプレートパラメーターの JSON 形式ブックデータを操作する

次のステップ

フィードバック

その他のリソース

次の方法で共有

プログラムでブックを管理する

ブック テンプレートをデプロイするための ARM テンプレート

パラメーター

ギャラリー

ブック インスタンスをデプロイするための ARM テンプレート

サンプル ARM テンプレート

Template parameters

ブックの種類

serializedData テンプレート パラメーターの JSON 形式ブック データを操作する

次のステップ

フィードバック

その他のリソース

ブックテンプレートをデプロイするための ARM テンプレート

ブックインスタンスをデプロイするための ARM テンプレート

serializedData テンプレートパラメーターの JSON 形式ブックデータを操作する