Opis struktury i składni szablonów usługi ARM

W tym artykule opisano strukturę szablonu Azure Resource Manager (szablonu USŁUGI ARM). Przedstawia on różne sekcje szablonu i właściwości, które są dostępne w tych sekcjach.

Ten artykuł jest przeznaczony dla użytkowników, którzy znają szablony arm. Zawiera on szczegółowe informacje o strukturze szablonu. Aby uzyskać samouczek krok po kroku, który przeprowadzi Cię przez proces tworzenia szablonu, zobacz Samouczek:tworzenie i wdrażanie pierwszego szablonu usługi ARM. Aby dowiedzieć się więcej o szablonach usługi ARM za pomocą zestawu modułów z przewodnikiem na platformie Microsoft Learn, zobacz Wdrażanie zasobów i zarządzanie nimi na platformie Azure przy użyciu szablonów usługi ARM.

Template format (Format szablonu)

W najprostszej strukturze szablon ma następujące elementy:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "",
  "apiProfile": "",
  "parameters": {  },
  "variables": {  },
  "functions": [  ],
  "resources": [  ],
  "outputs": {  }
}
Nazwa elementu Wymagane Opis
$schema Tak Lokalizacja pliku JavaScript Object Notation (JSON) opisujący wersję języka szablonu. Używany numer wersji zależy od zakresu wdrożenia i edytora JSON.

Jeśli używasz usługi Visual Studio Code z rozszerzeniem narzędzi Azure Resource Manager,użyj najnowszej wersji dla wdrożeń grupy zasobów:
https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#

Inne edytory (w tym Visual Studio) mogą nie być w stanie przetworzyć tego schematu. W przypadku tych edytorów użyj:
https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#

W przypadku wdrożeń subskrypcji użyj:
https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#

W przypadku wdrożeń grup zarządzania użyj:
https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#

W przypadku wdrożeń dzierżawy użyj:
https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#
contentVersion Tak Wersja szablonu (na przykład 1.0.0.0). Dla tego elementu można podać dowolną wartość. Ta wartość pozwala udokumentować znaczące zmiany w szablonie. Podczas wdrażania zasobów przy użyciu szablonu tej wartości można użyć, aby upewnić się, że używany jest właściwy szablon.
apiProfile Nie Wersja interfejsu API, która służy jako kolekcja wersji interfejsu API dla typów zasobów. Użyj tej wartości, aby uniknąć konieczności określania wersji interfejsu API dla każdego zasobu w szablonie. Jeśli określisz wersję profilu interfejsu API i nie określisz wersji interfejsu API dla typu zasobu, usługa Resource Manager użyje wersji interfejsu API dla tego typu zasobu zdefiniowanego w profilu.

Właściwość profilu interfejsu API jest szczególnie przydatna podczas wdrażania szablonu w różnych środowiskach, takich jak Azure Stack globalnej platformy Azure. Użyj wersji profilu interfejsu API, aby upewnić się, że szablon automatycznie używa wersji obsługiwanych w obu środowiskach. Aby uzyskać listę bieżących wersji profilu interfejsu API i zasobów wersji interfejsu API zdefiniowanych w profilu, zobacz Profil interfejsu API.

Aby uzyskać więcej informacji, zobacz Track versions using API profiles (Śledzenie wersji przy użyciu profilów interfejsu API).
Parametry Nie Wartości podane podczas wdrażania w celu dostosowania wdrożenia zasobów.
Zmiennych Nie Wartości, które są używane jako fragmenty JSON w szablonie, aby uprościć wyrażenia języka szablonu.
Funkcje Nie Funkcje zdefiniowane przez użytkownika, które są dostępne w szablonie.
Zasobów Tak Typy zasobów wdrażane lub aktualizowane w grupie zasobów lub subskrypcji.
Wyjść Nie Wartości zwracane po wdrożeniu.

Każdy element ma właściwości, które można ustawić. W tym artykule bardziej szczegółowo opisano sekcje szablonu.

