Azure DevOps Services REST API 参考

项目
08/24/2023

欢迎使用 Azure DevOps Services/Azure DevOps Server REST API 参考。

表述性状态转移 (REST) API 是支持一组 HTTP 操作（方法）的服务终结点，它们提供针对服务资源的创建、检索、更新或删除访问权限。本文介绍：

REST API 请求/响应对的基本组件。
创建和发送 REST 请求以及处理响应的概述。

大多数 REST API 都可以通过客户端库进行访问，这些库可用于大大简化客户端代码。

REST API 请求/响应对的组件

REST API 请求/响应对可分解为五个组件：

请求 URI，采用以下形式：VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}
- 实例：要向其发送请求Azure DevOps Services组织或 TFS 服务器。它们的结构如下：
  - Azure DevOps Services：dev.azure.com/{organization}
  - TFS： {server:port}/tfs/{collection} (默认端口为 8080，并且集合的值应为 DefaultCollection ，但可以是任何集合)
- 资源路径：资源路径如下所示： _apis/{area}/{resource}。例如，_apis/wit/workitems。
- api-version：每个 API 请求都应包含一个 API 版本，以避免随着 API 的发展而中断应用或服务。 api 版本采用以下格式： {major}.{minor}[-{stage}[.{resource-version}]]例如：
  - api-version=1.0
  - api-version=1.2-preview
  - api-version=2.0-preview.1
注意：区域和 团队项目 是可选的，具体取决于 API 请求。请查看下面的 TFS 到 REST API 版本映射矩阵，查找适用于 TFS 版本的 REST API 版本。
HTTP 请求消息标头 字段：
- 所需的 HTTP 方法（也称为操作或谓词），它告知该服务你请求的操作类型。 Azure REST API 支持 GET、HEAD、PUT、POST 和 PATCH 方法。
- 指定的 URI 和 HTTP 方法所需的其他可选的标头字段。例如，提供持有者令牌的授权标头，其中包含请求的客户端授权信息。
可选的 HTTP 请求消息正文字段，用于支持 URI 和 HTTP 操作。例如，POST 操作包含作为复杂参数传递的 MIME 编码对象。
- 对于 POST 或 PUT 操作，还应在 Content-type 请求标头中指定正文的 MIME 编码类型。某些服务要求使用特定的 MIME 类型，如 application/json。
HTTP 响应消息标头字段：
- HTTP 状态代码，包括从 2xx 成功代码到 4xx 或 5xx 错误代码在内的各种代码。或者，可能返回服务定义的状态代码，如 API 文档中所指示。
- 可选的其他标头字段，用于支持请求的响应，例如 Content-type 响应标头。
可选的 HTTP 响应消息正文字段：
- 可以在 HTTP 响应正文中返回 MIME 编码的响应对象，例如来自返回数据的 GET 方法的响应。通常，这些对象以结构化格式（如 JSON 或 XML）返回，如 Content-type 响应标头所指示。例如，从 Azure AD 请求访问令牌时，该令牌将在响应正文中作为元素返回，该元素是 access_token 数据收集中多个名称/值配对对象之一。在此示例中，还包含的 Content-Type: application/json 响应标头。

创建请求

Authenticate

可通过多种方法使用 Azure DevOps Services 或 TFS 对应用程序或服务进行身份验证。下表是确定哪种方法最适合的极佳方法：

应用程序类型	说明	示例	身份验证机制	代码示例
交互式客户端	客户端应用程序，允许用户交互，Azure DevOps Services REST API 调用	枚举组织中的项目的控制台应用程序	Microsoft 身份验证库 (MSAL)	sample
交互式 JavaScript	基于 GUI 的 JavaScript 应用程序	显示用户项目信息的 AngularJS 单页应用	MSAL	sample
非交互式客户端	仅限无外设文本的客户端应用程序	显示分配给用户的所有 bug 的控制台应用	设备配置文件	sample
交互式 Web	基于 GUI 的 Web 应用程序	显示生成摘要的自定义 Web 仪表板	OAuth	sample
TFS 应用程序	使用客户端 OM 库的 TFS 应用	显示团队 bug 仪表板的 TFS 扩展	客户端库	sample
Azure DevOps Services扩展	Azure DevOps Services扩展	Azure DevOps 扩展示例	VSS Web 扩展 SDK	示例演练

注意： 有关身份验证的详细信息，请参阅我们的身份验证指南页。

组合请求

Azure DevOps Services

对于Azure DevOps Services，实例为 dev.azure.com/{organization}，因此模式如下所示：

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

例如，下面介绍如何获取Azure DevOps Services组织中的团队项目列表。

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

