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

  • Artigo

Resource Manager fornece as seguintes funções para obter valores relacionados com a implementação atual do modelo do Azure Resource Manager (modelo arm):

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

Dica

Recomendamos o Bicep porque oferece as mesmas capacidades que os modelos do ARM e a sintaxe é mais fácil de utilizar. Para saber mais, veja deployment functions (Funções de implementação ).

implementação

deployment()

Devolve informações sobre a operação de implementação atual.

No Bicep, utilize a função de implementação .

Valor devolvido

Esta função devolve o objeto que é transmitido durante a implementação. As propriedades no objeto devolvido diferem consoante:

  • implementar um modelo ou uma especificação de modelo.
  • implementar um modelo que seja um ficheiro local ou implementar um modelo que seja um ficheiro remoto acedido através de um URI.
  • implementar num grupo de recursos ou implementar num dos outros âmbitos (subscrição do Azure, grupo de gestão ou inquilino).

Ao implementar um modelo local num grupo de recursos: a função devolve o seguinte formato:

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

Ao implementar um modelo remoto num grupo de recursos: a função devolve o seguinte formato:

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

Ao implementar uma especificação de modelo num grupo de recursos: a função devolve o seguinte formato:

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

Quando implementa numa subscrição, grupo de gestão ou inquilino do Azure, o objeto de retorno inclui uma location propriedade. A propriedade de localização é incluída ao implementar um modelo local ou um modelo externo. O formato é:

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

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

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

Observações

Pode utilizar deployment() para ligar a outro modelo com base no URI do modelo principal.

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

Se reimplementar um modelo a partir do histórico de implementações no portal, o modelo é implementado como um ficheiro local. A templateLink propriedade não é devolvida na função de implementação. Se o seu modelo depender templateLink de construir uma ligação para outro modelo, não utilize o portal para reimplementar. Em vez disso, utilize os comandos que utilizou para implementar originalmente o modelo.

Exemplo

O exemplo seguinte devolve um objeto de implementaçã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 devolve 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 implementação de subscrição, o exemplo seguinte devolve um objeto de implementaçã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()

Devolve informações sobre o ambiente do Azure utilizado para a implementação.

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

Observações

Para ver uma lista de ambientes registados para a sua conta, utilize az cloud list ou Get-AzEnvironment.

Valor devolvido

Esta função devolve propriedades para o ambiente atual do Azure. O exemplo seguinte mostra as propriedades do Azure global. As clouds soberanas podem devolver 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 seguinte devolve o objeto de 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 devolve o seguinte objeto quando implementado 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"
  }
}

parâmetros

parameters(parameterName)

Devolve um valor de parâmetro. O nome do parâmetro especificado tem de ser definido na secção parâmetros do modelo.

No Bicep, referencie diretamente os parâmetros com os respetivos nomes simbólicos .

Parâmetros

Parâmetro Necessário Tipo Description
parameterName Yes string O nome do parâmetro a devolver.

Valor devolvido

O valor do parâmetro especificado.

Observações

Normalmente, utiliza parâmetros para definir valores de recursos. O exemplo seguinte define o nome do web site para o valor do parâmetro transmitido durante a implementação.

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

Exemplo

O exemplo seguinte mostra uma utilização simplificada da função parameters.

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

O resultado do exemplo anterior com os valores predefinidos é:

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

Para obter mais informações sobre a utilização de parâmetros, veja Parameters in ARM templates (Parâmetros nos modelos arm).

variáveis

variables(variableName)

Devolve o valor da variável. O nome da variável especificada tem de ser definido na secção de variáveis do modelo.

No Bicep, referencie diretamente as variáveis com os respetivos nomes simbólicos.

Parâmetros

Parâmetro Necessário Tipo Description
variableName Sim String O nome da variável a devolver.

Valor devolvido

O valor da variável especificada.

Observações

Normalmente, utiliza variáveis para simplificar o modelo ao construir valores complexos apenas uma vez. O exemplo seguinte 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 seguinte devolve valores 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')]"
    }
  }
}

O resultado do exemplo anterior com os valores predefinidos é:

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

Para obter mais informações sobre como utilizar variáveis, veja Variables in ARM template (Variáveis no modelo do ARM).

Passos seguintes