Parametry

W sekcji szablonu określ wartości, które można wprowadzić parameters podczas wdrażania zasobów. W szablonie można umieścić maksymalnie 256 parametrów. Liczbę parametrów można zmniejszyć, używając obiektów, które zawierają wiele właściwości.

Dostępne są następujące właściwości parametrów:

"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-parameters>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}
Nazwa elementu Wymagane Opis
nazwa parametru Tak Nazwa parametru. Musi być prawidłowym identyfikatorem JavaScript.
typ Tak Typ wartości parametru. Dozwolone typy i wartości to ciąg, securestring, int, bool, object, secureObject i tablica. Zobacz Typy danych w szablonach arm.
Defaultvalue Nie Wartość domyślna parametru, jeśli nie podano żadnej wartości dla parametru.
Allowedvalues Nie Tablica dozwolonych wartości dla parametru, aby upewnić się, że podano właściwą wartość.
Minvalue Nie Minimalna wartość parametrów typu int, ta wartość jest włącznie.
Maxvalue Nie Maksymalna wartość parametrów typu int, ta wartość jest włącznie.
Minlength Nie Minimalna długość parametrów ciągu, ciągu bezpiecznego i typu tablicy. Ta wartość jest włącznie.
Maxlength Nie Maksymalna długość parametrów ciągu, ciągu bezpiecznego i typu tablicy. Ta wartość jest włącznie.
description (opis) Nie Opis parametru, który jest wyświetlany użytkownikom za pośrednictwem portalu. Aby uzyskać więcej informacji, zobacz Komentarze w szablonach.

Aby uzyskać przykłady użycia parametrów, zobacz Parameters in ARM templates (Parametry w szablonach arm).

Zmienne

W sekcji variables konstruuje się wartości, które mogą być używane w całym szablonie. Nie trzeba definiować zmiennych, ale często upraszczają szablon przez zmniejszenie liczby złożonych wyrażeń. Format każdej zmiennej odpowiada jednem z typów danych.

W poniższym przykładzie przedstawiono dostępne opcje definiowania zmiennej:

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

Aby uzyskać informacje o używaniu funkcji do copy tworzenia kilku wartości dla zmiennej, zobacz Iteracja zmiennej.

Aby uzyskać przykłady użycia zmiennych, zobacz Zmienne w szablonie usługi ARM.

Funkcje

W szablonie możesz tworzyć własne funkcje. Te funkcje są dostępne do użycia w szablonie. Zazwyczaj definiuje się skomplikowane wyrażenia, których nie chcesz powtarzać w całym szablonie. Funkcje zdefiniowane przez użytkownika tworzy się na podstawie wyrażeń i funkcji obsługiwanych w szablonach.

Podczas definiowania funkcji użytkownika istnieją pewne ograniczenia:

  • Funkcja nie może uzyskać dostępu do zmiennych.
  • Funkcja może używać tylko parametrów zdefiniowanych w funkcji . Jeśli używasz funkcji parameters w ramach funkcji zdefiniowanej przez użytkownika, ograniczasz się do parametrów tej funkcji.
  • Funkcja nie może wywołać innych funkcji zdefiniowanych przez użytkownika.
  • Funkcja nie może używać funkcji odwołania.
  • Parametry funkcji nie mogą mieć wartości domyślnych.
"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>"
        }
      }
    }
  }
],
Nazwa elementu Wymagane Opis
namespace Tak Przestrzeń nazw dla funkcji niestandardowych. Użyj , aby uniknąć konfliktów nazw z funkcjami szablonu.
nazwa funkcji Tak Nazwa funkcji niestandardowej. Podczas wywoływania funkcji połącz nazwę funkcji z przestrzenią nazw . Aby na przykład wywołać funkcję o nazwie uniqueName w przestrzeni nazw contoso, użyj . "[contoso.uniqueName()]"
nazwa parametru Nie Nazwa parametru, który ma być używany w ramach funkcji niestandardowej.
parametr-wartość Nie Typ wartości parametru. Dozwolone typy i wartości to ciąg, securestring, int, bool, object, secureObject i tablica.
typ danych wyjściowych Tak Typ wartości wyjściowej. Wartości wyjściowe obsługują te same typy co parametry wejściowe funkcji.
output-value Tak Wyrażenie języka szablonu, które jest obliczane i zwracane z funkcji .

