Azure DevOps REST API を使ってみよう
はじめに
この記事は、Azure DevOps Advent Calendar 2019 の23日目の記事です。 Azure DevOps REST API の入門記事です。Azure DevOps は既定で様々なサービスと連携することができるので、REST API を使う機会はまれかもしれませんが、知っておくと便利なこともあるかもしれません。（例えば、Azure DevOps にユーザーを追加するアプリをノンコーディングで作成することもできます。）
まとめ
- Azure DevOps には、REST API が提供されていて、この API を利用すると自作アプリから Azure DevOps 上のいろいろなサービスを利用することができる
- 最も簡単な認証方法は、PAT（Personal Access Token）を利用した基本認証
- もちろん、その他の様々な認証方式をサポートしている
- Fiddler や curl などから叩いて試すことができる（今回の記事の内容）
- C# から呼び出したいときは、このあたりのサンプルを参考にすればよい
Azure DevOps REST API を使う
PAT(Personal Access Token) を取得
API の認証で利用する PAT を取得します。
1. User settings のメニューを表示
- Azure DevOps のページで、自分のアイコンを選択する
- […] を選択する
- [User settings] を選択する
2. PAT を選択
表示されたメニューの中から、[Personal access tokens] を選択します。
3. [+ New Token] を選択する
Personal Access Tokens のページで、[+ New Token] を選択します。
4. トークン名、有効期間、スコープを選択してトークンを作成する
| 項目 | 説明 |
|---|---|
| Name | トークンの名前を入力します。 |
| Organization | トークンを作成する Azure DevOps の組織名を選択します。 |
| Expiration | トークンの有効期限を設定します。最長で1年間。トークンを作成した後、有効期限を伸ばすこともできます。 |
| Scopes | トークンの権限を指定します。今回は、Full access で実験しています。 |
5. 作成したトークンを保存しておく
作成したトークンをコピーして、保存しておきます。
REST API を呼び出す
取得した PAT をもとに、Fiddler で REST API を呼び出していきます。
- チームプロジェクトのリストを取得する
- プロジェクトのビルドのリストを取得する
- ビルドをキューに入れる
0. 注意事項
1. {organization} の値は？
Azure DevOps にアクセスしたときに表示される URL で dev.azure.com/{organization} に該当する部分です。例えば、以下のような URL のときは、azdevopsiscool がその値になります。
https://dev.azure.com/azdevopsiscool/
2. 基本認証で使うヘッダー値の生成
基本認証では、ユーザー名とパスワードを: でつなげて、Base64 エンコードして送信する必要があります。
Fiddler の [TextWizard] を利用すると Base64 エンコードした文字列を生成することができます。Fiddler で [Text Wizard] を選択します。
[Text Wizard] の上の部分に、[ユーザー名]:[Personal Access Token] の形式で文字列を入力します。なお、[ユーザー名] は、どんな名前でもかまいません。
[Text Wizard] に Base64 エンコードされた文字列が表示されるので、この値をコピーしておき、API を呼び出すときには、HTTP ヘッダーに値を設定して送信してください。（Authorization: Basic [Base64 エンコードした文字列]）
1. チームプロジェクトのリストを取得する
以下の API を利用して、自分の組織内のプロジェクトのリストを取得します。
Fiddler の [Composer] でリクエストURL、基本認証の HTTP ヘッダー値を設定して、[Execute] ボタンを押します。
Azure DevOps にあるプロジェクトのリストが JSON で返却されていることが分かります。
2. プロジェクトのビルドのリストを取得する
次は、プロジェクト内のビルドのリストを取得する API を呼び出します。
API のリファレンスには、{project} の値が必要であることが記載されています。
GET https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=5.1
{project} の値は、プロジェクト ID かプロジェクト名です。先ほど、プロジェクトのリストを取得する API を呼び出しましたが、そのレスポンス JSON の中にプロジェクト ID を見つけることができます。
図の例では、2b518d54-7469-496a-aef3-c5a6b4addca5 という GUID 値になります。
{project} の値を利用して、Fiddler の [Composer] からリクエストを送ります。
プロジェクトに定義されているビルドのリストが JSON で返却されることが分かります。
3. ビルドをキューに入れる
最後に、プロジェクトに定義されているビルドをキューに入れて、Azure DevOps で自動ビルドを行う API を呼び出します。
この API は、POST リクエストを送る必要があります。API リファレンスを見ると、多くのパラメータが必要なように思われますが、リクエストの Body 野中にビルド定義の ID を含めて送れば、ビルドをキューに入れることができます。 なお、ビルド定義の ID は、ビルドのリストを取得する API を呼び出したときのレスポンスの中に含まれています。
この ID 値を利用して、ビルドをキューに入れる API を呼び出します。リクエストヘッダで Content-Type: application/json を指定し、リクエストの Body に JSON で { "definition": { "id": [ビルド定義の ID] } } を設定する必要があります。
API を呼び出すと、Azure DevOps 上でビルドが開始されます。
