通过REST API创建VSTS发布：ReleaseStartMetadata必填字段与PowerShell构建问题

我之前在写PowerShell脚本自动化Azure DevOps（原VSTS）发布的时候，也被ReleaseStartMetadata这个对象的字段搞得头大——官方文档确实有些模糊的地方，尤其是必填项和一些字段的取值逻辑。结合我踩过的坑，给你整理一下关键信息：

必须填的核心字段 #

这些字段是API必须要的，少一个都会报错：

• definitionId: 你要基于的发布定义的ID，直接从发布定义页面的URL里就能拿到（比如https://dev.azure.com/你的组织/你的项目/_release?definitionId=123里的123）。
• artifacts: 数组类型，对应发布定义里关联的所有工件（构建、GitHub、容器镜像等）。每个工件对象必须包含：
  • alias: 和发布定义里设置的工件别名完全一致（去发布定义的「工件」标签里核对，大小写都不能错）。
  • instanceReference: 用来指定要使用的具体工件版本，比如构建工件的话，这里的id就是构建的数字ID；如果想用最新成功的构建，也可以填{"id": "latest"}（亲测有效）。
• isDraft: 布尔值，一般设为$false，因为我们是直接启动发布，不是存为草稿。

关于BuildVersion字段的疑惑 #

这个字段是可选的，官方文档没讲清楚确实坑人。它其实是给你创建的这个新发布设置一个自定义版本号，比如你可以填v2.3.1-hotfix来标识这个发布的版本。如果不填，系统会自动生成默认的格式（比如Release-456这种带序号的）。它和工件的版本（比如构建版本号）不是一回事，只是这个发布实例的标识。

完整PowerShell示例脚本 #

下面是一个可以直接用的示例，替换成你的实际信息就行：

# 配置参数
$orgName = "你的Azure DevOps组织名"
$projName = "你的项目名"
$patToken = "你的PAT令牌（需要有发布创建权限）"
$releaseDefId = 123 # 替换为你的发布定义ID
$targetBuildId = 456 # 替换为要使用的构建ID
$artifactAlias = "你的工件别名" # 替换为发布定义里的工件别名

# 构建ReleaseStartMetadata请求体
$releasePayload = @{
    definitionId = $releaseDefId
    isDraft = $false
    artifacts = @(
        @{
            alias = $artifactAlias
            instanceReference = @{
                id = $targetBuildId.ToString()
            }
        }
    )
    # 可选：自定义发布版本号
    # buildVersion = "v2.3.1-prod"
} | ConvertTo-Json -Depth 10

# 设置请求头
$authHeader = @{
    Authorization = "Basic " + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$patToken"))
}

# 调用API创建并启动发布
$apiUrl = "https://vsrm.dev.azure.com/$orgName/$projName/_apis/release/releases?api-version=7.1-preview.8"
Invoke-RestMethod -Uri $apiUrl -Method Post -Headers $authHeader -Body $releasePayload -ContentType "application/json"

额外踩坑提示 #

• API版本：尽量用较新的版本，上面用的7.1-preview.8是比较稳定的，太老的版本可能不支持某些字段。
• 多工件处理：如果你的发布定义关联了多个工件，只需要在artifacts数组里添加对应的每个工件对象，每个都要填对alias和instanceReference。
• 权限问题：你的PAT令牌必须有发布管理的权限，至少要勾选「创建发布」的权限，否则会返回403错误。

内容的提问来源于stack exchange，提问作者jkindwall