共用方式為

開始使用 REST API

Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022

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 識別碼 - 建議用於生產應用程式
  • 個人存取令牌 （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 取得資源或資源清單 取得專案、工作項目
郵件 建立資源，或使用進階查詢取得資源 建立工作項目、查詢工作專案
放置 建立或完全取代資源 建立/更新工作專案
補丁 更新資源的特定欄位 更新工作專案欄位
刪除 刪除資源 刪除工作專案

小提示

如需具有完整程式代碼範例之每個 HTTP 方法的實際範例，請參閱 REST API 範例。

要求標頭和內容

當您提供請求主體時（通常是 POST、PUT 和 PATCH），請包含適當的標頭：

Content-Type: application/json

針對工作專案的 PATCH 作業，請使用：

Content-Type: application/json-patch+json

HTTP 方法覆寫

某些 Web Proxy 可能只支援 HTTP 動詞 GET 和 POST，但不支援更現代化的 HTTP 動詞，例如 PATCH 和 DELETE。 如果您的呼叫可能通過其中一個代理伺服器，您可以使用 POST 方法傳送實際的 HTTP 動詞，並搭配標頭來覆蓋方法。 例如，您可能想要 更新工作專案 （PATCH _apis/wit/workitems/3），但您可能必須經過只允許 GET 或 POST 的 Proxy。 您可以將適當的動詞（在此案例中為 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.27.2-preview ）
  • 當可用時，請使用特定的預覽修訂： 7.2-preview.1、 7.2-preview.2
  • 當預覽 API 已被取代時升級至已發行的版本

用法

將 API 版本指定為網址查詢參數：

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

或在要求標頭中：

Accept: application/json;api-version=7.2

如需支援的版本，請參閱 REST API 版本控制。

更多資源

如需實際實作指引和完整的程式碼範例，請參閱：

後續步驟

試用 REST API 範例

  • Last updated on