ARM テンプレートの構造と構文について

この記事では、Azure Resource Manager テンプレート (ARM テンプレート) の構造について説明します。 テンプレートの各種セクションとそこで使用できるプロパティを紹介しています。

この記事は、ARM テンプレートにある程度慣れているユーザー向けです。 テンプレートの構造に関する詳細情報を提供します。 テンプレートの作成手順について説明したチュートリアルについては、「チュートリアル:初めての ARM テンプレートを作成してデプロイする」を参照してください。 Learn モジュールのガイド付きセットを使用して ARM テンプレートを学習するには、「ARM テンプレートを使用して Azure にリソースをデプロイして管理する」を参照してください。

テンプレートの形式

最も単純な構造のテンプレートは、次の要素で構成されます。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "",
  "contentVersion": "",
  "apiProfile": "",
  "definitions": { },
  "parameters": { },
  "variables": { },
  "functions": [ ],
  "resources": [ ], /* or "resources": { } with languageVersion 2.0 */
  "outputs": { }
}

各要素には、設定できるプロパティがあります。 この記事では、テンプレートのセクションについて詳しく説明します。

定義

テンプレートの definitions セクションで、配列とオブジェクトの値を検証するために使用するスキーマを指定します。 Definitions は languageVersion 2.0 でのみ使用できます。

"definitions": {
  "<definition-name": {
    "type": "<data-type-of-definition>",
    "allowedValues": [ "<array-of-allowed-values>" ],
    "minValue": <minimum-value-for-int>,
    "maxValue": <maximum-value-for-int>,
    "minLength": <minimum-length-for-string-or-array>,
    "maxLength": <maximum-length-for-string-or-array>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the-type-definition>"
    }
  }
}

型定義の使用方法の例については、「ARM テンプレートの型定義」を参照してください。

Bicep の「ユーザー定義データ型」を参照してください。

パラメーター

テンプレートの parameters セクションでは、リソースをデプロイするときにどのような値を入力できるかを指定します。 テンプレートではパラメーターが 256 個に制限されます。 複数のプロパティを含むオブジェクトを使用すると、パラメーター数を減らすことができます。

パラメーターで使用可能なプロパティは次のとおりです。

