如何在VSTS Web扩展中调用REST API获取发布定义的工件列表？

Hey, I’ve been in exactly this spot before when building VSTS (now Azure DevOps Server/Services) release management extensions—figuring out the right artifact versions (and that default pre-selected one VSTS picks) is such a headache, especially since the public APIs don’t explicitly surface this. Good call noticing that internal API VSTS uses itself; let me break down how to leverage it properly:

1. The "Preview Release" API Endpoint #

The internal API you’re thinking of is the release preview endpoint, which VSTS uses to render the "Create Release" UI with all artifact options and defaults. Here’s the format:

POST https://{your-instance}/_apis/release/releases?action=preview&api-version=7.1-preview.8

• Replace {your-instance} with your VSTS/Azure DevOps URL (e.g., dev.azure.com/your-org or your-org.visualstudio.com for older instances)
• Stick with the latest preview API version you can find—preview versions tend to stay stable for this endpoint, but double-check if you run into issues.

2. Request Body Setup #

You only need to pass the release definition ID and minimal metadata to trigger the preview. Here’s a sample request body:

{
  "definitionId": 123, // Replace with your release definition ID
  "isDraft": false,
  "reason": "none",
  "manualEnvironments": [],
  "artifacts": []
}

Leave the artifacts array empty—VSTS will automatically populate all artifacts linked to your release definition, along with their available versions and default selection.

3. Parse the Response for What You Need #

The response will include an artifacts array that’s exactly what you’re looking for. Each entry has:

• version: The default pre-selected artifact version (the one VSTS would pick if you clicked "Create Release" without changing anything)
• availableVersions: A full list of all valid versions for that artifact
• definitionReference: Metadata about the artifact source (like build definition ID, project info, etc.)

Here’s a simplified snippet of what that looks like:

"artifacts": [
  {
    "type": "Build",
    "definitionReference": {
      "definition": {"id": "45", "name": "MyApp-Build"},
      "project": {"id": "abc123", "name": "MyProject"}
    },
    "version": {"id": "987", "name": "20240520.1"},
    "availableVersions": [
      {"id": "987", "name": "20240520.1"},
      {"id": "986", "name": "20240519.2"},
      {"id": "985", "name": "20240518.1"}
    ]
  }
]

4. Key Caveats to Keep in Mind #

• Unsupported API: This is an internal, undocumented endpoint, so Microsoft could change it in a future update. Test thoroughly when upgrading your Azure DevOps instance.
• Permissions: Make sure your extension has the necessary Release permissions (at minimum, the "Create release" permission) to call this API.
• Cloud vs. Server: For Azure DevOps Server (on-prem), adjust the API version to match your server’s supported versions (e.g., 5.1-preview.8 for older server versions).

5. Use the Data to Create a Release #

Once you’ve grabbed the artifact version(s) you want (either the default or a user-selected one), use the public Create Release API to launch the actual release. The endpoint is:

POST https://{your-instance}/{project-name}/_apis/release/releases?api-version=7.1-preview.8

Populate the artifacts array in the request body with the version data from the preview response, like this:

{
  "definitionId": 123,
  "artifacts": [
    {
      "type": "Build",
      "definitionReference": {
        "definition": {"id": "45"},
        "project": {"id": "abc123"}
      },
      "version": {"id": "987"}
    }
  ]
}

This workflow will let you accurately replicate the same artifact version selection logic that VSTS uses natively, so your extension creates releases exactly as users expect.

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