Partilhar via

Desenvolver um script de implantação no Bicep

  • Artigo

Este artigo fornece exemplos para mostrar como desenvolver um script de implantação no 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 ou uma instância do Docker. Para obter mais informações, consulte Criar um ambiente de desenvolvimento.

Sintaxe

O seguinte arquivo Bicep é 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: Especifique tags de 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 de suporte é através de seus sufixos, que contêm azscripts. Para obter mais informações, consulte Monitorar e solucionar problemas de scripts de implantação.

  • identity: Para a versão 2020-10-01 da API do script de implantação ou posterior, uma identidade gerenciada atribuída pelo usuário é opcional, a menos que você precise executar quaisquer ações específicas do Azure no script ou 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 identity propriedade, o serviço de script chama Connect-AzAccount -Identity antes de invocar o script de usuário. Atualmente, apenas uma identidade gerenciada atribuída pelo usuário é suportada. 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: Especifique o tipo de script, ou AzurePowerShellAzureCLI. Além de kind, você precisa especificar a azPowerShellVersion propriedade 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: Personalize o nome da instância de contêiner do Azure. Para obter informações sobre como configurar o nome do 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: Especifique as variáveis de ambiente a serem passadas para o script.

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

    Consulte uma lista de versões suportadas da CLI do Azure.

    Importante

    O script de implantação usa as imagens de CLI disponíveis do Microsoft Artifact Registry. Normalmente, leva cerca de um mês para certificar uma imagem da CLI para um script de implantação. Não use versões da CLI lançadas nos últimos 30 dias. Para encontrar as datas de lançamento das imagens, consulte Notas de versão da CLI do Azure. Se utilizar uma versão não suportada, a mensagem de erro lista as versões suportadas.

  • arguments: Especifique os valores dos parâmetros. Os valores são separados por espaços.

    O script de implantação divide os argumentos em uma matriz de cadeias de caracteres invocando a chamada do sistema CommandLineToArgvW . Esta etapa é necessária porque os argumentos são passados como uma propriedade de comando para Instâncias de Contêiner do Azure e a propriedade de comando é uma matriz de cadeias de caracteres.

    Se os argumentos contiverem caracteres com escape, escape duas vezes dos caracteres. Por exemplo, no exemplo anterior de sintaxe do Bíceps, o argumento é -name \"John Dole\". A cadeia de caracteres com 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, em seguida, use a função replace() para substituir as aspas () por aspas com escape duplo (\\""). Por exemplo:

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

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

  • scriptContent: Especifique o conteúdo do script. Pode ser um script embutido ou um arquivo de script externo que você importou usando a função loadTextContent . Para obter mais informações, consulte Arquivo embutido versus externo mais adiante neste artigo. Para executar um script externo, use primaryScriptUri em vez disso.

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

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

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

  • forceUpdateTag: Alterar esse valor entre implantações de arquivo Bicep força o script de implantação a ser executado novamente. Se você usar a newGuid() função 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 mais adiante 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 entrar em um estado terminal. A configuração padrão é Always, que exige a exclusão de recursos de suporte independentemente do estado do terminal (Succeeded, , Failedou Canceled). Para saber mais, consulte Limpar recursos de script de implantação mais adiante neste artigo.

  • retentionInterval: Especifique 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 de script de implantação é excluído quando essa duração expira. A duração é baseada no padrão ISO 8601. O intervalo de retenção é entre 1 hora () e 26 horas (PT1HPT26H). Você usa essa propriedade quando cleanupPreference está definido como OnExpiration. Para saber mais, consulte Limpar recursos de script de implantação mais adiante neste artigo.

Mais exemplos

  • Exemplo 1: Crie um cofre de chaves e use um script de implantação para atribuir um certificado ao cofre de chaves.
  • Exemplo 2: crie um grupo de recursos no nível da assinatura, crie um cofre de chaves no grupo de recursos e use um script de implantação para atribuir um certificado ao cofre de chaves.
  • Exemplo 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.
  • Exemplo 4: Crie manualmente uma identidade gerenciada atribuída pelo usuário e atribua-lhe 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.

Arquivo embutido vs. 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 embutido

O seguinte arquivo Bicep mostra como usar um script embutido.

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'
  }
}

Inclua set -e em seu script para habilitar 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. Esta função permite manter o script em um arquivo externo e acessá-lo como um script de implantação. O caminho especificado para o arquivo de script é relativo ao arquivo Bicep.

Você pode extrair o script embutido do arquivo Bicep anterior em um arquivo hello.sh e, em seguida, 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 embutidos. Somente scripts principais do PowerShell com a extensão .ps1 são suportados. Para scripts CLI, os scripts primários podem carregar quaisquer extensões de script Bash válidas ou não ter 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 script externos devem estar acessíveis. Para ajudar a proteger seus arquivos de script armazenados em contas de armazenamento do Azure, gere um token de assinatura de acesso compartilhado (SAS) e inclua-o no URI do modelo. Defina a expiração para permitir tempo suficiente para concluir a implantação. Para obter mais informações, consulte Implantar um modelo ARM privado com um token SAS.

