Compartilhar via

Desenvolver um script de implantação em Bicep

  • Artigo

Este artigo fornece exemplos para mostrar como desenvolver um script de implantação em Bicep.

Os recursos de script de implantação podem ter uma duração de implantação. Para um desenvolvimento e teste eficientes desses scripts, considere estabelecer um ambiente de desenvolvimento dedicado, como uma instância de contêiner do Azure (ACI) ou uma instância do Docker. Para obter mais informações, consulte Criar um ambiente de desenvolvimento.

Sintaxe

O arquivo Bicep a seguir é um exemplo de um recurso de script de implantação. Para obter mais informações, consulte o esquema de script de implantação mais recente.

resource <symbolic-name> 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: '<resource-name>'
  location: resourceGroup().location
  tags: {}
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '<user-assigned-identity-id>': {}
    }
  }
  kind: 'AzureCLI'
  properties: {
    storageAccountSettings: {
      storageAccountName: '<storage-account-name>'
      storageAccountKey: '<storage-account-key>'
    }
    containerSettings: {
      containerGroupName: '<container-group-name>'
      subnetIds: [
        {
          id: '<subnet-id>'
        }
      ]
    }
    environmentVariables: []
    azCliVersion: '2.52.0'
    arguments: '<script-arguments>'
    scriptContent: '''<azure-cli-or-azure-powershell-script>''' // or primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/inlineScript.ps1'
    supportingScriptUris: []
    timeout: 'P1D'
    cleanupPreference: 'OnSuccess'
    retentionInterval: 'P1D'
    forceUpdateTag: '1'
  }
}

