はじめに
お久しぶりです、筆者です。
最近お仕事が大変だったり、Library of Ruinaやcyberpunk2077の影響だったりでブログ記事を更新し切れてませんでしたね…。
久しぶりの今回の投稿では、個人用ドキュメント作成にお世話になってる『esa.io』というサービスのAPIについてまとめていこうかと。
esa.io
せっかくですのでこのesa.ioについても軽く紹介してからまとめていこうかと。
※APIのまとめだけでいい場合はこちらから読み始めてください→API概要
それではいきましょう。
※本記事に書かれている内容は「執筆当時(2021/01/07)」段階での情報を元に構成されたものです。
情報が古い可能性もあるので悪しからず。
esa.ioとは
こちらのサービスは「Markdownベースでドキュメント管理ができるサービス」です。
有料ですが月々500円と結構お安めなサービスです。
料金は、そのチーム内(Slackで言うワークスペースみたいなもの)のメンバーが増える毎に+500円加算されていきますが…。
個人用ドキュメント(メンバー数が1人のチーム)であれば気にならないでしょう。
もちろんドキュメント自体を非公開にも公開にもできます。
また、ドキュメント内の「一部のページ」のみ公開にもできるそうです。
※共有用のURLが発行される形で共有できます、くわしくはこちら(公式Docs)
どんな感じで利用できるかは、esa.ioのドキュメントを見るといいかと。
docs.esa.io
esa.ioでは「サービスヘルプドキュメントをesa.io自身で作っている」ので、ドキュメントを見ればどんな感じのツールかも分かるかと。
ただし…もちろんのことながらドキュメントでは編集モードは使えません、閲覧のみ可能です。
もし編集モードも試してみたいときは、1ヶ月のFree Trialで試してみるのも良いかと。
また、esa.ioには「エクスポート」機能と「インポート」機能もあります。
エクスポート機能は画面上から使用できるのですが、インポート機能は現状API経由からしか行えないそうです…。
インポート機能を使うのであれば、esa.ioのAPIを使うしか選択肢はないですね…。
というわけで、esa.ioのAPIについて見ていきましょう。
API概要
- 所属チームの基本情報、統計情報取得(チームに投稿された記事総数も見れます)
- 所属チームの統計情報取得(直近24時間以内に記事投稿等を行ったメンバー数も見れます)
- 各記事の情報取得(記事のコメント内容やスター数も取得可能です)
- 記事の投稿、編集、削除
- チーム招待用URL発行&再取得
- カテゴリ情報取得
- チーム内で使用している絵文字情報取得
ちなみに、esa.ioのAPIは利用制限が設けられているらしく…。
「ユーザ毎に15分間毎75リクエストまで」しか叩けません。
※問い合わせれば、チーム毎に「一時的に」利用制限の緩和ができるそうですが…
API発火時点で「あと何回APIが発火できるか」については、レスポンスヘッダの下記のパラメータを参照とのこと。
X-RateLimit-Limit: [リクエスト可能な最大数] X-RateLimit-Remaining: [現時点で残っているリクエスト可能数] X-RateLimit-Reset: [リクエスト回数がリセットされる日時(UNIXタイムスタンプ形式)]
ちなみにちなみに、esa.ioのAPIはHTTPSリクエスト形式のもののみ提供されています。Web APIというものに分類されるかな?
各APIは機能別にGET, POST, PUT, PATCH, DELETEのHTTPメソッドを使用してあります。
機能毎にHTTPメソッドをきちんと使い分けているのは好感持てますね…。
GETリクエスト以外のリクエストには文字UTF-8Bodyパラメータを使用し、JSON形式でデータを送付する様に規定されているそうです。
XML形式じゃなくて本当によかった…。
もっと詳しく知りたい場合はesa.ioの公式ドキュメントを参考に。
概要はこんなところで、お次はいよいよesa.ioAPIを触ってみましょう。
APIを使ってみよう-事前準備
esa.ioのAPIを使用するには、事前に「アクセストークンの取得」が必要になります。
アクセストークンの取得方法には大きく分けて2種類あります:
- 所属チームの設定画面より直接アクセストークンを使用する方法
- 👍画面から手軽に発行可能
- 👎ユーザー毎には発行できない
- OAuthを使用し外部アプリケーション使用ユーザー毎に取得する方法
- 👍ユーザー毎にアクセストークンを発行できる
- 👎手軽には利用できず使用ハードルが高い
今回は手軽さを優先し、1の「直接アクセストークンを使用する」方法でいこうかと。
APIを使ってみよう-実践編
さてアクセストークンも取得したので…あとは書くだけですね。
ここからの実装方法は流石に省略します。いろんな方法あると思うので…。
参考までに、私の方でNode.jsベースの「記事のインポートを行うスクリプト」を作ってみたので参考までに:
esa-api_sample/import_file.js at main · aik0aaac/esa-api_sample · GitHub
…ただ、ここで終わっても味気ないのでね。
記事のインポートを行うのに使用したAPIが、どんな感じのものかを紹介できればと。
記事インポートにAPI紹介
今回記事インポートに使用したAPIは、esa.ioでは「記事を新たに投稿する」APIとして提供されています。
公式ドキュメント
POST形式のメソッドで、記事を投稿できるAPIです。
最低限必要な情報は「記事タイトルname」だけですね。
必須以外のパラメータについては下記を参照に:
// POST https://api.esa.io/v1/teams/docs/posts HTTP/1.1 // Content-Type: application/json { "post":{ "name":"[記事タイトル]", "body_md":"[記事内容(Markdown形式で記述)]", "tags":[ "[登録したいタグを配列形式で指定可能]", ], "category":"[記事カテゴリ、`日報/10月`のカテゴリで登録する場合はそのまま`日報/10月`と打てばOK", "wip": [WIPモードで投稿するかどうかのBool値。デフォルトではtrue(WIPモードで投稿)], "message":"[コメント内容]" } }
レスポンスデータはこんな感じ:
※公式Docsの記述を引用させていただきました
{ "number": 5, "name": "hi!", "full_name": "dev/2015/05/10/hi! #api #dev", "wip": false, "body_md": "# Getting Started\n", "body_html": "<h1 id=\"1-0-0\" name=\"1-0-0\">\n<a class=\"anchor\" href=\"#1-0-0\"><i class=\"fa fa-link\"></i><span class=\"hidden\" data-text=\"Getting Started\"> > Getting Started</span></a>Getting Started</h1>\n", "created_at": "2015-05-09T12:12:37+09:00", "message": "Add Getting Started section", "url": "https://docs.esa.io/posts/5", "updated_at": "2015-05-09T12:12:37+09:00", "tags": [ "api", "dev" ], "category": "dev/2015/05/10", "revision_number": 1, "created_by": { "myself": true, "name": "Atsuo Fukaya", "screen_name": "fukayatsu", "icon": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png" }, "updated_by": { "myself": true, "name": "Atsuo Fukaya", "screen_name": "fukayatsu", "icon": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png" }, "kind": "flow", "comments_count": 0, "tasks_count": 0, "done_tasks_count": 0, "stargazers_count": 0, "watchers_count": 1, "star": false, "watch": false }
「記事ID」も返却されるので、作成した記事をそのまま編集したい場合にも活用できそうです。
執筆当時のesa.ioのAPI一覧には、「記事インポート」にあたるAPIがなかったため…おそらくこれを使用して記事インポートを行なっていくしかないんじゃないかなぁと思います。
本当は画面上から、フォルダをアップロードすればその中のMarkdownファイルが一気にインポートできる(カテゴリ階層はディレクトリ構造を元に解析)と嬉しいのですが…今後のアップデートに期待ですね。
おわりに
今回の記事では、esa.ioというサービスにてAPIを介し記事をインポートしてみました。
現時点では、APIを介しては1ファイル1ファイル毎にしかインポートできないですが…。
今後複数ファイルをインポートできる口が増えると嬉しいですね。
おまけとして、筆者がおもしろそうだと感じた下記のesa.io APIのサンプルファイルも用意しました。
- 記事一覧取得
- 所属チーム基本情報取得
- 所属チーム統計情報取得
- 所属チーム参加メンバー情報取得
サンプルファイル:
esa-api_sample/talend-api-tester_export.json at main · aik0aaac/esa-api_sample · GitHub
上記リンクファイルを保存し、Talend API TesterというChrome拡張機能にExportすると使用できると思います。
※「チーム名」と「AccessToken」についてはEnvironmentsに載っけてるので、適宜変更してご使用ください
もしよければ使ってみてください。
それでは|дﾟ*)