"parameters": {
  "<parameter-name>" : {
    "type" : "<type-of-parameter-value>",
    "defaultValue": "<default-value-of-parameter>",
    "allowedValues": [ "<array-of-allowed-values>" ],
    "minValue": <minimum-value-for-int>,
    "maxValue": <maximum-value-for-int>,
    "minLength": <minimum-length-for-string-or-array>,
    "maxLength": <maximum-length-for-string-or-array>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}

パラメーターの使用方法の例については、「ARM テンプレートのパラメーター」を参照してください。

Bicep で、「 パラメーター」を参照してください。

変数

テンプレート内で使用できる値は、variables セクションで作成します。 必ずしも変数を定義する必要はありませんが、変数を定義することによって複雑な式が減り、テンプレートが単純化されることはよくあります。 各変数の形式は、いずれかのデータ型に一致します。 テンプレートでは変数が 256 個に制限されます。

次の例では、変数の定義に使用できるオプションを示します。

"variables": {
  "<variable-name>": "<variable-value>",
  "<variable-name>": {
    <variable-complex-type-value>
  },
  "<variable-object-name>": {
    "copy": [
      {
        "name": "<name-of-array-property>",
        "count": <number-of-iterations>,
        "input": <object-or-value-to-repeat>
      }
    ]
  },
  "copy": [
    {
      "name": "<variable-array-name>",
      "count": <number-of-iterations>,
      "input": <object-or-value-to-repeat>
    }
  ]
}

copy を使用して変数に複数の値を作成する方法については、「copy」をご覧ください。

変数の使用方法の例については、「ARM テンプレートの変数」を参照してください。

Bicep では、「 変数」を参照してください。

関数

テンプレート内で、独自の関数を作成できます。 これらの関数は、テンプレートで使用可能です。 通常は、テンプレート全体で繰り返したくない複雑な式を定義します。 ユーザー定義関数は、テンプレートでサポートされている関数および式から作成します。

ユーザー関数を定義するときに、適用される制限がいくつかあります。

• 関数は変数にアクセスできません。
• 関数は、関数内で定義されているパラメーターのみを使用できます。 ユーザー定義関数内で parameters 関数を使用する場合は、その関数のパラメーターに制限されます。
• 関数は、その他のユーザー定義関数を呼び出すことはできません。
• 関数は reference 関数を使用できません。
• 関数のパラメーターでは既定値を指定できません。

"functions": [
  {
    "namespace": "<namespace-for-functions>",
    "members": {
      "<function-name>": {
        "parameters": [
          {
            "name": "<parameter-name>",
            "type": "<type-of-parameter-value>"
          }
        ],
        "output": {
          "type": "<type-of-output-value>",
          "value": "<function-return-value>"
        }
      }
    }
  }
],

カスタム関数の使用方法の例については、「ARM テンプレートのユーザー定義関数」を参照してください。

Bicep では、ユーザー定義関数はサポートされていません。 Bicep では、さまざまな関数と演算子がサポートされています。

リソース

resources セクションでは、デプロイまたは更新されるリソースを定義します。 テンプレートではリソースが 800 個に制限されます。

リソースは、次の構造で定義します。

"resources": [
  {
    "condition": "<true-to-deploy-this-resource>",
    "type": "<resource-provider-namespace/resource-type-name>",
    "apiVersion": "<api-version-of-resource>",
    "name": "<name-of-the-resource>",
    "comments": "<your-reference-notes>",
    "location": "<location-of-resource>",
    "dependsOn": [
        "<array-of-related-resource-names>"
    ],
    "tags": {
        "<tag-name1>": "<tag-value1>",
        "<tag-name2>": "<tag-value2>"
    },
    "identity": {
      "type": "<system-assigned-or-user-assigned-identity>",
      "userAssignedIdentities": {
        "<resource-id-of-identity>": {}
      }
    },
    "sku": {
        "name": "<sku-name>",
        "tier": "<sku-tier>",
        "size": "<sku-size>",
        "family": "<sku-family>",
        "capacity": <sku-capacity>
    },
    "kind": "<type-of-resource>",
    "scope": "<target-scope-for-extension-resources>",
    "copy": {
        "name": "<name-of-copy-loop>",
        "count": <number-of-iterations>,
        "mode": "<serial-or-parallel>",
        "batchSize": <number-to-deploy-serially>
    },
    "plan": {
        "name": "<plan-name>",
        "promotionCode": "<plan-promotion-code>",
        "publisher": "<plan-publisher>",
        "product": "<plan-product>",
        "version": "<plan-version>"
    },
    "properties": {
        "<settings-for-the-resource>",
        "copy": [
            {
                "name": ,
                "count": ,
                "input": {}
            }
        ]
    },
    "resources": [
        "<array-of-child-resources>"
    ]
  }
]

ARM JSON テンプレートで Bicep シンボリック名をサポートするには、バージョン 2.0 以降で languageVersion を追加し、リソース定義を配列からオブジェクトに変更します。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
      ...
    }
  }
}

詳しくは、リソースに関する記事をご覧ください。

Bicep で、 リソースに関するページを参照してください。

出力

outputs セクションではデプロイから返される値を指定します。 通常は、デプロイされたリソースからの値を返します。 テンプレートでは出力が 64 個に制限されます。

次の例では、出力の定義の構造を示します。

"outputs": {
  "<output-name>": {
    "condition": "<boolean-value-whether-to-output-value>",
    "type": "<type-of-output-value>",
    "value": "<output-value-expression>",
    "copy": {
      "count": <number-of-iterations>,
      "input": <values-for-the-variable>
    }
  }
}

出力の使用方法の例については、「ARM テンプレートの出力」を参照してください。

Bicep で、出力に関するページを 参照してください。

コメントとメタデータ

テンプレートにコメントとメタデータを追加するためのオプションがいくつかあります。

説明

インライン コメントについては、// または /* ... */ のいずれかを使用できます。 Visual Studio Code で、コメントを含むパラメーター ファイルをコメント付き JSON (JSONC) のファイルの種類として保存します。そうしないと、"コメントが JSON で許可されていません" というエラー メッセージが表示されます。

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[parameters('location')]", //defaults to resource group location
  "dependsOn": [ /* storage account and network interface must be deployed first */
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Visual Studio Code では、Azure Resource Manager ツール拡張機能により、ARM テンプレートが自動的に検出され、言語モードが変更されます。 Visual Studio Code の右下隅に [Azure Resource Manager テンプレート] が表示されている場合は、インライン コメントを使用できます。 インライン コメントは無効としてマークされなくなります。

Bicep で、コメントに関するページを参照してください。

Metadata

metadata オブジェクトは、テンプレート内のほとんどどこにでも追加できます。 このオブジェクトは、Resource Manager では無視されますが、お使いの JSON エディターによっては、プロパティが無効であると警告される場合があります。 オブジェクトで、必要なプロパティを定義します。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "comments": "This template was developed for demonstration purposes.",
    "author": "Example Name"
  },

