Funções de implantação para modelos do ARM

  • Artigo

O Resource Manager fornece as seguintes funções para obter valores relacionados à implantação atual de seu modelo do ARM (Azure Resource Manager):

Para obter valores de recursos, de grupos de recursos ou de assinaturas, veja Funções de recurso.

Dica

Recomendamos o Bicep porque ele oferece as mesmas funcionalidades que os modelos do ARM e a sintaxe é mais fácil de usar. Para saber mais, confira as funções de implantação.

implantação

deployment()

Retorna informações sobre a operação de implantação atual.

No Bicep, use a função deployment.

Retornar valor

Essa função retorna o objeto que é passado durante a implantação. As propriedades no objeto retornado diferem se você estiver:

  • implantando um modelo ou uma especificação de modelo.
  • implantando um modelo que é um arquivo local ou implantando um modelo que é um arquivo remoto acessado por meio de um URI.
  • implantando em um grupo de recursos ou implantando em um dos outros escopos (assinatura do Azure, grupo de gerenciamentoou locatário).

Ao implantar um modelo local em um grupo de recursos: a função retorna o seguinte formato:

{
  "name": "",
  "properties": {
    "template": {
      "$schema": "",
      "contentVersion": "",
      "parameters": {},
      "variables": {},
      "resources": [],
      "outputs": {}
    },
    "templateHash": "",
    "parameters": {},
    "mode": "",
    "provisioningState": ""
  }
}

Ao implantar um modelo remoto em um grupo de recursos: a função retorna o seguinte formato:

{
  "name": "",
  "properties": {
    "templateLink": {
      "uri": ""
    },
    "template": {
      "$schema": "",
      "contentVersion": "",
      "parameters": {},
      "variables": {},
      "resources": [],
      "outputs": {}
    },
    "templateHash": "",
    "parameters": {},
    "mode": "",
    "provisioningState": ""
  }
}

Ao implantar uma especificação de modelo em um grupo de recursos: a função retorna o seguinte formato:

{
  "name": "",
  "properties": {
    "templateLink": {
      "id": ""
    },
    "template": {
      "$schema": "",
      "contentVersion": "",
      "parameters": {},
      "variables": {},
      "resources": [],
      "outputs": {}
    },
    "templateHash": "",
    "parameters": {},
    "mode": "",
    "provisioningState": ""
  }
}

Quando você implanta em uma assinatura do Azure, grupo de gerenciamento ou locatário, o objeto de retorno inclui uma propriedade location. A propriedade de localização é incluída ao implantar um modelo local ou externo. O formato é:

{
  "name": "",
  "location": "",
  "properties": {
    "template": {
      "$schema": "",
      "contentVersion": "",
      "resources": [],
      "outputs": {}
    },
    "templateHash": "",
    "parameters": {},
    "mode": "",
    "provisioningState": ""
  }
}

Ao implantar um modelo languageVersion 2.0, a função deployment retorna um subconjunto limitado de propriedades:

{
  "name": "",
  "location": "",
  "properties": {
    "template": {
      "contentVersion": ""
    },
    "templateLink": {
      "id": "",
      "uri": ""
    }
  }
}

Comentários

Você pode usar deployment() para vincular a outro modelo com base no URI do modelo pai.

"variables": {
  "sharedTemplateUrl": "[uri(deployment().properties.templateLink.uri, 'shared-resources.json')]"
}

Se você reimplantar um modelo usando o histórico de implantação no portal, o modelo será implantando como um arquivo local. A propriedade templateLink não é retornada na função de implantação. Se o seu modelo depender de templateLink para criar um link para outro modelo, não use o portal para reimplantação. Ao invés disso, emita os comandos usados para implantar originalmente o modelo.

Exemplo

O exemplo a seguir retorna um objeto de implantação.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "deploymentOutput": {
      "type": "object",
      "value": "[deployment()]"
    }
  }
}

