Funzioni di ambito per Bicep

  • Articolo

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.

Commenti

managementGroup() può essere usato solo nelle distribuzioni di un gruppo di gestione. Restituisce il gruppo di gestione corrente per l'operazione di distribuzione. Usare quando si ottiene un oggetto scope 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 scope. Per recuperare le proprietà per un gruppo di gestione, non è possibile passare l'identificatore del gruppo di gestione.

Parametri

Parametro Obbligatoria Tipo Descrizione
identificatore No string Identificatore univoco per il gruppo di gestione da distribuire. Non usare il nome visualizzato per il gruppo di gestione. Se non si specifica un valore, viene restituito il gruppo di gestione corrente.

Valore restituito

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

Esempio di gruppo di gestione

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

param managementGroupIdentifier string

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

L'esempio successivo restituisce le 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": "00000000-0000-0000-0000-000000000000"
    },
    "type": "/providers/Microsoft.Management/managementGroups"
  }
}

L'esempio successivo crea un nuovo gruppo di gestione e usa questa funzione per impostare il gruppo di gestione padre.

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()

Restituisce un oggetto che rappresenta il gruppo di risorse corrente.

resourceGroup(resourceGroupName)

e

resourceGroup(subscriptionId, resourceGroupName)

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

Spazio dei nomi: az.

Commenti

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

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

resourceGroup(resourceGroupName) e resourceGroup(subscriptionId, resourceGroupName) può essere usato solo per l'impostazione dell'ambito.

Parametri

Parametro Obbligatoria Tipo Descrizione
resourceGroupName No string Nome del gruppo di risorse da distribuire in. Se non si specifica un valore, viene restituito il gruppo di risorse corrente.
subscriptionId No string Identificatore univoco per la sottoscrizione da distribuire in. Se non si specifica un valore, viene restituita la sottoscrizione corrente.

Valore restituito

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

Quando viene usato per ottenere dettagli 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

Nell'esempio seguente viene inserito un ambito di un modulo in un gruppo di risorse.

param resourceGroupName string

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

Nell'esempio successivo vengono restituite 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.

Commenti

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

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

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

Parametri

Parametro Obbligatoria Tipo Descrizione
subscriptionId No string Identificatore univoco per la sottoscrizione da distribuire in. Se non si specifica un valore, viene restituita la sottoscrizione corrente.

Valore restituito

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

Quando viene usato per ottenere dettagli 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 seguente vengono restituiti i dettagli per una sottoscrizione.

output subscriptionOutput object = subscription()

tenant

tenant()

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

Oppure

Restituisce il tenant dell'utente.

Spazio dei nomi: az.

Commenti

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 scope proprietà su un modulo o un tipo di risorsa di estensione. In alternativa, un oggetto con proprietà sul tenant corrente.

Esempio di tenant

L'esempio seguente mostra un modulo distribuito nel tenant.

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

Nell'esempio seguente vengono restituite le proprietà di 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": "00000000-0000-0000-0000-000000000000"
  }
}

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@2021-06-01-preview' = {
  name: 'examplekeyvault'
  location: 'westus'
  properties: {
    tenantId: tenant().tenantId
    ...
  }
}

Passaggi successivi

Per altre informazioni sugli ambiti di distribuzione, vedere: