Funciones de ámbito para Bicep

  • Artículo

En este artículo se describen las funciones de Bicep para obtener valores de ámbito.

managementGroup

managementGroup()

Devuelve un objeto con propiedades del grupo de administración de la implementación actual.

managementGroup(identifier)

Devuelve un objeto utilizado para establecer el ámbito en un grupo de administración.

Espacio de nombres: az.

Comentarios

managementGroup() solo se puede usar en implementaciones de un grupo de administración. Devuelve el grupo de administración actual para la operación de implementación. Se usa al obtener un objeto de ámbito o al obtener propiedades para el grupo de administración actual.

managementGroup(identifier) se puede usar para cualquier ámbito de implementación, pero solo al obtener el objeto de ámbito. Para recuperar las propiedades de un grupo de administración, no se puede pasar el identificador del grupo de administración.

Parámetros

Parámetro Obligatorio Tipo Descripción
identificador No string El identificador único en el que se implementará el grupo de administración. No use el nombre para mostrar del grupo de administración. Si no proporciona un valor, se devuelve el grupo de administración actual.

Valor devuelto

Un objeto que se usa para establecer la propiedad scope en un módulo o en un tipo de recurso de extensión. O bien, un objeto con las propiedades del grupo de administración actual.

Ejemplo de grupo de administración

En el ejemplo siguiente se establece el ámbito de un módulo en un grupo de administración.

param managementGroupIdentifier string

module  'mgModule.bicep' = {
  name: 'deployToMG'
  scope: managementGroup(managementGroupIdentifier)
}

En el ejemplo siguiente se devuelven las propiedades del grupo de administración actual.

targetScope = 'managementGroup'

var mgInfo = managementGroup()

output mgResult object = mgInfo

Se devuelve lo siguiente:

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

En el ejemplo siguiente se crea un grupo de administración y se usa esta función para establecer el grupo de administración primario.

targetScope = 'managementGroup'

param mgName string = 'mg-${uniqueString(newGuid())}'

resource newMG 'Microsoft.Management/managementGroups@2020-05-01' = {
  scope: tenant()
  name: mgName
  properties: {
    details: {
      parent: {
        id: managementGroup().id
      }
    }
  }
}

output newManagementGroup string = mgName

resourceGroup

resourceGroup()

Devuelve un objeto que representa el grupo de recursos actual.

resourceGroup(resourceGroupName)

And

resourceGroup(subscriptionId, resourceGroupName)

Devuelve un objeto utilizado para establecer el ámbito en un grupo de recursos.

Espacio de nombres: az.

Comentarios

La función resourceGroup tiene dos usos distintos. Un uso es establecer el ámbito en un módulo o en un tipo de recurso de extensión. El otro uso es para obtener detalles sobre el grupo de recursos actual. La colocación de la función determina su uso. Cuando se usa para establecer la propiedad scope, devuelve un objeto de ámbito.

resourceGroup() se puede usar para establecer el ámbito u obtener detalles sobre el grupo de recursos.

resourceGroup(resourceGroupName) y resourceGroup(subscriptionId, resourceGroupName) solo se puede usar para establecer el ámbito.

Parámetros

Parámetro Obligatorio Tipo Descripción
resourceGroupName No string El nombre del grupo de recursos en el que se va a realizar la implementación. Si no proporciona un valor, se devuelve el grupo de recursos actual.
subscriptionId No string El identificador único de la suscripción en la que se va a implementar. Si no proporciona un valor, se devuelve la suscripción actual.

Valor devuelto

Cuando se usa para establecer el ámbito, la función devuelve un objeto que es válido para la propiedad scope en un módulo o tipo de recurso de extensión.

Cuando se usa para obtener detalles sobre el grupo de recursos, la función devuelve el formato siguiente:

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

La propiedad managedBy solo se devuelve para los grupos de recursos que contienen recursos administrados por otro servicio. En los casos de Managed Applications, Databricks y AKS, el valor de la propiedad es el identificador del recurso que realiza la administración.