No script de implantação, especifique estes valores de propriedade:

  • tags: especifica as tags do script de implantação. Se o serviço de script de implantação criar os dois recursos de suporte (uma conta de armazenamento e uma instância de contêiner), as tags serão passadas para ambos os recursos. Você pode usar as tags para identificar os recursos. Outra maneira de identificar esses recursos é por meio de seus sufixos, que contêm azscripts. Para obter mais informações, confira Monitorar e solucionar problemas de scripts de implantação.

  • identity: para a API de script de implantação versão 2020-10-01 ou posterior, uma identidade gerenciada atribuída pelo usuário é opcional, a menos que você precise executar ações específicas do Azure no script ou que você esteja executando o script de implantação em uma rede privada. A versão 2019-10-01-preview da API requer uma identidade gerenciada porque o serviço de script de implantação a usa para executar os scripts.

    Quando você especifica a propriedade identity, o serviço de script chama Connect-AzAccount -Identity antes de invocar o script do usuário. No momento, somente há suporte para uma identidade gerenciada atribuída pelo usuário. Para fazer login com uma identidade diferente no script de implantação, você pode chamar Connect-AzAccount. Para obter mais informações, consulte Configurar as permissões mínimas.

  • kind: especifica o tipo de script, AzurePowerShell ou AzureCLI. Além de kind, você precisa especificar a propriedade azPowerShellVersion ou azCliVersion.

  • storageAccountSettings: Especifique as configurações para usar uma conta de armazenamento existente. Se storageAccountName não for especificado, uma conta de armazenamento será criada automaticamente. Para obter mais informações, consulte Usar uma conta de armazenamento existente.

  • containerSettings: personaliza o nome da instância de contêiner do Azure. Para obter informações sobre como configurar o nome de grupo do contêiner, consulte Configurar uma instância de contêiner mais adiante neste artigo. Para obter informações sobre como configurar subnetIds para executar o script de implantação em uma rede privada, consulte Acessar uma rede virtual privada.

  • environmentVariables: especifica as variáveis de ambiente a serem passadas para o script.

  • azPowerShellVersion/azCliVersion: Especifique a versão de módulo a ser usada.

    Consulte uma lista de versões da CLI do Azure compatíveis.

    Importante

    O script de implantação usa as imagens da CLI disponíveis no Registro de Artefato da Microsoft. A certificação de uma imagem da CLI para o script de implantação normalmente leva cerca de um mês. Não use as versões da CLI que foram lançadas nos últimos 30 dias. Para localizar as datas de lançamento das imagens, consulte as notas de versão da CLI do Azure. Se você usar uma versão não compatível, a mensagem de erro listará as versões compatíveis.

  • arguments: Especifique os valores de parâmetro. os valores são separados por espaços.

    Os scripts de implantação dividem os argumentos em uma matriz de cadeias de caracteres, invocando a chamada do sistema CommandLineToArgvW. Essa etapa é necessária porque os argumentos são passados como uma propriedade de comando para as Instâncias de Contêiner do Azure e a propriedade de comando é uma matriz de cadeias de caracteres.

    Se os argumentos contiverem caracteres de escape, faça o escape dos caracteres novamente. Por exemplo, na sintaxe Bicep da amostra anterior, o argumento é -name \"John Dole\". A cadeia de caracteres de escape é -name \\"John Dole\\".

    Para passar um parâmetro Bicep do tipo object como um argumento, converta o objeto em uma cadeia de caracteres usando a função string() e use a função replace() para substituir quaisquer aspas (") por aspas com escape duplo (\\"). Por exemplo:

    replace(string(parameters('tables')), '"', '\\"')

    Para obter mais informações, consulte o exemplo de arquivo Bicep.

  • scriptContent: especifique o conteúdo do script. Pode ser um script em linha ou um arquivo de script externo importado usando a função loadTextContent. Para obter mais informações, consulte Arquivo em linha versus externo posteriormente neste artigo. Para executar um script externo, use primaryScriptUri.

  • primaryScriptUri: Especifique uma URL acessível publicamente para o script de implantação primário com extensões de arquivo compatíveis. Para obter mais informações, consulte Usar scripts externos mais adiante neste artigo.

  • supportingScriptUris: Especifique uma matriz de URLs acessíveis publicamente para dar suporte a arquivos que são chamados em scriptContent ou primaryScriptUri. Para obter mais informações, consulte Arquivo em linha versus externo posteriormente neste artigo.

  • timeout: especifica o tempo máximo permitido para a execução do script, no formato ISO 8601. O valor padrão é P1D.

  • forceUpdateTag: alterar esse valor entre implantações de arquivos Bicep força o script de implantação a ser executado novamente. Se você usar a função newGuid() ou utcNow(), poderá usá-la somente no valor padrão de um parâmetro. Para saber mais, consulte Executar um script mais de uma vez posteriormente neste artigo.

  • cleanupPreference. Especifique a preferência para limpar os dois recursos de implantação de suporte (a conta de armazenamento e a instância de contêiner) quando a execução do script estiver em estado terminal. A configuração padrão é Always, que exige a exclusão de recursos de suporte, independentemente do estado terminal (Succeeded, Failed ou Canceled). Para saber mais, confira Limpar os recursos do script de implantação mais adiante neste artigo.

  • retentionInterval: especifica o intervalo para o qual o serviço retém o recurso de script de implantação depois que a execução do script de implantação atingir um estado terminal. O recurso do script de implantação é excluído quando essa duração expira. A duração é baseada na norma ISO 8601. O intervalo de retenção está entre 1 hora (PT1H) e 26 horas (PT26H). Você usa essa propriedade quando cleanupPreference está definido como OnExpiration. Para saber mais, confira Limpar os recursos do script de implantação mais adiante neste artigo.

Mais amostras

  • Amostra 1: crie um cofre de chaves e use um script de implantação para atribuir um certificado ao cofre de chaves.
  • Amostra 2: crie um grupo de recursos no nível da assinatura, crie um cofre de chaves no grupo de recursos e, em seguida, use um script de implantação para atribuir um certificado ao cofre de chaves.
  • Amostra 3: crie uma identidade gerenciada atribuída pelo usuário, atribua a função de colaborador à identidade no nível do grupo de recursos, crie um cofre de chaves e use um script de implantação para atribuir um certificado ao cofre de chaves.
  • Amostra 4: crie manualmente uma identidade gerenciada atribuída pelo usuário e atribua a ela permissão para usar a API do Microsoft Graph para criar aplicativos do Microsoft Entra. No arquivo Bicep, use um script de implantação para criar um aplicativo e uma entidade de serviço do Microsoft Entra e para gerar as IDs de objeto e a ID do cliente como saída.

Arquivo em linha versus externo

