Funzioni di ambito per Bicep

Questo articolo descrive le funzioni Bicep per ottenere valori di ambito.

managementGroup

managementGroup()

Restituisce un oggetto con proprietà del gruppo di gestione nella distribuzione corrente.

managementGroup(identifier)

Restituisce un oggetto utilizzato per impostare l'ambito su un gruppo di gestione.

Spazio dei nomi: az.

Osservazioni:

managementGroup() può essere usato solo nelle distribuzioni di un gruppo di gestione. Restituisce il gruppo di gestione corrente per l'operazione di distribuzione. Utilizzare quando si ottiene un oggetto ambito o si ottengono proprietà per il gruppo di gestione corrente.

managementGroup(identifier) può essere usato per qualsiasi ambito di distribuzione, ma solo quando si ottiene l'oggetto ambito. Per recuperare le proprietà per un gruppo di gestione, non è possibile passare l'identificatore del gruppo di gestione.

Parametri

Valore restituito

Oggetto utilizzato per impostare la proprietà scope su un modulo o un tipo di risorsa di estensione. O un oggetto con le proprietà per il gruppo di gestione corrente.

Esempio di gruppo di gestione

Nell'esempio seguente l'ambito di un modulo viene impostato su un gruppo di gestione.

param managementGroupIdentifier string

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

Nell'esempio successivo vengono restituite proprietà per il gruppo di gestione corrente.

targetScope = 'managementGroup'

var mgInfo = managementGroup()

output mgResult object = mgInfo

Il risultato è il seguente:

"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": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    },
    "type": "/providers/Microsoft.Management/managementGroups"
  }
}

Nell'esempio seguente viene creato un nuovo gruppo di gestione e viene usata questa funzione per impostare il gruppo di gestione padre.

targetScope = 'managementGroup'

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

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

output newManagementGroup string = mgName

resourceGroup

resourceGroup()

Restituisce un oggetto che rappresenta il gruppo di risorse corrente.

resourceGroup(resourceGroupName)

And

resourceGroup(subscriptionId, resourceGroupName)

Restituisce un oggetto utilizzato per impostare l'ambito su un gruppo di risorse.

Spazio dei nomi: az.

Osservazioni:

La funzione resourceGroup ha due utilizzi distinti. Un utilizzo consiste nell'impostare l'ambito in un modulo o in un tipo di risorsa di estensione. L'altro utilizzo consiste nell’ottenere informazioni dettagliate sul gruppo di risorse corrente. La posizione della funzione determina l'utilizzo. Quando utilizzato per impostare la proprietà scope, restituisce un oggetto ambito.

resourceGroup() può essere usato per impostare l'ambito o ottenere informazioni dettagliate sul gruppo di risorse.

resourceGroup(resourceGroupName) e resourceGroup(subscriptionId, resourceGroupName) possono essere usati solo per impostare l'ambito.

Parametri

Valore restituito

Se utilizzata per l'impostazione dell'ambito, la funzione restituisce un oggetto valido per la proprietà scope in un modulo o in un tipo di risorsa di estensione.

Se usato per ottenere informazioni dettagliate sul gruppo di risorse, la funzione restituisce il formato seguente:

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

La proprietà managedBy viene restituita solo per gruppi di risorse che contengono risorse gestite da un altro servizio. Per le applicazioni gestite, Databricks e il servizio Azure Kubernetes, il valore della proprietà è l'ID della risorsa di gestione.

Esempio di gruppo di risorse

L'esempio seguente definisce l'ambito di un modulo in un gruppo di risorse.

param resourceGroupName string

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

L’esempio successivo restituisce le proprietà del gruppo di risorse.

output resourceGroupOutput object = resourceGroup()

Restituisce un oggetto nel formato seguente:

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

Un utilizzo comune della funzione resourceGroup consiste nel creare risorse nello stesso percorso del gruppo di risorse. L'esempio seguente usa la posizione del gruppo di risorse per un valore di parametro predefinito.

param location string = resourceGroup().location

È inoltre possibile usare la funzione resourceGroup per applicare tag a una risorsa dal gruppo di risorse. Per altre informazioni, vedere Applicare tag da un gruppo di risorse.

sottoscrizione

subscription()

Restituisce i dettagli sulla sottoscrizione per la distribuzione corrente.

subscription(subscriptionId)

Restituisce un oggetto utilizzato per impostare l'ambito su una sottoscrizione.

Spazio dei nomi: az.

Osservazioni:

La funzione di sottoscrizione ha due usi distinti. Un utilizzo consiste nell'impostare l'ambito in un modulo o in un tipo di risorsa di estensione. L'altro utilizzo consiste nell’ottenere informazioni dettagliate sulla sottoscrizione corrente. La posizione della funzione determina l'utilizzo. Quando utilizzato per impostare la proprietà scope, restituisce un oggetto ambito.

subscription(subscriptionId) può essere usato solo per l'impostazione dell'ambito.

subscription() può essere usato per impostare l'ambito o ottenere informazioni dettagliate sulla sottoscrizione.

Parametri

Valore restituito

Se utilizzata per l'impostazione dell'ambito, la funzione restituisce un oggetto valido per la proprietà scope in un modulo o in un tipo di risorsa di estensione.

Se usata per ottenere informazioni dettagliate sulla sottoscrizione, la funzione restituisce il formato seguente:

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

Esempio della funzione subscription

L'esempio seguente definisce l'ambito di un modulo per la sottoscrizione.

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

Nell'esempio successivo vengono restituiti i dettagli di una sottoscrizione.

output subscriptionOutput object = subscription()

tenant

tenant()

Restituisce un oggetto utilizzato per impostare l'ambito sul tenant.

O

Restituisce il tenant dell'utente.

Spazio dei nomi: az.

Osservazioni:

tenant() può essere usato con qualsiasi ambito di distribuzione. Restituisce sempre il tenant corrente. È possibile usare questa funzione per impostare l'ambito di una risorsa o per ottenere le proprietà per il tenant corrente.

Valore restituito

Oggetto utilizzato per impostare la proprietà scope su un modulo o un tipo di risorsa di estensione. O un oggetto con proprietà relative al tenant corrente.

Esempio di tenant

L'esempio seguente mostra un modulo distribuito nel tenant.

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

Nell'esempio successivo vengono restituite le proprietà per un tenant.

var tenantInfo = tenant()

output tenantResult object = tenantInfo

Il risultato è il seguente:

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

Alcune risorse richiedono l'impostazione dell'ID tenant per una proprietà. Anziché passare l'ID tenant come parametro, è possibile recuperarlo con la funzione tenant.

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

Passaggi successivi

Per ulteriori informazioni sugli ambiti di distribuzione, vedere:

• Distribuzioni di un gruppo di risorse
• Distribuzioni di sottoscrizioni
• Distribuzioni di gruppi di gestione
• Distribuzioni di tenant