Heroku Platform APIのJavaラッパー

しばらく別の仕事をしていたため一ヵ月以上放置していたんですが、Heroku Platform APIのJavaラッパーをリリースしました。

 

http://oss.flect.co.jp/libs/ja/heroku-platform-api.html

 

Platform API自体がまだベータでどのように変更されるかわからないのでバージョンは0.9としています。(というかいくつかFeatureRequestしようと思ってます。)

元々は全メソッドを実装するつもりはなかったんですが、7割ぐらい実装した段階で全部作ろうと決心しました。でも、どう考えても使うことのなさそうなメソッドも多いです。(^^;

使い方は多分PlatformAPIのJavaDocとHerokuのDevCenterのリファレンスを並べて眺めればだいたいわかるんではないかと。

- http://oss.flect.co.jp/apidocs/heroku-platform-api/jp/co/flect/heroku/platformapi/PlatformApi.html

- https://devcenter.heroku.com/articles/platform-api-reference

基本的にはRESTのAPIとJSONを忠実にJavaに落としていっただけです。ちなみにJavaDocは全クラス、メソッドがGitHubのソースへのリンク付きという親切仕様です。(^^;

以下、いくつかポイントを絞ってわかりにくそうなところと突っ込みどころを解説していきます。

 

★認証

APIを使用するための認証方法には以下の4つがあります。(括弧内は対応するPlatformApiクラスのメソッド名)

  • OAuth(fromOAuth)
  • refresh_tokenをaccess_tokenと交換する方法(fromRefreshToken)
  • ユーザー名とパスワードをaccess_tokenと交換する方法(fromPassword)
  • ユーザー名とAPIキーを使用する方法(fromApiToken)

一番基本的な使い方はOAuthでの認証です。OAuthを使用するためにはあらかじめHerokuダッシュボードのAccount画面でOAuthClientを登録してClientIDとClientSecretを取得する必要があります。

このJavaラッパーではPlatformApi#getOAuthUrlメソッドでHerokuの認可画面のURLがとれるので、そこにブラウザでアクセスしてリダイレクトで返ってきたcodeをPaltformApi#fromOAuthに渡せば有効なPlatformApiクラスが取得できます。

OAuth認証のレスポンスには常にrefresh_tokenが含まれています。つまり一度認可を受けてしまえばあとはずっとオフラインアクセスが可能です。

refresh_tokenはユーザがダッシュボードでそのアプリをRevokeしないかぎりずっと有効です。

あとはユーザ名とパスワードまたはAPIKeyを使用してAPIを叩くこともできます。(APIKeyはコマンドで「heroku auth:token」を叩くと表示されます。)

パスワードでの認証はaccess_tokenとの交換が必要なのに対しAPIKeyは交換なしでいきなり使用できます。

これが可能なのでPlatform APIは実は全部以下のようにcurlで1コマンドで実行可能です。

 

curl -i -H "Accept: application/vnd.heroku+json; version=3"
    -u <USER>:`heroku auth:token`
    https://api.heroku.com/apps

 

★Scope

OAuthで認可を求める際に指定できるScopeは以下です。

  • global(全権限)
  • identity(アカウント情報のみ)
  • read(アプリの環境変数以外を読める)
  • write(アプリの環境変数以外を書ける)
  • read-protected(アプリの環境変数も読める)
  • write-protected(アプリの環境変数も読める)

アプリの環境変数が見えてしまうとDATABASE_URLやその他のAddonの設定情報も丸見えなのでデータベースの中身まで見ることが可能になるわけです。

そのためにread/read-protectedのような分け方がされているんだと思うんですが、全アプリに対して同じスコープが適用されるのでほとんど有効なバリアとはなりません。

現状、アプリ毎に個別に権限が指定できないのがPlatform APIの一番の問題点だと思います。

ちなみにglobalスコープでも実行できないメソッドもいくつかあります。(OAuthClientやAuthorizationなど。これらのメソッドを実行するにはパスワードかAPIKeyでの認証が必要。。。なんですけどそもそも使い道が思いつかないですね)

 

★Formation

とはProcfileで定義するWebプロセスやWorkerプロセスのことです。（前は「Process」と呼ばれてた気がするけどこれから変わるのか？？？)

heroku psコマンド相当のことはFormationまたはDyno関連のメソッドでだいたいできます。

たぶんこの辺が今のところ一番実用的なメソッドです。

 

★ LogDrain

LogDrainはDynoのログを外部のSyslogに流す仕組みです。PapertrailやTreasureDataなどのログを扱うAddonはこの仕組みを利用しています。

一覧を取得するとそこにはAddonが使用しているURLも含まれているので、それを別のアプリでaddすると複数のアプリから一つのAddonに対してログを流すことが可能です。

やっていいのかどうかはわかりませんが。。。(^^;;;

でも多分Addon側からはログを流してきたDynoがどのアプリに属しているかを知る術はないと思うんですよね。。。

 

★LogSession

作成するとhttpsのURLが生成されて、そこにGETでアクセスすると直近のログが取得できます。URLは5分間または接続してから1時間有効です。(とドキュメントに書いてあります。)

接続してから1時間？？？

どういう意味かと思ってたら作成時のオプションで「tail=true」と指定すると、レスポンスはContent-Lengthなしで繋ぎっぱなしになります。

なんつー乱暴な。。。(--

しかし実際にtailっぽく動作するので便利は便利です。。。でもアリなのか？これ？

 

□□□□

その他、releasesの一覧は取れてもrollbackはできないとか、全体的に突っ込みどころ満載な感じはありますがFeatureRequestやバグレポも割とちゃんと聞いてくれて実際に修正されたりもしているので、皆もっとガシガシ突っ込んであげると良いと思います。(^^;

コメント(0)