CData Software Blog

クラウド連携のCData Software の技術ブログです。

プロジェクト管理ツール backlog の API の使い方

こんにちは。CData Software Japan リードエンジニアの杉本です。

今日はプロジェクト管理のクラウドサービスとして有名なbacklog の API の使い方を解説したいと思います。

CData Driver での Backlog 利用方法は以下のリンクからどうぞ。

www.cdatablog.jp

www.cdatablog.jp

backlog とは?

backlogはウェブ制作、ソフトウェア開発、大手広告代理店、全国版新聞社など様々な業種で使われているプロジェクト管理ツールです。

f:id:sugimomoto:20191224113044p:plain

プロジェクトの管理のための重要な機能が一通り揃っているのが魅力的で、例えばガントチャートを自動的に生成してくれたり

f:id:sugimomoto:20191224113052p:plain

Markdownで記述できるWiki

f:id:sugimomoto:20191224113057p:plain

プロジェクトでのファイル共有機能もあります。

f:id:sugimomoto:20191224113107p:plain

またそれらの機能を扱うための100種類以上ある高機能なAPIが公開されているのが素晴らしいです。ほとんどの操作がAPIで完結できるのではないかと思います。

https://developer.nulab.com/ja/docs/backlog/

f:id:sugimomoto:20191224113116p:plain

使い方

それでは API の使い方を解説していきます。

ちなみに記事の後半では API テストツールの Postman で実行する方法を紹介していますが、以下の記事では backlog のすべてのリクエストをまとめたPostman Collection を公開しているので、併せて参考にしてみてください。

www.cdatablog.jp

基本概要

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」を利用します。

developer.nulab.com

ベース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.com

認証方式

backlog API では2種類の認証と認可の方法を提供しています。

一つはユーザー毎に発行されたAPI Keyを利用する方法、もう一つは OAuth 2.0を用いて、API Tokenを取得して、利用する方法です。

developer.nulab.com

API Key

API Keyはユーザーの設定画面から取得し、クエリパラメータに指定することで認証されます。

API Keyはbacklogの個人設定から取得できます。

まず、backlog にログインし「個人設定」に移動します。

f:id:sugimomoto:20191224113140p:plain

設定画面のメニューから「API」を選択し、任意のメモを入力して「登録」をクリックします。

f:id:sugimomoto:20191224113146p:plain

登録をクリック後、以下のようにAPI Keyが生成されるので、これを後ほど利用します。

f:id:sugimomoto:20191224113153p:plain

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/

f:id:sugimomoto:20200510113309p:plain

アプリケーションの登録から、任意のリダイレクトURIとアプリケーション名などを指定し、作成します。

f:id:sugimomoto:20200510113315p:plain

アプリ登録後、以下のようなClientIdとClientSecretを取得できます。(削除済み)

  • Client Id:NfCay3OoRSdUOZRbZeGppN0KOAdYqQ8J

  • Client Secret:c3WkPgFpoeAkg38PhSIwoYgAgUby6J4q9W4fqyhSWWC8flLPveDyc5FMqhMlM05u

f:id:sugimomoto:20200510113324p:plain

認可リクエストは「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にアクセスすると、ログインおよび認可画面が表示されるので、許可を実施します。

f:id:sugimomoto:20200510113330p:plain

すると、以下のように認可コードがリダイレクトURIに返却されます。

https://localhost:33333/?code=DKXizkXm7WEbujktNuPGn2zjg1EA6xShJhRibzrIUrybXw9MSEDx8vm0bAV0CKdj&state=12345

あとは、Tokenをリクエストします。

  • URIhttps://{YOUR_ORGANIZATION_URI}/api/v2/oauth2/token
  • メソッド:POST

パラメータの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

f:id:sugimomoto:20200510113339p:plain

あとは、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

f:id:sugimomoto:20200510113428p:plain

リスト取得時のパラメータ指定方法

フィルターなどを実行する場合は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

f:id:sugimomoto:20200510113452p:plain

最低限 projectId、 issueTypeId 、 properotyIdを知っておく必要があります。プロジェクト一覧の取得優先度一覧の取得種別一覧の取得から把握しておきましょう

プログラムから実行する

最後に .NET Core / RestSharp を使って、リクエストしてみたいと思います。PostmanのCode Snippetを利用して、リクエストのためのコードを取得します。

f:id:sugimomoto:20200510113502p:plain

gist.github.com

f:id:sugimomoto:20200510113512p:plain

なお、課題を格納するクラスは以下のURLで公開しています。(JSONペーストを利用しただけなので、あまり信用しないでください)

https://gist.github.com/sugimomoto/032a91b739163d60441b77cfb16a2060

おわりに

backlog API は比較的シンプルなAPIなので、使いやすい部類に入るかと思います。ただ、機能の数が多いのと、それぞれのIDを事前に把握しておく必要があったりするので、その辺は注意する必要があるかなと思います。