REST API を使い始める

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}

Azure DevOps Services

Azure DevOps Services の場合、 instance は dev.azure.com/{organization} され、 collection は 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) を指定する場合は、まず PAT にコロンを付加します。 次に、コロンと PAT の連結を Base64 文字列に変換します。 次の例は、C# を使用して Base64 に変換する方法を示しています。 結果の文字列は、HTTP ヘッダーとして次の形式で指定できます。

Authorization: Basic BASE64COLONANDPATSTRING

次の例は、 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());
    }
}

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

これで、作業項目の追跡や Git などの特定の API 領域を確認し、必要なリソースを取得できます。 これらの API で使用される一般的なパターンの詳細については、こちらをご覧ください。

HTTP 動詞

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

要求本文 (通常は 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)
}

応答コード

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

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

バージョン管理

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.1、 1.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 のバージョン管理、サポートされているバージョンに関する説明を参照してください。