Aby uzyskać przykłady użycia funkcji niestandardowych, zobacz User-defined functions in ARM template (Funkcje zdefiniowane przez użytkownika w szablonie usługi ARM).

Zasoby

W resources sekcji należy zdefiniować zasoby, które są wdrażane lub aktualizowane.

Zasoby definiuje się przy użyciu następującej struktury:

"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>"
      ]
  }
]
Nazwa elementu Wymagane Opis
Warunek Nie Wartość logiczna wskazująca, czy zasób zostanie aprowowany podczas tego wdrożenia. W true przypadku programu zasób jest tworzony podczas wdrażania. W false przypadku , zasób jest pomijany dla tego wdrożenia. Zobacz warunek.
typ Tak Typ zasobu. Ta wartość jest kombinacją przestrzeni nazw dostawcy zasobów i typu zasobu (takiego jak Microsoft.Storage/storageAccounts ). Aby określić dostępne wartości, zobacz informacje o szablonie. W przypadku zasobu podrzędnego format typu zależy od tego, czy jest zagnieżdżony w zasobie nadrzędnym, czy zdefiniowany poza zasobem nadrzędnym. Zobacz Ustawianie nazwy i typu dla zasobów podrzędnych.
apiVersion Tak Wersja interfejsu API REST do użycia podczas tworzenia zasobu. Podczas tworzenia nowego szablonu ustaw tę wartość na najnowszą wersję wdrażanych zasobów. Jeśli szablon działa zgodnie z potrzebami, zachowaj tę samą wersję interfejsu API. Kontynuując korzystanie z tej samej wersji interfejsu API, można zminimalizować ryzyko, że nowa wersja interfejsu API zmieni sposób działania szablonu. Należy rozważyć zaktualizowanie wersji interfejsu API tylko wtedy, gdy chcesz użyć nowej funkcji wprowadzonej w nowszej wersji. Aby określić dostępne wartości, zobacz informacje o szablonie.
name Tak Nazwa zasobu. Nazwa musi być przestrzegana ograniczeń składnika URI zdefiniowanych w dokumencie RFC3986. Usługi platformy Azure, które uwidoczniają nazwę zasobu stronom zewnętrznym, weryfikują nazwę, aby upewnić się, że nie jest to próba fałszowania innej tożsamości. W przypadku zasobu podrzędnego format nazwy zależy od tego, czy jest ona zagnieżdżona w zasobie nadrzędnym, czy zdefiniowana poza zasobem nadrzędnym. Zobacz Ustawianie nazwy i typu dla zasobów podrzędnych.
komentarze Nie Uwagi dotyczące dokumentowania zasobów w szablonie. Aby uzyskać więcej informacji, zobacz Komentarze w szablonach.
location Różnie Obsługiwane lokalizacje geograficzne dostarczonego zasobu. Możesz wybrać dowolną z dostępnych lokalizacji, ale zazwyczaj warto wybrać lokalizację, która znajduje się blisko użytkowników. Zazwyczaj sensowne jest również umieszczanie zasobów, które współdziałają ze sobą w tym samym regionie. Większość typów zasobów wymaga lokalizacji, ale niektóre typy (takie jak przypisanie roli) nie wymagają lokalizacji. Zobacz Ustawianie lokalizacji zasobu.
dependsOn Nie Zasoby, które należy wdrożyć przed wdrożeniem tego zasobu. Resource Manager ocenia zależności między zasobami i wdraża je w odpowiedniej kolejności. Gdy zasoby nie są zależne od siebie, są wdrażane równolegle. Wartość może być rozdzielaną przecinkami listą nazw zasobów lub unikatowych identyfikatorów zasobów. Lista zawiera tylko zasoby wdrożone w tym szablonie. Zasoby, które nie są zdefiniowane w tym szablonie, muszą już istnieć. Unikaj dodawania niepotrzebnych zależności, ponieważ mogą one spowalniać wdrożenie i tworzyć zależności cykliczne. Aby uzyskać wskazówki dotyczące ustawiania zależności, zobacz Define the order for deploying resources in ARM templates (Definiowanie kolejności wdrażania zasobów w szablonach usługi ARM).
tags Nie Tagi skojarzone z zasobem. Stosowanie tagów w celu logicznego organizowania zasobów w ramach subskrypcji.
identity Nie Niektóre zasoby obsługują tożsamości zarządzane dla zasobów platformy Azure. Te zasoby mają obiekt tożsamości na poziomie głównym deklaracji zasobu. Można określić, czy tożsamość jest przypisana przez użytkownika, czy przypisana przez system. W przypadku tożsamości przypisanych przez użytkownika podaj listę identyfikatorów zasobów dla tożsamości. Ustaw klucz na identyfikator zasobu, a wartość na pusty obiekt. Aby uzyskać więcej informacji, zobacz Configure managed identities for Azure resources on an Azure VM using templates (Konfigurowanie tożsamości zarządzanych dla zasobów platformy Azure na maszynie wirtualnej platformy Azure przy użyciu szablonów).
sku Nie Niektóre zasoby zezwalają na wdrażanie wartości, które definiują sku. Można na przykład określić typ nadmiarowości konta magazynu.
Rodzaju Nie Niektóre zasoby zezwalają na wartość definiującą typ wdrażanych zasobów. Można na przykład określić typ bazy danych, Cosmos db.
scope Nie Właściwość scope jest dostępna tylko dla typów zasobów rozszerzenia. Użyj go podczas określania zakresu, który jest inny niż zakres wdrożenia. Zobacz Ustawianie zakresu dla zasobów rozszerzeń w szablonach arm.
kopiowanie Nie Jeśli potrzebne jest więcej niż jedno wystąpienie, liczba zasobów do utworzenia. Tryb domyślny jest równoległy. Określ tryb szeregowy, jeśli nie chcesz, aby wszystkie zasoby lub zasoby zostały wdrożone w tym samym czasie. Aby uzyskać więcej informacji, zobacz Tworzenie kilku wystąpień zasobów w programie Azure Resource Manager.
plan Nie Niektóre zasoby zezwalają na wartości definiujące plan wdrożenia. Można na przykład określić obraz witryny Marketplace dla maszyny wirtualnej.
properties Nie Ustawienia konfiguracji specyficzne dla zasobów. Wartości właściwości są takie same jak wartości podane w treści żądania dla operacji interfejsu API REST (metoda PUT) w celu utworzenia zasobu. Można również określić tablicę kopiowania, aby utworzyć kilka wystąpień właściwości. Aby określić dostępne wartości, zobacz informacje o szablonie.
zasoby Nie Zasoby podrzędne, które zależą od definiowanego zasobu. Podaj tylko typy zasobów, które są dozwolone przez schemat zasobu nadrzędnego. Zależność od zasobu nadrzędnego nie jest implikowana. Należy jawnie zdefiniować zależność. Zobacz Set name and type for child resources (Ustawianie nazwy i typu dla zasobów podrzędnej).