Um script de implantação pode residir em um arquivo Bicep ou você pode armazená-lo externamente como um arquivo separado.

Usar um script em linha

O arquivo Bicep a seguir mostra como usar um script em linha.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlineCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'set -e; output="Hello $1"; echo $output'
    retentionInterval: 'P1D'
  }
}

Incluir set -e em seu script para ativar a saída imediata se um comando retornar um status diferente de zero. Essa prática simplifica os processos de depuração de erros.

Carregar um arquivo de script

Use a função loadTextContent para recuperar um arquivo de script como uma cadeia de caracteres. Essa função permite que você mantenha o script em um arquivo externo e o acesse como um script de implantação. O caminho especificado para o arquivo de script é relativo ao arquivo Bicep.

Você pode extrair o script em linha do arquivo Bicep anterior em um arquivo hello.sh e, então, colocar o arquivo em uma subpasta chamada scripts.

output="Hello $1"
echo $output

Em seguida, você pode revisar o arquivo Bicep anterior, como o exemplo a seguir:

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'loadTextContentCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: loadTextContent('./scripts/hello.sh')
    retentionInterval: 'P1D'
  }
}

Usar scripts externos

Você pode usar arquivos de script externos em vez de scripts em linha. Há suporte somente para scripts primários do PowerShell com a extensão .ps1. Para scripts da CLI, os scripts principais podem conter qualquer extensão válida de script Bash ou nenhuma extensão. Para empregar arquivos de script externos, troque scriptContent por primaryScriptUri.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'externalScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/hello.sh'
    arguments: '-name ${name}'
    retentionInterval: 'P1D'
  }
}

Os arquivos de scripts externos devem estar acessíveis. Para ajudar a proteger os arquivos de script armazenados nas contas de armazenamento do Azure, gere um token SAS (Assinatura de Acesso Compartilhado) e inclua-o no URI para o modelo. Defina a validade de forma a permitir que haja tempo suficiente para concluir a implantação. Para obter mais informações, consulte Implantar um modelo do ARM particular com um token SAS.

Você é responsável por garantir a integridade do script ao qual o script de implantação faz referência (primaryScriptUri ou supportingScriptUris). Referencie somente scripts nos quais você confia.

Usar scripts de suporte

Você pode separar as lógicas complicadas em um ou mais arquivos de script de suporte. Use a propriedade supportingScriptUris para fornecer uma matriz de URIs para os arquivos de script de suporte, caso seja necessário.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'supportingScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'output="Hello $1"; echo $output; ./hello.sh "$1"'
    supportingScriptUris: [
      'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/master/samples/deployment-script/hello.sh'
    ]
    retentionInterval: 'P1D'
  }
}

Você pode chamar os arquivos de script de suporte dos scripts em linha e dos arquivos de script primários. Os arquivos de script de suporte não têm restrições sobre a extensão do arquivo.

Os arquivos de suporte são copiados para azscripts/azscriptinput no runtime. Use um caminho relativo para referenciar os arquivos de suporte dos scripts em linha e dos arquivos de script primários.

Acessar recursos do Azure

Para acessar os recursos do Azure, você deve configurar o elemento identity. O arquivo Bicep a seguir demonstra como recuperar uma lista de cofres de chaves do Azure. Também é necessário conceder permissão à identidade de gerenciamento de atribuição do usuário para acessar o cofre de chaves.

param identity string
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listKvCLI'
  location: location
  kind: 'AzureCLI'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity}': {}
    }
  }
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'result=$(az keyvault list); echo $result | jq -c \'{Result: map({id: .id})}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output result object = deploymentScript.properties.outputs

Observação

A lógica de repetição para entrar no Azure agora está incorporada ao script de wrapper. Caso conceda permissões no mesmo arquivo Bicep que seus scripts de implantação, o serviço de script de implantação tentará entrar por 10 minutos (com intervalos de 10 segundos) até que a atribuição de função da identidade gerenciada seja replicada.

Trabalhar com saídas

A abordagem para lidar com saídas varia de acordo com o tipo de script que você está usando – do Azure PowerShell ou da CLI do Azure.

