Sviluppare uno script di distribuzione in Bicep

Questo articolo fornisce esempi per illustrare come sviluppare uno script di distribuzione in Bicep.

Le risorse dello script di distribuzione potrebbero avere una durata di distribuzione. Per uno sviluppo e un test efficienti di questi script, è consigliabile stabilire un ambiente di sviluppo dedicato, ad esempio un'istanza del contenitore di Azure (ACI) o un'istanza Docker. Per altre informazioni, vedere Creare un ambiente di sviluppo.

Sintassi

Il file Bicep seguente è un esempio di risorsa script di distribuzione. Per altre informazioni, vedere lo schema dello script di distribuzione più 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'
  }
}

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: 'AzurePowerShell'
  properties: {
    storageAccountSettings: {
      storageAccountName: '<storage-account-name>'
      storageAccountKey: '<storage-account-key>'
    }
    containerSettings: {
      containerGroupName: '<container-group-name>'
      subnetIds: [
        {
          id: '<subnet-id>'
        }
      ]
    }
    environmentVariables: []
    azPowerShellVersion: '10.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'
  }
}

Nello script di distribuzione specificare i valori delle proprietà seguenti:

• tags: specificare i tag dello script di distribuzione. Se il servizio script di distribuzione crea le due risorse di supporto (un account di archiviazione e un'istanza del contenitore), i tag vengono passati a entrambe le risorse. È possibile usare i tag per identificare le risorse. Un altro modo per identificare queste risorse di supporto consiste nell'usare i relativi suffissi, che contengono azscripts. Per altre informazioni, vedere Monitorare e risolvere i problemi relativi agli script di distribuzione.

• identity: per la versione dell'API dello script di distribuzione o versione successiva2020-10-01, un'identità gestita assegnata dall'utente è facoltativa, a meno che non sia necessario eseguire azioni specifiche di Azure nello script o che si esegua lo script di distribuzione in una rete privata. La versione 2019-10-01-preview dell'API richiede un'identità gestita perché il servizio script di distribuzione lo usa per eseguire gli script.

  Quando si specifica la proprietà identity, il servizio script chiama Connect-AzAccount -Identity prima di richiamare lo script utente. Attualmente è supportata solo un'identità gestita assegnata dall'utente. Per accedere con un'identità diversa nello script di distribuzione, è possibile chiamare Connect-AzAccount. Per altre informazioni, vedere Configurare le autorizzazioni minime.

• kind: specificare il tipo di script, AzurePowerShell o AzureCLI. Oltre a kind, è necessario specificare la proprietà azPowerShellVersion o azCliVersion.

• storageAccountSettings: Specificare le impostazioni per l'uso di un account di archiviazione esistente. Se storageAccountName non è specificato, l’account di archiviazione viene creato automaticamente. Per altre informazioni, vedere Usare un account di archiviazione esistente.

• containerSettings: personalizzare il nome dell'istanza del contenitore di Azure. Per informazioni sulla configurazione del nome del gruppo del contenitore, vedere Configurare un'istanza del contenitore più avanti in questo articolo. Per informazioni sulla configurazione subnetIds per l'esecuzione dello script di distribuzione in una rete privata, vedere Accedere a una rete virtuale privata.

• environmentVariables: Specificare le variabili di ambiente da passare allo script.

• azPowerShellVersion/azCliVersion:Specificare la versione del modulo da usare.

  • CLI
  • PowerShell

  Vedere un elenco delle versioni supportate dell'interfaccia della riga di comando di Azure.

  Importante

  Lo script di distribuzione usa le immagini dell'interfaccia della riga di comando disponibili dal Registro Artefatti Microsoft. In genere ci vuole circa un mese per certificare un'immagine CLI per uno script di distribuzione. Non utilizzare versioni della CLI rilasciate negli ultimi 30 giorni. Per trovare le date di rilascio delle immagini, vedere Note sulla versione dell'interfaccia della riga di comando di Azure. Se si usa una versione non supportata, il messaggio di errore elenca le versioni supportate.

• arguments: Specificare i valori del parametro. I valori sono separati da uno spazio.

  Lo script di distribuzione suddivide gli argomenti in una matrice di stringhe richiamando la chiamata di sistema CommandLineToArgvW. Questo passaggio è necessario perché gli argomenti vengono passati come proprietà del comando a Istanze di Azure Container e la proprietà del comando è una matrice di stringhe.

  Se gli argomenti contengono caratteri di escape, eseguire un doppio escape dei caratteri. Ad esempio, nella sintassi Bicep di esempio precedente, l'argomento è -name \"John Dole\". La stringa di escape è -name \\"John Dole\\".

  Per passare un parametro Bicep di tipo object come argomento, convertire l'oggetto in una stringa usando la funzione string() e quindi usare la funzione replace() per sostituire le virgolette (") con virgolette doppie (\\"). Ad esempio:

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

  Per altre informazioni, vedere il file Bicep di esempio.

• scriptContent:specificare il contenuto dello script. Può trattarsi di uno script inline o di un file di script esterno importato tramite la funzione loadTextContent. Per altre informazioni, vedere File inline rispetto a esterno più avanti in questo articolo. Per eseguire uno script esterno, usare primaryScriptUri.

• primaryScriptUri: Specificare un URL accessibile pubblicamente per lo script di distribuzione primario con estensioni di file supportate. Per altre informazioni, vedere Usare script esterni più avanti in questo articolo.

• supportingScriptUris: Specificare una matrice di URL accessibili pubblicamente per supportare i file che vengono chiamati in scriptContent o primaryScriptUri. Per altre informazioni, vedere File inline rispetto a esterno più avanti in questo articolo.

• timeout: specificare il tempo massimo consentito per l'esecuzione dello script, in formato ISO 8601. Il valore predefinito è P1D.

• forceUpdateTag: La modifica di questo valore tra le distribuzioni dei file Bicep obbliga a eseguire nuovamente lo script di distribuzione. Se si usa la funzione newGuid() o utcNow(), è possibile usarla solo nel valore predefinito per un parametro. Per altre informazioni, vedere Eseguire uno script più di una volta più avanti in questo articolo.

• cleanupPreference. Specificare la preferenza per la pulizia delle due risorse di distribuzione di supporto (l'account di archiviazione e l'istanza del contenitore) quando l'esecuzione dello script diventa in uno stato terminale. L'impostazione predefinita è Always, che richiede l'eliminazione delle risorse di supporto indipendentemente dallo stato del terminale (Succeeded, Failed o Canceled). Per altre informazioni, vedere Pulire le risorse dello script di distribuzione più avanti in questo articolo.

• retentionInterval: Specificare l'intervallo per il quale il servizio conserva la risorsa script di distribuzione dopo che l'esecuzione dello script di distribuzione raggiunge uno stato terminale. La risorsa script di distribuzione viene eliminata alla scadenza di questa durata. La durata è basata sul modello ISO 8601. L'intervallo di conservazione è compreso tra 1 ora (PT1H) e 26 ore (PT26H). Questa proprietà viene usata quando cleanupPreference è impostato su OnExpiration. Per altre informazioni, vedere Pulire le risorse dello script di distribuzione più avanti in questo articolo.

Altri esempi

• Esempio 1: Creare un insieme di credenziali delle chiavi e usare uno script di distribuzione per assegnare un certificato all'insieme di credenziali delle chiavi.
• Esempio 2: Creare un gruppo di risorse a livello di sottoscrizione, creare un insieme di credenziali delle chiavi nel gruppo di risorse e quindi usare uno script di distribuzione per assegnare un certificato all'insieme di credenziali delle chiavi.
• Esempio 3: Creare un'identità gestita assegnata dall'utente, assegnare il ruolo di collaboratore all'identità a livello di gruppo di risorse, creare un insieme di credenziali delle chiavi e quindi usare uno script di distribuzione per assegnare un certificato all'insieme di credenziali delle chiavi.
• Esempio 4: creare manualmente un'identità gestita assegnata dall'utente e assegnarla l'autorizzazione per usare l'API Microsoft Graph per creare applicazioni Microsoft Entra. Nel file Bicep usare uno script di distribuzione per creare un'applicazione Microsoft Entra e un'entità servizio e per restituire gli ID oggetto e l'ID client.

File inline rispetto a esterno

Uno script di distribuzione può trovarsi all'interno di un file Bicep oppure archiviarlo esternamente come file separato.

Usare uno script inline

Il file Bicep seguente illustra come usare uno script inline.

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

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlinePS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      $ErrorActionPreference = 'Stop'
      $output = "Hello {0}" -f $name
      Write-Output "Output is: '$output'."
    '''
    retentionInterval: 'P1D'
  }
}

Caricare un file di script

Usare la funzione loadTextContent per recuperare un file di script come stringa. Questa funzione consente di mantenere lo script in un file esterno e accedervi come script di distribuzione. Il percorso specificato per il file script è relativo al file Bicep.

output="Hello $1"
echo $output

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

param([string] $name)
$output = "Hello {0}" -f $name
Write-Output "Output is: '$output'."

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'loadTextContentPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: loadTextContent('./scripts/hello.ps1')
    retentionInterval: 'P1D'
  }
}

Usare script esterni

È possibile usare file di script esterni anziché script inline. Sono supportati solo gli script di PowerShell primari con l'estensione .ps1. Per gli script dell'interfaccia della riga di comando, gli script primari possono contenere qualsiasi estensione di script Bash valida o non avere alcuna estensione. Per usare file di script esterni, eseguire lo scambio scriptContent con 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'
  }
}

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'externalScriptPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/hello.ps1'
    arguments: '-name ${name}'
    retentionInterval: 'P1D'
  }
}

I file di script esterni devono essere accessibili. Per proteggere i file di script archiviati negli account di archiviazione di Azure, generare un token di firma di accesso condiviso (SAS) e includerlo nell'URI (Uniform Resource Identifier) per il modello. Impostare la scadenza in modo da garantire un tempo sufficiente per completare la distribuzione. Per altre informazioni, vedere Distribuire un modello di ARM privato con un token di firma di accesso condiviso (SAS).

L'utente è responsabile di garantire l'integrità dello script a cui fa riferimento lo script di distribuzione (primaryScriptUri o supportingScriptUris). Fare riferimento solo a script attendibili.

Usare script di supporto

È possibile separare le logiche complesse in uno o più file di script di supporto. Se necessario, usare la proprietà supportingScriptUris per fornire una matrice di URI ai file di script di supporto.

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

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'supportingScriptPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      $output = "Hello {0}" -f $name
      Write-Output "Output is: '$output'."
      ./hello.ps1 -name $name
    '''
    supportingScriptUris: [
      'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/master/samples/deployment-script/hello.ps1'
    ]
    retentionInterval: 'P1D'
  }
}

I file script di supporto possono essere chiamati sia da script inline sia da file di script primari. I file di script di supporto non prevedono alcuna restrizione sull'estensione di file.

I file di supporto vengono copiati in azscripts/azscriptinput in fase di esecuzione. Usare il percorso relativo per fare riferimento ai file di supporto da script inline e file di script primari.

Accedere alle risorse di Azure

Per accedere alle risorse di Azure, è necessario configurare l'elemento identity. Il file Bicep seguente illustra come recuperare un elenco di insiemi di credenziali delle chiavi di Azure. È necessaria anche la concessione dell'autorizzazione di gestione dell'assegnazione utente per accedere all'insieme di credenziali delle chiavi.

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

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listKvPS'
  location: location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity}': {}
    }
  }
  properties: {
    azPowerShellVersion: '10.0'
    scriptContent: '''
      $kvs=Get-AzKeyVault

      $output = @()
      foreach($kv in $kvs){
        $newKv = @{
          id = $kv.resourceId
        }
        $output = $output + $newKv
      }
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs["kvs"] = $output
    '''
    retentionInterval: 'P1D'
  }
}

output result object = deploymentScript.properties.outputs

Usare gli output

L'approccio alla gestione degli output varia in base al tipo di script in uso, ovvero l'interfaccia della riga di comando di Azure o Azure PowerShell.

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

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

resource deploymentScript1 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputPS1'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      $output = 'Hello {0}' -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    retentionInterval: 'P1D'
  }
}

resource deploymentScript2 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputPS2'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-textToEcho \\"${deploymentScript1.properties.outputs.text}\\"'
    scriptContent: '''
      param([string] $textToEcho)
      Write-Output $textToEcho
    '''
    retentionInterval: 'P1D'
  }
}

Uso delle variabili di ambiente

Passare stringhe protette allo script di distribuzione

È possibile impostare variabili d'ambiente (EnvironmentVariable) nelle istanze del contenitore per fornire una configurazione dinamica dell'applicazione o dello script eseguito dal contenitore. Uno script di distribuzione gestisce le variabili d'ambiente non protette e protette allo stesso modo delle istanze di Azure Container. Per altre informazioni, vedere Impostare variabili di ambiente in istanze di contenitore.

La dimensione massima consentita per le variabili di 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'
  }
}

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'passEnvVariablesPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    environmentVariables: [
      {
        name: 'UserName'
        value: 'jdole'
      }
      {
        name: 'Password'
        secureValue: 'jDolePassword'
      }
    ]
    scriptContent: '''
      Write-output "Username is :$Username"
      Write-output "Password is: $Password"
    '''
    retentionInterval: 'P1D'
  }
}

Variabili di ambiente definite dal sistema

La tabella seguente elenca le variabili di ambiente definite dal sistema:

Per un esempio di uso di AZ_SCRIPTS_OUTPUT_PATH, vedere Usare gli output in precedenza in questo articolo.

Per accedere alle variabili di ambiente, usare il codice seguente.

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

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listEnvVariablesPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    scriptContent: '''
      Write-Output "AZ_SCRIPTS_AZURE_ENVIRONMENT is : ${Env:AZ_SCRIPTS_AZURE_ENVIRONMENT}"
      Write-Output "AZ_SCRIPTS_CLEANUP_PREFERENCE	is : ${Env:AZ_SCRIPTS_CLEANUP_PREFERENCE}"
      Write-Output "AZ_SCRIPTS_OUTPUT_PATH	is : ${Env:AZ_SCRIPTS_OUTPUT_PATH}"
      Write-Output "AZ_SCRIPTS_PATH_INPUT_DIRECTORY is : ${Env:AZ_SCRIPTS_PATH_INPUT_DIRECTORY}"
      Write-Output "AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY is : ${Env:AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY}"
      Write-Output "AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME is : ${Env:AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	is : ${Env:AZ_SCRIPTS_USER_ASSIGNED_IDENTITY}"
    '''
    retentionInterval: 'P1D'
  }
}

Usare un account di archiviazione esistente

Per consentire l'esecuzione dello script e la risoluzione dei problemi, è necessario un account di archiviazione e un'istanza del contenitore. È possibile designare un account di archiviazione esistente o consentire al servizio script di creare automaticamente l'account di archiviazione e l'istanza del contenitore.

Requisiti per l'uso di un account di archiviazione esistente:

• Nella tabella seguente sono elencati i tipi di account supportati. La colonna per i livelli fa riferimento al valore del parametro -SkuName o --sku. La colonna per i tipi supportati fa riferimento al parametro -Kind o --kind.

  Livello	Tipo supportato
  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

  Queste combinazioni supportano condivisioni di file. Per altre informazioni, vedere Creare una condivisione file di Azure e Tipi di account di archiviazione.

• Le regole del firewall per gli account di archiviazione non sono ancora supportate. Per altre informazioni, vedere Configurare i firewall e le reti virtuali di Archiviazione di Azure.

• L'entità di distribuzione deve disporre delle autorizzazioni per gestire l'account di archiviazione, che include la lettura, la creazione e l'eliminazione di condivisioni file. Per altre informazioni, vedere Configurare le autorizzazioni minime.

• La proprietà allowSharedKeyAccess dell'account di archiviazione deve essere impostata su true. L'unico modo per montare un account di archiviazione nell'istanza del contenitore di Azure (ACI) consiste nell’usare una chiave di accesso.

Per specificare un account di archiviazione esistente, aggiungere il file Bicep seguente all'elemento della proprietà di 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
    }
  }
}

Per un esempio di definizione completo Microsoft.Resources/deploymentScripts, vedere Sintassi in precedenza in questo articolo.

Quando si usa un account di archiviazione esistente, il servizio script crea una condivisione file con un nome univoco. Per informazioni su come il servizio script pulisce la condivisione file, vedere Pulire le risorse dello script di distribuzione più avanti in questo articolo.

Configurare un’istanza di contenitore

Uno script di distribuzione richiede una nuova istanza del contenitore di Azure. Non è possibile specificare un'istanza del contenitore esistente. Tuttavia, è possibile personalizzare il nome del gruppo del contenitore usando containerGroupName. Se non specificato, il nome gruppo viene generato automaticamente. Sono necessarie configurazioni aggiuntive per la creazione di questa istanza del contenitore. Per altre informazioni, vedere Configurare le autorizzazioni minime.

È anche possibile specificare i valori subnetId per l'esecuzione dello script di distribuzione in una rete privata. Per altre informazioni, vedere Accedere a una rete virtuale privata.

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

Eseguire lo script più di una volta

L'esecuzione dello script di distribuzione è un'operazione idempotente. Se non sono state apportate modifiche alle proprietà della risorsa deploymentScripts, incluso lo script inline, lo script non viene eseguito quando si ridistribuisce il file Bicep.

Il servizio script di distribuzione confronta i nomi delle risorse nel file Bicep con le risorse esistenti nello stesso gruppo di risorse. Se si vuole eseguire lo stesso script di distribuzione più volte, sono disponibili due opzioni:

