Azure DevOps Services REST API リファレンス

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

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

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

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

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

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

1. 要求 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 のバージョンを確認してください。

2. HTTP 要求メッセージ ヘッダー フィールド:

   • 必須の HTTP メソッド (操作または動詞ともいう)。要求する操作の種類をサービスに通知します。 Azure REST API では、GET、HEAD、PUT、POST、PATCH の各メソッドがサポートされています。
   • 省略可能な追加ヘッダー フィールド。指定された URI および HTTP メソッドで必要です。 たとえば、要求のクライアント承認情報を含むベアラー トークンを提供する Authorization ヘッダーです。

3. 省略可能な HTTP 要求メッセージ本文のフィールド。URI および HTTP 操作をサポートするためのものです。 たとえば、POST 操作には、複合パラメーターとして渡される MIME でエンコードされたオブジェクトが含まれます。

   • POST または PUT 操作の場合は、本文の MIME エンコードの種類も Content-type 要求ヘッダーで指定する必要があります。 一部のサービスでは、application/json などの特定の MINE の種類を使用する必要があります。

4. HTTP 応答メッセージ ヘッダーのフィールド:

   • HTTP 状態コード。成功コードの 2xx から、エラー コードの 4xx または 5xx までの範囲です。 または、API のドキュメントに記載されているように、サービスで定義された状態コードが返されることもあります。
   • 省略可能な追加ヘッダー フィールド。要求の応答をサポートするために必要です (Content-type 応答ヘッダーなど)。

5. 省略可能な HTTP 応答メッセージ本文のフィールド:

   • MIME でエンコードされた応答オブジェクトは、データを返す GET メソッドからの応答など、HTTP 応答本文で返される場合があります。 通常、これらのオブジェクトは、Content-type 応答ヘッダーで示される、JSON や XML などの構造化された形式で返されます。 たとえば、Azure AD にアクセス トークンを要求すると、応答本文で要素として access_token 返されます。これは、データ コレクション内のいくつかの名前と値のペアのオブジェクトのいずれかです。 この例では、 の応答ヘッダー Content-Type: application/json も含まれています。

要求を作成する

認証

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

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

要求をアセンブルする

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 バージョンは、前述のサーバー バージョンとそれ以降のバージョンで動作します。

関連コンテンツ

REST API サンプルとユース ケースの 統合に関するドキュメント を参照してください。

• 認証ガイダンス
• サンプル

クライアント ライブラリ

これらの REST API のクライアント ライブラリを検出します。

• .NET の概念ドキュメント と .NET リファレンス ドキュメント
• Go
• Node.js
• Python
• Swagger 2.0
• Web 拡張機能 SDK

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

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

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