Declaração de recursos em Bicep

Este artigo descreve a sintaxe que utiliza para adicionar um recurso ao seu ficheiro Bicep.

Declaração

Adicione uma declaração de recurso com resource a palavra-chave. Define um nome simbólico para o recurso. O nome simbólico não é o mesmo que o nome do recurso. Utilize o nome simbólico para referenciar o recurso noutras partes do seu ficheiro Bicep.

resource <symbolic-name> '<full-type-name>@<api-version>' = {
  <resource-properties>
}

Por isso, pode começar com uma declaração para uma conta de armazenamento:

resource stg 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  ...
}

Os nomes simbólicos são sensíveis às caixas. Podem conter letras, números e sublinhados ( _ ). Não podem começar com um número. Um recurso não pode ter o mesmo nome que um parâmetro, variável ou módulo.

Para ver os tipos de recursos disponíveis e a versão, consulte Referência de recursos Bicep. O Bicep não suporta , que está disponível nos modelos do apiProfileapiProfile

Para implementar condicionalmente um recurso, utilize if a sintaxe. Para obter mais informações, consulte Implementação condicional em Bicep.

resource <symbolic-name> '<full-type-name>@<api-version>' = if (condition) {
  <resource-properties>
}

Para implementar mais do que uma instância de um recurso, utilize for a sintaxe. Pode utilizar o decorador para especificar se as instâncias estão implementadas em série batchSize ou em paralelo. Para obter mais informações, consulte Ciclos iterativos em Bicep.

@batchSize(int) // optional decorator for serial deployment
resource <symbolic-name> '<full-type-name>@<api-version>' = [for <item> in <collection>: {
  <properties-to-repeat>
}]

Também pode utilizar for a sintaxe nas propriedades do recurso para criar uma matriz.

resource <symbolic-name> '<full-type-name>@<api-version>' = {
  properties: {
    <array-property>: [for <item> in <collection>: <value-to-repeat>]
  }
}

Nome do recurso

Cada recurso tem um nome. Ao definir o nome do recurso, preste atenção às regras e restrições de nomes de recursos.

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: 'examplestorage'
  ...
}

Normalmente, tem de definir o nome para um parâmetro para que possa passar com valores diferentes durante a implementação.

@minLength(3)
@maxLength(24)
param storageAccountName string

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: storageAccountName
  ...
}

Localização

Muitos recursos necessitam de uma localização. Pode determinar se o recurso necessita de uma localização através do intellisense ou da referência de modelo. O exemplo seguinte adiciona um parâmetro de localização utilizado para a conta de armazenamento.

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: 'examplestorage'
  location: 'eastus'
  ...
}

Normalmente, definiria uma localização para um parâmetro para que possa implementar em localizações diferentes.

param location string = resourceGroup().location

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: 'examplestorage'
  location: location
  ...
}

São suportados diferentes tipos de recursos em localizações diferentes. Para obter as localizações suportadas para um serviço do Azure, consulte Produtos disponíveis por região. Para obter as localizações suportadas de um tipo de recurso, utilize Azure PowerShell ou CLIzure do Azure.

