REST API 入门

  • 项目

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

使用这些 REST API 将应用与 Azure DevOps 集成。

这些 API 遵循常见模式：

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

提示

为了避免随着 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 标头提供个人访问令牌，必须先将其转换为 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());
	}
}

如果没有组织，可以 免费设置一个。

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

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

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

响应

应收到如下所示的响应。

{
    "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 ，并获取所需的资源。 继续阅读，了解有关这些 API 中使用的常规模式的详细信息。

HTTP 谓词

谓词 用于...
GET 获取资源或资源列表
POST 创建资源，使用更高级查询获取资源列表
PUT 创建资源（如果不存在），或者（如果存在）更新资源
修补程序 更新资源
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。

跨域资源共享 (CORS)

Azure DevOps Services支持 CORS，它允许从域提供 JavaScript 代码，而不是dev.azure.com/*向 Azure DevOps Services REST API 发出 Ajax 请求。 每个请求都必须提供凭据， (个人访问令牌和 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 (替换为个人访问令牌)

版本管理

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

准则

  • 必须为每个请求指定 API 版本。
  • API 版本采用 {major} 格式。{minor}-{stage}。{resource-version} - 例如，、1.0、1.11.2-preview、 2.0。
  • 虽然 API 处于预览状态，但在需要时可以指定特定 API 的精确版本 (，例如， 1.0-preview.11.0-preview.2)
  • (1.0 发布 API（例如) ）后，其预览版本 (1.0-preview) 已弃用，可在 12 周后停用。
  • 现在，应升级到已发布的 API 版本。 停用预览 API 后，指定 -preview 版本的请求将被拒绝。

使用情况

可以在 HTTP 请求的标头或 URL 查询参数中指定 API 版本：

HTTP 请求标头：

Accept: application/json;api-version=1.0

查询参数：

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

支持的版本

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