本日ついにNotionAPIがpublic betaになりました！
notionの料金ページでcoming soonになってから1年以上経過しており、いつになったら公開するんだろうと思っていましたが、ついにnotion apiがpublic betaになりました！
Start building with the Notion API
待ちに待ったapiですので、明日でも良いかなとも思ったんですが、せめてドキュメントの調査だけでもやっておこうと思います。
introductionを読んでみる
Start building with the Notion API
api requestsのURLは https://api.notion.com だそうです。notionはどうやらRESTfulを採用したようで、graphqlではないようでした。
page固有のidについて
例えば以下のようなurlの aa074d7320554d15893aeafde547b073の部分です。
https://www.notion.so/taiyop/aa074d7320554d15893aeafde547b073
どういうルールでこの文字列になってるんだろうなとは思ってたんですが、UUID v4を採用してるみたいですね。
非公開のapiを使ってた時に、aa074d73-2055-4d15-893a-eafde547b073 のような形式でpage_idを取得してたんですが、これはUUID v4だったんですね。
wiki引用で申し訳ないんですが、wikiによると
元来は分散システム上で統制なしに作成できる識別子として設計されており、したがって将来にわたって重複や偶然の一致が起こらないという前提で用いることができる
と書かれていて、wikiの脚注を読んでもID衝突はないことが期待できそうで、自分も今後使いたくなりました。
認証について
認証についてはこちらに書かれています。
Start building with the Notion API
自分だけ使う場合は次に記載しているHOW_TO_USEをみて貰えば良いのですが、一般公開して他の人２つ買ってもらうためにはOAuth認証の実装が必要になります。
利用ユーザーには安心・安全の、選択したページのみ編集できる権限設定が可能に。
notion連携サービスは今までも非公開API TOKENを使えばつくれたんですが、その非公開API TOKENは全てのページにアクセスできてしまい、情報保護の観点で一般提供しづらいものでした。今回提供されたOAuth認証によるサービス連携では、アクセス可能なページを制限できるみたいで、これでかなりnotion連携サービスをつくりやすくなったと思います。
通信回数の上限について
１秒間に平均３リクエストまで。
「Some bursts beyond the average rate are allowed.」とあるので、一時的な超過リクエストは許容するとありますが、databaseの一括処理といったバッチ処理の際は注意が必要です。
Rate-limited requests will return a “rate_limited” error code (HTTP response status 429). The rate limit for incoming requests is an average of 3 requests per second. Some bursts beyond the average rate are allowed.
Integrations should accommodate variable rate limits by handling HTTP 429 responses and backing off (or slowing down) the speed of future requests. A common way to implement this is using one or several queues for pending requests, which can be consumed by sending requests as long as Notion does not respond with an HTTP 429.
Start building with the Notion API
HOW TO USE
まず、操作をするにはworkspaceのadmin_userである必要があります。チームのworkspaceしかない場合は、無料ですので個人のworkspaceをつくると良いと思います。
まずはこちらのurlをクリック
サービス名と連携先workspaceを選ぶ
↓
api tokenをゲット。
自分専用にするか、一般公開するか選べるようです。
ここで表示されているInternal Integration Tokenは自分がadmin userの場合のみ使えるもので、一般公開して使ってもらった場合はOAuth認証後に渡されるAccess Tokenを使います。
取得したtokenを使ってデータ取得してみる。
Postmanで試すかーと思ったら、notion公式からテストしやすい環境が提供されていました。
ただ、こちらからだと、疎通テストはできても、出力結果まではなぜか見れなかったので、postmanの理解は今回の本題ではないことから、今回はシンプルにpostmanでのget requestの設定をして試してみます。
Postman | The Collaboration Platform for API Development
↓適当に名前をつけて保存
↓ postmanで設定して送信
送信すると、こんな結果が返ってきました。
notion公式からgithub issue連携のsampleもありました。
ただ、こちらは自分でnode サーバーを管理する必要がありそうです。
notionの1 databaseにつき、１github repositoryになるようで、複数の github repositoryと連携をしたい場合はnotionのdatabaseを分けるか、自前でカスタマイズが必要になりそうです。
また、notionのdatabaseが更新されたら自動でサービスに通知するという仕組みはまだ実装されてないようで、cronなどを使ったスケジューリング処理を実装する必要もありそうです。
notion側で更新されたらサービスに自動通知、自動更新する仕組みはあるか？
調べてみたところ、公式ではまだ提供されてませんでした。
こちらをみると、「page更新したらemail送信できる仕組みの例あるよ」と思うかもしれませんが、実装コードを見ると５秒に１回チェックしているだけのようです。
Start building with the Notion API
ただ、notionはページのslack連携はできるので、自分がつくっているサービスではslackのwebhookを利用して、
notion→slack→自分のサービス
という仕組みで自動連携を実現させています。
ゆるふわリアルタイム同期の実現方法として参考になれば幸いです。
notion apiからdatabaseをつくることはできるか？
できないそうです。
一般公開する方法について
一般公開を選択するとこんな感じで入力を求められます。OAuth認証に必要なRedirect URIの設定と連携サービスについての説明を書けば良いそうです。
公式記事によると、notionのmarket placeに公開されるかどうかはnotionが決めるようです。こちらからリクエストをするというボタンはなさそうでした。
まとめ
実際試してみると、まだまだ動作が不安定だと感じるときもありましたが、非公式ではなく公式APIを使うことによってユーザーへの安心感、急なAPI変更がないことによる運用しやすさが得られたと思います。
特に権限管理は自分が求めていた機能なので、安心してさっそくNotion連携サービスを公式API利用にして動かしてみようと思います。
コメント