((Get-AzResourceProvider -ProviderNamespace Microsoft.Batch).ResourceTypes `
  | Where-Object ResourceTypeName -eq batchAccounts).Locations

Etiquetas

Pode aplicar etiquetas a um recurso durante a implementação. As etiquetas ajudam-no a organizar logicamente os seus recursos implementados. Para ver exemplos das diferentes formas de especificar as etiquetas, consulte Etiquetas ARM modelo.

Identidades geridas para recursos do Azure

Alguns recursos suportam identidades geridas para recursos do Azure. Esses recursos têm um objeto de identidade no nível de raiz da declaração do recurso.

Pode utilizar identidades atribuídas pelo sistema ou identidades atribuídas pelo utilizador.

O exemplo seguinte mostra como configurar uma identidade atribuída ao sistema para um Cluster de Serviços do Azure Kubernetes.

resource aks 'Microsoft.ContainerService/managedClusters@2020-09-01' = {
  name: clusterName
  location: location
  tags: tags
  identity: {
    type: 'SystemAssigned'
  }

O exemplo seguinte mostra como configurar uma identidade atribuída pelo utilizador para uma máquina virtual.

param userAssignedIdentity string

resource vm 'Microsoft.Compute/virtualMachines@2020-06-01' = {
  name: vmName
  location: location
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${userAssignedIdentity}': {}
    }
  }

Propriedades específicas de recursos

As propriedades anteriores são genéricas para a maioria dos tipos de recursos. Depois de definir esses valores, tem de definir as propriedades específicas do tipo de recurso que está a implementar.

Utilize intellisense ou Referência de recursos Bicep para determinar que propriedades estão disponíveis e quais são necessárias. O exemplo seguinte define as restantes propriedades de uma conta de armazenamento.

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: 'examplestorage'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'
    tier: 'Standard'
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

Dependências

Ao implementar recursos, poderá ter de se certificar de que alguns recursos existem antes de outros recursos. Por exemplo, precisa de um servidor SQL lógico antes de implementar uma base de dados. Esta relação é estabelecendo um recurso como dependente do outro recurso. A ordem da implementação de recursos pode ser influenciada de duas formas: dependência implícita e dependênciaexplícita

O Gestor de Recursos do Azure avalia as dependências entre recursos e implementa-as pela sua ordem dependente. Quando os recursos não estão dependentes uns dos outros, o Gestor de Recursos implementa-os em paralelo. Só precisa de definir dependências para recursos implementados no mesmo ficheiro Bicep.

Dependência implícita

É criada uma dependência implícita quando uma declaração de recurso referencia outro recurso na mesma implementação. Por exemplo, dnsZone é referenciado pela segunda definição de recurso no seguinte exemplo:

resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = {
  name: 'myZone'
  location: 'global'
}

resource otherResource 'Microsoft.Example/examples@2020-06-01' = {
  name: 'exampleResource'
  properties: {
    // get read-only DNS zone property
    nameServers: dnsZone.properties.nameServers
  }
}

Um recurso aninhado também tem uma dependência implícita do recurso que contém.

resource myParent 'My.Rp/parentType@2020-01-01' = {
  name: 'myParent'
  location: 'West US'

  // depends on 'myParent' implicitly
  resource myChild 'childType' = {
    name: 'myChild'
  }
}

Quando existir uma dependência implícita, não adicione uma dependência explícita.

Para obter mais informações sobre recursos aninhados, consulte Definir nome e tipo de recursos para crianças no Bicep.

Dependência explícita

Uma dependência explícita é declarada com a dependsOn propriedade. A propriedade aceita uma matriz de identificadores de recursos, para que possa especificar mais do que uma dependência.

O exemplo seguinte mostra uma zona DNS com nome otherZone que depende de uma zona DNS denominada: dnsZone

resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = {
  name: 'demoeZone1'
  location: 'global'
}

resource otherZone 'Microsoft.Network/dnszones@2018-05-01' = {
  name: 'demoZone2'
  location: 'global'
  dependsOn: [
    dnsZone
  ]
}

Apesar de estar disposto a utilizar para mapear relações entre os seus recursos, é importante compreender o motivo pelo qual o dependsOn está a fazer. Por exemplo, para documentar a forma como os recursos estão interligados, dependsOn não é a abordagem certa. Não pode consulta quais os recursos que foram definidos no dependsOn elemento após a implementação. Definir dependências desnecessárias diminui o tempo de implementação porque o Gestor de Recursos não consegue implementar esses recursos em paralelo.

Embora por vezes sejam necessárias dependências explícitas, a necessidade das mesmas é rara. Na maioria dos casos, pode utilizar um nome simbólico para sugerir a dependência entre recursos. Se definir dependências explícitas, deve ter em consideração se existe uma forma de a remover.

Visualizar dependências

Visual Studio Código fornece uma ferramenta para visualizar as dependências. Abra um ficheiro Bicep no Visual Studio e, em seguida, selecione o botão de visualização no canto superior esquerdo. A captura de ecrã seguinte mostra as dependências de uma máquina virtual.

Screenshot of Visual Studio Code Bicep resource visualizer

Recursos existentes

Para referenciar um recurso que está fora do ficheiro Bicep atual, utilize existing a palavra-chave numa declaração de recurso.

Ao utilizar a existing palavra-chave, forneça name o recurso. O exemplo seguinte obtemos uma conta de armazenamento existente no mesmo grupo de recursos da implementação atual.

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' existing = {
  name: 'examplestorage'
}

output blobEndpoint string = stg.properties.primaryEndpoints.blob

Opcionalmente, pode definir scope a propriedade para aceder a um recurso num âmbito diferente. O exemplo seguinte referencia uma conta de armazenamento existente num grupo de recursos diferente.

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' existing = {
  name: 'examplestorage'
  scope: resourceGroup(exampleRG)
}

output blobEndpoint string = stg.properties.primaryEndpoints.blob

Se tentar referenciar um recurso que não existe, receberá o erro NotFound e a implementação falhará.

Para obter mais informações sobre como definir o âmbito, consulte Funções de âmbito para Bicep.

Os exemplos anteriores não implementam a conta de armazenamento. Em vez disso, pode aceder às propriedades do recurso existente com o nome simbólico.

Passos seguintes