Azure DevOps Services REST API 参考
欢迎使用 Azure DevOps Services/Azure DevOps Server REST API 参考。
表述性状态转移 (REST) API 是支持一组 HTTP 操作(方法)的服务终结点,它们提供针对服务资源的创建、检索、更新或删除访问权限。 本文介绍:
- REST API 请求/响应对的基本组件。
- 创建和发送 REST 请求以及处理响应的概述。
大多数 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
,但可以是任何集合)
- Azure DevOps Services:
-
资源路径:资源路径如下所示:
_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 版本。
-
实例:要向其发送请求Azure DevOps Services组织或 TFS 服务器。 它们的结构如下:
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
。
- 对于 POST 或 PUT 操作,还应在 Content-type 请求标头中指定正文的 MIME 编码类型。 某些服务要求使用特定的 MIME 类型,如
HTTP 响应消息标头字段:
- HTTP 状态代码,包括从 2xx 成功代码到 4xx 或 5xx 错误代码在内的各种代码。 或者,可能返回服务定义的状态代码,如 API 文档中所指示。
- 可选的其他标头字段,用于支持请求的响应,例如
Content-type
响应标头。
可选的 HTTP 响应消息正文字段:
- 可以在 HTTP 响应正文中返回 MIME 编码的响应对象,例如来自返回数据的 GET 方法的响应。 通常,这些对象以结构化格式(如 JSON 或 XML)返回,如
Content-type
响应标头所指示。 例如,从 Azure AD 请求访问令牌时,该令牌将在响应正文中作为 元素返回,该元素是access_token
数据收集中多个名称/值配对对象之一。 在此示例中,还包含 的Content-Type: application/json
响应标头。
- 可以在 HTTP 响应正文中返回 MIME 编码的响应对象,例如来自返回数据的 GET 方法的响应。 通常,这些对象以结构化格式(如 JSON 或 XML)返回,如
可通过多种方法使用 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 中使用的常规模式。
下面提供了 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 的每个人提供更清晰、更深入、更准确的文档。 由于技术限制,我们只能使用此方法记录 API 版本 4.1 及更新 版本。 我们相信,由于此更改,API 版本 4.1 及更新版本的文档将更易于使用。
如果使用的是 TFS 或正在查找旧版 REST API,则可以查看 适用于 TFS 2015、2017 和 2018 的 REST API 概述。