次の方法で共有

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

  • [アーティクル]

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

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

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

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

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

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

  1. プログラムでデプロイするブックを開きます。

  2. [編集] を選択して、ブックを編集モードに切り替えます。

  3. ツール バーの </> ボタンを使用して [詳細エディター] を開きます。

  4. [ギャラリー テンプレート] タブが確実に表示されている状態にします。

    Screenshot that shows the Gallery Template tab.

  5. ギャラリー テンプレート内の JSON をクリップボードにコピーします。

  6. 次のサンプル 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>
            }
        }
    ]
}

  7. galleries オブジェクトで、name および category キーに、使用する値を入力します。 パラメーターの詳細については、次のセクションを参照してください。

  8. Azure portal、コマンド ライン インターフェイス、または PowerShell のいずれかを使用して、この ARM テンプレートをデプロイします。

  9. 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 テンプレート

  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'))]"
        }
    }
}

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 テンプレートのカスタマイズを容易にしています。

  1. 前のセクションで説明したように、ブックを ARM テンプレートとしてエクスポートします。
  2. テンプレートの variables セクションで、次を実行します。
    1. serializedData 値を JSON オブジェクト変数に解析します。これにより、ブックの内容を表す項目の配列を含む JSON 構造体が作成されます。
    2. 変更する項目またはプロパティのみを表す新しい JSON オブジェクトを作成します。
    3. union() 関数を使用して、JSON コンテンツ項目の新しいセット (updatedItems) を投影し、元の JSON 項目に変更を適用します。
    4. 新しいブック オブジェクト updatedWorkbookData を作成します。これには、元の解析済みデータからの updatedItems および version/isLocked データと、fallbackResourceIds の訂正されたセットが含まれます。
    5. 新しい JSON コンテンツをシリアル化して、新しい文字列変数 reserializedData に戻します。
  3. 元の serializedData プロパティの代わりに新しい reserializedData 変数を使用します。
  4. 更新された ARM テンプレートを使用して、新しいブック リソースをデプロイします。

次のステップ

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