第2章開発環境のセットアップと認証

Notion API を利用するためのインテグレーション作成、認証トークンの取得、対象ページへのアクセス権限の付与、および Python 開発環境の構築手順を解説します。

1. インテグレーションの作成

Notion API を利用するには、まず Notion の開発者ポータルで インテグレーション（Integration） を登録する必要があります。インテグレーションとは、外部プログラムと Notion ワークスペースを仲介する専用アカウントのようなものです。

Web ブラウザで Notion Developers にアクセスします。
画面右上の「新しいインテグレーション（New integration）」ボタンをクリックします。
基本情報を入力します：
- 名前: プログラムの目的がわかる名前（例: My Notion Bot）を入力します。
- 関連付けられたワークスペース: API を利用したいワークスペースを選択します。
- 機能（Capabilities）: コンテンツの読み取り、更新、挿入に必要な権限にチェックを入れます。
「保存」をクリックすると、インテグレーションが作成されます。

2. 内部インテグレーションシークレットの取得

インテグレーションが作成されると、「シークレット」タブに 内部インテグレーションシークレット（Internal Integration Secret） が表示されます。この文字列は secret_... または ntn_... から始まります。

このシークレットは、Notion に「誰からのリクエストか」を証明するパスワードのような重要情報です。絶対に他人に教えたり、GitHub などの公開リポジトリにコミットしたりしないでください。

3. ページやデータベースへの接続権限の付与

インテグレーションを作成しただけでは、ワークスペース内のデータには一切アクセスできません。プログラムから操作したいページやデータベースごとに、個別にアクセスを許可（コネクトを追加）する必要があります。

Notion アプリまたはブラウザで、操作対象のページまたはデータベースを開きます。
画面右上の「…」（その他のオプション）メニューを開きます。
メニュー下部の「接続（Connect to）」または「コネクト」を選択します。
作成したインテグレーション名（例: My Notion Bot）を検索して選択し、アクセスを許可します。

親ページへのアクセスを許可すると、そのページ配下にある子ページやデータベースにも自動的に権限が継承されます。

4. ページIDとデータベースIDの確認方法

API からページやデータベースを特定するには、32 桁の 16 進数で構成される一意の ID を指定します。 ID は、ブラウザで対象のページを開いた際の URL から簡単に取得できます。

https://www.notion.so/myworkspace/My-Database-Title-a1b2c3d4e5f67890123456789abcdef0?v=...

URL 内のタイトル名に続くハイフン後の 32 文字（上記例では a1b2c3d4e5f67890123456789abcdef0）が ID です。クエリパラメータ（?v=... 以降）は不要です。ハイフンが含まれている形式でも、ハイフンなしの形式でも、どちらでも API に指定可能です。

5. Python環境のセットアップ

Python で Notion API を操作するために、必要なライブラリをインストールします。

pip install notion-client requests python-dotenv

notion-client: Notion 公式が提供する Python SDK です。API の呼び出しや型ヒント、自動エラーハンドリングが組み込まれています。
requests: Python で最も広く使われている HTTP 通信ライブラリです。SDK を使わずに生の REST API を直接操作する場合に利用します。
python-dotenv: .env ファイルに記述した環境変数を Python コードから読み込むためのライブラリです。

6. 認証情報の安全な管理

シークレットキーをプログラムコードに直接書き込むのは危険です。作業ディレクトリ内に .env ファイルを作成し、環境変数として管理します。

NOTION_TOKEN=secret_your_actual_integration_secret_here
NOTION_DATABASE_ID=a1b2c3d4e5f67890123456789abcdef0

.gitignore ファイルに .env を追加して、Git の管理対象から除外することを忘れないようにしましょう。

7. 疎通確認スクリプト

環境変数を読み込んで、Notion API と正常に通信できるかを確認する簡単な Python スクリプトを作成します。

import os
from dotenv import load_dotenv
from notion_client import Client

# .env ファイルから環境変数を読み込む
load_dotenv()

notion_token = os.getenv("NOTION_TOKEN")
if not notion_token:
    raise ValueError("NOTION_TOKEN が設定されていません。")

# クライアントの初期化
notion = Client(auth=notion_token)

# 自身のインテグレーション（Bot）情報を取得
bot_user = notion.users.me()
print("接続成功！")
print(f"Bot 名: {bot_user.get('name')}")
print(f"Bot ID: {bot_user.get('id')}")

このスクリプトを実行し、「接続成功！」と Bot 名が表示されれば、環境構築と認証設定は完了です。

Keyboard shortcuts