Azure Pipelines から Azure REST API を叩く

どうも、よこけんです。
最近 Azure Pipelines で遊んでいるのですが、Azure REST API を叩く方法がわかりづらかったので簡単にまとめてみました。

Azure Pipelines から REST API を叩く方法あれこれ

Azure Pipelines から REST API を叩く方法は色々あります。
主な方法は下記の４種類です。

• InvokeRESTAPI タスクを使う
• AzureCLI タスクで az rest コマンドを叩く
• PowerShell タスクで Invoke-RestMethod コマンドを叩く
• bash タスクで curl コマンドを叩く

InvokeRESTAPI タスクと AzureCLI タスクはお勧めしません。これらは機能的にバイナリファイルの POST ができません¹ので不完全です。また、InvokeRESTAPI はエージェントレスジョブでしか使えないなど制限が非常に厳しいですし、AzureCLI タスクはサービス接続を別途 (無駄に) 用意する必要があり煩雑です。

実用レベルなのは PowerShell タスクと bash タスクになりますが、本記事では PowerShell タスクについて紹介しようと思います。

Azure Pipelines から Azure REST API を叩く

例として、Pull Request の一覧を取得する Azure REST API を叩いてみます。

jobs:
- job: temp
  pool:
    vmImage: ubuntu-latest
  # variables:
  #   System.Debug: true
  steps:
  - powershell: |
      Invoke-RestMethod `
        -Method get `
        -Uri $(System.CollectionUri)_apis/git/repositories/$(Build.Repository.ID)/pullrequests?api-version=5.1-preview.1 `
        -Headers @{
          "Authorization" = "Bearer $(System.AccessToken)";
        } `
        -TimeoutSec 60

定義済み変数が色々用意されていますので活用しましょう。
私の環境では、Uri は https://dev.azure.com/moromoro-sample/_apis/git/repositories/8bf6fb38-5007-4819-a26b-7f73dacb5295/pullrequests?api-version=5.1-preview.1 として展開されます。
ちなみに５行目と６行目のコメントを外すことで、展開された Uri がパイプラインのログに出力されるようになります。

Authorization ヘッダーにで使用している System.AccessToken 変数には、パイプライン実行用ユーザーのアクセストークンが格納されています。
パイプライン実行ユーザーの権限は若干制限されており、例えば Pull Request にファイルを添付するなどの Azure REST API を叩くと権限エラーになります。
パイプライン実行ユーザーの権限はプロジェクト設定にて行えます。例えば Pull Request への書き込み権限は下記の手順で付加できます。

1. [Project settings] - [Repos] - [Repositories] を開く。
2. [Git Repositories] を選択し、[Azure DevOps Groups] の下の [Users] に含まれている [{プロジェクト名} Build Service ({組織名})] ユーザーを選択する。
3. [Contribute to pull requests] を "Allow" に設定する。

TimeoutSec は、既定では15秒に設定されていますが、時々タイムアウトになることがあるので60秒に増やしてあります。

この例では使用しませんでしたが、Invoke-RestApi コマンドでは InFile パラメータで POST するファイルを指定したり、OutFile パラメータでレスポンスを書き込むファイルを指定することもできます。

終わりに

私は色々と回り道 (特にアクセストークン周りと冒頭のバイナリファイルの POST の件で) したので中々苦労しましたが、やり方さえわかってしまえば Azure Pipelines から Azure REST API を叩くのはとても簡単です。

Azure REST API を使うことで Pull Request や Work Item の操作など色々なことができますので、CI/CD の可能性が広がると思います。
ちなみに私の場合、Pull Request をトリガーとするパイプラインでマージ前後のスナップショット画像の Diff を取っていたので、それを Pull Request に添付し更に Pull Request 内にそのリンクを張り付けたコメントスレッドを作成する、という処理を Azure REST API を利用して仕込みました。これに加え、コメントスレッドのステータスが Resolved にならないと Pull Request を完了できないようにリポジトリを設定しておくことで、Diff を見逃すことなくしっかりレビューできるようになります。

本記事が皆様の CI/CD の可能性を広げることに少しでも貢献できればなと思います。

参考

• Get started with the REST APIs for Azure DevOps Services and Team Foundation Server - Azure DevOps Services REST API | Microsoft Docs
• Invoke-RestMethod
• Predefined variables - Azure Pipelines | Microsoft Docs

1. AzureCLI はファイルを読み取って POST する機能を持ってはいるのですが、バイナリファイルを POST しようとすると Base64 Binary でエンコードされてしまうようです。 ↩