Trabalhar com bancos de dados existentes

4 minutos

Os arquivos Bicep geralmente precisam se referir aos recursos criados em outro lugar. Esses recursos podem ser criados manualmente, talvez por um colega usando o portal do Azure. Ou eles podem ser criados em outro arquivo Bicep. Há muitos motivos pelos quais você precisa se referir a esses recursos, por exemplo:

Você está adicionando um banco de dados SQL a uma instância do servidor lógico do SQL do Azure que alguém já criou.
Quando está definindo configurações de diagnóstico para recursos definidos em outro módulo Bicep.
Você precisa acessar com segurança as chaves de uma conta de armazenamento que foi implantada manualmente em sua assinatura.

O Bicep fornece a palavra-chave existing para você usar nessas situações.

Observação

Os comandos nesta unidade são mostrados para ilustrar conceitos. Não execute os comandos ainda. Você praticará o que aprendeu aqui em breve.

Fazer referência a recursos existentes

Em um arquivo Bicep, você pode definir um recurso que já existe. A declaração é semelhante a uma definição de recurso normal, mas há algumas diferenças importantes. No exemplo a seguir de uma definição de recurso existente, a definição refere-se a uma conta de armazenamento chamada toydesigndocs. A conta de armazenamento está no mesmo grupo de recursos no qual o modelo Bicep está implantando recursos.

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' existing = {
  name: 'toydesigndocs'
}

Vejamos de perto o que constitui essa definição:

Como faria com um recurso normal, inclua a palavra-chave resource, um nome simbólico, o tipo de recurso e a versão da API.

Observação

Lembre-se de que o nome simbólico é usado somente dentro desse arquivo Bicep. Se você criar esse recurso usando um arquivo Bicep e se referir a ele com o recurso existing em um arquivo Bicep diferente, os nomes simbólicos não precisarão ser correspondentes.
A palavra-chave existing indica ao Bicep que essa definição de recurso é uma referência a um recurso já criado e que o Bicep não deve tentar implantá-lo.
A propriedade name é o nome do recurso do Azure da conta de armazenamento que foi implantada anteriormente.
Você não precisa especificar location, sku ou properties porque o modelo não implanta o recurso. Ele simplesmente faz referência a um recurso existente. Pense nele como um recurso de espaço reservado.

Fazer referência a recursos filho

Você também pode fazer referência a um recurso filho existente. Use o mesmo tipo de sintaxe que você usou quando implantou um recurso filho. O exemplo a seguir mostra como você pode se referir a uma sub-rede existente, que é um recurso filho de uma rede virtual. O exemplo usa um recurso filho aninhado, como mostrado aqui:

resource vnet 'Microsoft.Network/virtualNetworks@2024-05-01' existing = {
  name: 'toy-design-vnet'

  resource managementSubnet 'subnets' existing = {
    name: 'management'
  }
}

Observe que o recurso pai e filho têm a palavra-chave existing aplicada.

Você pode se referir à sub-rede usando o mesmo operador :: que usa para outros recursos filho aninhados:

output managementSubnetResourceId string = vnet::managementSubnet.id

Fazer referência a recursos fora do grupo de recursos

Muitas vezes, você precisa se referir a recursos em um grupo de recursos diferente. Por exemplo, se você tiver uma rede virtual em um grupo de recursos centralizado, convém implantar uma máquina virtual nessa rede em seu próprio grupo de recursos. Você pode usar a palavra-chave scope para se referir a recursos existentes em um grupo de recursos diferente. O seguinte exemplo mostra como você pode se referir a uma rede virtual chamada toy-design-vnet dentro do grupo de recursos networking-rg:

resource vnet 'Microsoft.Network/virtualNetworks@2024-05-01' existing = {
  scope: resourceGroup('networking-rg')
  name: 'toy-design-vnet'
}

Observe que o scope usa a palavra-chave resourceGroup() para se referir ao grupo de recursos que contém a rede virtual.

Você pode até mesmo fazer referência a recursos em uma assinatura diferente do Azure, desde que a assinatura esteja dentro de seu locatário do Microfone Entra. Se a sua equipe de rede provisionar a rede virtual em uma assinatura diferente, o modelo poderá se referir a ela, como neste exemplo:

resource vnet 'Microsoft.Network/virtualNetworks@2024-05-01' existing = {
  scope: resourceGroup('A123b4567c-1234-1a2b-2b1a-1234abc12345', 'networking-rg')
  name: 'toy-design-vnet'
}