O script de implantação da CLI do Azure usa uma variável de ambiente chamada AZ_SCRIPTS_OUTPUT_PATH para indicar o local do arquivo para as saídas de script. Ao executar um script de implantação em um arquivo Bicep, o shell do Bash configurará automaticamente essa variável de ambiente para você. Seu valor predefinido é definido como /mnt/azscripts/azscriptoutput/scriptoutputs.json.

As saídas devem estar em conformidade com uma estrutura de objeto de cadeia de caracteres JSON válida. O conteúdo do arquivo deve ser formatado como um par chave-valor. Por exemplo, salve uma matriz de cadeias de caracteres como { "MyResult": [ "foo", "bar"] }. Armazenar apenas os resultados da matriz, como [ "foo", "bar" ], é inválido.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output text string = deploymentScript.properties.outputs.text

O exemplo anterior usa jq para construir as saídas. A ferramenta jq vem com as imagens de contêiner. Para obter mais informações, confira Configurar um ambiente de desenvolvimento.

Usar variáveis de ambiente

Passar cadeias de caracteres seguras para um script de implantação

Você pode definir variáveis de ambiente (EnvironmentVariable) em suas instâncias de contêiner para fornecer a configuração dinâmica do aplicativo ou script executado pelo contêiner. Um script de implantação lida com variáveis de ambiente não seguras e seguras da mesma maneira que a Instância de Contêiner do Azure. Para saber mais, consulte Definir variáveis de ambiente em instâncias de contêiner.

O tamanho máximo permitido para variáveis de ambiente é 64 KB.

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'passEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    environmentVariables: [
      {
        name: 'UserName'
        value: 'jdole'
      }
      {
        name: 'Password'
        secureValue: 'jDolePassword'
      }
    ]
    scriptContent: 'echo "Username is :$Username"; echo "Password is: $Password"'
    retentionInterval: 'P1D'
  }
}

Variáveis de ambiente definidas pelo sistema

A tabela a seguir lista as variáveis de ambiente definidas pelo sistema:

Variável de ambiente Valor padrão (CLI) Valor padrão (PowerShell) Sistema reservado
AZ_SCRIPTS_AZURE_ENVIRONMENT AzureCloud AzureCloud Não
AZ_SCRIPTS_CLEANUP_PREFERENCE Always Always Não
AZ_SCRIPTS_OUTPUT_PATH /mnt/azscripts/azscriptoutput/scriptoutputs.json Não aplicável Sim
AZ_SCRIPTS_PATH_INPUT_DIRECTORY /mnt/azscripts/azscriptinput|/mnt/azscripts/azscriptinput Não Aplicável Sim
AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY /mnt/azscripts/azscriptoutput|/mnt/azscripts/azscriptoutput Não Aplicável Sim
AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME userscript.sh userscript.ps1 Sim
AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME primaryscripturi.config primaryscripturi.config Sim
AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME supportingscripturi.config supportingscripturi.config Sim
AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME scriptoutputs.json scriptoutputs.json Sim
AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME executionresult.json executionresult.json Sim
AZ_SCRIPTS_USER_ASSIGNED_IDENTITY Não Aplicável Não Aplicável Não

Para obter um exemplo do uso de AZ_SCRIPTS_OUTPUT_PATH, consulte Trabalhar com saídas anteriormente neste artigo.

Para acessar as variáveis de ambiente, use o código a seguir.

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'echo "AZ_SCRIPTS_AZURE_ENVIRONMENT is : $AZ_SCRIPTS_AZURE_ENVIRONMENT",echo "AZ_SCRIPTS_CLEANUP_PREFERENCE	is : $AZ_SCRIPTS_CLEANUP_PREFERENCE",echo "AZ_SCRIPTS_OUTPUT_PATH	is : $AZ_SCRIPTS_OUTPUT_PATH",echo "AZ_SCRIPTS_PATH_INPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_INPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME is : $AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME",echo "AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	is : $AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME",echo "AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	is : $AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME",echo "AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	is : $AZ_SCRIPTS_USER_ASSIGNED_IDENTITY"'
    retentionInterval: 'P1D'
  }
}

Usar uma conta de armazenamento existente