Ejemplo de grupo de recursos

En el ejemplo siguiente se establece el ámbito de un módulo en un grupo de recursos.

param resourceGroupName string

module exampleModule 'rgModule.bicep' = {
  name: 'exampleModule'
  scope: resourceGroup(resourceGroupName)
}

En el ejemplo siguiente se devuelven las propiedades del grupo de recursos.

output resourceGroupOutput object = resourceGroup()

Devuelve un objeto con el formato siguiente:

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

Un uso común de la función resourceGroup es crear recursos en la misma ubicación que el grupo de recursos. En el ejemplo siguiente se utiliza la ubicación del grupo de recursos para un valor de parámetro predeterminado.

param location string = resourceGroup().location

También puede usar la función resourceGroup para aplicar etiquetas del grupo de recursos a un recurso. Para más información, consulte Aplicación de etiquetas de un grupo de recursos.

subscription

subscription()

Devuelve detalles sobre la suscripción para la implementación actual.

subscription(subscriptionId)

Devuelve un objeto utilizado para establecer el ámbito en una suscripción.

Espacio de nombres: az.

Comentarios

La función de suscripción tiene dos usos distintos. Un uso es establecer el ámbito en un módulo o en un tipo de recurso de extensión. El otro uso es para obtener detalles sobre la suscripción actual. La colocación de la función determina su uso. Cuando se usa para establecer la propiedad scope, devuelve un objeto de ámbito.

subscription(subscriptionId) solo se puede usar para establecer el ámbito.

subscription() se puede usar para establecer el ámbito u obtener detalles sobre la suscripción.

Parámetros

Parámetro Obligatorio Tipo Descripción
subscriptionId No string El identificador único de la suscripción en la que se va a implementar. Si no proporciona un valor, se devuelve la suscripción actual.

Valor devuelto

Cuando se usa para establecer el ámbito, la función devuelve un objeto que es válido para la propiedad scope en un módulo o tipo de recurso de extensión.

Cuando se usa para obtener detalles sobre la suscripción, la función devuelve el formato siguiente:

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

Ejemplo de suscripción

En el ejemplo siguiente se establece el ámbito de un módulo en la suscripción.

module exampleModule 'subModule.bicep' = {
  name: 'deployToSub'
  scope: subscription()
}

En el ejemplo siguiente se devuelven los detalles de una suscripción.

output subscriptionOutput object = subscription()

tenant

tenant()

Devuelve un objeto utilizado para establecer el ámbito en el inquilino.

Or

Devuelve el inquilino del usuario.

Espacio de nombres: az.

Comentarios

tenant() se puede usar con cualquier ámbito de implementación. Siempre devuelve el inquilino actual. Puede usar esta función para establecer el ámbito de un recurso o para obtener las propiedades del inquilino actual.

Valor devuelto

Un objeto que se usa para establecer la propiedad scope en un módulo o en un tipo de recurso de extensión. O bien, un objeto con propiedades sobre el inquilino actual.

Ejemplo de inquilino

En el ejemplo siguiente se muestra un módulo que se implementa en el inquilino.

module exampleModule 'tenantModule.bicep' = {
  name: 'deployToTenant'
  scope: tenant()
}

En el ejemplo siguiente se devuelven las propiedades de un inquilino.

var tenantInfo = tenant()

output tenantResult object = tenantInfo

Se devuelve lo siguiente:

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

Algunos recursos requieren el establecimiento del identificador de inquilino para una propiedad. En lugar de pasar el identificador de inquilino como parámetro, puede recuperarlo con la función de inquilino.

resource kv 'Microsoft.KeyVault/vaults@2021-06-01-preview' = {
  name: 'examplekeyvault'
  location: 'westus'
  properties: {
    tenantId: tenant().tenantId
    ...
  }
}

Pasos siguientes

Para más información sobre los ámbitos de implementación, consulte: