使用 Bicep 编写部署脚本

借助 deploymentScripts 资源，用户可以在 Bicep 部署中执行脚本并查看执行结果。

将用户添加到目录。
执行数据平面操作；例如，复制 blob 或种子数据库。
查找并验证许可证密钥。
创建自签名证书。
在 Microsoft Entra ID 中创建对象。
从自定义系统中查找 IP 地址块。

部署脚本的优点包括：

它们易于进行编码、使用和调试。你可以在最喜欢的开发环境中开发部署脚本。脚本可以嵌入 Bicep 文件或外部脚本文件中。
可以指定脚本语言和平台。目前支持 Linux 环境中的 Azure PowerShell 和 Azure CLI 部署脚本。
可以允许将命令行参数传递给脚本。
可以指定脚本输出，并将其传递回部署。

部署脚本资源仅在 Azure 容器实例可用的区域中可用。有关详细信息，请参阅 ACI 的资源可用性和配额限制。

警告

部署脚本服务需要两个额外的资源用于脚本运行和故障排除：存储帐户和容器实例。通常，服务会在部署脚本完成后清理这些资源。这些资源在被删除之前会产生费用。

有关定价信息，请参阅 Azure 容器实例定价和 Azure Blob 存储定价。若要了解详细信息，请参阅清理部署脚本资源。

培训资源

如果您更喜欢通过分步指南了解部署脚本，请参阅 Microsoft Learn 模块通过部署脚本扩展 Bicep 和 ARM 模板。

配置最低权限

对于部署脚本 API 2020-10-01 或更高版本，部署脚本的执行会涉及两个主体：

部署主体：此主体用于部署 Bicep 文件。它创建部署脚本资源运行存储帐户和 Azure 容器实例所需的基础资源。若要配置最小特权权限，请将具有以下属性的自定义角色分配给部署主体：

{
  "roleName": "deployment-script-minimum-privilege-for-deployment-principal",
  "description": "Configure least privilege for the deployment principal in deployment script",
  "type": "customRole",
  "IsCustom": true,
  "permissions": [
    {
      "actions": [
        "Microsoft.Storage/storageAccounts/*",
        "Microsoft.ContainerInstance/containerGroups/*",
        "Microsoft.Resources/deployments/*",
        "Microsoft.Resources/deploymentScripts/*"
      ],
    }
  ],
  "assignableScopes": [
    "[subscription().id]"
  ]
}

如果未注册 Azure 存储和 Azure 容器实例资源提供程序，请添加 Microsoft.Storage/register/action 和 Microsoft.ContainerInstance/register/action。

部署脚本主体：只有在部署脚本需要向 Azure 进行身份验证并调用 Azure CLI 或 PowerShell 时，此主体才是必需的。可通过两种方法指定部署脚本主体：
- 在属性中指定identity;请参阅部署脚本资源语法。指定用户分配的托管标识时，脚本服务会在调用部署脚本之前调用 Connect-AzAccount -Environment AzureChinaCloud -Environment AzureChinaCloud -Identity 。托管标识必须具有完成脚本中操作所需的访问权限。目前仅支持用户分配的托管标识用于该属性 identity。若要使用另一标识登录，请使用此列表中的第二种方法。
- 将服务主身份验证信息作为安全环境变量传递，然后在部署脚本中调用 Connect-AzAccount -Environment AzureChinaCloud -Environment AzureChinaCloud 或 az login。
如果使用托管标识，则部署主体需要分配给托管标识资源的内置“托管的标识操作员”角色。

目前，内置角色尚不适用于配置部署脚本权限。

创建部署脚本

以下示例文件演示了一个简单的 Bicep 文件，其中包含部署脚本资源。该脚本采用一个字符串参数并创建另一个字符串：

Azure CLI
Azure PowerShell

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: 'echo "The argument is ${name}."; jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'PT1H'
  }
}

output text string = deploymentScript.properties.outputs.text

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: '14.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      Write-Host 'The argument is {0}' -f $name
      $output = 'Hello {0}' -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    retentionInterval: 'PT1H'
  }
}

output result string = deploymentScript.properties.outputs.text

有关创建部署脚本资源的详细信息，请参阅在 Bicep 中开发部署脚本。若要为部署脚本资源创建脚本，建议建立专用脚本开发环境，例如 Azure 容器实例或 Docker 映像。脚本开发完成并经过全面测试后，就可以从部署脚本资源集成或调用脚本文件。有关详细信息，请参阅在 Bicep 文件中为部署脚本配置开发环境。

将脚本保存在 inlineScript.bicep 文件中，然后使用以下脚本部署资源：

$resourceGroupName = Read-Host -Prompt "Enter the name of the resource group to be created"
$location = Read-Host -Prompt "Enter the location (i.e. chinanorth2)"

New-AzResourceGroup -Name $resourceGroupName -Location $location

New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateFile "inlineScript.bicep"

Write-Host "Press [ENTER] to continue ..."

使用托管标识

以下示例演示如何使用托管标识从部署脚本内部与 Azure 交互：

@description('The location of the resources.')
param location string = resourceGroup().location

@description('The storage account to list blobs from.')
param storageAccountData {
  name: string
  container: string
}

@description('The role id of Storage Blob Data Reader.')
var storageBlobDataReaderRoleId = '2a2b9908-6ea1-4ae2-8e65-a410df84e7d1'

@description('The storage account to read blobs from.')
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
  name: storageAccountData.name
}

@description('The Storage Blob Data Reader Role definition from [Built In Roles](/role-based-access-control/built-in-roles).')
resource storageBlobDataReaderRoleDef 'Microsoft.Authorization/roleDefinitions@2022-05-01-preview' existing = {
  scope: subscription()
  name: storageBlobDataReaderRoleId
}

@description('The user identity for the deployment script.')
resource scriptIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2025-01-31-preview' = {
  name: 'script-identity'
  location: location
}

@description('Assign permission for the deployment scripts user identity access to the read blobs from the storage account.')
resource dataReaderRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  scope: storageAccount
  name: guid(storageBlobDataReaderRoleDef.id, scriptIdentity.id, storageAccount.id)
  properties: {
    principalType: 'ServicePrincipal'
    principalId: scriptIdentity.properties.principalId
    roleDefinitionId: storageBlobDataReaderRoleDef.id
  }
}

@description('The deployment script.')
resource script 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'script'
  location: location
  kind: 'AzureCLI'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${scriptIdentity.id}': {}
    }
  }
  properties: {
    azCliVersion: '2.59.0'
    retentionInterval: 'PT1H'
    arguments: '${storageAccount.properties.primaryEndpoints.blob} ${storageAccountData.container}'
    scriptContent: '''
      #!/bin/bash
      set -e
      az storage blob list --auth-mode login --blob-endpoint $1 --container-name $2
    '''
  }
}

监视部署脚本并对其进行故障排除

对部署脚本资源进行部署时，需要一个存储帐户来存储用户脚本、执行结果和 stdout 文件。可以指定自己的存储帐户。有关详细信息，请参阅使用现有存储帐户。

指定自己的存储帐户的替代方法包括将 cleanupPreference 设置为 OnExpiration。然后，将 retentionInterval 配置为一段时间，以允许有充足的时间在移除存储帐户之前查看输出。有关详细信息，请参阅清理部署脚本资源。

将 cleanupPreference 属性添加到上述 Bicep 文件，并将值设置为 OnExpiration。默认值为 Always。此外，将 rentalInterval 设置为 PT1H（1 小时）或更短时间。

Azure CLI
Azure PowerShell

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: 'echo "The argument is ${name}."; jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    cleanupPreference: 'OnExpiration'
    retentionInterval: 'PT1H'
  }
}

output text string = deploymentScript.properties.outputs.text

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: '14.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      Write-Output "The argument is {0}." -f $name
      $output = "Hello {0}." -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    cleanupPreference: 'OnExpiration'
    retentionInterval: 'PT1H'
  }
}

output text string = deploymentScript.properties.outputs.text

成功部署 Bicep 文件后，请使用 Azure 门户、Azure CLI、Azure PowerShell 或 REST API 检查结果。

Azure 门户

部署好部署脚本资源后，该资源会在 Azure 门户中的资源组下列出。除了部署脚本资源外，概述页面还列出了两个支持资源。超出保留间隔后，将删除支持资源。

请注意，这两个支持资源的名称中都有 azscripts 后缀，因为这些资源会自动进行创建。标识支持资源的另一种方法是使用标记。

屏幕截图显示了一个部署脚本资源组。

从列表中选择部署脚本资源。部署脚本资源的 “概述 ”页显示有关资源的重要信息，包括 预配状态 和两个支持资源、 存储帐户 和 容器实例。 “日志”区域显示了脚本中的打印文本。

屏幕截图显示了有关部署脚本资源的信息。

选择“输出”以显示脚本的输出。

屏幕截图显示了部署脚本输出。

返回到资源组，选择存储帐户，选择“文件共享”，然后选择共享名称追加了 azscripts 的文件共享。列表中会显示两个文件夹：azscriptinput 和 azscriptoutput。输出文件夹包含 executionresult.json 文件和脚本输出文件。 executionresult.json 文件包含脚本执行错误消息。仅当成功运行脚本时，才会创建输出文件。

屏幕截图显示了一个部署脚本的输出文件夹的内容。

输入文件夹包含一个系统脚本文件和一些用户部署脚本文件。可以使用修订后的文件替换用户部署脚本文件，然后从 Azure 容器实例重新运行部署脚本。

Azure CLI

可以使用 Azure CLI 在订阅或资源组范围内管理部署脚本：

az deployment-scripts delete：删除部署脚本。
az deployment-scripts list：列出所有部署脚本。
az deployment-scripts show：检索部署脚本。
az deployment-scripts show-log：显示部署脚本日志。

list 命令的输出与以下实例类似：

{
  "arguments": "John Dole",
  "azCliVersion": "2.52.0",
  "cleanupPreference": "OnExpiration",
  "containerSettings": {
    "containerGroupName": null
  },
  "environmentVariables": null,
  "forceUpdateTag": null,
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlineCLI",
  "identity": null,
  "kind": "AzureCLI",
  "location": "chinanorth2",
  "name": "inlineCLI",
  "outputs": {
    "text": "Hello John Dole"
  },
  "primaryScriptUri": null,
  "provisioningState": "Succeeded",
  "resourceGroup": "dsDemo",
  "retentionInterval": "1:00:00",
  "scriptContent": "echo \"The argument is John Dole.\"; jq -n -c --arg st \"Hello John Dole\" '{\"text\": $st}' > $AZ_SCRIPTS_OUTPUT_PATH",
  "status": {
    "containerInstanceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/jgczqtxom5oreazscripts",
    "endTime": "2023-12-11T20:20:12.149468+00:00",
    "error": null,
    "expirationTime": "2023-12-11T21:20:12.149468+00:00",
    "startTime": "2023-12-11T20:18:26.674492+00:00",
    "storageAccountId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
  },
  "storageAccountSettings": null,
  "supportingScriptUris": null,
  "systemData": {
    "createdAt": "2023-12-11T19:45:32.239063+00:00",
    "createdBy": "johndole@contoso.com",
    "createdByType": "User",
    "lastModifiedAt": "2023-12-11T20:18:26.183565+00:00",
    "lastModifiedBy": "johndole@contoso.com",
    "lastModifiedByType": "User"
  },
  "tags": null,
  "timeout": "1 day, 0:00:00",
  "type": "Microsoft.Resources/deploymentScripts"
}

Azure PowerShell

可以使用 Azure PowerShell 在订阅或资源组范围内管理部署脚本：

Get-AzDeploymentScript：获取或列出部署脚本。
Get-AzDeploymentScriptLog：获取部署脚本执行日志。
Remove-AzDeploymentScript：删除部署脚本及其关联资源。
Save-AzDeploymentScriptLog：将部署脚本执行日志保存到磁盘。

Get-AzDeploymentScript 输出与以下示例类似：

Name                : inlinePS
Id                  : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlinePS
ResourceGroupName   : dsDemo
Location            : chinanorth2
SubscriptionId      : aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e
ProvisioningState   : Succeeded
Identity            :
ScriptKind          : AzurePowerShell
AzPowerShellVersion : 14.0
StartTime           : 12/11/2023 9:45:50 PM
EndTime             : 12/11/2023 9:46:59 PM
ExpirationDate      : 12/11/2023 10:46:59 PM
CleanupPreference   : OnExpiration
StorageAccountId    : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/ee5o4rmoo6ilmazscripts
ContainerInstanceId : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/ee5o4rmoo6ilmazscripts
Outputs             :
                      Key                 Value
                      ==================  ==================
                      text                Hello John Dole.

RetentionInterval   : PT1H
Timeout             : P1D

REST API

可以使用 REST API 获取有关资源组级别和订阅级别的部署脚本资源的信息：

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>?api-version=2020-10-01

/subscriptions/<SubscriptionID>/providers/microsoft.resources/deploymentScripts?api-version=2020-10-01

下面的示例使用 ARMClient。 ARMClient 不是受支持的Microsoft工具。

armclient login
armclient get /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01

输出类似于以下示例：

{
  "kind": "AzureCLI",
  "identity": null,
  "location": "chinanorth2",
  "systemData": {
    "createdAt": "2023-12-11T19:45:32.239063+00:00",
    "createdBy": "johndole@contoso.com",
    "createdByType": "User",
    "lastModifiedAt": "2023-12-11T20:18:26.183565+00:00",
    "lastModifiedBy": "johndole@contoso.com",
    "lastModifiedByType": "User"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "azCliVersion": "2.52.0",
    "scriptContent": "echo \"The argument is John Dole.\"; jq -n -c --arg st \"Hello John Dole\" '{\"text\": $st}' > $AZ_SCRIPTS_OUTPUT_PATH",
    "arguments": "John Dole",
    "retentionInterval": "1:00:00",
    "timeout": "1 day, 0:00:00",
    "containerSettings": {
      "containerGroupName": null
    },
    "status": {
      "containerInstanceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/jgczqtxom5oreazscripts",
      "endTime": "2023-12-11T20:20:12.149468+00:00",
      "error": null,
      "expirationTime": "2023-12-11T21:20:12.149468+00:00",
      "startTime": "2023-12-11T20:18:26.674492+00:00",
      "storageAccountId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
    },
    "outputs": {
      "text": "Hello John Dole"
    },
    "cleanupPreference": "OnSuccess"
  },
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlineCLI",
  "type": "Microsoft.Resources/deploymentScripts",
  "name": "inlineCLI",
}

以下 REST API 返回日志：

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>/logs?api-version=2020-10-01

它仅在删除部署脚本资源之前有效。

部署脚本错误代码

下表列出了部署脚本的错误代码：

错误代码	说明
`DeploymentScriptInvalidOperation`	Bicep 文件中的部署脚本资源定义包含无效的属性名。
`DeploymentScriptResourceConflict`	如果部署脚本资源处于非终端状态且执行未超过 1 小时，则无法删除该部署脚本资源。或者，不能使用相同的资源标识符（同一订阅、资源组名称和资源名称）重新运行同一部署脚本，但同时使用不同的脚本正文内容。
`DeploymentScriptOperationFailed`	部署脚本操作在内部失败。请联系 Microsoft 支持部门。
`DeploymentScriptStorageAccountAccessKeyNotSpecified`	尚未为现有存储帐户指定访问密钥。
`DeploymentScriptContainerGroupContainsInvalidContainers`	部署脚本服务创建的容器组是在外部修改的，并且添加了无效的容器。
`DeploymentScriptContainerGroupInNonterminalState`	两个或更多部署脚本资源在同一资源组中使用相同的 Azure 容器实例名称，其中一个尚未完成其执行。
`DeploymentScriptExistingStorageNotInSameSubscriptionAsDeploymentScript`	部署中提供的现有存储未在部署脚本的订阅中找到。
`DeploymentScriptStorageAccountInvalidKind`	`BlobBlobStorage` 或 `BlobStorage` 类型的现有存储帐户不支持文件共享，无法进行使用。
`DeploymentScriptStorageAccountInvalidKindAndSku`	现有存储帐户不支持文件共享。有关支持的存储帐户类型的列表，请参阅“使用现有存储帐户”。
`DeploymentScriptStorageAccountNotFound`	存储帐户不存在，或者已由外部进程或工具删除。
`DeploymentScriptStorageAccountWithServiceEndpointEnabled`	指定的存储帐户包含一个服务终结点。不支持具有服务终结点的存储帐户。
`DeploymentScriptStorageAccountInvalidAccessKey`	为现有存储帐户指定的访问密钥无效。
`DeploymentScriptStorageAccountInvalidAccessKeyFormat`	存储帐户密钥的格式无效。请参阅管理存储帐户访问密钥。
`DeploymentScriptExceededMaxAllowedTime`	部署脚本执行时间超过了部署脚本资源定义中指定的超时值。
`DeploymentScriptInvalidOutputs`	部署脚本输出不是有效的 JSON 对象。
`DeploymentScriptContainerInstancesServiceLoginFailure`	用户分配的托管标识在 10 次尝试后，将以一分钟为间隔，无法进行登录。
`DeploymentScriptContainerGroupNotFound`	外部工具或进程删除了部署脚本服务创建的容器组。
`DeploymentScriptDownloadFailure`	支持脚本下载失败。请参阅使用支持脚本。
`DeploymentScriptError`	用户脚本引发错误。
`DeploymentScriptBootstrapScriptExecutionFailed`	启动脚本引发错误。启动脚本是协调部署脚本执行的系统脚本。
`DeploymentScriptExecutionFailed`	执行部署脚本期间发生未知错误。
`DeploymentScriptContainerInstancesServiceUnavailable`	创建容器实例时，Azure 容器实例服务会引发“服务不可用”错误。
`DeploymentScriptContainerGroupInNonterminalState`	在创建容器实例期间，另一个部署脚本在同一范围内使用相同的容器实例名称（同一订阅、资源组名称和资源名称）。
`DeploymentScriptContainerGroupNameInvalid`	指定的容器实例名称不符合 Azure 容器实例要求。请参阅排查 Azure 容器实例中的常见问题。

访问专用虚拟网络

可以在具有一些附加配置的专用网络中运行部署脚本。有关详细信息，请参阅从 Bicep 部署脚本访问专用虚拟网络，或通过专用终结点私下运行 Bicep 部署脚本。

后续步骤

若要浏览本文中的主题，请参阅：

Last updated on 2025-11-27

通过