Para que o script seja executado e permita a solução de problemas, é necessário ter uma conta de armazenamento e uma instância de contêiner. Você pode designar uma conta de armazenamento existente ou permitir que o serviço de script crie a conta de armazenamento e a instância de contêiner automaticamente.

Estes são os requisitos para usar uma conta de armazenamento existente:

  • A tabela a seguir lista os tipos de conta com suporte. A coluna para camadas refere-se ao valor do parâmetro -SkuName ou --sku. A coluna para tipos com suporte refere-se ao parâmetro -Kind ou --kind.

    Camada Tipo com suporte
    Premium_LRS FileStorage
    Premium_ZRS FileStorage
    Standard_GRS Storage, StorageV2
    Standard_GZRS StorageV2
    Standard_LRS Storage, StorageV2
    Standard_RAGRS Storage, StorageV2
    Standard_RAGZRS StorageV2
    Standard_ZRS StorageV2

    Essas combinações são compatíveis com compartilhamentos de arquivos. Para obter mais informações, consulte Criar um compartilhamento de arquivo do Azure e Tipos de contas de armazenamento.

  • As regras de firewall para contas de armazenamento ainda não têm suporte. Para saber mais, consulte Configurar Redes Virtuais e Firewalls de Armazenamento do Azure.

  • A entidade de segurança de implantação deve ter permissões para gerenciar a conta de armazenamento, que inclui ler, criar e excluir compartilhamentos de arquivos. Para obter mais informações, consulte Configurar as permissões mínimas.

  • A propriedade allowSharedKeyAccess da conta de armazenamento deve ser definida como true. A única maneira de montar uma conta de armazenamento na Instância de Contêiner do Azure (ACI) é por meio de uma chave de acesso.

Para especificar uma conta de armazenamento existente, adicione o seguinte código Bicep ao elemento de propriedade de Microsoft.Resources/deploymentScripts:

param storageAccountName string = 'myStorageAccount'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    storageAccountSettings: {
      storageAccountName: storageAccountName
      storageAccountKey: listKeys(resourceId('Microsoft.Storage/storageAccounts', storageAccountName), '2023-01-01').keys[0].value
    }
  }
}

Para obter um exemplo de definição de Microsoft.Resources/deploymentScripts completa, consulte Sintaxe anteriormente neste artigo.

Quando você usa uma conta de armazenamento existente, o serviço de script cria um compartilhamento de arquivos que tem um nome exclusivo. Para saber como o serviço de script limpa o compartilhamento de arquivos, consulte Limpar os recursos de script de implantação mais adiante neste artigo.

Configurar uma instância de contêiner

Um script de implantação requer uma nova instância de contêiner do Azure. Você não pode especificar uma instância de contêiner existente. No entanto, pode personalizar o nome do grupo do contêiner usando containerGroupName. Se você não especificar um nome de grupo, ele será gerado automaticamente. Configurações adicionais são necessárias para criar essa instância de contêiner. Para obter mais informações, consulte Configurar as permissões mínimas.

Você também pode especificar os valores subnetId para executar o script de implantação em uma rede privada. Para obter mais informações, consulte Acessar uma rede virtual privada.

param containerGroupName string = 'mycustomaci'
param subnetId string = '/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    containerSettings: {
      containerGroupName: containerGroupName
      subnetIds: [
        {
          id: subnetId
        }
      ]
    }
  }
}

Executar um script mais de uma vez

A execução do script de implantação é uma operação idempotente. Se não houver alterações em nenhuma das propriedades do recurso deploymentScripts, incluindo no script em linha, o script não será executado quando você reimplantar o arquivo Bicep.

O serviço de script de implantação compara os nomes de recursos no arquivo Bicep com os recursos existentes no mesmo grupo de recursos. Há duas opções se você quiser executar o mesmo script de implantação várias vezes:

  • Altere o nome do seu recurso deploymentScripts. Por exemplo, use a função utcNow como o nome do recurso ou como parte do nome do recurso. Você pode usar a função utcNow somente no valor padrão de um parâmetro.

    Alterar o nome do recurso cria um novo recurso deploymentScripts. É bom para manter um histórico da execução do script.

  • Especifique um valor diferente na propriedade forceUpdateTag. Por exemplo, use utcNow como o valor.