Dane wyjściowe

W sekcji outputs określisz wartości zwracane z wdrożenia. Zazwyczaj zwracane są wartości z wdrożonych zasobów.

W poniższym przykładzie pokazano strukturę definicji danych wyjściowych:

"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>
    }
  }
}
Nazwa elementu Wymagane Opis
nazwa danych wyjściowych Tak Nazwa wartości wyjściowej. Musi być prawidłowym identyfikatorem języka JavaScript.
Warunek Nie Wartość logiczna wskazująca, czy ta wartość wyjściowa jest zwracana. Gdy true wartość jest uwzględniana w danych wyjściowych wdrożenia. W false przypadku wartości wartość wyjściowa dla tego wdrożenia jest pomijana. Jeśli nie zostanie określona, wartość domyślna to true .
typ Tak Typ wartości wyjściowej. Wartości wyjściowe obsługują te same typy co parametry wejściowe szablonu. W przypadku określenia typu danych wyjściowych securestring wartość nie jest wyświetlana w historii wdrażania i nie można jej pobrać z innego szablonu. Aby użyć wartości tajnej w więcej niż jednym szablonie, należy zapisać klucz tajny w Key Vault i odwołać się do tego tajnego w pliku parametrów. Aby uzyskać więcej informacji, zobacz Use Azure Key Vault to pass secure parameter value during deployment (Używanie funkcji Azure Key Vault do przekazania wartości bezpiecznego parametru podczas wdrażania).
wartość Nie Wyrażenie języka szablonu, które jest obliczane i zwracane jako wartość wyjściowa. Określ wartość lub skopiuj wartość.
kopiowanie Nie Służy do zwracania więcej niż jednej wartości dla danych wyjściowych. Określ wartość lub skopiuj wartość. Aby uzyskać więcej informacji, zobacz Output iteration in ARM templates (Iteracja danych wyjściowych w szablonach arm).

