Aikの技術日記

技術的な進捗とか成果とかを細々と投稿するブログです。時々雑記も。

トップ > API > esa.ioのAPIを使用して記事をインポートしてみた

esa.ioのAPIを使用して記事をインポートしてみた

API 単発

はじめに

お久しぶりです、筆者です。
最近お仕事が大変だったり、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概要

esa.ioの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を使用する…前にまずは事前準備を。

esa.ioのAPIを使用するには、事前に「アクセストークンの取得」が必要になります。
アクセストークンの取得方法には大きく分けて2種類あります:

  1. 所属チームの設定画面より直接アクセストークンを使用する方法
    • 👍画面から手軽に発行可能
    • 👎ユーザー毎には発行できない
  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\"> &gt; 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に載っけてるので、適宜変更してご使用ください
もしよければ使ってみてください。

それでは|дﾟ*)