こんにちは。
\nこの記事はHamee Advent Calendar 2016の25日目の記事です。
Hameeカレンダーの大トリを努めます。れこです。
\n今回は敬虔たるネクストエンジン(以下NEと略します)開発者の皆様へクリスマスプレゼントです。
\nNEのNodejs版APIクライアントを作成したので紹介させていただきたいと思います。
作ったものはこちらです。
\nインストール方法、詳しい使い方などもこのリポジトリを参照してください。
\n\n\n
このクライアント、 非公式 です。
\n何度でも書きます。 非公式 です。
\nとある案件でNodejs使ったのですが、NE APIのクライアントが無かったので勝手にドッグフーディングしつつ作って公開したという感じです。
感覚的にはGoogleAnalyticsチームが公開している非公式プロダクトautotrackなんかと近いかな、と思っています。
\nメンテナンスは私個人として行っていきますので、何かあればPRやIssueにお願いします。
NE APIを利用していて、既存のSDKたちを見ていて思った問題点がこれら
\nNE APIのリクエストURL一覧を見るとわかると思いますが、
\n/api_v1_receiveorder_base/countのような感じでパスの途中にv1と思い切りバージョン番号が入っています。
\nもしアプデかかったらどうするんだろう。一括置換でもするのだろうか。と不安があります。
例えばChatWorkのようにhttps://api.chatwork.com/v1と、先頭に入ってくれていればまだ救いようがあるのですが、パスの途中は辛い。
\n同じく非公式のNE API Ruby版SDKはおそらく同じことを感じたのか回避されています。
ということでパスを隠蔽してコード内にバージョン番号が混じらないようにしました。
\nconst Nextengine = require('next-engine')\nconst { ReceiveOrder } = require('next-engine/Entity')\n\nconst client = new Nextengine({\n clientId: 'XXXXXXXXXX',\n clientSecret: 'XXXXXXXXXX',\n accessToken: 'XXXXXXXXXX',\n refreshToken: 'XXXXXXXXXX'\n})\nclient.query(ReceiveOrder).count()\n .then(count => console.log(count))ゴリ押しですが、コード内にパスがハードコートされていて、バージョンアップが来たときに追従できないよりはマシだと思っています。
\nこれで仮にパスが変わってもライブラリ内部で吸収が可能です。
NE APIの比較演算子一覧を見てもらえばわかると思いますが、
\n割と柔軟に検索条件が組めるようになっています。
\nただし形式がSQLっぽい感じのフォーマットを矯正されるので結構扱いにくいと感じています。
SQLっぽいものが書けるのであれば、パラメータを頑張って作るのではなく、クエリビルダっぽいDSLで書けたら良いのでは。
\nと思って作ってみました。
const { Goods } = require('next-engine/Entity')\nclient.query(Goods)\n .where('goods_id', 'abc')\n .limit(500)\n .offset(350)\n .get()\n .then(results => console.log(results))まだ機能は少ない（where, limit, offsetくらい）ですが、もしメソッドを足すとしたらknexというクエリビルダのライブラリのAPIに寄せていこうと思っています。
という操作が何箇所かあるのですが、扱いにくい。
\nですがjsにはPromiseという非同期処理を抽象化する機構が用意されているので、
const zlib = require('zlib')\nconst promisify = require('es6-promisify')\nconst stringify = promisify(require('csv-stringify'))\nconst deflate = promisify(zlib.deflate)\nconst { UploadQueue } = require('next-engine/Entity')\n\ninput = [\n ['syohin_code', 'jan_code'],\n [ 'abc', '1234567890' ]\n]\nstringify(input)\n .then(csv => deflate(csv))\n .then(gz => client.uploadAndWaitFor({ data_type: 'gz', data: gz }))\n .then(() => console.log('Imported!'))のように、uploadAndWaitForというメソッドを用意して「アップロードして（ポーリングしながら結果を）待つ」処理を非同期化してみました。
\nこれ使うと楽ではあるのですが、プロセスを長いこと握ることになるので、ワーカージョブやバッチでしか使用を推奨できません。
それ以外の場合はuploadメソッドとwaitForメソッドをそれぞれ別個に使用し、アップロードとキューの監視を別プロセスに分けるようにも作れます。
NE APIでは、レスポンスに常にアクセストークンが含まれており、 これが不定期に勝手に更新されます。
\nよく意味がわからないかもしれませんが、要はよくあるOAuth2風に
という形式ではなく、「いつ変わるかわならないアクセストークンをAPIリクエスト１回ごとに考慮する」必要があります。
\nこればかりは要件や実装によって保持・更新する方法が変わると思うので抽象化できませんでした。
とりあえず、new NextengineしたインスタンスはaccessToken, refreshTokenプロパティ経由で最新のアクセストークン・リフレッシュトークンを入手できます。
const { Goods } = require('next-engine/Entity')\nclient.query(Goods)\n .where('goods_id', 'abc')\n .limit(500)\n .offset(350)\n .get()\n .then(results => console.log(results))もしくは、内部で使用しているConnectionクラスを拡張することでも対応可能です。
\nconst Nextengine = require('next-engine')\nconst Connection = require('next-engine/lib/Connection')\n\nclass MyConnection extends Connection {\n handleResponse (res) {\n super(res)\n .then(json => json) // 何か拡張する\n }\n}\n\nclass MyNextengine extends Nextengine {\n getConnection (accessToken, refreshToken) {\n return new MyConnection(accessToken, refreshToken)\n }\n}他にもPROXY噛ませたりと共通で行いたい処理などがあれば上記方法で拡張可能です。
\nちなみにHTTPクライアントはnode-fetchを(isomorphic-fetch経由で)使用しています。
\n最悪、上記方法で無理やり差し替えも可能です。
例えば、NextEngine.on('refresh', ({ accessToken, refreshToken }) => ...)みたいなAPI設計も可能かなーと思ったんですが、
\nイベントベースにするとトリッキーさが増してしまうのであえて作らないという方向に倒しました。
ネクストエンジンAPIの認証についてのページに認証フローが書かれているのですが、
\n何度見したか覚えてないとすら感じる不思議なフローです。
この認証フローをアプリごとにスクラッチするのは骨が折れるので、
\nNodejsアプリの認証レイヤを抽象化するPassportというライブラリに対応したストラテジーを作成しました。
\n\nLeko/passport-nextengine: Nextengine authentication strategy for Passport and Node.js
\n
これで認証方法の特殊さを気にすることなく、OAuth2のストラテジー（Githubとか）の感覚で扱えるようになります。
\nそもそもなんで作ったのかという話ですが、
\n「Nodejsの公式SDK出てないからNodeで作る選択肢がない」をぶち壊そうとしたというのが根幹にあります。
\nその次に私自身が(Node)jsが好きだから手に馴染んでいる言語で書けるように作っておいたという感じです。
ライブラリは機能はもちろんですが、ガワの設計が何より大事だと思っているので、自分が使いたいAPIクライアントを作りました。
\n一度ベースを作ってしまえば必要に応じてリトライの考慮入れたりなんだりと強化していけるので、今後に期待していただければと思います。
繰り返しますが、 非公式です 。
\n何かあればリポジトリのIssueにお願いします。もしくはPRください！
ネクストエンジンには Developer Network (略してDevNet）という開発者向けコミュニティサイトがあります。
\nここには 開発ガイド 、 APIリファレンス 、チュートリアルなど開発の役に立つ情報が盛りだくさんです。
\nまた開発者同士でディスカッションする コミュニティ もあります。
\nわからないことがあれば こちら に質問を投稿してください。
ネクストエンジン Developer Networkwork
\nhttps://developer.next-engine.com/