Você é responsável por garantir a integridade do script ao qual o script de implantação faz referência (ou primaryScriptUrisupportingScriptUris). Faça referência apenas a scripts em que confia.

Usar scripts de suporte

Você pode separar lógicas complicadas em um ou mais arquivos de script de suporte. Use a supportingScriptUris propriedade para fornecer uma matriz de URIs para os arquivos de script de suporte, se 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 arquivos de script de suporte a partir de scripts embutidos e 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 em tempo de execução. Use um caminho relativo para fazer referência aos arquivos de suporte de scripts embutidos e arquivos de script primários.

Acessar recursos do Azure

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

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

Nota

A lógica de repetição para entrada no Azure agora está incorporada ao script de wrapper. Se você conceder permissões no mesmo arquivo Bicep que seus scripts de implantação, o serviço de script de implantação tentará entrar novamente 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: a CLI do Azure ou o Azure PowerShell.

O script de implantação da CLI do Azure usa uma variável de ambiente nomeada AZ_SCRIPTS_OUTPUT_PATH para indicar o local do arquivo para saídas de script. Quando você está executando um script de implantação em um arquivo Bicep, o shell Bash configura 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 ficheiro 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 saídas. A ferramenta jq vem com as imagens de contêiner. Para obter mais informações, consulte Configurar um ambiente de desenvolvimento.

Utilizar 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 configuração dinâmica do aplicativo ou script que o contêiner executa. Um script de implantação lida com variáveis de ambiente não seguras e protegidas da mesma forma que as Instâncias de Contêiner do Azure. Para obter mais informações, consulte Definir variáveis de ambiente em instâncias de contêiner.

O tamanho máximo permitido para variáveis de ambiente é de 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 No
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 de uso AZ_SCRIPTS_OUTPUT_PATHdo , 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, você precisa de 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.

Aqui estão os requisitos para usar uma conta de armazenamento existente:

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

    Escalão de serviço Tipo suportado
    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 suportam compartilhamentos de arquivos. Para obter mais informações, consulte Criar um compartilhamento de arquivos do Azure e Tipos de contas de armazenamento.

  • As regras de firewall para contas de armazenamento ainda não são suportadas. Para obter mais informações, veja Configurar firewalls e redes virtuais do Armazenamento do Microsoft Azure.

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

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 completa Microsoft.Resources/deploymentScripts , 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 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. Não é possível especificar uma instância de contêiner existente. No entanto, você 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 subnetId valores 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/01234567-89AB-CDEF-0123-456789ABCDEF/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 deploymentScripts recurso, incluindo o script embutido, 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 deploymentScripts recurso. Por exemplo, use a função utcNow como o nome do recurso ou como parte do nome do recurso. Você pode usar a utcNow função somente no valor padrão para um parâmetro.

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

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

Escreva scripts de implantação para garantir idempotência, para que reexecuções acidentais não resultem em alterações no 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 az ad grupo de comandos 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 az rest comando.

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

Permissões

A identidade que seu script de implantação usa precisa ser autorizada para trabalhar com a API do Microsoft Graph, com as permissões apropriadas para as operações que ele executa. Você deve autorizar a identidade fora do 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, consulte este exemplo de início rápido.

Limpar recursos de script de implantação

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

  • cleanupPreference: Especifique a preferência de limpeza dos dois recursos de suporte quando a execução do script entrar em um estado terminal. Os valores suportados são:

    • Always: Exclua os dois recursos de suporte depois que a execução do script entrar em um 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 ainda pode estar presente depois que os recursos de suporte são limpos, o deploymentScripts serviço de script persiste os resultados da execução do script (por exemplo, stdout), saídas e valor de retorno antes que os recursos sejam excluídos.

    • OnSuccess: Exclua os dois recursos de suporte somente quando a execução do script for 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 expire antes de limpar os recursos de suporte e, em seguida, o retentionInterval recurso de script de implantação.

    • OnExpiration: exclua os dois recursos de suporte somente quando a retentionInterval configuração expirar. Se você usar uma conta de armazenamento existente, o serviço de script removerá o compartilhamento de arquivos, mas reterá a conta de armazenamento.

    A instância do contêiner e a conta de armazenamento são excluídas de acordo com o cleanupPreference valor. 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 seja limpo. Você pode usar o tempo para solucionar problemas 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 script. Por exemplo, adicione Start-Sleep ao final do script. Se você não adicionar a etapa de suspensão, o contêiner será definido para um estado terminal e não poderá ser acessado, mesmo que você ainda não o tenha excluído.

  • retentionInterval: Especifique o intervalo de tempo em que um deploymentScript recurso será retido antes de expirar e ser excluído.

Nota

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 outros fins. Os dois recursos podem ser removidos, dependendo do ciclo de vida do script.

Próximos passos

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

Usar scripts de implantação no Bicep