O exemplo anterior retorna o seguinte objeto:

{
  "name": "deployment",
  "properties": {
    "template": {
      "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
      "contentVersion": "1.0.0.0",
      "resources": [],
      "outputs": {
        "deploymentOutput": {
          "type": "Object",
          "value": "[deployment()]"
        }
      }
    },
    "templateHash": "13135986259522608210",
    "parameters": {},
    "mode": "Incremental",
    "provisioningState": "Accepted"
  }
}

Para uma implantação de assinatura, o exemplo a seguir retorna um objeto de implantação.

{
  "$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "variables": {},
  "resources": [],
  "outputs": {
    "exampleOutput": {
      "type": "object",
      "value": "[deployment()]"
    }
  }
}

ambiente

environment()

Retorna informações sobre o ambiente do Azure usado para implantação.

No Bicep, use a função de ambiente.

Comentários

Para ver uma lista de ambientes registrados para sua conta, use az cloud list ou Get-AzEnvironment.

Retornar valor

Essa função retorna propriedades para o ambiente atual do Azure. O exemplo a seguir mostra as propriedades do Azure global. Nuvens soberanas podem retornar propriedades ligeiramente diferentes.

{
  "name": "",
  "gallery": "",
  "graph": "",
  "portal": "",
  "graphAudience": "",
  "activeDirectoryDataLake": "",
  "batch": "",
  "media": "",
  "sqlManagement": "",
  "vmImageAliasDoc": "",
  "resourceManager": "",
  "authentication": {
    "loginEndpoint": "",
    "audiences": [
      "",
      ""
    ],
    "tenant": "",
    "identityProvider": ""
  },
  "suffixes": {
    "acrLoginServer": "",
    "azureDatalakeAnalyticsCatalogAndJob": "",
    "azureDatalakeStoreFileSystem": "",
    "azureFrontDoorEndpointSuffix": "",
    "keyvaultDns": "",
    "sqlServerHostname": "",
    "storage": ""
  }
}

Exemplo

O modelo de exemplo a seguir retorna o objeto do ambiente.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "environmentOutput": {
      "type": "object",
      "value": "[environment()]"
    }
  }
}

O exemplo anterior retorna o seguinte objeto quando implantado no Azure global:

{
  "name": "AzureCloud",
  "gallery": "https://gallery.azure.com/",
  "graph": "https://graph.windows.net/",
  "portal": "https://portal.azure.com",
  "graphAudience": "https://graph.windows.net/",
  "activeDirectoryDataLake": "https://datalake.azure.net/",
  "batch": "https://batch.core.windows.net/",
  "media": "https://rest.media.azure.net",
  "sqlManagement": "https://management.core.windows.net:8443/",
  "vmImageAliasDoc": "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-compute/quickstart-templates/aliases.json",
  "resourceManager": "https://management.azure.com/",
  "authentication": {
    "loginEndpoint": "https://login.microsoftonline.com/",
    "audiences": [
      "https://management.core.windows.net/",
      "https://management.azure.com/"
    ],
    "tenant": "common",
    "identityProvider": "AAD"
  },
  "suffixes": {
    "acrLoginServer": ".azurecr.io",
    "azureDatalakeAnalyticsCatalogAndJob": "azuredatalakeanalytics.net",
    "azureDatalakeStoreFileSystem": "azuredatalakestore.net",
    "azureFrontDoorEndpointSuffix": "azurefd.net",
    "keyvaultDns": ".vault.azure.net",
    "sqlServerHostname": ".database.windows.net",
    "storage": "core.windows.net"
  }
}

parameters

parameters(parameterName)

Retorna um valor de parâmetro. O nome do parâmetro especificado deve ser definido na seção de parâmetros do modelo.

No Bicep, consulte diretamente os parâmetros usando seus nomes simbólicos.

Parâmetros

Parâmetro Obrigatório Tipo Descrição
parameterName Sim string O nome do parâmetro a retornar.

