Notionには、無料で使えるAPIがあります。
今回は、Notion APIのセットアップから、Rubyのfaraday gemを使ってリクエストを投げ、ページの本文やテーブルビューの一覧を取得するまで、を記事にしてみました。
使用したバージョン
- Ruby: 4.0.3
- faraday: 2.14.2
1. インテグレーション作成
この作業はワークスペースのオーナーしか実行できない点に注意してください。
ここでやるのは、権限設定とAPIキーの発行、というイメージです。
「インテグレーション」という公式ドキュメントの記事タイトルですが、画面には「コネクト」という名前になっていて、少し混乱しましたが、おそらく同じことを指していると思います。
今回は以下で作成してみました。
- コネクト名:
TestConnect - 認証方法: アクセストークン
- 機能: 「コンテンツを読み取る」のみチェック
- ユーザー機能: 「ユーザー情報なし」
2. ページに接続
この作業はワークスペースのゲストアカウントだと仮にフルアクセス権限を持っていても実行できないようです。
また、ページに対して編集権限ではおそらく実行できません。
（この辺りの権限周りについては有料プランなど、色々設定がありそなのでやや曖昧です。もし設定できない場合は疑ってみると良いかもという意味で記載してみます。）
作成したコネクト（インテグレーション）で読み取りたいページに移動します。
ページ右上の3点リーダーから、「接続」にマウスオーバーすると、先ほど作ったコネクトが表示されていると思います。
これを接続することで、API接続の準備ができました。
3. 実際に読み取れるかを確認
Notion APIのページには、使用できるエンドポイントが記載されています。
先ほど作成したトークンがあれば、例えば「Retrieve a page」のページで「Tri it」から、接続確認ができます。
4. Ruby（faraday）でリクエスト
先ほどの「Try it」にもRubyのリクエストサンプルコードがありますが、Net::HTTPを使う方法でした。
今回は、faradayを使ったサンプルコードを紹介します。
page_id = "36e7e3c5cd238088b01ae2e5464f0402" url = "https://api.notion.com/v1/pages/#{page_id}" headers = { 'Notion-Version' => '2026-03-11', 'Authorization' => 'Bearer ntn_xxx（トークン）' } response = Faraday.new.run_request(:get, url, nil, headers) p JSON.parse response.body
こんな感じで、Notion APIを使ってRubyでNotionの内容を読み取り、取得することができました🎉
5. ページの本文にはRetrieve block childrenが使える
自分がハマったポイントとして、Retrieve a pageエンドポイントでは、本文は取得できないというものがありました。
エンドポイント名からして、ページの内容を本文含めてごそっと取れるのかなーと思ったのですが、どうやらページのプロパティ情報（更新日など）が取れるエンドポイントで、本文の取得はできませんでした。
以下のようなページをしているとき（ページタイトルが「テストのページ」）、「ここに本文が入ります。」は Retrieve a pageのレスポンスには含まれませんでした。
その代わり、Retrieve block childrenというエンドポイントが使えます。
これは、block_idを渡す、という仕様ですが、このblock_idにページID（そのNotionページのURLの文字列）を渡してあげれば良いです。
block_id = "36e7e3c5cd238088b01ae2e5464f0402" url = "https://api.notion.com/v1/blocks/#{block_id}/children" headers = { 'Notion-Version' => '2026-03-11', 'Authorization' => 'Bearer ntn_xxx（トークン）' } response = Faraday.new.run_request(:get, url, nil, headers) p JSON.parse response.body
6. テーブルビューの一覧取得には Query a data sourceが使える
Notionでは、以下のような「テーブルビュー」というものが作れます。
このテーブルの中のアイテムの一覧を取得したかったのですが、上記で紹介した Retrieve block childrenでは取得できないようでした。
（「テストのデータベース」という名前のデータベースはあるよ、くらいはわかりますが、各項目（記事Aなど）は取得できませんでした。）
調べた結果、「Query a data source」（postリクエスト）を使えば取得できました。
必要になるのは、「データソースID」というもので、以下の画像の箇所から取得できます。
data_source_id = "36e7e3c5-cd23-80e4-822c-000b96b271f8" url = "https://api.notion.com/v1/data_sources/#{data_source_id}/query" headers = { 'Notion-Version' => '2026-03-11', 'Authorization' => 'Bearer ntn_xxx（トークン）, 'Content-Type' => 'application/json' } response = Faraday.new.run_request(:post, url, nil, headers) p JSON.parse response.body
その他: レート制限について
Notion APIのリクエスト制限については以下に記載があり、レート制限にも言及があります。
インテグレーションごとの受信リクエストのレート制限は、1 秒あたり平均 3 リクエストです。平均レートを超える一部のバーストは許可されます。
とあります。
「平均レートを超える一部のバーストは許可されます。」とあるように、瞬間的に1秒あたり/3リクエストを超える分には問題ないようです。
実際、連続的に20回ほどリクエスト投げてみましたが、全て200が返ってきました。
レート制限はページごと？あるいはコネクト（インテグレーション）全体で判定？など気になることもあります（ドキュメントの書き方だとインテグレーション丸ごと使えなくなりそうですが）が、そこまでの言及はされておらず、単なる興味のためにバーストまでリクエストするのも良くない気がしたので、検証はできていません。
