notion apiがpublic betaになったので調べてみた。

本日ついに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によると

元来は分散システム上で統制なしに作成できる識別子として設計されており、したがって将来にわたって重複や偶然の一致が起こらないという前提で用いることができる

UUID - Wikipedia

と書かれていて、wikiの脚注を読んでもID衝突はないことが期待できそうで、自分も今後使いたくなりました。

認証について

認証についてはこちらに書かれています。

Start building with the Notion API

自分だけ使う場合は次に記載しているHOW_TO_USEをみて貰えば良いのですが、一般公開して他の人2つ買ってもらうためにはOAuth認証の実装が必要になります。

利用ユーザーには安心・安全の、選択したページのみ編集できる権限設定が可能に。

notion連携サービスは今までも非公開API TOKENを使えばつくれたんですが、その非公開API TOKENは全てのページにアクセスできてしまい、情報保護の観点で一般提供しづらいものでした。今回提供されたOAuth認証によるサービス連携では、アクセス可能なページを制限できるみたいで、これでかなりnotion連携サービスをつくりやすくなったと思います。

引用元:https://files.readme.io/f1d5665-notion-integration-user-authorization.png

通信回数の上限について

1秒間に平均3リクエストまで。

「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をクリック

Notion – The all-in-one workspace for your notes, tasks, wikis, and databases.
A new tool that blends your everyday work apps into one. It's the all-in-one workspace for you and your team

サービス名と連携先workspaceを選ぶ

api tokenをゲット。

自分専用にするか、一般公開するか選べるようです。

ここで表示されているInternal Integration Tokenは自分がadmin userの場合のみ使えるもので、一般公開して使ってもらった場合はOAuth認証後に渡されるAccess Tokenを使います。

取得したtokenを使ってデータ取得してみる。

Postmanで試すかーと思ったら、notion公式からテストしやすい環境が提供されていました。

Postman

ただ、こちらからだと、疎通テストはできても、出力結果まではなぜか見れなかったので、postmanの理解は今回の本題ではないことから、今回はシンプルにpostmanでのget requestの設定をして試してみます。

Postman | The Collaboration Platform for API Development

↓適当に名前をつけて保存

↓ postmanで設定して送信

送信すると、こんな結果が返ってきました。

notion公式からgithub issue連携のsampleもありました。

ただ、こちらは自分でnode サーバーを管理する必要がありそうです。

Build software better, together
GitHub is where people build software. More than 100 million people use GitHub to discover, fork, and contribute to over 330 million projects.

notionの1 databaseにつき、1github repositoryになるようで、複数の github repositoryと連携をしたい場合はnotionのdatabaseを分けるか、自前でカスタマイズが必要になりそうです。

また、notionのdatabaseが更新されたら自動でサービスに通知するという仕組みはまだ実装されてないようで、cronなどを使ったスケジューリング処理を実装する必要もありそうです。

notion側で更新されたらサービスに自動通知、自動更新する仕組みはあるか?

調べてみたところ、公式ではまだ提供されてませんでした。

こちらをみると、「page更新したらemail送信できる仕組みの例あるよ」と思うかもしれませんが、実装コードを見ると5秒に1回チェックしているだけのようです。

Start building with the Notion API

ただ、notionはページのslack連携はできるので、自分がつくっているサービスではslackのwebhookを利用して、

notion→slack→自分のサービス

という仕組みで自動連携を実現させています。

ゆるふわリアルタイム同期の実現方法として参考になれば幸いです。

notion apiからdatabaseをつくることはできるか?

できないそうです。

Start building with the Notion API
Connect Notion pages and databases to the tools you use every day, creating powerful workflows.

一般公開する方法について

一般公開を選択するとこんな感じで入力を求められます。OAuth認証に必要なRedirect URIの設定と連携サービスについての説明を書けば良いそうです。

公式記事によると、notionのmarket placeに公開されるかどうかはnotionが決めるようです。こちらからリクエストをするというボタンはなさそうでした。

Developer Terms
The following terms (“Developer Terms”) govern your use of the APIs that are made available by Notion Labs, Inc. (“Notion”) for the purpose of (1) developing an...

まとめ

実際試してみると、まだまだ動作が不安定だと感じるときもありましたが、非公式ではなく公式APIを使うことによってユーザーへの安心感、急なAPI変更がないことによる運用しやすさが得られたと思います。

特に権限管理は自分が求めていた機能なので、安心してさっそくNotion連携サービスを公式API利用にして動かしてみようと思います。

コメント