通过

REST API 入门

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020

Azure DevOps REST API 提供对工作项、存储库、生成、发布等的强大编程访问。 无论是构建自定义集成、自动化工作流还是扩展 Azure DevOps 功能，了解基本模式和概念对于成功实现至关重要。

小提示

准备好开始编码了吗？ 跳到 REST API 示例 ，获取使用新式身份验证模式的完整工作示例。

本文介绍 Azure DevOps REST API 的基本概念和模式。 有关实际实现示例，请参阅 REST API 示例。

URL 结构

API 遵循常见模式，如以下示例所示：

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

小提示

随着 API 的发展，我们建议在每个请求中包含 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}

示例终结点：

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

Azure DevOps Server

对于 Azure DevOps Server， instance 为 {server:port}. 非 SSL 连接的默认端口为 8080。

默认集合是 DefaultCollection，但可以使用任何集合。

示例：

  • SSL： https://{server}/DefaultCollection/_apis/projects?api-version=7.2
  • 非 SSL： http://{server}:8080/DefaultCollection/_apis/projects?api-version=7.2

身份验证

Azure DevOps REST API 支持多种身份验证方法：

  • Microsoft Entra ID - 建议用于生产应用程序
  • 个人访问令牌 （PAT） - 脚本和测试的简单身份验证
  • OAuth 2.0 - 对于非Microsoft应用程序
  • 服务主体 - 适用于自动方案

重要

Microsoft Entra ID 身份验证是生产应用程序的推荐方法。 有关实现示例和完整的身份验证指南，请参阅 REST API 示例 和 身份验证指南。

响应格式

Azure DevOps REST API 通常返回 JSON 响应。 下面是一个示例响应结构：

{
    "value": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "TeamFoundationVersionControlprojects"
        }
    ],
    "count": 1
}

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

小提示

有关演示如何分析这些响应的完整工作示例，请参阅 REST API 示例。

HTTP 方法和操作

Azure DevOps REST API 使用标准 HTTP 方法：

方法 用于... 示例：
GET 获取资源或资源列表 获取项目、工作项
POST 创建资源，或使用高级查询获取资源 创建工作项，查询工作项
PUT 创建或完全替换资源 创建/更新工作项
PATCH 更新资源的特定字段 更新工作项字段
DELETE 删除资源 删除工作项

小提示

有关每个包含完整代码示例的 HTTP 方法的实际示例，请参阅 REST API 示例。

请求头和内容

提供请求正文（通常为 POST、PUT 和 PATCH）时，请包含适当的标头：

Content-Type: application/json

要针对工作项进行 PATCH 操作，请使用：

Content-Type: application/json-patch+json

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)
}

响应代码

了解 HTTP 响应代码有助于正确处理 API 响应：

响应 含义 注释
200 成功 响应正文包含请求的数据
201 已创建 已成功创建资源
204 成功 无响应正文（常见于 DELETE）
400 错误的请求 参数或请求正文无效
401 未经 授权 身份验证失败或缺失
403 已禁止 用户操作权限不足
404 未找到 资源不存在或无权查看
409 冲突 请求与当前资源状态冲突

API 版本控制

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

准则

  • 对每个请求始终指定 API 版本（必需）
  • 将 API 版本的格式设置为：{major}.{minor} 或 {major}.{minor}-{stage}（例如，7.2, 7.2-preview）
  • 在可用时使用特定的预览版： 7.2-preview.17.2-preview.2
  • 在弃用预览 API 时升级到已发布版本

用法

将 API 版本指定为 URL 查询参数：

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

或在请求标头中：

Accept: application/json;api-version=7.2

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

更多资源

有关实际实现指南和完整的代码示例，请参阅：

后续步骤

试用 REST API 示例