--- title: "Notion APIとは？データソース対応の使い方とレート制限・社内連携の実装【2026年10月】" url: "https://www.issoh.co.jp/tech/details/18713/" published: 2026-10-22 updated: 2026-10-22 categories: ["業務システム"] publisher: "株式会社一創" --- # Notion APIとは？データソース対応の使い方とレート制限・社内連携の実装【2026年10月】 Notion APIは、Notionのページやデータベースを外部のプログラムから読み書きするためのREST APIです。2025年9月の版でデータベースの中に「データソース」という層が入り、2026年10月時点の最新版は2026-03-11です。この記事では、認証方式の選び方、データソースIDを使ったクエリとページ作成、2026年9月に変わったレート制限と再送処理、Webhookの受信とMarkdownでの本文取得を、公式ドキュメントの数値と動かせるコードで解説し、個別開発すべき条件も整理しました。 ## まとめ：Notion APIは2026-03-11版とデータソースIDと毎分180回の枠で組む 新しく書くコードは`Notion-Version: 2026-03-11`を指定し、データベースIDではなくデータソースIDでクエリとページ作成を行います。日本語の解説記事の多くは`/v1/databases/{id}/query`のままで、2025-09-03版より前の書き方です。チームで使う自動化には内部コネクション、自分専用のスクリプトには個人アクセストークンを使い分けます。 レート制限は2026年9月9日から接続ごとに60秒の固定窓になり、Business・Enterpriseは毎分600回、それ以外のプランは毎分180回です。429と529は`Retry-After`の秒数だけ待って再送し、書き込みの503は保存済みのことがあるため読み直してから判断します。変更の検知はWebhookに任せ、全件の定期取得は避ける設計が安全です。 ## Notion APIとは：ページ・データベース・データソースの外部操作用REST API Notion APIの入口は`https://api.notion.com/v1`の1つで、要求も応答もJSONです。まずは扱うオブジェクトの単位と、2025年以降に変わった構造を押さえます。 ### api.notion.comで扱うページ・データソース・ブロック・ユーザーとできること [Notion APIのリファレンス冒頭](https://developers.notion.com/reference/intro)によると、APIは可能な範囲でRESTの慣習に従い、GET・POST・PATCH・DELETEでページやデータベースを操作します。項目名はスネークケースで、IDはUUIDv4です。NotionのURLからコピーしたIDはハイフンを省いたまま渡せます。 | オブジェクト | 中身 | 主な操作 | | ------ | ------------- | ----------- | | ページ | 1件の文書か表の1行 | 作成・取得・項目の更新 | | データベース | データソースの入れ物 | 作成・取得 | | データソース | 列の定義を持つ表 | クエリ・列の変更 | | ブロック | 段落や見出しなど本文の部品 | 子要素の取得・追加 | | ユーザー | メンバーとボット | 一覧・取得 | 社内の連携でよく使うのは、データソースの行を条件で取り出す処理と、行を1件追加する処理の2つです。 ### 2025-09-03版で入ったデータソースとデータベースIDの関係と旧記事との違い [2025-09-03版への移行ガイド](https://developers.notion.com/guides/get-started/upgrade-guide-2025-09-03)は、データベースを「入れ物」、データソースを「表」として分けました。1つのデータベースに、列の定義が違う複数のデータソースを持てます。この変更で、クエリは`/v1/data_sources/{id}/query`へ、ページ作成の親は`data_source_id`へ移りました。 旧版の書き方のまま動かしている接続は、対象のデータベースにデータソースが追加された時点で、そのデータベースへのページ作成やクエリが失敗します。利用者が画面でデータソースを足しただけで連携が止まるので、既存のコードも移行の対象です。 ### 2026-03-11版の3つの破壊的変更とNotion-Versionヘッダの指定方法 [バージョン管理の公式ページ](https://developers.notion.com/reference/versioning)では、すべての要求に`Notion-Version`ヘッダが必須です。版は公開日の名前で、後方互換の無い変更があるときだけ新版が出ます。新しい項目やエンドポイントの追加は、古い版を指定していても同時に反映されます。 [2026-03-11版の移行ガイド](https://developers.notion.com/guides/get-started/upgrade-guide-2026-03-11)が挙げる変更は3つだけです。ブロック追加の`after`が`position`に、ごみ箱を表す`archived`が`in_trash`に、`transcription`ブロックが`meeting_notes`に変わりました。JavaScriptの公式SDKは[notion-sdk-js](https://github.com/makenotion/notion-sdk-js)のv5.12.0から対応し、npmの最新は2026年10月22日時点で5.27.1系です。 応答に入るページの`url`も、2026年6月に`app.notion.com/p/`の形へ変わりました。URLからIDを切り出すコードは壊れるので、`id`の項目を使います。 ## 認証方式の選び方：内部コネクションと個人アクセストークン、OAuthの違い どの方式でも、トークンを`Authorization: Bearer`ヘッダで送る点は同じです。違うのは、誰の権限で動き、どのページに届くかです。 ### チームの自動化で選ぶ内部コネクションとAdd connectionsでの共有手順 [認可の公式ガイド](https://developers.notion.com/guides/get-started/authorization)によると、内部コネクションは開発者ポータルでワークスペースの所有者が作り、設定画面の`Configuration`タブでトークンを取得します。内部コネクションは独立したボットとして動き、共有されたページにしか届きません。 1. 開発者ポータルで内部コネクションを作り、読み取り・書き込みなど必要な権限だけを選ぶ 2. 対象のページかデータベースを開き、右上の「•••」から「Add connections」を選ぶ 3. 作ったコネクションを検索して追加する（子ページにも引き継がれる） 4. トークンを環境変数かシークレット管理に置き、コードには書かない APIが`object_not_found`を返すとき、まず疑うのは2番目の共有漏れです。担当者が退職しても動き続けるので、業務の自動化は内部コネクションで作ります。 ### 個人アクセストークンの有効期限と作成できる人、使ってはいけない場面 2026年5月12日からは、個人アクセストークン（PAT）も使えます。[PATの公式ガイド](https://developers.notion.com/guides/get-started/personal-access-tokens)によると、PATは作成した本人の権限で動き、Add connectionsの共有が要りません。有効期限は7日から1年の5段階で、指定しなければ1年で切れます。 | 方式 | 誰として動くか | 向く用途 | | --------------- | -------- | ------------ | | 内部コネクション | 専用のボット | チームで使う業務の自動化 | | 個人アクセストークン | 作成した本人 | 手元のスクリプトや検証 | | 公開コネクション（OAuth） | 認可した各利用者 | 他社にも配る連携製品 | PATを業務の連携に使ってはいけません。作成者がページへのアクセスを失えばPATも同じページに届かなくなり、異動や退職で連携が止まります。作成できる人はプランで決まり、Freeは所有者だけ、Plusは全メンバーです。 ## curlとPythonでデータソースのクエリとページ作成を試す手順 ここからは内部コネクションのトークンを環境変数`NOTION_TOKEN`に入れた前提で進めます。最初にcurlでデータソースIDを取り、以降はPythonで書きます。 ### データベースIDからdata\_source\_idを取り出すGETリクエストと応答の読み方 データベースのURLに含まれる32桁の文字列がデータベースIDです。2025-09-03版以降、このIDを渡す取得APIは、中に含まれるデータソースの一覧を返します。 ``` export NOTION_TOKEN="（内部コネクションのトークン）" export DATABASE_ID="（データベースのURLに含まれる32桁のID）" curl -s "https://api.notion.com/v1/databases/${DATABASE_ID}" \ -H "Authorization: Bearer ${NOTION_TOKEN}" \ -H "Notion-Version: 2026-03-11" # 応答の抜粋 # { # "object": "database", # "id": "（データベースID）", # "data_sources": [ # { "id": "（データソースID）", "name": "案件管理" } # ] # } ``` データソースが1つなら`data_sources[0].id`を控えれば足ります。複数ある場合は`name`で選びます。IDは利用者が名前を変えても変わらないので、名前ではなくIDを設定ファイルに持たせてください。 ### Pythonの条件・返却列の絞り込みと100件単位のページング処理 次のコードを動かすために追加インストールが必要なライブラリは、`pip install requests`で入るrequestsだけです。ステータスが「完了」以外の行を、更新日時の新しい順に100件ずつ取り出します。[データソースのクエリの公式リファレンス](https://developers.notion.com/reference/query-a-data-source)が勧めるとおり、`filter_properties`で返す列を絞り、応答を小さくしています。 ``` import os import random import time import requests API = "https://api.notion.com/v1" HEADERS = { "Authorization": f"Bearer {os.environ['NOTION_TOKEN']}", "Notion-Version": "2026-03-11", "Content-Type": "application/json", } def call(method, path, **kwargs): """429・529は待って再送し、5xxは読み取り（GET）のときだけ再送する""" for attempt in range(6): res = requests.request(method, API + path, headers=HEADERS, timeout=60, **kwargs) retryable = res.status_code in (429, 529) or ( method == "GET" and res.status_code in (500, 502, 503, 504) ) if res.status_code == 429: reason = res.json().get("additional_data", {}).get("rate_limit_reason") if reason == "public_api_request_blocked": retryable = False # 接続が止められている。待っても直らない if not retryable or attempt == 5: res.raise_for_status() return res.json() wait = float(res.headers.get("Retry-After") or min(2 ** attempt, 30)) time.sleep(wait + random.uniform(0, 0.25)) # ゆらぎを足して再送の集中を避ける def open_tasks(data_source_id): """ステータスが「完了」以外の行を100件ずつ取り出す""" body = { "filter": {"property": "ステータス", "status": {"does_not_equal": "完了"}}, "sorts": [{"timestamp": "last_edited_time", "direction": "descending"}], "page_size": 100, } while True: data = call( "POST", f"/data_sources/{data_source_id}/query", params={"filter_properties": ["title", "ステータス"]}, json=body, ) if data.get("request_status", {}).get("type") == "incomplete": raise RuntimeError("1クエリ1万件の上限に達した。期間で条件を分けて取り直す") yield from data["results"] if not data["has_more"]: break body["start_cursor"] = data["next_cursor"] if __name__ == "__main__": for page in open_tasks(os.environ["DATA_SOURCE_ID"]): print(page["id"], page["url"]) ``` `page_size`の上限は100で、続きは`next_cursor`を`start_cursor`に渡して取ります。カーソルは中身を解析せず、受け取った文字列をそのまま返してください。1つの条件で取れるのは1万件までで、超えると`has_more`が`false`になり、`request_status`に打ち切りの印が付きます。大きな表は作成日時の範囲で条件を分けて取ります。 ### data\_source\_idを親に指定して行を追加するページ作成と入力値の上限 行の追加は`POST /v1/pages`で、親に`data_source_id`を指定します。前の節の`call`関数をそのまま使えます。 ``` def add_task(data_source_id, title, status="未着手"): """データソースに1行追加し、作られたページのIDを返す""" payload = { "parent": {"type": "data_source_id", "data_source_id": data_source_id}, "properties": { "名前": {"title": [{"text": {"content": title[:2000]}}]}, "ステータス": {"status": {"name": status}}, }, } return call("POST", "/pages", json=payload)["id"] ``` [要求の上限を定めた公式ページ](https://developers.notion.com/reference/request-limits)では、リッチテキストの本文とURLは2,000字、メールアドレスと電話番号は200字、複数選択・リレーション・ユーザーは1回100件までです。超えると400の`validation_error`になるため、外部の値は送る前に切り詰めるか、超えた行を記録して知らせる処理を入れておきます。値を消すときは空文字ではなく`null`です。 ## レート制限の実装：毎分180回・600回の枠と429・529・503で分ける再送処理 日本語の解説で「平均で毎秒3回」と書かれる上限は、2026年9月に数え方が変わりました。 ### 2026年9月9日に変わった接続ごとの上限とワークスペース共有枠の数え方 [Notion APIの変更履歴](https://developers.notion.com/page/changelog)によると、2026年9月9日から接続ごとの上限は60秒の固定窓で数えるようになりました。BusinessとEnterpriseは毎分600回、それ以外のプランは毎分180回です。窓の中ではまとめて使っても均等に使ってもよく、待ち時間の`Retry-After`は最大60秒に縮みました。それまでは最大15分でした。 これとは別に設けられているのが、ワークスペース全体で共有する上限です。1つの接続が枠内でも、同じワークスペースの別の連携が使い切れば429が返り、この場合の待ち時間は1分を超えることがあります。社内に連携が増えるほどこの上限に当たりやすくなるため、夜間のバッチは実行時刻をずらして組んでください。上限の考え方の一般論は[APIレート制限（レートリミット）とは？5方式の比較と429設計・分散実装【2026年版】](https://www.issoh.co.jp/tech/details/16179/)で整理しています。 ### rate\_limit\_reasonとRetry-Afterで待つ時間を決める再送の分岐 上限を超えた要求は429と`rate_limited`を返し、応答本文の`additional_data.rate_limit_reason`で理由が分かります。前の章の`call`関数は、公式ページの方針どおり次のように分岐しています。 - 429と529（Notion側の過負荷）は、`Retry-After`の秒数だけ待って再送する - 理由が`public_api_request_blocked`の429は、接続が止められているので再送しない - 500・502・503・504は、GETとDELETEのように何度送っても結果が同じ要求だけ再送する - 400は要求の誤りなので、直さずに再送しない ヘッダが無いときは1秒から倍々に延ばして最大30秒で止め、ゆらぎを足します。公式ページが示す方針は、再送の仕組みをワーカーごとに持たせず、1か所にまとめるというものです。指数バックオフの設計判断は[リトライパターンとは？指数バックオフ・ジッター・リトライ予算の実装判断を解説](https://www.issoh.co.jp/tech/details/16185/)で詳しく扱っています。 ### 503でも保存済みのことがある書き込みを二重に実行しない確認手順 書き込みが保存されたのに、応答を組み立てる時間が足りずに503が返ることがあります。同じ要求を送り直すと、行が2件できます。 ``` res = requests.post(API + "/pages", headers=HEADERS, json=payload, timeout=60) if res.status_code == 503: extra = res.json().get("additional_data", {}) created_id = extra.get("committed_resource_id") if created_id: # 保存は済んでいる。作り直さず、作られたページを読み直す page = call("GET", f"/pages/{created_id}") else: # 保存されたか分からない。同じ内容の行が無いかを検索してから判断する ... ``` ページやデータベースを作った要求なら、`committed_resource_id`に新しいIDが入ります。ブロックの追加で作られた子ブロックのIDが並ぶ項目は、`committed_child_ids`です。どちらも無い503は保存の有無が分からないため、外部システム側のIDを列に持たせておき、その列で検索してから再送を決めます。重複を止める考え方は[冪等キーとは？Idempotency-Keyの発行・保存・再生の実装と二重課金の止め方を解説【2026年版】](https://www.issoh.co.jp/tech/details/16293/)と同じです。 ### Freeプランの1,000ブロック上限で作成系のAPIが403になる条件 2026年9月1日から、Freeプランのブロック上限がREST APIにも適用されました。[ワークスペースのブロック上限の公式ページ](https://developers.notion.com/reference/workspace-block-limits)によると、対象はメンバーが2人以上のFreeワークスペースで、累計1,000ブロックです。消しても枠は戻りません。 上限に達した書き込みは成功し、そこから3日の猶予が始まります。猶予が切れると、ページ作成やブロック追加は403の`restricted_resource`で失敗し、`additional_data.block_limit`が付きます。項目の値の更新や読み取りは使えますが、回数の上限ではないため待っても直りません。Freeで検証した連携を本番に移す前に、プランを確かめてください。 ## 社内ツール連携の3パターン：Webhook受信とMarkdown取得、正データの置き場所 社内連携は、変更を受け取る、本文を取り出す、他のシステムと値をそろえる、の3つに分かれます。 ### Webhook受信時のトークンによる購読の有効化とHMAC-SHA256署名の検証 [Webhookの公式リファレンス](https://developers.notion.com/reference/webhooks)によると、購読を作るとNotionは1回だけ`verification_token`を受信URLへ送ります。その値を開発者ポータルの画面に貼ると購読が有効になり、以後の通知には、このトークンを鍵にして本文をHMAC-SHA256にかけた`X-Notion-Signature`が付きます。受信URLはHTTPSで外部から届く必要があり、localhostは使えません。 ``` import hashlib import hmac import os from flask import Flask, abort, request app = Flask(__name__) TOKEN = os.environ.get("NOTION_WEBHOOK_TOKEN", "").encode() def enqueue(event_type, entity_id): # 実運用ではキューに積み、別プロセスでAPIを呼んで中身を取り直す print(event_type, entity_id) @app.post("/notion/webhook") def receive(): body = request.get_json() if "verification_token" in body: # 購読の作成時に1回だけ届く。値はログに出さず、受信を確かめて画面に貼る return "", 200 raw = request.get_data() # 受け取ったままのバイト列で署名を計算する expected = "sha256=" + hmac.new(TOKEN, raw, hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, request.headers.get("X-Notion-Signature", "")): abort(401) enqueue(body["type"], body["entity"]["id"]) return "", 200 ``` 通知に入るのは種類とページIDなどだけで、中身は受け取ったIDでAPIを呼んで取り直します。`page.content_updated`のような編集の通知は、細かい編集をまとめるため少し遅れて届き、公式の動作確認の手順でも1〜2分待つよう案内されています。即時性が要る処理には向きません。受信側の作り全般は[Webhookの作り方と実装方法｜受信側の署名検証・冪等性と送信側の再送をNode.js・Pythonで解説](https://www.issoh.co.jp/tech/details/1378/)を参照してください。 ### ページをMarkdownで取り出すエンドポイントで社内検索や生成AIへ渡す方法 社内のNotionを検索システムや生成AIの参照データにする場合、ブロックを1つずつたどる必要はなくなりました。[ページをMarkdownで取得する公式リファレンス](https://developers.notion.com/reference/retrieve-page-markdown)の`GET /v1/pages/{page_id}/markdown`は、本文を1つのMarkdown文字列で返します。 ``` curl -s "https://api.notion.com/v1/pages/${PAGE_ID}/markdown" \ -H "Authorization: Bearer ${NOTION_TOKEN}" \ -H "Notion-Version: 2026-03-11" # 応答の項目 # object: "page_markdown" # markdown: ページ本文のMarkdown # truncated: 約2万ブロックを超えて切り詰められたら true # unknown_block_ids: 読めなかったブロックのID（最大100件） ``` 共有されていない子ページやブックマーク、埋め込みは`unknown`のタグになります。`truncated`が`true`なら、`unknown_block_ids`のIDを同じエンドポイントに渡して、残りの本文を取得してください。AIのクライアントから対話的にNotionを読むだけなら、APIを書かずに[Notion MCPサーバーのURL・接続方法まとめ｜mcp.notion.com への接続手順【2026年最新】](https://www.issoh.co.jp/tech/details/6232/)の方法でつなぐほうが早く済みます。 ### 基幹システムとNotionの定期同期で正データをどちらに置くかの決め方 顧客や案件のマスタをNotionと基幹システムの両方に持つなら、どちらを正にするかを最初に決めます。もう一方を読み取り専用の写しにすれば同期は片方向で済み、両方で編集させると衝突を解く規則が要って開発費が一段上がります。 Notionを正にする場合は、Webhookで変更を受けて基幹側へ写します。基幹側を正にする場合は、変更があった行だけを`add_task`のような関数で追加・更新し、毎回の全件書き込みは避けます。毎分180回の枠なら、1行1回の書き込みで1時間に最大1万800行です。共有枠の分を差し引いて、半分程度を上限に見積もると安全です。経路の選び方を発注者の目線でまとめた[Notion連携アプリ一覧と連携方法｜Slack・Jira・GitHub・国産ツールの対応状況【2026年10月】](https://www.issoh.co.jp/column/details/2055/)も、設計前の確認に使えます。 ## 受託開発の視点で見る、Notion APIで個別開発すべき条件と見送る場面 ここからは、連携開発を受ける立場からの判断です。分かれ目は件数と、失敗したときの扱いにあります。 ### 個別開発を選ぶ条件：1日数千行の同期・二重登録の防止・失敗行の再送 次のどれかに当てはまるなら、APIで個別に開発します。1日に数千行以上を同期し、毎分180回の枠と共有枠を自分で配分したいとき。503や再送で行が二重にできることを、外部IDの照合で確実に止めたいとき。失敗した行だけを再送し、理由を記録して担当者に知らせたいとき。 個別開発で継続して必要になる保守は、版の更新、トークンの管理、Webhookの監視です。2025-09-03版と2026-03-11版のように、1年に満たない間隔で書き換えが要る変更が出た実績もあります。要件の整理から実装と保守までをまとめて頼みたい場合は、[API開発・システム連携](https://www.issoh.co.jp/service/system/api/)で連携開発を受け付けています。 ### 個別開発を見送る場面：1日数百件までの転記と標準の連携機能で足りる用途 フォームの回答をNotionの表に1行追加する、Notionの更新をSlackに知らせる、といった1日数百件までの転記に個別開発は過剰です。iPaaSなら画面の設定で組め、担当者が自分で直せます。料金の数え方は[Zapierとは？読み方・できること・料金とタスク課金の仕組み【2026年版】](https://www.issoh.co.jp/tech/details/15956/)で確認してください。 SlackやJira、GitHubのように標準の連携機能がある製品もまずはそれで始め、届かない部分だけをAPIで作り足すのが費用を抑える進め方です。 ## Notion APIのよくある質問：無料プランでの利用・Python・MCPとの違い Notion APIで連携を作る前によく寄せられる質問に、2026年10月時点の公式ドキュメントをもとに回答します。 ### Notion APIは無料プランでも使えますか？ 使えます。Freeのワークスペースでも内部コネクションを作ってAPIを呼べ、接続ごとの上限は毎分180回です。ただしメンバーが2人以上のFreeワークスペースは、累計1,000ブロックを超えて3日の猶予が過ぎると、ページ作成などの書き込みが403になります。本番の連携は有料プランで動かす前提で計画してください。 ### PythonでNotion APIを使うにはどのライブラリを選べばよいですか？ Notionが公開している公式SDKはJavaScript向けの`@notionhq/client`です。Pythonでは、[notion-sdk-py](https://github.com/ramnes/notion-sdk-py)がPyPIで`notion-client`として配布されており、2026年5月公開の3.1.0系はデータソースのクエリに対応しています。依存を増やしたくないなら、この記事のように`requests`で直接呼んでも数十行で書けます。 ### NotionのAPIとNotion MCPはどう使い分ければよいですか？ 自社のプログラムが決まった処理を繰り返すならAPI、ClaudeやChatGPTのようなAIの画面から人が対話的にNotionを読み書きするならMCPです。MCPはOAuthで接続し、ツールの応答は`Notion-Version`の版管理の対象外です。定期実行の同期やWebhookの受信のように、入出力の形を固定したい処理にはAPIを選んでください。 ### 古い記事のdatabases/{id}/queryのコードはまだ動きますか？ 旧版を指定していれば、データソースが1つのデータベースでは動きます。公式の説明では、古い版の提供を終える予定は今のところ無いという方針です。ただし利用者がデータベースに2つ目のデータソースを足すと、旧版のクエリやページ作成は失敗します。JavaScriptのSDKはv5.0.0から2022-06-28以前の版を扱わなくなったので、SDKの更新と合わせて移すのが確実です。 ### APIがobject\_not\_foundを返すときは何を確かめればよいですか？ 最初に、対象のページかデータベースがコネクションに共有されているかを確かめます。内部コネクションは、Add connectionsで追加したページとその子ページにしか届きません。次に、データベースIDとデータソースIDを取り違えていないかを見ます。 ## 関連記事 - [Notion連携アプリ一覧と連携方法｜Slack・Jira・GitHub・国産ツールの対応状況【2026年10月】](https://www.issoh.co.jp/column/details/2055/)：APIを書く前に検討する標準連携とiPaaSの経路 - [Notion MCPサーバーのURL・接続方法まとめ｜mcp.notion.com への接続手順【2026年最新】](https://www.issoh.co.jp/tech/details/6232/)：AIクライアントからNotionへつなぐ場合の手順 - [社内wikiのおすすめツール比較｜選定軸とSaaS・OSS・自社開発の判断基準](https://www.issoh.co.jp/column/details/15955/)：Notionを社内wikiに選ぶかどうかの比較 - [DifyをPodmanのrootlessで動かす手順とNotion連携の設定](https://www.issoh.co.jp/tech/details/2791/)：Notionの本文を生成AIの参照データにする構成例 - [Salesforceのシステム連携とは？API方式の選定とコール上限の設計を実装目線で解説](https://www.issoh.co.jp/tech/details/16155/)：別の業務SaaSでのAPI上限の設計例 --- 出典: [Notion APIとは？データソース対応の使い方とレート制限・社内連携の実装【2026年10月】]()（株式会社一創）