Observe que o scope usa a palavra-chave resourceGroup() para se referir à ID da assinatura do Azure (A123b4567c-1234-1a2b-2b1a-1234abc12345) e ao nome do grupo de recursos que contém a rede virtual.

Agora que você entende como se referir aos recursos existentes, vejamos como usar essa capacidade em seus modelos.

Adicionar recursos filho e de extensão a um recurso existente

Você pode adicionar um recurso filho a um recurso pai já criado usando uma combinação da palavra-chave existing com a parent. O seguinte modelo de exemplo cria um banco de dados SQL do Azure em um servidor que já existe:

resource server 'Microsoft.Sql/servers@2024-05-01-preview' existing = {
  name: serverName
}

resource database 'Microsoft.Sql/servers/databases@2024-05-01-preview' = {
  parent: server
  name: databaseName
  location: location
  sku: {
    name: 'Standard'
    tier: 'Standard'
  }
}

Para implantar um recurso de extensão em um recurso existente, use a palavra-chave scope. Confira um modelo que usa as palavras-chave existing e scope para adicionar um bloqueio de recurso a uma conta de armazenamento que já existe:

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' existing = {
  name: 'toydesigndocs'
}

resource lockResource 'Microsoft.Authorization/locks@2020-05-01' = {
  scope: storageAccount
  name: 'DontDelete'
  properties: {
    level: 'CanNotDelete'
    notes: 'Prevents deletion of the toy design documents storage account.'
  }
}

Fazer referência às propriedades de um recurso existente

Os recursos geralmente precisam se referir às propriedades de outros recursos. Por exemplo, se você implantar um aplicativo, poderá ser necessário saber as chaves ou as informações de conexão de outro recurso. Ao usar a palavra-chave existing, você obtém acesso às propriedades do recurso ao qual está se referindo.

Dica

É uma melhor prática procurar chaves de outros recursos dessa maneira, em vez de passá-las por meio de saídas. Você sempre obterá os dados mais atualizados. Além disso, é importante que as saídas não sejam projetadas para lidar com dados seguros, como chaves.

A maneira como você acessa as informações sobre um recurso depende do tipo de informação que você está recebendo. Se for uma propriedade não segura, você normalmente usará apenas o recurso properties. O seguinte modelo de exemplo implanta um aplicativo do Azure Functions e usa os detalhes de acesso (chave de instrumentação) para uma instância do Application Insights que já foi criada:

resource applicationInsights 'Microsoft.Insights/components@2020-02-02' existing = {
  name: applicationInsightsName
}

resource functionApp 'Microsoft.Web/sites@2024-04-01' = {
  name: functionAppName
  location: location
  kind: 'functionapp'
  properties: {
    siteConfig: {
      appSettings: [
        // ...
        {
          name: 'APPINSIGHTS_INSTRUMENTATIONKEY'
          value: applicationInsights.properties.InstrumentationKey
        }
      ]
    }
  }
}

Neste exemplo, como a chave de instrumentação não é considerada de dados confidenciais, ela está disponível nas properties do recurso. Quando você precisar acessar dados seguros, como as credenciais usadas para acessar um recurso, use a função listKeys(), conforme mostrado neste código:

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' existing = {
  name: storageAccountName
}

resource functionApp 'Microsoft.Web/sites@2024-04-01' = {
  name: functionAppName
  location: location
  kind: 'functionapp'
  properties: {
    siteConfig: {
      appSettings: [
        // ...
        {
          name: 'StorageAccountKey'
          value: storageAccount.listKeys().keys[0].value
        }
      ]
    }
  }
}

Observe que a função listKeys retorna uma matriz keys. O código Bicep recupera a propriedade value do primeiro item na matriz keys. Cada tipo de recurso tem informações diferentes disponíveis na função listKeys(). A extensão Bicep para Visual Studio Code fornece dicas para ajudar você a entender os dados que a função listKeys() de cada recurso retorna. A captura de tela a seguir mostra a saída da função listKeys() para uma conta de armazenamento:

Captura de tela da extensão Bicep para Visual Studio Code. O IntelliSense exibe várias informações retornadas pela função listKeys para uma conta de armazenamento.

Alguns recursos também dão suporte a outras funções. O IntelliSense do Visual Studio Code lista as funções disponíveis para cada recurso. Na captura de tela a seguir, você pode ver que as contas de armazenamento fornecem funções nomeadas listAccountSas() e listServiceSas() além de listKeys():

Captura de tela da extensão Bicep para Visual Studio Code. O IntelliSense exibe várias funções disponíveis para a conta de armazenamento.

Importante