Azure DevOps Services REST API リファレンス

[アーティクル]
08/24/2023

Azure DevOps Services/Azure DevOps Server REST API リファレンスへようこそ。

Representational State Transfer (REST) API は、一連の HTTP 操作 (メソッド) をサポートするサービスエンドポイントであり、サービスのリソースに関する作成、取得、更新、削除アクセスが提供されます。この記事で説明する内容は次のとおりです。

REST API の要求と応答のペアの基本的なコンポーネント。
REST 要求の作成と送信と応答の処理の概要。

ほとんどの REST API には、クライアントライブラリを使用してアクセスできます。これは、クライアントコードを大幅に簡略化するために使用できます。

REST API 要求/応答ペアのコンポーネント

REST API の要求/応答ペアは、次の 5 つのコンポーネントに分けることができます。

要求 URI を次の形式で指定します。VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}
- instance: 要求を送信するAzure DevOps Services organizationまたは 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 へのバージョンマッピングマトリックスを確認して、TFS のバージョンに適用される REST API のバージョンを確認してください。
HTTP 要求メッセージヘッダー フィールド:
- 必須の HTTP メソッド (操作または動詞ともいう)。要求する操作の種類をサービスに通知します。 Azure REST API では、GET、HEAD、PUT、POST、PATCH の各メソッドがサポートされています。
- 省略可能な追加ヘッダーフィールド。指定された URI および HTTP メソッドで必要です。たとえば、要求のクライアント承認情報を含むベアラートークンを提供する Authorization ヘッダーです。
省略可能な HTTP 要求メッセージ本文のフィールド。URI および HTTP 操作をサポートするためのものです。たとえば、POST 操作には、複合パラメーターとして渡される MIME でエンコードされたオブジェクトが含まれます。
- POST または PUT 操作の場合は、本文の MIME エンコードの種類も Content-type 要求ヘッダーで指定する必要があります。一部のサービスでは、application/json などの特定の MINE の種類を使用する必要があります。
HTTP 応答メッセージヘッダーのフィールド:
- HTTP 状態コード。成功コードの 2xx から、エラーコードの 4xx または 5xx までの範囲です。または、API のドキュメントに記載されているように、サービスで定義された状態コードが返されることもあります。
- 省略可能な追加ヘッダーフィールド。要求の応答をサポートするために必要です (Content-type 応答ヘッダーなど)。
省略可能な HTTP 応答メッセージ本文のフィールド:
- MIME でエンコードされた応答オブジェクトは、データを返す GET メソッドからの応答など、HTTP 応答本文で返される場合があります。通常、これらのオブジェクトは、Content-type 応答ヘッダーで示される、JSON や XML などの構造化された形式で返されます。たとえば、Azure AD にアクセストークンを要求すると、応答本文で要素として access_token 返されます。これは、データコレクション内のいくつかの名前と値のペアのオブジェクトのいずれかです。この例では、の応答ヘッダー Content-Type: application/json も含まれています。

要求を作成する

認証

Azure DevOps Servicesまたは TFS を使用してアプリケーションまたはサービスを認証するには、さまざまな方法があります。次の表は、最適な方法を決定する優れた方法です。

アプリケーションの種類	説明	例	認証メカニズム	コードサンプル
対話型クライアント側	ユーザー操作を可能にするクライアントアプリケーションAzure DevOps Services REST API を呼び出す	organization内のプロジェクトを列挙するコンソールアプリケーション	Microsoft Authentication Library (MSAL)	sample
対話型 JavaScript	GUI ベースの JavaScript アプリケーション	ユーザーのプロジェクト情報を表示する AngularJS シングルページアプリ	MSAL	sample
非対話型クライアント側	ヘッドレステキストのみのクライアント側アプリケーション	ユーザーに割り当てられたすべてのバグを表示するコンソールアプリ	デバイスプロファイル	sample
対話型 Web	GUI ベースの Web アプリケーション	ビルドの概要を表示するカスタム Web ダッシュボード	OAuth	sample
TFS アプリケーション	クライアント OM ライブラリを使用した TFS アプリ	チームバグダッシュボードを表示する TFS 拡張機能	クライアントライブラリ	sample
Azure DevOps Services拡張機能	Azure DevOps Services拡張機能	Azure DevOps 拡張機能のサンプル	VSS Web 拡張機能 SDK	サンプルチュートリアル

メモ： 認証の詳細については、認証ガイダンスページを参照してください。

要求をアセンブルする

Azure DevOps Services

Azure DevOps Servicesの場合、instance は dev.azure.com/{organization}であるため、パターンは次のようになります。

VERB https://dev.azure.com/{organization}/_apis[/{area}]/{resource}?api-version={version}

たとえば、Azure DevOps Services organizationでチームプロジェクトの一覧を取得する方法を次に示します。

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

このサイトのほとんどのサンプルでは、サービスで認証するためのコンパクトな例であるため、個人用アクセストークンを使用します。ただし、MSAL、OAuth、セッショントークンなど、Azure DevOps Servicesで使用できるさまざまな認証メカニズムがあります。シナリオに最適なガイダンスについては、「認証」セクションを参照してください。

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 など、いくつかの例外があります。

これで、作業項目の追跡や Git などの特定の API 領域を調べ、必要なリソースにアクセスできるようになります。これらの 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 のクライアントライブラリを検出します。

以前のバージョンの REST API はどこにありますか? (4.1 より前)

私たちは最近、エンジニアリングシステムとドキュメント生成プロセスを変更しました。この変更を行い、これらの REST API を使用しようとしているすべてのユーザーに対して、より明確で詳細で正確なドキュメントを提供しました。技術的な制約により、このメソッドを使用して API バージョン 4.1 以降 を文書化することしかできません。この変更により、API バージョン 4.1 以降のドキュメントの方が使いやすくなります。

TFS で作業している場合、または以前のバージョンの REST API を探している場合は、「 TFS 2015、2017、2018 の REST API の概要」を参照してください。

Azure DevOps Services REST API リファレンス

REST API 要求/応答ペアのコンポーネント

要求を作成する

認証

要求をアセンブルする

応答の処理

API と TFS のバージョン マッピング

関連コンテンツ

クライアント ライブラリ

以前のバージョンの REST API はどこにありますか? (4.1 より前)

その他のリソース

API と TFS のバージョンマッピング

クライアントライブラリ