REST API 参考

项目
08/06/2022

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

表示性状态传输 (REST) API 是支持) (方法集的服务终结点。这些方法提供对服务资源的创建、检索、更新或删除访问权限。了解 REST API 请求和响应对的基本组件，并查看有关如何创建和发送 REST 请求以及处理响应的概述。

注意

大多数 REST API 都有相应的 .NET 客户端库，可用于简化客户端代码。有关详细信息，请参阅 .NET 客户端库文档

REST API 请求和响应对的组件

可以将 REST API 请求和响应对分为以下五个组件：

请求 URI，采用以下格式： VERB https://{instance}[/{collection}][/{team-project}]/_apis[/{area}]/{resource}?api-version={version}
- 实例：要向其发送请求的 Azure DevOps 组织或Azure DevOps Server。它们的结构如下：
  - Azure DevOps： dev.azure.com/{organization}
  - Azure DevOps Server： server:port (默认端口为 8080)
- 集合：集合的值应 DefaultCollection 为 Azure DevOps。
- 资源路径：集合应后跟 _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 请求。
HTTP 请求消息标头 字段：
- 所需的 HTTP 方法 (也称为操作或谓词) ，它告知服务所请求的操作类型。 Azure REST API 支持 GET、HEAD、PUT、POST 和 PATCH 方法。
- 指定的 URI 和 HTTP 方法所需的其他可选的标头字段。例如，提供包含请求客户端授权信息的持有者令牌的授权标头。
可选的 HTTP 请求消息正文字段，用于支持 URI 和 HTTP 操作。例如，POST 操作包含作为复杂参数传递的 MIME 编码对象。
- 对于 POST 或 PUT 操作，还应在内容类型请求标头中指定正文的 MIME 编码类型。某些服务要求使用特定的 MIME 类型，如 application/json。
HTTP 响应消息标头字段：
- HTTP 状态代码，包括从 2xx 成功代码到 4xx 或 5xx 错误代码在内的各种代码。或者，可以返回服务定义的状态代码，如 API 文档中所示。
- 可选的其他标头字段，用于支持请求的响应，例如 Content-type 响应标头。
可选的 HTTP 响应消息正文字段：
- MIME 编码的响应对象可能在 HTTP 响应正文中返回，例如来自返回数据的 GET 方法的响应。通常，这些对象以结构化格式（如 JSON 或 XML）返回，如 Content-type 响应标头所指示。例如，从 Azure AD 请求访问令牌时，它会在响应正文中作为 access_token 元素返回，它是数据收集中多个名称/值配对对象之一。在此示例中，还包括响应标头 Content-Type: application/json 。

创建请求

Authenticate

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

应用程序类型	说明	示例	身份验证机制	代码示例
交互式客户端	基于 GUI 的客户端应用程序	Windows 应用枚举用户的 bug	Microsoft 身份验证库	样本
交互式 JavaScript	基于 GUI 的 JavaScript 应用程序	显示用户工作项的 AngularJS 单页应用	Microsoft 身份验证库	即将推出示例 ()
非交互式客户端	仅无头文本客户端应用程序	显示分配给用户的所有 bug 的控制台应用	设备配置文件	样本
交互式 Web	基于 GUI 的 Web 应用程序	显示生成摘要的自定义 Web 仪表板	OAuth	样本
Azure DevOps Server应用程序	使用客户端 OM 库Azure DevOps Server应用	显示团队 bug 仪表板的Azure DevOps Server扩展	客户端库	样本
Azure DevOps Services扩展	Azure DevOps Services扩展	敏捷卡	VSS Web 扩展 SDK	示例演练

注意

可以在我们的身份验证指南页上找到有关身份验证的详细信息

汇编请求

对于Azure DevOps Services，实例是dev.azure.com/{organization}和集合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 标头提供个人访问令牌，必须先将其转换为 Base64 字符串， (以下示例演示如何使用 C#) 转换为 Base64。然后，可以采用以下格式将生成的字符串作为 HTTP 标头提供：

Authorization: Basic BASE64PATSTRING

下面是使用 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 Services，包括 Microsoft 身份验证库、OAuth 和会话令牌。有关最适合你的方案的指南，请参阅 “身份验证 ”部分。

对于Azure DevOps Server， instance{server:port}端口默认为 8080。默认集合是 DefaultCollection，但可以是任何集合。

下面介绍如何获取项目列表：

curl -u {username}[:{personalaccesstoken}] https://{server}:8080/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"
            },
            "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"
            },
            "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。

查找 API 区域所需的资源，例如工作项跟踪或 Git。

查看 REST API 示例和用例的集成文档
- 身份验证指南
- 示例
发现这些 REST API 的 .NET 客户端库
- 示例