Aby uzyskać przykłady użycia danych wyjściowych, zobacz Outputs in ARM template (Dane wyjściowe w szablonie usługi ARM).

Komentarze i metadane

Dostępnych jest kilka opcji dodawania komentarzy i metadanych do szablonu.

Komentarze

W przypadku komentarzy w tekście można użyć lub // /* ... */ .

Uwaga

W przypadku wdrażania szablonów z komentarzami przy użyciu interfejsu wiersza polecenia platformy Azure użyj wersji 2.3.0 lub nowszej i określ --handle-extended-json-format przełącznik.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-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'))]"
  ],

W Visual Studio Code rozszerzenie Azure Resource Manager Tools może automatycznie wykrywać szablon usługi ARM i zmieniać tryb języka. Jeśli w Azure Resource Manager w prawym dolnym rogu strony Visual Studio Code, możesz użyć komentarzy w tekście. Komentarze wbudowane nie są już oznaczone jako nieprawidłowe.

Visual Studio Code Azure Resource Manager szablonu

Metadane

Obiekt można dodać metadata niemal w dowolnym miejscu w szablonie. Resource Manager obiekt , ale edytor JSON może ostrzec, że właściwość jest prawidłowa. W obiekcie zdefiniuj potrzebne właściwości.

{
  "$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"
  },

W parameters przypadku obiektu dodaj obiekt z metadata description właściwością .

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

Podczas wdrażania szablonu za pośrednictwem portalu tekst w opisie jest automatycznie używany jako porada dla tego parametru.

Pokaż poradę parametru

Dla resources elementu dodaj element lub obiekt comments metadata . W poniższym przykładzie pokazano comments zarówno element, jak i metadata obiekt .

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2018-07-01",
    "name": "[concat('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": {}
  }
]

W outputs przypadku obiektu dodaj obiekt do wartości metadata wyjściowej.

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

Nie można dodać obiektu metadata do funkcji zdefiniowanych przez użytkownika.

Ciągi wielo wierszowe

Ciąg można rozbić na wiele wierszy. Na przykład zobacz właściwość location i jeden z komentarzy w poniższym przykładzie JSON.

Uwaga

Aby wdrożyć szablony z ciągami wielo wierszowymi, użyj Azure PowerShell interfejsu wiersza polecenia platformy Azure. W przypadku interfejsu wiersza polecenia użyj wersji 2.3.0 lub nowszej i określ --handle-extended-json-format przełącznik .

Ciągi wielo wierszowe nie są obsługiwane w przypadku wdrażania szablonu za pośrednictwem Azure Portal, DevOps potoku lub interfejsu API REST.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-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'))]"
  ],

Następne kroki