Compartilhar via


Início Rápido: Solucionar problemas de implantações de arquivo Bicep

Este início rápido descreve como solucionar problemas de erros de implantação de arquivo Bicep. Você criará um arquivo com erros e aprenderá a corrigir os erros.

Há três tipos de erros relacionados a uma implantação:

  • Os erros de validação ocorrem antes do início de uma implantação e são causados por erros de sintaxe em seu arquivo. Um editor de código como Visual Studio Code pode identificar esses erros.
  • Erros de validação de simulação ocorrem quando um comando de implantação é executado, mas os recursos não são implantados. Esses erros são encontrados sem que seja necessário iniciar a implantação. Por exemplo, se um valor de parâmetro estiver incorreto, o erro será encontrado na validação de simulação.
  • Os erros de implantação ocorrem durante o processo de implantação e só podem ser encontrados por meio da avaliação do progresso da implantação no seu ambiente do Azure.

Todos os tipos de erros retornam um código de erro que você usa para solucionar problemas de implantação. Os erros de validação de simulação são mostrados no log de atividades, mas não aparecem no histórico de implantação. Um arquivo Bicep com erros de sintaxe não é compilado em JSON nem mostrado no log de atividades.

Pré-requisitos

Para concluir este início rápido, você precisará dos seguintes itens:

Criar um arquivo Bicep com erros

Copie o arquivo Bicep a seguir e salve-o localmente. Você usará esse arquivo para solucionar um erro de validação, um erro de simulação e um erro de implantação. Este início rápido pressupõe que o arquivo tenha sido nomeado como troubleshoot.bicep, mas você pode dar a ele qualquer nome.

@description('SKU for the storage account')
@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
parameter storageAccountType string = 'Standard_LRS'

@description('Prefix for storage name.')
param prefixName string

var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
  properties: {}
}

resource existingVNet 'Microsoft.Network/virtualNetworks@2021-03-01' existing = {
  name: 'doesnotexist'
}

output storageAccountName string = storageAccountName
output vnetResult object = existingVNet

Corrigir erro de validação

Abra o arquivo no Visual Studio Code. Você observará que o Visual Studio Code identifica um erro de sintaxe. A primeira declaração de parâmetro é marcada com sublinhados vermelhos para indicar um erro.

Captura de tela do Visual Studio Code com rabiscos vermelhos destacando um erro de sintaxe em um arquivo Bicep.

As linhas marcadas com um erro são:

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
parameter storageAccountType string = 'Standard_LRS'

Ao passar o mouse sobre parameter, você verá uma mensagem de erro.

Captura de tela de uma mensagem de erro detalhada exibida no Visual Studio Code ao passar o mouse sobre um erro de sintaxe em um arquivo Bicep.

A mensagem informa: este tipo de declaração não é reconhecido. Especifique um parâmetro, variável, recurso ou declaração de saída. Se você tentar implantar esse arquivo, obterá a mesma mensagem de erro do comando de implantação.

Se você olhar para a documentação de uma declaração de parâmetro, verá que a palavra-chave é, na verdade, param. Quando você altera essa sintaxe, o erro de validação desaparece. O decorador @allowed também foi marcado como um erro, mas esse erro também é resolvido alterando a declaração de parâmetro. O decorador foi marcado como um erro porque espera uma declaração de parâmetro após o decorador. Essa condição não era verdadeira quando a declaração estava incorreta.

A linha fixa é:

param storageAccountType string = 'Standard_LRS'

Corrigir erro de simulação

Agora que você corrigiu o erro de validação, é hora de implantar o arquivo. Porém, você fornecerá um valor de parâmetro incorreto para ver um erro de simulação.

az group create --name troubleshootRG --location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.bicep \
  --parameters prefixName=longNamewith!!Charactersthatarenotallowed

O Azure Resource Manager determina que o nome da conta de armazenamento contém caracteres que não são permitidos. Ele não tenta implantar.

Você verá uma mensagem de erro que indica falha na validação de simulação. Você também pode receber uma mensagem informando que o nome da conta de armazenamento deve ter entre 3 e 24 caracteres e usar apenas números e letras maiúsculas. O prefixo fornecido não atende a esse requisito. Para saber mais, confira Solucionar erros de nomes de conta de armazenamento.

Como o erro foi capturado na simulação, não haverá implantação no histórico.

Captura de tela da seção de histórico de implantação do portal do Azure que não mostra implantações para um arquivo Bicep.

No entanto, a implantação com falha existirá no Log de Atividades.

Captura de tela do registro de atividades do portal do Azure que exibe um erro de validação de preflight para uma implantação de arquivo Bicep.

Você pode abrir detalhes da entrada de log para ver a mensagem de erro.

Corrigir erro de implantação

Você implantará o arquivo novamente e fornecerá um valor permitido para o parâmetro de prefixo de nome.

az group create --name troubleshootRG --location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.bicep \
  --parameters prefixName=stg

A implantação é iniciada, mas falha com uma mensagem de que a rede virtual não foi encontrada. Normalmente, você corrigiria esse erro alterando a referência para o recurso. Neste início rápido, você excluirá a referência. Para saber mais sobre esse código de erro, confira Solucionar erros de recurso não encontrado.

Observe no portal que a implantação aparece no histórico.

Captura de tela da seção de histórico de implantação do portal do Azure que mostra uma implantação que falhou para um arquivo Bicep.

Você pode abrir a entrada no histórico de implantação para obter detalhes sobre o erro. O erro também existe no log de atividades.

O arquivo Bicep tenta referenciar uma rede virtual que não existe no grupo de recursos. Exclua a referência à rede virtual existente para corrigir o erro.

@description('SKU for the storage account')
@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

@description('Prefix for storage name.')
param prefixName string

var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
  properties: {}
}

output storageAccountName string = storageAccountName

Você pode implantar esse arquivo Bicep sem erros.

Limpar os recursos

Quando os recursos do Azure não forem mais necessários, exclua o grupo de recursos. Você pode excluir o grupo de recursos do Cloud Shell ou do portal.

az group delete --name troubleshootRG

Para excluir o grupo de recursos do portal, siga estas etapas:

  1. Na portal do Azure, insira Grupos de recursos na caixa de pesquisa.
  2. No campo Filtrar por nome, insira o nome do grupo de recursos.
  3. Selecione o nome do grupo de recursos.
  4. Selecione Excluir grupo de recursos.
  5. Para confirmar a exclusão, insira o nome do grupo recursos e selecione Excluir.

Próximas etapas

Neste início rápido, você aprendeu a solucionar problemas de erros de implantação de arquivo Bicep.