Notion APIのデータベース操作APIに破壊的変更があったので、実装を修正してみる
Notion APIはバージョン2025-09-03において、データベースの概念を根本的に変更しています。
従来の単一データベースモデルからマルチソースデータベースモデルへと移行し、これに伴い後方互換性のない破壊的変更が導入されました。
詳細は以下の公式ドキュメントをご確認いただきたいのですが、ここでは私が実際に触ってみてつまづいたところをまとめていきます。
主要な変更点
APIエンドポイントの移行
Most API operations that used
database_idnow require adata_source_id
- 従来:
databases.query({ database_id }) - 新仕様:
dataSources.query({ data_source_id })
新しい@notionhq/client v5.2.1ではdatabasesオブジェクトにqueryメソッドが存在しないため、型エラーになることが発生します。
GitHub Actionsからactions/github-scriptを用いてNotionへのアクセスを行おうとした結果、以下のような型エラーが発生しました。
import type { Client } from '@notionhq/client';
export type NotionClient = Client;
// プロパティ 'query' は型 '{ retrieve: (args: WithAuth<GetDatabasePathParameters>) => Promise<GetDatabaseResponse>; create: (args: WithAuth<CreateDatabaseBodyParameters>) => Promise<...>; update: (args: WithAuth<...>) => Promise<...>; }' に存在しません。
export type NotionDatabaseQueryResult = Awaited<
ReturnType<NotionClient['databases']['query']>
>;
このように修正すれば型エラーは発生しなくなります。
import type { Client } from '@notionhq/client';
export type NotionClient = Client;
export type NotionDataSourceQueryResult = Awaited<
ReturnType<NotionClient['dataSources']['query']>
>;
IDの取得方法の変更
従来のデータベースIDの取得方法は、290779d04d0280548d2be29e12530de6の部分を設定すればよかったのですが、新しくデータソースIDという概念が登場しました。
実際にデータベースを開いて、データベース設定 → "データベースを管理する" → "⋯" → "データソースIDをコピー"で取得することができます。
データソースIDは290779d0-4d02-808a-a37f-000b48c16318のようなハイフン付きのIDが取得可能です。
以下のようなコードで取得したデータソースへアクセスが可能です。
const notionToken = process.env.NOTION_TOKEN;
const dataSourceId = process.env.NOTION_DATA_SOURCE_ID;
const notion = new Client({ auth: notionToken });
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
page_size: 5,
});
実装時の注意点
開発時はClaude CodeでContext7等のドキュメント検索ツールを使用していましたが、まだドキュメントの修正が追いついておらず、取得される情報は旧APIバージョンに基づいている場合が多かったです。
特に以下の点に注意する必要があります。
- 例示されている
databases.queryは現在の最新SDKでは利用できない -
database_idパラメータはdata_source_idに置き換える必要がある
参考資料
Discussion