Azure DevOps Services REST API 參考

歡迎使用 Azure DevOps Services/Azure DevOps Server REST API 參考。

具象狀態傳輸 (REST) API 是支援一組 HTTP 作業 (方法) 的服務端點，提供服務資源的建立、擷取、更新或刪除存取權限。 本文將引導您：

• REST API 要求/回應組的基本元件。
• 建立和傳送 REST 要求的概觀，以及處理回應。

大部分的 REST API 都可透過 我們的用戶端程式庫存取，可用來大幅簡化您的用戶端程式代碼。

REST API 要求/回應組的元件

REST API 要求/回應配對可分成五個元件：

1. 要求 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 ，但可以是任何集合)
   • 資源路徑：資源路徑如下： _apis/{area}/{resource} 。 例如 _apis/wit/workitems。
   • api-version：每個 API 要求都應該包含 API 版本，以避免隨著 API 演進而中斷您的應用程式或服務。 api-versions 的格式如下：，例如： {major}.{minor}[-{stage}[.{resource-version}]]
     • api-version=1.0
     • api-version=1.2-preview
     • api-version=2.0-preview.1

   注意： 區域 和 小組專案 是選擇性的，視 API 要求而定。 請查看下方 的 TFS 與 REST API 版本對應矩陣 ，以找出哪些 REST API 版本適用于您的 TFS 版本。

2. HTTP 要求訊息標頭 欄位：

   • 必要的 HTTP 方法 (也稱為作業或動詞)，這會告知服務所要求的作業類型。 Azure REST API 支援 GET、HEAD、PUT、POST 和 PATCH 方法。
   • 指定的 URI 和 HTTP 方法所需的其他選擇性標頭欄位。 例如，提供持有人權杖的授權標頭，其中包含要求的用戶端授權資訊。

3. 選擇性的 HTTP 要求訊息主體欄位，以支援 URI 和 HTTP 作業。 例如，POST 作業包含當作複雜參數傳遞的 MIME 編碼物件。

   • 針對 POST 或 PUT 作業，本文的 MIME 編碼類型也應該在內容類型要求標頭中指定。 某些服務要求您使用特定 MIME 類型，例如 application/json。

4. HTTP 回應訊息標頭欄位：

   • HTTP 狀態碼，範圍可介於 2xx 成功碼到 4xx 或 5xx 錯誤碼之間。 或者，可能會傳回服務定義的狀態碼，如 API 文件中所示。
   • 支援要求回應所需的其他選擇性標頭欄位，例如 Content-type 回應標頭。

5. 選擇性的 HTTP 回應訊息主體欄位：

   • MIME 編碼的回應物件可能會在 HTTP 回應本文中傳回，例如來自傳回資料的 GET 方法的回應。 一般而言，這些物件會以 JSON 或 XML 等結構化格式傳回，如 Content-type 回應標頭所示。 例如，當您向 Azure AD 要求存取權杖時，它會在回應本文中當做 access_token 元素傳回，這是資料收集中數個名稱/值配對物件的其中一個。 在此範例中，也會包含 的 Content-Type: application/json 回應標頭。

建立要求

Authenticate

有許多方式可以使用 Azure DevOps Services 或 TFS 來驗證您的應用程式或服務。 下表是決定哪一種方法最適合您的絕佳方式：

應用程式類型	Description	範例	驗證機制	程式碼範例
互動式用戶端	用戶端應用程式，可讓使用者互動、呼叫Azure DevOps Services REST API	主控台應用程式列舉組織中的專案	Microsoft Authentication Library (MSAL)	樣品
互動式 JavaScript	以 GUI 為基礎的 JavaScript 應用程式	AngularJS 單頁應用程式，顯示使用者的專案資訊	MSAL	樣品
非互動式用戶端	僅限無前端文字用戶端應用程式	顯示指派給使用者之所有 Bug 的主控台應用程式	裝置設定檔	樣品
互動式 Web	GUI 型 Web 應用程式	顯示組建摘要的自訂 Web 儀表板	OAuth	樣品
TFS 應用程式	使用用戶端 OM 程式庫的 TFS 應用程式	顯示小組 Bug 儀表板的 TFS 擴充功能	用戶端程式庫	樣品
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。

現在您應該能夠查看特定 API 區域，例如 工作專案追蹤 或 Git ，並取得您需要的資源。 請繼續閱讀，以深入瞭解這些 API 中使用的一般模式。

API 和 TFS 版本對應

您可以在下方找到 REST API 版本的快速對應及其對應的 TFS 版本。 所有 API 版本都會在提及的伺服器版本和更新版本上運作。

TFS 版本	REST API 版本	組建版本
Azure DevOps Server vNext	7.1
Azure DevOps Server 2022	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 的用戶端程式庫。

• .NET 概念檔 與 .NET 參考檔
• Go
• Node.js
• Python
• Swagger 2.0
• Web Extensions SDK

舊版 REST API 在哪裡？ (4.1 之前)

我們最近對工程系統和檔產生程式進行了變更;我們已進行這項變更，為嘗試使用這些 REST API 的每個人提供更清楚、更深入且更精確的檔。 由於技術限制，我們只能使用此方法來記錄 API 4.1 版和更新版本 。 我們相信 API 4.1 版和更新版本的檔會因為這項變更而更容易使用。

如果您正在 TFS 中工作，或正在尋找舊版 REST API，您可以查看 TFS 2015、2017 和 2018 的 REST API 概觀。