REST API 入门

2025-04-18

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

使用本文提供的 REST API 将应用程序与 Azure DevOps 集成。这些 API 允许以编程方式与服务交互，使你能够自动执行工作流、与其他系统集成以及扩展 Azure DevOps 的功能。

API 遵循常见模式，如以下示例所示：

VERB https://{instance}/{collection}/{team-project}/_apis/{area}/{resource}?api-version={version}

小提示

随着 API 的发展，我们建议在每个请求中包含 API 版本。这种做法有助于避免 API 中可能会中断的意外更改。

Azure DevOps Services

对于 Azure DevOps Services，instance 是 dev.azure.com/{organization}，而 collection 是 DefaultCollection，因此模式如下例所示：

VERB https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version={version}

以下示例演示如何获取组织中的项目列表：

curl -u {username}:{personalaccesstoken} https://dev.azure.com/{organization}/_apis/projects?api-version=2.0

如果要通过 HTTP 标头提供个人访问令牌（PAT），请先在 PAT 前加上冒号。然后，将冒号和 PAT 的串联转换为 Base64 字符串。以下示例演示如何使用 C# 转换为 Base64。然后，可以采用以下格式将生成的字符串作为 HTTP 标头提供：

Authorization: Basic BASE64COLONANDPATSTRING

注释

在 PAT 之前包括冒号以避免身份验证错误。

以下示例演示了使用 HttpClient 类的 C#：

public static async void GetProjects()
{
    try
    {
        var personalaccesstoken = "PAT_FROM_WEBSITE";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Accept.Add(
                new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
                Convert.ToBase64String(
                    System.Text.ASCIIEncoding.ASCII.GetBytes(
                        string.Format("{0}:{1}", "", personalaccesstoken))));

            using (HttpResponseMessage response = client.GetAsync(
                        "https://dev.azure.com/{organization}/_apis/projects").Result)
            {
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.ToString());
    }
}

重要

虽然为了简单起见，我们在许多示例中使用了个人访问令牌 (PAT)，但我们不建议将其用于生产应用程序。相反，请考虑使用更安全的身份验证机制。有关详细信息，请参阅身份验证指南。

Azure DevOps Server

对于 Azure DevOps Server， instance 为 {server:port}. 非 SSL 连接的默认端口为 8080。

默认集合是 DefaultCollection，但可以使用任何集合。

下面介绍如何使用跨 SSL 的默认端口和集合从 Azure DevOps Server 获取项目列表：

curl -u {username}:{personalaccesstoken} https://{server}/DefaultCollection/_apis/projects?api-version=2.0

若要跨非 SSL 连接获取相同的列表，

curl -u {username}:{personalaccesstoken} http://{server}:8080/DefaultCollection/_apis/projects?api-version=2.0

这些示例使用 PAT，这要求你创建 PAT。

反应

应会获得一个响应，如下例所示：

{
    "value": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "TeamFoundationVersionControlprojects",
            "collection": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/00000000-0000-0000-0000-000000000000",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
            },
            "defaultTeam": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "Fabrikam-Fiber-TFVCTeam",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000/teams/00000000-0000-0000-0000-000000000000"
            }
        },
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-Git",
            "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "Gitprojects",
            "collection": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/00000000-0000-0000-0000-000000000000",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
            },
            "defaultTeam": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "Fabrikam-Fiber-GitTeam",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000/teams/00000000-0000-0000-0000-000000000000"
            }
        }
    ],
    "count": 2
}

响应是 JSON，通常是从 REST API 返回的内容，尽管存在一些例外情况，例如 Git Blob。

现在，可以查看特定的 API 区域，例如工作项跟踪或 Git ，并获取所需的资源。继续阅读，详细了解这些 API 中使用的常规模式。

HTTP 谓词

动词	用于...
GET	获取资源或资源列表
POST	创建资源，使用更高级查询获取资源列表
PUT	如果资源不存在，则创建资源，或者，如果不存在，请更新它
PATCH	更新资源
DELETE	删除资源

请求标头和请求内容

当您提供请求正文（通常与 POST、PUT 和 PATCH 动词一起使用时），请包括描述该正文的请求标头。例如，

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/build-release/requests

Content-Type: application/json

{
   "definition": {
      "id": 3
   },
   "reason": "Manual",
   "priority": "Normal"
}

HTTP 方法替代

某些 Web 代理可能仅支持 HTTP 谓词 GET 和 POST，但不支持更现代的 HTTP 谓词，如 PATCH 和 DELETE。如果调用可能通过其中一个代理，则可以使用 POST 方法发送实际谓词，并使用标头替代该方法。例如，你可能想要更新工作项（PATCH _apis/wit/workitems/3），但可能需要通过仅允许 GET 或 POST 的代理。可以将正确的动词（在本例中为 PATCH）作为 HTTP 请求头参数传递，并使用 POST 作为实际的 HTTP 方法。

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/wit/workitems/3

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

响应代码

响应	注释
200	成功，且有响应正文。
201	在创造资源时取得成功。成功创建资源时，某些 API 返回 200。查看您正在使用的 API 的文档以确保。
204	成功，且有响应正文。例如，删除资源时会收到此响应。
400	URL 或请求正文中的参数无效。
401	身份验证失败。通常，此响应是由于缺少或格式不正确的授权标头。
403	经过身份验证的用户无权执行该作。
404	资源不存在，或者经过身份验证的用户无权查看该资源是否存在。
409	请求与服务器上的数据状态之间存在冲突。例如，如果尝试提交拉取请求，并且已经有一个提交的拉取请求了，那么响应代码是 409。

Azure DevOps Services 支持 CORS，这使得 JavaScript 代码可以从不同于 dev.azure.com/* 的域发出 Ajax 请求，访问 Azure DevOps Services REST API。每个请求都必须提供凭据（PAT 和 OAuth 访问令牌都是受支持的选项）。示例：

    $( document ).ready(function() {
        $.ajax({
            url: 'https://dev.azure.com/fabrikam/_apis/projects?api-version=1.0',
            dataType: 'json',
            headers: {
                'Authorization': 'Basic ' + btoa("" + ":" + myPatToken)
            }
        }).done(function( results ) {
            console.log( results.value[0].id + " " + results.value[0].name );
        });
    });

将 myPatToken 替换为 PAT。

版本控制

Azure DevOps REST API 经过版本控制，以确保应用程序和服务继续随着 API 的发展而工作。

准则

使用每个请求指定 API 版本（必需）。
按以下方式设置 API 版本格式：{major}.{minor}-{stage}.{resource-version}。例如、1.0、1.11.2-preview、2.0。
使用以下版本格式来指定 API 在预览版时的特定修订：1.0-preview.1 和 1.0-preview.2。一旦 '1.0'（例如）的 API 发布，其预览版（例如 1.0-preview）将被弃用，并可能会在 12 周后失效。
升级到 API 的已发布版本。停用预览 API 后，指定 -preview 版本的请求将被拒绝。

用法

在 HTTP 请求的标头中指定 API 版本，或指定为 URL 查询参数。

HTTP 请求标头：

Accept: application/json;api-version=1.0

查询参数：

GET https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version=1.0

支持的版本

有关支持的版本的信息，请参阅 REST API 版本控制、支持的版本。

通过