こんにちは。CData Software Japan リードエンジニアの杉本です。
今日はプロジェクト管理のクラウドサービスとして有名なbacklog の API の使い方を解説したいと思います。
CData Driver での Backlog 利用方法は以下のリンクからどうぞ。
backlog とは？
backlogはウェブ制作、ソフトウェア開発、大手広告代理店、全国版新聞社など様々な業種で使われているプロジェクト管理ツールです。
プロジェクトの管理のための重要な機能が一通り揃っているのが魅力的で、例えばガントチャートを自動的に生成してくれたり
プロジェクトでのファイル共有機能もあります。
またそれらの機能を扱うための100種類以上ある高機能なAPIが公開されているのが素晴らしいです。ほとんどの操作がAPIで完結できるのではないかと思います。
https://developer.nulab.com/ja/docs/backlog/
使い方
それでは API の使い方を解説していきます。
ちなみに記事の後半では API テストツールの Postman で実行する方法を紹介していますが、以下の記事では backlog のすべてのリクエストをまとめたPostman Collection を公開しているので、併せて参考にしてみてください。
基本概要
backlog API は RESTベースアーキテクチャのAPIです。ベースURLとリソースの指定、「GET」・「POST」・「PATCH」「DELETE」のパラメータを利用してリクエストします。
https://{baseurl}/api/v2/{resource}
課題を取得する場合のリクエスト例
GET https://cdataa.backlog.com/api/v2/issues?apiKey=XXXXXX&count=10&offset=0
フィルターやページネーションのためのクエリ記法はURLの「クエリパラメータ」、データを登録する時のContent-Typeは「application/x-www-form-urlencoded」です。
なお、ファイルアップロード時のみ「multipart/form-data」を利用します。
ベースURL
backlog を使う上で一つ注意したいのが、ベースのURLです。URLは「.jp」と「.com」の2種類存在するようです。
<!-- .jp type --> https://xx.backlog.jp/api/v2/
<!-- .com type --> https://xx.backlog.com/api/v2/
なお、backlog にはオンプレミス版も提供されていますが、API Reference にオンプレミス版に関する記載はありませんでしたのでちょっと詳細はわかりません。
認証方式
backlog API では2種類の認証と認可の方法を提供しています。
一つはユーザー毎に発行されたAPI Keyを利用する方法、もう一つは OAuth 2.0を用いて、API Tokenを取得して、利用する方法です。
API Key
API Keyはユーザーの設定画面から取得し、クエリパラメータに指定することで認証されます。
API Keyはbacklogの個人設定から取得できます。
まず、backlog にログインし「個人設定」に移動します。
設定画面のメニューから「API」を選択し、任意のメモを入力して「登録」をクリックします。
登録をクリック後、以下のようにAPI Keyが生成されるので、これを後ほど利用します。
API Key の例：vFJBXQqqEO4n2erfbIZ1dwH0DkVokAzxj99WKTfV5Rg5XvLM5BMHORShf4Vp1VmU
※このAPI Key は既に削除済みです。各自の環境から取得してください。
このAPI KeyはURLクエリパラメータに指定することで利用できます。なお、GET以外、POSTやPATCHなどのメソッドの場合でも変わりありません。
https://XXXX.backlog.com/api/v2/issues?apiKey=XXXXXX
OAuth 2.0
backlog の OAuth 2.0 は現在 Authorization Code Grant のみサポートしています。AuthURLでログイン後、コールバックURLに認可コードが付与された状態で返ってくるので、それを利用してTokenを取得します。
OAuth 2.0 のアプリ登録・ClientID・Client Secretの取得は以下のページから行います。
https://backlog.com/developer/applications/
アプリケーションの登録から、任意のリダイレクトURIとアプリケーション名などを指定し、作成します。
アプリ登録後、以下のようなClientIdとClientSecretを取得できます。（削除済み）
Client Id：NfCay3OoRSdUOZRbZeGppN0KOAdYqQ8J
Client Secret：c3WkPgFpoeAkg38PhSIwoYgAgUby6J4q9W4fqyhSWWC8flLPveDyc5FMqhMlM05u
認可リクエストは「https://{YOUR_ORGANIZATION_URI}/OAuth2AccessRequest.action」に対して、それぞれのクエリパラメータを付与して、行います。
この時、「/api/v2」は使用しない点と、RedirectURIをURLエンコードする点に注意しましょう。
GET https://{YOUR_ORGANIZATION_URI}/OAuth2AccessRequest.action?response_type=code&client_id={YOUR_CLIENT_ID}&redirect_uri={YOUR_REDIRECT_URI}&state={YOUR_STATE}
上記アプリを元にした場合、以下のようなリクエストになります。
GET https://sample.backlog.com/OAuth2AccessRequest.action?response_type=code&client_id=NfCay3OoRSdUOZRbZeGppN0KOAdYqQ8J&redirect_uri=https%3A%2F%2Flocalhost%3A33333&state=12345
上記URLにアクセスすると、ログインおよび認可画面が表示されるので、許可を実施します。
すると、以下のように認可コードがリダイレクトURIに返却されます。
https://localhost:33333/?code=DKXizkXm7WEbujktNuPGn2zjg1EA6xShJhRibzrIUrybXw9MSEDx8vm0bAV0CKdj&state=12345
あとは、Tokenをリクエストします。
パラメータのContentTypeは「application/x-www-form-urlencoded」で以下のパラメータを指定します。
- grant_type：値は”authorization_code”で固定
- code：AuthURLからリダイレクトされたURIに付与してある認可コードを指定
- redirect_uri：OAuthアプリ登録したRedirectURI（例：https://localhost:33333/）
- client_id：アプリのClient ID（例：NfCay3OoRSdUOZRbZeGppN0KOAdYqQ8J）
- client_secret ：アプリのClientSecret（例：c3WkPgFpoeAkg38PhSIwoYgAgUby6J4q9W4fqyhSWWC8flLPveDyc5FMqhMlM05u）
実際のリクエスト例は以下のとおりです。
POST /api/v2/oauth2/token HTTP/1.1 Host: XXXXX.backlog.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=DKXizkXm7WEbujktNuPGn2zjg1EA6xShJhRibzrIUrybXw9MSEDx8vm0bAV0CKdj&redirect_uri=https://localhost:33333&client_id=NfCay3OoRSdUOZRbZeGppN0KOAdYqQ8J&client_secret=c3WkPgFpoeAkg38PhSIwoYgAgUby6J4q9W4fqyhSWWC8flLPveDyc5FMqhMlM05u
あとは、Authorization ヘッダーにBearer {AccessToken}を指定することでリクエストできます。
GET /api/v2/issues HTTP/1.1 Host: XXXX.backlog.com Authorization: Bearer 2seZwVtep9MhhjL6EiTd8WDRcHQ0jpa7Q6c7o9qQsq3zcZEwxYzyZV7Zb0wF8GFz
Postman から実行する
それでは Postman から実行してみたいと思います。
とりあえず一番利用するであろう「課題一覧の取得」を実行してみます。
リクエストはシンプルに「/api/v2/issues」とApiKeyをクエリパラメータに指定するだけで、課題の一覧が取得できます。
GET /api/v2/issues?apiKey=XXXXXX HTTP/1.1 Host: XXXX.backlog.com
リスト取得時のパラメータ指定方法
フィルターなどを実行する場合はURLクエリパラメータで指定を行います。
利用できるクエリはリソース毎に異なるので注意しましょう。例えば、課題一覧の場合は以下のようにKeywordで検索できます。
GET /api/v2/issues?apiKey=XXXXX&keyword=デザイン HTTP/1.1 Host: XXXXX.backlog.com
また、複数値を検索可能な「projectId」などのパラメータがありますが、この指定は若干特殊です。
複数のプロジェクトを対象として絞り込む場合は「projectId=81609&projectId=81608」のように指定します。私がよく勘違いするのですが「projectId=81609,81608」ではリクエストが失敗します。
GET /api/v2/issues?apiKey=XXXXX&projectId[]=81609&projectId[]=81608 HTTP/1.1 Host: XXXXX.backlog.com
ページネーション
ページネーションはクエリパラメータで「count（取得したい件数：デフォルト20件・最大100件）」「offset」で指定します。
ページネーションはできるリソースとできないリソースがあり、指定が無い場合はデフォルトで全件取得するようです。
例えば課題の1件目～100件目を取得する場合は、以下のようにリクエストし
GET /api/v2/issues?apiKey=XXXXX&count=100&offset=1 HTTP/1.1 Host: XXXX.backlog.com
101件目以降を取得する場合は、「offset」を101に指定します。
GET /api/v2/issues?apiKey=XXXXX&count=100&offset=101 HTTP/1.1 Host: XXXX.backlog.com
なお、件数は専用のcountリソースを利用します。ページネーションが利用できるリソースはこの機能が提供されているようです。
GET /api/v2/issues/count?apiKey=XXXXXHTTP/1.1 Host: XXXXX.backlog.com
データ登録時のパラメータ指定方法（課題の作成）
データ登録には「POST」メソッドでパラメータを「application/x-www-form-urlencoded」で指定しリクエストします。
例えば課題作成では以下のようにリクエストを実施します。
POST /api/v2/issues?apiKey=XXXXX HTTP/1.1 Host: XXXXX.backlog.com Content-Type: application/x-www-form-urlencoded projectId=81609&summary=New Task&issueTypeId=381203&priorityId=3
最低限 projectId、 issueTypeId 、 properotyIdを知っておく必要があります。プロジェクト一覧の取得・優先度一覧の取得 ・種別一覧の取得から把握しておきましょう
プログラムから実行する
最後に .NET Core / RestSharp を使って、リクエストしてみたいと思います。PostmanのCode Snippetを利用して、リクエストのためのコードを取得します。
なお、課題を格納するクラスは以下のURLで公開しています。（JSONペーストを利用しただけなので、あまり信用しないでください）
https://gist.github.com/sugimomoto/032a91b739163d60441b77cfb16a2060
おわりに
backlog API は比較的シンプルなAPIなので、使いやすい部類に入るかと思います。ただ、機能の数が多いのと、それぞれのIDを事前に把握しておく必要があったりするので、その辺は注意する必要があるかなと思います。
