【Notion API】2025-09-03アップグレード完全ガイド - マルチソースデータベース対応とSDK v5移行

Notion API バージョン 2025-09-03 では、マルチソースデータベースという大きなアーキテクチャ変更が導入されました。これまで「データベース」として一体だった概念が「データベース」と「データソース」に分離され、API のエンドポイントや SDK にも破壊的変更が入っています。

この記事では、既存の Notion API 連携を 2025-09-03 バージョンに安全にアップグレードする手順を解説します。

データモデルの変更点

旧モデル（2025-09-03 より前）

従来は「データベース」がスキーマ（プロパティ定義）とページの両方を管理していました。database_id さえあれば、スキーマの取得もページのクエリも可能でした。

新モデル（2025-09-03）

新しいデータモデルでは、3 つの階層に分離されています。

エンドポイントの変更一覧

主要なエンドポイントの変更をまとめます。

アップグレード手順

Step 1: data_source_id の取得

まず、既存の database_id から data_source_id を取得するステップを追加します。

// 2025-09-03 バージョンで databases.retrieve を呼ぶと
// data_sources 配列が返される
const db = await notion.databases.retrieve({
  database_id: DATABASE_ID,
});

// data_sources[0].id が data_source_id
const dataSourceId = db.data_sources[0].id;
console.log("Data Source ID:", dataSourceId);

Step 2: parent 参照の更新

ページ作成時の parent を database_id から data_source_id に変更します。

await notion.pages.create({
  parent: {
    type: "data_source_id",
    data_source_id: dataSourceId,
  },
  properties: { /* ... */ },
});

await notion.pages.create({
  parent: {
    type: "database_id",
    database_id: databaseId,
  },
  properties: { /* ... */ },
});

Step 3: エンドポイントの移行

データベース操作を Data Source エンドポイントに移行します。

スキーマ取得

// Before
const schema = await notion.databases.retrieve({
  database_id: DATABASE_ID,
});

// After
const schema = await notion.dataSources.retrieve({
  data_source_id: dataSourceId,
});

ページクエリ

// Before
const pages = await notion.databases.query({
  database_id: DATABASE_ID,
  filter: { /* ... */ },
});

// After
const pages = await notion.dataSources.query({
  data_source_id: dataSourceId,
  filter: { /* ... */ },
});

スキーマ更新

// Before
await notion.databases.update({
  database_id: DATABASE_ID,
  properties: { /* ... */ },
});

// After
await notion.dataSources.update({
  data_source_id: dataSourceId,
  properties: { /* ... */ },
});

Step 4: Search API の更新

検索 API のフィルタ値を変更します。

// Before
const results = await notion.search({
  filter: {
    value: "database",
    property: "object",
  },
});

// After
const results = await notion.search({
  filter: {
    value: "data_source",
    property: "object",
  },
});

Step 5: SDK v5 へのアップグレード

npm install @notionhq/client@^5

SDK v5 では新しいメソッドが使えるようになります。

import { Client } from "@notionhq/client";

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
});

// 新しい SDK メソッド
await notion.dataSources.retrieve({ data_source_id: "..." });
await notion.dataSources.query({ data_source_id: "..." });
await notion.dataSources.update({ data_source_id: "...", properties: {} });

Step 6: Webhook の更新（該当する場合）

Webhook を使用している場合、イベントタイプが変更されています。

新しく追加されたイベントもあります。

• data_source.created
• data_source.moved
• data_source.deleted
• data_source.undeleted

実践例: Netlify Functions での移行

Netlify Functions で Notion API を使っている場合の具体的な移行例です。

// netlify/functions/fetchNotion.ts
import { Client } from "@notionhq/client";

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
});

const DATABASE_ID = process.env.NOTION_DATABASE_ID;

export async function handler() {
  try {
    // Step 1: data_source_id を取得
    const db = await notion.databases.retrieve({
      database_id: DATABASE_ID,
    });
    const dataSourceId = db.data_sources[0].id;

    // Step 3: Data Source エンドポイントでクエリ
    const response = await notion.dataSources.query({
      data_source_id: dataSourceId,
    });

    return {
      statusCode: 200,
      body: JSON.stringify(response.results),
    };
  } catch (error) {
    console.error("Notion API Error:", error);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: error.message }),
    };
  }
}

移行時の注意点

後方互換性について

旧 API バージョンの廃止日は発表されていませんが、ユーザーがデータソースを追加するだけで旧 API が壊れるため、早めの移行が推奨されます。

よくあるエラーと対処法

validation_error: database has multiple data sources

データベースに複数のデータソースがある状態で旧エンドポイントを使った場合に発生します。data_source_id を使うエンドポイントに移行してください。

object_not_found: data source not found

data_source_id が間違っているか、インテグレーションにデータソースへのアクセス権がありません。databases.retrieve で最新の data_source_id を再取得してください。

参考文献

• Upgrading to Version 2025-09-03 - Notion Developer Docs
• FAQs: Version 2025-09-03 - Notion Developer Docs
• Notion API Changelog
• @notionhq/client - npm

まとめ

Notion API 2025-09-03 の主な変更は、「データベース」と「データソース」の分離です。移行の核心は以下の 3 点です。

1. databases.retrieve で data_source_id を取得するステップを追加する
2. databases.query / databases.update を dataSources.query / dataSources.update に置き換える
3. SDK を v5 にアップグレードする

旧 API はユーザーがデータソースを追加するだけで壊れるため、早めの対応をおすすめします。