Funções de escopo para modelos do ARM

  • Artigo

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

Para obter valores de parâmetros, de variáveis ou da implantação atual, veja Funções de valor de implantação.

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 funções de escopo.

managementGroup

managementGroup()

Retorna um objeto com propriedades do grupo de gerenciamento na implantação atual.

No Bicep, use a função de escopo managementGroup.

Comentários

managementGroup() só pode ser usado em implantações de grupo de gerenciamento. Ele retorna o grupo de gerenciamento atual para a operação de implantação. Use para obter propriedades para o grupo de gerenciamento atual.

Valor retornado

Um objeto com as propriedades do grupo de gerenciamento atual.

Exemplo de grupo de gerenciamento

O exemplo a seguir retorna propriedades para o grupo de gerenciamento atual.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "mgInfo": "[managementGroup()]"
  },
  "resources": [],
  "outputs": {
    "mgResult": {
      "type": "object",
      "value": "[variables('mgInfo')]"
    }
  }
}

Isso retorna:

"mgResult": {
  "type": "Object",
  "value": {
    "id": "/providers/Microsoft.Management/managementGroups/examplemg1",
    "name": "examplemg1",
    "properties": {
      "details": {
        "parent": {
          "displayName": "Tenant Root Group",
          "id": "/providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000000",
          "name": "00000000-0000-0000-0000-000000000000"
        },
        "updatedBy": "00000000-0000-0000-0000-000000000000",
        "updatedTime": "2020-07-23T21:05:52.661306Z",
        "version": "1"
      },
      "displayName": "Example MG 1",
      "tenantId": "00000000-0000-0000-0000-000000000000"
    },
    "type": "/providers/Microsoft.Management/managementGroups"
  }
}

O próximo exemplo cria um novo grupo de gerenciamento e usa essa função para definir o grupo de gerenciamento pai.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "mgName": {
      "type": "string",
      "defaultValue": "[format('mg-{0}', uniqueString(newGuid()))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Management/managementGroups",
      "apiVersion": "2020-05-01",
      "scope": "/",
      "name": "[parameters('mgName')]",
      "properties": {
        "details": {
          "parent": {
            "id": "[managementGroup().id]"
          }
        }
      }
    }
  ],
  "outputs": {
    "newManagementGroup": {
      "type": "string",
      "value": "[parameters('mgName')]"
    }
  }
}

resourceGroup

resourceGroup()

Retorna um objeto que representa o grupo de recursos atual.

No Bicep, use a função de escopo resourceGroup.

Valor retornado

O objeto retornado está no seguinte formato:

{
  "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}",
  "name": "{resourceGroupName}",
  "type":"Microsoft.Resources/resourceGroups",
  "location": "{resourceGroupLocation}",
  "managedBy": "{identifier-of-managing-resource}",
  "tags": {
  },
  "properties": {
    "provisioningState": "{status}"
  }
}

A propriedade managedBy é retornada somente para grupos de recursos que contêm recursos gerenciados por outro serviço. Para aplicativos gerenciados, databricks e AKS, o valor da propriedade é a ID de recurso do recurso de gerenciamento.

Comentários

A função resourceGroup() não pode ser usada em um modelo que está implantado no nível da assinatura. Ela só pode ser usada em modelos que são implantados em um grupo de recursos. Você pode usar a função resourceGroup() em um modelo vinculado ou aninhado (com escopo interno) que se destina a um grupo de recursos, mesmo quando o modelo pai é implantado na assinatura. Nesse cenário, o modelo vinculado ou aninhado é implantado no nível do grupo de recursos. Para obter mais informações sobre como direcionar um grupo de recursos em uma implantação em nível de assinatura, confira implantar recursos do Azure em mais de uma assinatura ou grupo de recursos.

Um uso comum da função resourceGroup é criar recursos no mesmo local que o grupo de recursos. O exemplo a seguir usa o local do grupo de recursos para um valor de parâmetro padrão.

"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
}

Você também pode usar a função resourceGroup para aplicar marcas do grupo de recursos a um recurso. Para obter mais informações, confira Aplicar marcas do grupo de recursos.

Ao usar modelos aninhados para implantar em vários grupos de recursos, você pode especificar o escopo para avaliar a função resourceGroup. Para saber mais, consulte Implantar recursos do Azure em mais de uma assinatura ou grupo de recursos.

Exemplo de grupo de recursos

O exemplo a seguir retorna as propriedades do grupo de recursos.

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

O exemplo anterior retorna um objeto no seguinte formato:

{
  "id": "/subscriptions/{subscription-id}/resourceGroups/examplegroup",
  "name": "examplegroup",
  "type":"Microsoft.Resources/resourceGroups",
  "location": "southcentralus",
  "properties": {
    "provisioningState": "Succeeded"
  }
}

subscription

subscription()

Retorna detalhes sobre a assinatura da implantação atual.

No Bicep, use a função de escopo assinatura.

Valor retornado

A função retorna o seguinte formato:

{
  "id": "/subscriptions/{subscription-id}",
  "subscriptionId": "{subscription-id}",
  "tenantId": "{tenant-id}",
  "displayName": "{name-of-subscription}"
}

Comentários

Ao usar modelos aninhados para implantar em várias assinaturas, você pode especificar o escopo para avaliar a função de assinatura. Para saber mais, consulte Implantar recursos do Azure em mais de uma assinatura ou grupo de recursos.

Exemplo de assinatura

O exemplo a seguir mostra a função de assinatura chamada na seção de saídas.

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

locatário

tenant()

Retorna o locatário do usuário.

No Bicep, use a função de escopo locatário.

Comentários

tenant() pode ser usado com qualquer escopo de implantação. Ele sempre retorna o locatário atual. Use essa função para obter propriedades para o locatário atual.

Ao configurar o escopo de um modelo vinculado ou recurso de extensão, use a sintaxe: "scope": "/".

Valor retornado

Um objeto com propriedades sobre o locatário atual.

Exemplo de locatário

O exemplo a seguir retorna as propriedades de um locatário.

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

Isso retorna:

"tenantResult": {
  "type": "Object",
  "value": {
    "countryCode": "US",
    "displayName": "Contoso",
    "id": "/tenants/00000000-0000-0000-0000-000000000000",
    "tenantId": "00000000-0000-0000-0000-000000000000"
  }
}

Próximas etapas