Azure DevOps Services REST API 参考

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

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

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

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

REST API 请求/响应对的组件

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

  1. 请求 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 版本。

  2. HTTP 请求消息标头 字段:

    • 所需的 HTTP 方法(也称为操作或谓词),它告知该服务你请求的操作类型。 Azure REST API 支持 GET、HEAD、PUT、POST 和 PATCH 方法。
    • 指定的 URI 和 HTTP 方法所需的其他可选的标头字段。 例如,提供持有者令牌的授权标头,其中包含请求的客户端授权信息。
  3. 可选的 HTTP 请求消息正文字段,用于支持 URI 和 HTTP 操作。 例如,POST 操作包含作为复杂参数传递的 MIME 编码对象。

    • 对于 POST 或 PUT 操作,还应在 Content-type 请求标头中指定正文的 MIME 编码类型。 某些服务要求使用特定的 MIME 类型,如 application/json
  4. HTTP 响应消息标头字段

    • HTTP 状态代码,包括从 2xx 成功代码到 4xx 或 5xx 错误代码在内的各种代码。 或者,可能返回服务定义的状态代码,如 API 文档中所指示。
    • 可选的其他标头字段,用于支持请求的响应,例如 Content-type 响应标头。
  5. 可选的 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 概述