REST API の概要

[アーティクル]
03/25/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

この記事で提供されている REST 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 の場合、instance次collection dev.azure.com/{organization} DefaultCollectionの例のようなパターンになります。

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) を指定する場合は、最初に Base64 文字列に変換する必要があります。次の例は、C# を使用して Base64 に変換する方法を示しています。その後、結果の文字列を HTTP ヘッダーとして形式で指定できます。

Authorization: Basic BASE64PATSTRING

次の例は、HttpClient クラスを使用する C# を示しています。

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 Services には、Microsoft Authentication Library (MSAL)、OAuth、セッショントークンなど、さまざまな認証メカニズムがあります。詳細については、シナリオに最適な認証ガイダンスを参照してください。

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": "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"
            },
            "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"
            },
            "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 で使用される一般的なパターンの詳細については、こちらをご覧ください。

HTTP 動詞

Verb	使用対象:...
GET	リソースまたはリソースの一覧を取得する
投稿	リソースを作成する、より高度なクエリを使用してリソースの一覧を取得する
PUT	リソースが存在しない場合は作成するか、存在する場合は更新します
PATCH	リソースの更新
DELETE	リソースの削除

要求ヘッダーと要求コンテンツ

要求本文 (通常は 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 プロキシでは、HTTP 動詞 GET と POST のみがサポートされますが、PATCH や DELETE などの最新の HTTP 動詞はサポートされない場合があります。呼び出しがこれらのプロキシのいずれかを通過する可能性がある場合は、POST メソッドを使用して実際の動詞を送信し、メソッドをオーバーライドするヘッダーを指定できます。たとえば、作業項目 (PATCH _apis/wit/workitems/3) を更新したいが、GET または POST のみを許可するプロキシを経由する必要がある場合があります。適切な動詞 (この場合は PATCH) を HTTP 要求ヘッダーパラメーターとして渡し、実際の HTTP メソッドとして POST を使用できます。

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	認証に失敗しました。多くの場合、この応答は、Authorization ヘッダーが見つからないか、形式が正しくないためです。
403	認証されたユーザーには、操作を実行するアクセス許可がありません。
404	リソースが存在しないか、認証されたユーザーに存在することを確認するアクセス許可がありません。
409	要求とサーバー上のデータの状態の間に競合があります。たとえば、pull request を送信しようとして、コミットに対するプル要求が既にある場合、応答コードは 409 です。

Azure DevOps Services では CORS がサポートされています。これにより、Azure DevOps Services REST API に対して Ajax 要求を行う以外dev.azure.com/*にメイン Do から提供される JavaScript コードが有効になります。各要求は資格情報を提供する必要があります (AT と 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 );
        });
    });

(個人用アクセストークンに置き換えます myPatToken )

バージョン管理

Azure DevOps REST API は、API の進化に伴ってアプリケーションとサービスが引き続き機能するようにバージョン管理されています。

ガイドライン

すべての要求で API バージョンを指定します (必須)。
API のバージョンを次のように書式設定します: {major}。{minor}-{stage}。{resource-version}。たとえば、1.0、1.1、1.2-preview、2.0 です。
プレビュー段階にある API の特定のリビジョンを指定するには、次のバージョン形式を使用します。 1.0-preview.11.0-preview.2 たとえば、API の 1.0 がリリースされた後、そのプレビューバージョン (1.0-プレビュー) は非推奨となり、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 のバージョン管理、サポートされているバージョンに関する説明を参照してください。

次の方法で共有

REST API の概要

Azure DevOps Services

Azure DevOps Server

応答

HTTP 動詞

要求ヘッダーと要求コンテンツ

HTTP メソッドのオーバーライド

応答コード

バージョン管理

ガイドライン

使用方法

サポートされているバージョン

フィードバック

フィードバック

その他のリソース

次の方法で共有

REST API の概要

Azure DevOps Services

Azure DevOps Server

応答

HTTP 動詞

要求ヘッダーと要求コンテンツ

HTTP メソッドのオーバーライド

応答コード

クロスオリジン リソース共有 (CORS)

バージョン管理

ガイドライン

使用方法

サポートされているバージョン

フィードバック

フィードバック

その他のリソース

クロスオリジンリソース共有 (CORS)