使用Azure DevOps REST API创建构建工件的技术疑问及示例请求

1. ArtifactResource中data字段的作用 #

data字段用于存储与工件资源类型绑定的元数据信息，不同type的工件对应不同的data结构：

• 若type为file，data通常包含文件大小、哈希值（如SHA256）等校验信息，帮助平台验证文件完整性；
• 若type为container，data会记录容器的存储路径、包含的文件列表等信息；
• 其他类型（如dockerimage）的data则会存储镜像的仓库地址、标签等专属元数据。
  简单来说，这个字段是给Azure DevOps平台提供识别和处理工件所需的额外关键信息。

2. type字段的可选值 #

官方定义的常用可选值包括：

• container：对应流水线中的文件夹类工件，支持多文件集合；
• file：单个独立文件工件；
• gitref：关联Git仓库的特定分支、标签或提交记录的工件；
• dockerimage：Docker镜像类型的工件，需关联镜像仓库信息。

3. 文件内容上传方式 #

不是通过Url字段让服务器主动下载，正确流程是先将文件上传到Azure DevOps的Blob存储，再通过Create Artifact接口关联已上传的文件：

1. 先调用「获取工件上传URL」接口，拿到可用于上传的SAS地址（带权限的临时存储链接）；
2. 将文件内容PUT到这个SAS地址完成上传；
3. 最后调用Create Artifact接口，在resource的Url字段填写这个SAS地址，同时配合正确的type和data元数据，完成工件的创建关联。

完整使用示例（以单个文件工件为例） #

步骤1：获取上传URL

发送POST请求获取临时上传地址：

POST https://dev.azure.com/{组织名}/{项目名}/_apis/build/builds/{构建ID}/artifacts?artifactName=MyFileArtifact&api-version=7.1

响应示例（关键字段）：

{
  "uploadUrl": "https://xxx.blob.core.windows.net/xxx/xxx.zip?sv=2021-08-06&sr=...",
  "resource": {
    "type": "file",
    "data": "{\"fileSize\": 0}",
    "url": "https://xxx.blob.core.windows.net/xxx/xxx.zip"
  }
}

步骤2：上传文件到存储地址

用curl或其他工具执行PUT上传：

curl -X PUT -T "/本地路径/your-file.zip" "https://xxx.blob.core.windows.net/xxx/xxx.zip?sv=2021-08-06&sr=..."

步骤3：创建关联工件

发送POST请求到Create Artifact接口，请求体如下：

{
  "name": "MyFileArtifact",
  "resource": {
    "type": "file",
    "data": "{\"fileSize\": 123456, \"hash\": \"SHA256:abcdef1234567890abcdef1234567890\"}",
    "url": "https://xxx.blob.core.windows.net/xxx/xxx.zip",
    "properties": {
      "artifactType": "file"
    }
  }
}

请求地址：

POST https://dev.azure.com/{组织名}/{项目名}/_apis/build/builds/{构建ID}/artifacts?api-version=7.1

空工件问题排查 #

你之前生成无内容、无法点击的空工件，大概率是以下原因：

• 跳过了文件上传步骤，直接调用Create Artifact接口，导致Url指向的存储位置无内容；
• data字段未填写对应type的必填元数据，平台无法识别工件的有效内容；
• type字段取值错误，导致平台无法正确解析工件资源。

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