Escreva scripts de implantação para garantir a idempotência, para que novas execuções acidentais não resultem em alterações do sistema. Por exemplo, ao criar um recurso do Azure por meio do script de implantação, valide sua ausência antes da criação para garantir que o script seja bem-sucedido ou evite a criação de recursos redundantes.

Usar o Microsoft Graph em um script de implantação

Um script de implantação pode usar o Microsoft Graph para criar e trabalhar com objetos no Microsoft Entra ID.

Comandos

Ao usar scripts de implantação da CLI do Azure, você pode usar comandos dentro do grupo de comandos az ad para trabalhar com aplicativos, entidades de serviço, grupos e usuários. Você também pode invocar diretamente as APIs do Microsoft Graph usando o comando az rest.

Ao usar scripts de implantação do Azure PowerShell, você pode usar o cmdlet Invoke-RestMethod para invocar diretamente as APIs do Microsoft Graph.

Permissões

A identidade usada pelo script de implantação precisa estar autorizada a trabalhar com a API do Microsoft Graph, com as permissões apropriadas para as operações que executa. Você deve autorizar a identidade fora do seu arquivo Bicep, por exemplo, pré-criando uma identidade gerenciada atribuída pelo usuário e atribuindo-lhe uma função de aplicativo para o Microsoft Graph. Para obter mais informações, confira este exemplo de início rápido.

Limpar recursos do script de implantação

Os dois recursos de suporte criados automaticamente nunca poderão sobreviver ao recurso deploymentScript, a menos que falhas os excluam. A propriedade cleanupPreference controla o ciclo de vida dos recursos de suporte. A propriedade retentionInterval controla o ciclo de vida do recurso deploymentScript. Veja como usar estas propriedades:

  • cleanupPreference: especifica a preferência de limpeza dos dois recursos de suporte quando a execução do script entra em estado terminal. Os valores com suporte são:

    • Always: exclui os dois recursos de suporte depois que a execução do script entra em estado terminal. Se você usar uma conta de armazenamento existente, o serviço de script excluirá o compartilhamento de arquivos que o serviço criou. Como o recurso deploymentScripts ainda pode estar presente depois que os recursos de suporte forem limpos, o serviço de script persiste os resultados da execução do script (por exemplo, stdout), as saídas e o valor retornado antes que os recursos sejam excluídos.

    • OnSuccess: exclui os dois recursos de suporte somente quando a execução do script é bem-sucedida. Se você usar uma conta de armazenamento existente, o serviço de script removerá o compartilhamento de arquivos somente quando a execução do script for bem-sucedida.

      Se a execução do script não for bem-sucedida, o serviço de script aguardará até que o valor retentionInterval expire antes de limpar os recursos de suporte e, em seguida, o recurso de script de implantação.

    • OnExpiration: exclui os dois recursos de suporte somente quando a configuração retentionInterval tiver expirado. Se você usar uma conta de armazenamento existente, o serviço de script removerá o compartilhamento de arquivo, mas manterá a conta de armazenamento.

    A instância de contêiner e a conta de armazenamento são excluídas de acordo com o valor cleanupPreference. No entanto, se o script falhar e cleanupPreference não estiver definido como Always, o processo de implantação manterá automaticamente o contêiner em execução por uma hora ou até que o contêiner tenha sido limpo. Você pode usar esse tempo para solucionar o problema do script.

    Se você quiser manter o contêiner em execução após implantações bem-sucedidas, adicione uma etapa de suspensão ao seu script. Por exemplo, adicione Start-Sleep ao final do seu script. Se você não adicionar a etapa de suspensão, o contêiner será definido como um estado terminal e não poderá ser acessado mesmo que você ainda não o tenha excluído.

  • retentionInterval: especifica o intervalo de tempo durante o qual um recurso deploymentScript será retido antes de expirar e ser excluído.

Observação

Não recomendamos que você use a conta de armazenamento e a instância de contêiner que o serviço de script gera para outras finalidades. Os dois recursos podem ser removidos, dependendo do ciclo de vida do script.

Próximas etapas

Neste artigo, você aprendeu a criar recursos de implantação de scripts. Para saber mais:

Usar scripts de implantação no Bicep