如果要通过 HTTP 标头提供个人访问令牌，必须先将其转换为 Base64 字符串 (以下示例演示如何使用 C#) 转换为 Base64。 (Postman 等某些工具默认应用 Base64 编码。如果通过此类工具尝试 API，则不需要 PAT 的 Base64 编码) 生成的字符串可以采用以下格式作为 HTTP 标头提供：

Authorization: Basic BASE64PATSTRING

此处，它是在 C# 中使用 [HttpClient 类] (/previous-versions/visualstudio/hh193681 (v=vs.118) 。

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 = await client.GetAsync(
						"https://dev.azure.com/{organization}/_apis/projects"))
			{
				response.EnsureSuccessStatusCode();
				string responseBody = await response.Content.ReadAsStringAsync();
				Console.WriteLine(responseBody);
			}
		}
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.ToString());
	}
}

此网站上的大多数示例都使用个人访问令牌，因为它们是用于对服务进行身份验证的紧凑示例。但是，有多种身份验证机制可用于Azure DevOps Services包括 MSAL、OAuth 和会话令牌。有关哪种身份验证最适合方案的指导，请参阅身份验证部分。

TFS

对于 TFS， instance 为 {server:port}/tfs/{collection} ，默认情况下端口为 8080。默认集合为 DefaultCollection，但可以是任何集合。

下面介绍如何使用默认端口和集合从 TFS 获取团队项目列表。

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

上述示例使用个人访问令牌，这要求创建个人访问令牌。

处理响应

应会收到如下所示的响应。

{
    "value": [
        {
            "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "description": "TeamFoundationVersionControlprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc/DefaultCollection"
            },
            "defaultTeam": {
                "id": "66df9be7-3586-467b-9c5f-425b29afedfd",
                "name": "Fabrikam-Fiber-TFVCTeam",
                "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd"
            }
        },
        {
            "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "name": "Fabrikam-Fiber-Git",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "description": "Gitprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection"
            },
            "defaultTeam": {
                "id": "8bd35c5e-30bb-4834-a0c4-d576ce1b8df7",
                "name": "Fabrikam-Fiber-GitTeam",
                "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/teams/8bd35c5e-30bb-4834-a0c4-d576ce1b8df7"
            }
        }
    ],
    "count": 2
}

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

现在，你应该能够查看工作项跟踪或 Git 等特定 API 领域，并获取所需的资源。请继续阅读，详细了解这些 API 中使用的常规模式。

API 和 TFS 版本映射

下面提供了 REST API 版本及其相应 TFS 版本的快速映射。所有 API 版本都将在上述服务器版本以及更高版本上运行。

TFS 版本	REST API 版本	内部版本
Azure DevOps Server vNext	7.1
2022 Azure DevOps Server	7.0	versions >= `19.205.33122.1`
Azure DevOps Server 2020	6.0	versions >= `18.170.30525.1`
Azure DevOps Server 2019	5.0	versions >= `17.143.28621.4`
TFS 2018 Update 3	4.1	versions >= `16.131.28106.2`
TFS 2018 Update 2	4.1	versions >= `16.131.27701.1`
TFS 2018 Update 1	4.0	versions >= `16.122.27409.2`
TFS 2018 RTW	4.0	versions >= `16.122.27102.1`
TFS 2017 Update 2	3.2	versions >= `15.117.26714.0`
TFS 2017 Update 1	3.1	versions >= `15.112.26301.0`
TFS 2017 RTW	3.0	versions >= `15.105.25910.0`
TFS 2015 Update 4	2.3	versions >= `14.114.26403.0`
TFS 2015 Update 3	2.3	versions >= `14.102.25423.0`
TFS 2015 Update 2	2.2	versions >= `14.95.25122.0`
TFS 2015 Update 1	2.1	versions >= `14.0.24712.0`
TFS 2015 RTW	2.0	versions >= `14.0.23128.0`

请查看 REST API 示例和用例的集成文档。

客户端库

发现这些 REST API 的客户端库。

REST API 的早期版本在哪里？ (4.1 之前)

我们最近对工程系统和文档生成过程进行了更改：我们进行了此更改，以便为尝试使用这些 REST API 的每个人提供更清晰、更深入、更准确的文档。由于技术限制，我们只能使用此方法记录 API 版本 4.1 及更新 版本。我们相信，由于此更改，API 版本 4.1 及更新版本的文档将更易于使用。

如果使用的是 TFS 或正在查找旧版 REST API，则可以查看适用于 TFS 2015、2017 和 2018 的 REST API 概述。

通过