Valor retornado

O valor do parâmetro especificado.

Comentários

Normalmente, você usa parâmetros para definir valores de recursos. O exemplo a seguir define o nome do site para o valor do parâmetro passado durante a implantação.

"parameters": {
  "siteName": {
    "type": "string"
  }
}, "resources": [
  {
    "type": "Microsoft.Web/Sites",
    "apiVersion": "2016-08-01",
    "name": "[parameters('siteName')]",
    ...
  }
]

Exemplo

O exemplo a seguir mostra um uso simplificado da função parâmetros.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringParameter": {
      "type": "string",
      "defaultValue": "option 1"
    },
    "intParameter": {
      "type": "int",
      "defaultValue": 1
    },
    "objectParameter": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b"
      }
    },
    "arrayParameter": {
      "type": "array",
      "defaultValue": [ 1, 2, 3 ]
    },
    "crossParameter": {
      "type": "string",
      "defaultValue": "[parameters('stringParameter')]"
    }
  },
  "variables": {},
  "resources": [],
  "outputs": {
    "stringOutput": {
      "type": "string",
      "value": "[parameters('stringParameter')]"
    },
    "intOutput": {
      "type": "int",
      "value": "[parameters('intParameter')]"
    },
    "objectOutput": {
      "type": "object",
      "value": "[parameters('objectParameter')]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[parameters('arrayParameter')]"
    },
    "crossOutput": {
      "type": "string",
      "value": "[parameters('crossParameter')]"
    }
  }
}

A saída do exemplo anterior com os valores padrão é:

Nome Tipo Valor
stringOutput String opção 1
intOutput int 1
objectOutput Objeto {"one": "a", "two": "b"}
arrayOutput Array [1, 2, 3]
crossOutput String opção 1

Para obter mais informações sobre como usar parâmetros, consulte Parâmetros em modelos do ARM.

variáveis

variables(variableName)

Retorna o valor da variável. O nome do parâmetro especificado deve ser definido na seção variáveis do modelo.

No Bicep, consulte diretamente as variáveis usando seus nomes simbólicos.

Parâmetros

Parâmetro Obrigatório Tipo Descrição
variableName Sim String O nome da variável a retornar.

Retornar valor

O valor da variável especificada.

Comentários

Normalmente, você usa variáveis para simplificar seu modelo criando valores complexos apenas uma vez. O exemplo a seguir constrói um nome exclusivo para uma conta de armazenamento.

"variables": {
  "storageName": "[concat('storage', uniqueString(resourceGroup().id))]"
},
"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "name": "[variables('storageName')]",
    ...
  },
  {
    "type": "Microsoft.Compute/virtualMachines",
    "dependsOn": [
      "[variables('storageName')]"
    ],
    ...
  }
],

Exemplo

O exemplo a seguir retorna valores de variáveis diferentes.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "variables": {
    "var1": "myVariable",
    "var2": [ 1, 2, 3, 4 ],
    "var3": "[ variables('var1') ]",
    "var4": {
      "property1": "value1",
      "property2": "value2"
    }
  },
  "resources": [],
  "outputs": {
    "exampleOutput1": {
      "type": "string",
      "value": "[variables('var1')]"
    },
    "exampleOutput2": {
      "type": "array",
      "value": "[variables('var2')]"
    },
    "exampleOutput3": {
      "type": "string",
      "value": "[variables('var3')]"
    },
    "exampleOutput4": {
      "type": "object",
      "value": "[variables('var4')]"
    }
  }
}

A saída do exemplo anterior com os valores padrão é:

Nome Tipo Valor
exampleOutput1 String myVariable
exampleOutput2 Array [1, 2, 3, 4]
exampleOutput3 String myVariable
exampleOutput4 Objeto {"property1": "value1", "property2": "value2"}

Para obter mais informações sobre como usar variáveis, consulte Variáveis no modelo ARM.

Próximas etapas