• Modificare il nome della risorsa deploymentScripts. Usare, ad esempio, la funzione utcNow come nome della risorsa o come parte del nome della risorsa. È possibile usare la funzione utcNow solo nel valore predefinito per un parametro.

  La modifica del nome della risorsa crea una nuova risorsa deploymentScripts. È utile per mantenere una cronologia dell'esecuzione dello script.

• Specificare un valore diverso nella proprietà forceUpdateTag. Ad esempio, usare utcNow come valore.

Scrivere script di distribuzione per garantire l'idempotenza, quindi le riesecuzioni accidentali non comportano modifiche del sistema. Ad esempio, quando si crea una risorsa di Azure tramite lo script di distribuzione, convalidarne l'assenza prima della creazione per assicurarsi che lo script abbia esito positivo o eviti la creazione di risorse ridondanti.

Usare Microsoft Graph all'interno di uno script di distribuzione

Uno script di distribuzione può usare Microsoft Graph per creare e usare oggetti in Microsoft Entra ID.

Comandi

Quando si usano gli script di distribuzione dell'interfaccia della riga di comando di Azure, è possibile usare i comandi all'interno del gruppo di comandi az ad per usare applicazioni, entità servizio, gruppi e utenti. È anche possibile richiamare direttamente le API Microsoft Graph usando il comando az rest.

Quando si usano gli script di distribuzione di Azure PowerShell, è possibile usare il Invoke-RestMethod cmdlet per richiamare direttamente le API Microsoft Graph.

Autorizzazioni

L'identità usata dallo script di distribuzione deve essere autorizzata a lavorare con l'API Microsoft Graph, con le autorizzazioni appropriate per le operazioni eseguite. È necessario autorizzare l'identità all'esterno del file Bicep, ad esempio tramite la creazione preliminare di un'identità gestita assegnata dall'utente e l'assegnazione di un ruolo dell'app per Microsoft Graph. Per altre informazioni, vedere l'avvio rapido seguente .

Pulire le risorse dello script di distribuzione

Le due risorse di supporto create automaticamente non possono mai sopravvivere alla risorsa deploymentScript, a meno che gli errori non li eliminino. La proprietà cleanupPreference controlla il ciclo di vita delle risorse di supporto. La proprietà retentionInterval controlla il ciclo di vita della risorsa deploymentScript. Ecco come usare queste proprietà:

• cleanupPreference: specificare la preferenza di pulizia delle due risorse di supporto quando l'esecuzione dello script si trova in uno stato terminale. I valori supportati sono:

  • Always: eliminare le due risorse di supporto dopo che l'esecuzione dello script diventa in uno stato del terminale. Se si usa un account di archiviazione esistente, il servizio script elimina la condivisione file creata dal servizio. Poiché la risorsa deploymentScripts potrebbe essere ancora presente dopo la pulizia delle risorse di supporto, il servizio script rende persistenti i risultati dell'esecuzione dello script (ad esempio, stdout), gli output e il valore restituito prima dell'eliminazione delle risorse.

  • OnSuccess: eliminare le due risorse di supporto solo quando l'esecuzione dello script ha esito positivo. Se si utilizza un account di archiviazione esistente, il servizio di script rimuove la condivisione di file solo quando l'esecuzione dello script ha successo.

    Se l'esecuzione dello script non riesce, il servizio script attende fino alla scadenza del valore retentionInterval prima di pulire le risorse di supporto e quindi la risorsa script di distribuzione.

  • OnExpiration: elimina le due risorse di supporto solo quando l'impostazione retentionInterval è scaduta. Se si utilizza un account di archiviazione esistente, il servizio di script rimuove la condivisione di file ma mantiene l'account di archiviazione.

  L'istanza del contenitore e l'account di archiviazione vengono eliminati in base al valore cleanupPreference. Tuttavia, se lo script ha esito negativo e cleanupPreference non è impostato su Always, il processo di distribuzione mantiene automaticamente il contenitore in esecuzione per un'ora o fino a quando il contenitore non viene pulito. È possibile usare il tempo per risolvere i problemi dello script.

  Se si vuole mantenere il contenitore in esecuzione dopo le distribuzioni riuscite, aggiungere un passaggio di sospensione allo script. Ad esempio, aggiungere Start-Sleep alla fine dello script. Se non si aggiunge il passaggio sospensione, il contenitore viene impostato su uno stato del terminale e non è possibile accedervi anche se non è ancora stato eliminato.

• retentionInterval: specificare l'intervallo di tempo che verrà conservato prima della scadenza e dell'eliminazione di una risorsa deploymentScript.

Passaggi successivi

In questo articolo si è appreso come creare risorse script di distribuzione. Per altre informazioni, vedere: