Azure DevOps Services |Azure DevOps Server 2022 - Azure DevOps Server 2019
使用本文提供的 REST API，將您的應用程式與 Azure DevOps 整合。 這些 API 可讓您以程式設計方式與服務互動，讓您自動化工作流程、與其他系統整合，以及擴充 Azure DevOps 的功能。
API 遵循一般模式，如下列範例所示：
VERB https://{instance}/{collection}/{team-project}/_apis/{area}/{resource}?api-version={version}
小提示
隨著 API 的發展，建議您在每個要求中包含 API 版本。 這種做法可協助您避免 API 中可能會中斷的非預期變更。
Azure DevOps Services
針對 Azure DevOps Services，#D0 是 #D1 且 #D2 是 #C3，因此模式如下例所示：
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 標頭提供個人存取令牌 （PAT），請先在 PAT 前面加上冒號。 然後，將冒號和 PAT 的串連轉換成 Base64 字串。 下列範例示範如何使用 C# 轉換成 Base64。 然後，產生的字串就可以以 HTTP 標頭的形式提供：
Authorization: Basic BASE64COLONANDPATSTRING
備註
在 PAT 之前包含冒號，以避免驗證錯誤。
使用 C# 的以下範例展示了 HttpClient 類別：
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 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
這些範例使用 PAT，這要求您 建立一個 PAT。
反應
您應該會收到類似以下範例的回應：
{
"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",
"collection": {
"id": "00000000-0000-0000-0000-000000000000",
"name": "DefaultCollection",
"url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/00000000-0000-0000-0000-000000000000",
"collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
},
"defaultTeam": {
"id": "00000000-0000-0000-0000-000000000000",
"name": "Fabrikam-Fiber-TFVCTeam",
"url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000/teams/00000000-0000-0000-0000-000000000000"
}
},
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "Fabrikam-Fiber-Git",
"url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
"description": "Gitprojects",
"collection": {
"id": "00000000-0000-0000-0000-000000000000",
"name": "DefaultCollection",
"url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/00000000-0000-0000-0000-000000000000",
"collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
},
"defaultTeam": {
"id": "00000000-0000-0000-0000-000000000000",
"name": "Fabrikam-Fiber-GitTeam",
"url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000/teams/00000000-0000-0000-0000-000000000000"
}
}
],
"count": 2
}
回應是 JSON，這通常是您從 REST API 取得的結果，但也有一些例外，例如 Git blob。
現在，您可以查看特定的 API 區域，例如工作項目追蹤或 Git，並獲取所需的資源。 繼續閱讀以深入了解這些 API 中使用的一般模式。
HTTP 動詞
| 動詞 | 用於... |
|---|---|
| GET | 取得資源或資源清單 |
| 郵件 | 建立資源、使用更進階的查詢取得資源清單 |
| 放置 | 如果資源不存在，則創建；如果存在，則更新。 |
| 補丁 | 更新資源 |
| 刪除 | 刪除資源 |
請求標頭和請求內容
當您提供請求主體時（通常使用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 Proxy 可能只支援 HTTP 動詞 GET 和 POST，但不支援更現代化的 HTTP 動詞，例如 PATCH 和 DELETE。 如果您的呼叫可能通過其中一個代理伺服器，您可以使用 POST 方法傳送實際的 HTTP 動詞，並搭配標頭來覆蓋方法。 例如，您可能想要 #B0 更新工作項目 #C1 (#A2)，但您可能必須經過只允許 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，允許從非 dev.azure.com/* 網域提供的 JavaScript 程式碼對 Azure DevOps Services 的 REST API 提出 Ajax 要求。 每個要求都必須提供認證（PAT 和 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 );
});
});
以 PAT 取代 myPatToken。
版本控制
Azure DevOps REST API 已建立版本，以確保應用程式和服務會隨著 API 的發展而繼續運作。
指導方針
- 為每個請求指定 API 版本（必要）。
- 格式化 API 版本，如下所示： {major}。{minor}-{stage}。{resource-version}。 例如，、
1.01.1、、。1.2-preview2.0 - 在預覽時使用下列版本格式來指定 API 的特定修訂：
1.0-preview.1、1.0-preview.2。 在發行 API 後 (以 1.0 為例)，其預覽版本 (1.0-preview) 將被取代並可在 12 週後停用。 - 升級至已發行的 API 版本。 停用預覽 API 之後，指定
-preview版本的要求就會遭到拒絕。
用法
在 HTTP 要求的標頭中指定 API 版本，或指定為 URL 查詢參數。
HTTP 要求標頭：
Accept: application/json;api-version=1.0
查詢參數：
GET https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version=1.0
支援的版本
如需支援版本的資訊，請參閱 REST API 版本、支援的版本。