parametersの場合、description プロパティを使って metadata オブジェクトを追加します。

"parameters": {
  "adminUsername": {
    "type": "string",
    "metadata": {
      "description": "User name for the Virtual Machine."
    }
  },

ポータルからテンプレートをデプロイする場合、説明で指定したテキストがそのパラメーターのヒントとして自動的に使用されます。

resources の場合、comments 要素または metadata オブジェクトを追加します。 次の例は、comments 要素と metadata オブジェクトの両方を示しています。

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2022-09-01",
    "name": "[format('{0}{1}', 'storage', uniqueString(resourceGroup().id))]",
    "comments": "Storage account used to store VM disks",
    "location": "[parameters('location')]",
    "metadata": {
      "comments": "These tags are needed for policy compliance."
    },
    "tags": {
      "Dept": "[parameters('deptName')]",
      "Environment": "[parameters('environment')]"
    },
    "sku": {
      "name": "Standard_LRS"
    },
    "kind": "Storage",
    "properties": {}
  }
]

outputs の場合、metadata オブジェクトを出力値に追加します。

"outputs": {
  "hostname": {
    "type": "string",
    "value": "[reference(variables('publicIPAddressName')).dnsSettings.fqdn]",
    "metadata": {
      "comments": "Return the fully qualified domain name"
    }
  },

metadata オブジェクトをユーザー定義関数に追加することはできません。

複数行の文字列

文字列を複数の行に分割することができます。 例として、次の JSON の例の location プロパティといずれかのコメントを参照してください。

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Bicep で、 マルチライン ストリングに関するページを参照してください。

languageVersion 2.0

languageVersion 2.0 を使用するには、"languageVersion": "2.0" を以下のテンプレートに追加します。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
      ...
    }
  }
}

languageVersion 2.0 に付属する機能強化と変更は以下のとおりです。

• ARM JSON テンプレートでシンボリック名を使用します。 詳細については、「シンボリック名を使用する」を参照してください。
• リソース コピー ループでシンボリック名を使用します。 「シンボル名を使用する」を参照してください。
• dependsOn 配列でシンボリック名を使用します。 「DependsOn」と「ループ内のリソースへの依存」を参照してください。
• reference 関数でリソース名の代わりにシンボリック名を使用します。 参考資料をご覧ください。
• リソース コレクションのランタイム状態を表すオブジェクトの配列を返す references() 関数。 「references」を参照してください。
• リソースをデプロイするのではなく、ARM が読み取る既存のリソースを宣言するには、'既存の' リソース プロパティを使用します。 「既存のリソースを宣言する」を参照してください。
• ユーザー定義型を作成します。 「型定義」を参照してください。
• parameters と outputs で使用される追加の集計型検証制約。
• expressionEvaluationOptions プロパティの既定値は inner です。 値 outer はブロックされます。 「入れ子になったテンプレートでの式の評価のスコープ」を参照してください。
• この deployment 関数は、プロパティの限られたサブセットを返します。 「デプロイ」を参照してください。
• シンボリック名のデプロイでデプロイのリソースが使用されている場合は、apiVersion 2020-09-01 以降を使用します。
• リソース定義では、式内の値の二重エスケープは不要になります。 「エスケープ文字」を参照してください。

次のいずれかの Bicep 機能を使用すると、言語バージョン 2.0 コード生成が自動的に有効になります。

• ユーザー定義型
• ユーザー定義関数
• コンパイル時インポート
• 実験的な機能

次のステップ

• さまざまな種類のソリューションのテンプレートについては、「 Azure クイック スタート テンプレート」をご覧ください。
• テンプレート内から使用できる関数の詳細については、「ARM テンプレート関数」を参照してください。
• デプロイ中に複数のテンプレートを結合するには、「Azure リソース デプロイ時のリンクされたテンプレートおよび入れ子になったテンプレートの使用」をご覧ください。
• テンプレートの作成に関するレコメンデーションについては、「ARM テンプレートのベストプラクティス」を参照してください。
• 一般的な質問に対する回答については、「ARM テンプレートに関してよく寄せられる質問」を参照してください。