Notion Management スキル

Node.js/JavaScript 開発向けの Notion API を使いこなすためのマスターガイドです。このスキルは、すべての一般的な Notion 操作のパターン、ツール、リファレンスを提供します。

クイックスタート

Notion リソースの取得

// ページまたはデータベースを取得
const page = await notion_notion-fetch({
  id: "page-id-or-url"
});

// ページはマークダウン コンテンツとプロパティを返す
// データベースはスキーマ、データソース、ビューを返す

ページの作成

// 単一ページの作成
const pages = await notion_notion-create-pages({
  pages: [{
    properties: {
      title: "My Page Title",
      // データベーススキーマに基づく他のプロパティ
    },
    content: "# Markdown content here\n\nSupports rich markdown."
  }],
  parent: {
    data_source_id: "collection-id" // またはpage_id、database_id
  }
});

ページの更新

// プロパティを更新
await notion_notion-update-page({
  page_id: "page-id",
  command: "update_properties",
  properties: {
    title: "Updated Title",
    status: "Done"
  }
});

// すべてのコンテンツを置き換え
await notion_notion-update-page({
  page_id: "page-id",
  command: "replace_content",
  new_str: "# New content here"
});

// 特定のセクションを置き換え
await notion_notion-update-page({
  page_id: "page-id",
  command: "replace_content_range",
  selection_with_ellipsis: "# Old heading...last paragraph.",
  new_str: "# New heading\nNew content"
});

// セクションの後にコンテンツを挿入
await notion_notion-update-page({
  page_id: "page-id",
  command: "insert_content_after",
  selection_with_ellipsis: "## Section...end of section.",
  new_str: "\n## New Section\nNew content here"
});

一般的なプロパティ型とフォーマット

シンプルなプロパティ

• title (文字列): ページタイトル、大きな見出しとして表示
• rich_text (文字列): テキストフィールド
• url (文字列): URL フィールド
• email (文字列): メールフィールド
• phone_number (文字列): 電話番号
• checkbox (文字列): "__YES__" または "__NO__" を使用
• number (数値): 文字列ではなく JavaScript の数値を使用

選択プロパティ

// single_select: オプション名をそのまま使用
properties: {
  Status: "In Progress"  // 正確なオプション名と一致する必要があります
}

// multi_select: 単一文字列またはカンマ区切り
// ❌ 間違い: ["option1", "option2"]  // 配列を使用しないでください
// ❌ 間違い: "option1,option2"       // カンマを使用しないでください
// ✅ 正解: 別の API 呼び出しまたは特定のフォーマットを使用する必要があります

日付プロパティ

// 日付プロパティは3つのキーを持つ拡張フォーマットを使用
properties: {
  "date:Due Date:start": "2025-01-30",
  "date:Due Date:end": null,  // 終了日付は任意
  "date:Due Date:is_datetime": 0  // 日付は0、日時は1
}

場所プロパティ

// 場所/ロケーション プロパティは拡張フォーマットを使用
properties: {
  "place:Office:name": "HQ",
  "place:Office:address": "123 Main St",
  "place:Office:latitude": 37.7749,
  "place:Office:longitude": -122.4194,
  "place:Office:google_place_id": "optional-id"
}

特別なプロパティ名

「id」または「url」という名前のプロパティ（大文字小文字を問わず）には「userDefined:」プレフィックスを付ける必要があります：

properties: {
  "userDefined:id": "value",
  "userDefined:URL": "https://example.com"
}

マルチセレクトフィールド - 重要

よくある間違い: マルチセレクトフィールドは厳密な検証があります。マルチセレクトプロパティを持つデータベースでページを作成または更新する場合：

1. 最初にデータベースを取得 して利用可能なオプションを確認してください：

   const db = await notion_notion-fetch({ id: "database-id" });
   // レスポンスは以下を示します: "Tags": {"options": [{"name": "Option1"}, {"name": "Option2"}]}
   

2. 有効なオプション名のみを使用してください：

   properties: {
     Tags: "Option1"  // 単一オプションを文字列として指定
   }
   

3. 複数のオプションの場合: 現在、API に制限があります。ベストプラクティス：

   • 1つのタグを付けてページを作成
   • 必要に応じて、追加のタグで更新
   • または特定のフォーマットで区切られた複数のタグを渡す（データベーススキーマを確認）

4. エラー処理: 「Invalid multi_select value」エラーが発生した場合は、以下を確認してください：

   • オプション名がデータベースに表示されているとおりに正確に綴られていますか？
   • 配列ではなく文字列を渡していますか？
   • データベーススキーマでこのオプションが許可されていますか？

データベース操作

データベーススキーマの取得

const db = await notion_notion-fetch({
  id: "database-id-or-url"
});

// 以下を返します：
// - データベースのタイトルとアイコン
// - データベース内のデータソース（コレクション）
// - 各データソースのスキーマ
// - 利用可能なビュー

データベースの作成

const db = await notion_notion-create-database({
  title: [{type: "text", text: {content: "My Database"}}],
  parent: {page_id: "parent-page-id"},
  properties: {
    "Task Name": {type: "title"},
    "Status": {
      type: "select",
      select: {
        options: [
          {name: "To Do", color: "red"},
          {name: "In Progress", color: "yellow"},
          {name: "Done", color: "green"}
        ]
      }
    },
    "Due Date": {type: "date"}
  }
});

データベーススキーマの更新

await notion_notion-update-database({
  database_id: "db-id",
  title: [{type: "text", text: {content: "New Title"}}],
  properties: {
    "New Property": {type: "rich_text"},
    "Property to Rename": {name: "Renamed Property"},
    "Property to Delete": null  // 削除するには null に設定
  }
});

コンテンツ（マークダウン）ガイドライン

サポートされているマークダウン

• 見出し: # H1、## H2 など
• リスト: 箇条書き - item、番号付き 1. item
• コード: インライン `code` とコードブロック
• 太字/イタリック: **bold**、*italic*
• リンク: [text](url)
• テーブル: 完全なマークダウン テーブル対応
• 引用: > quoted text
• トグル/折りたたみ: ▶ Collapsed content\n\tHidden items（注：タブでインデント）

トグル/折りたたみセクション

トグルは ▶ 文字の後に非表示にするコンテンツが続いて作成されます：

▶ Click to expand
	Hidden content line 1
	Hidden content line 2
	- Nested list item

重要: ▶ の後のコンテンツはタブまたはスペースでインデントする必要があります。

リッチテキスト アノテーション

コンテンツに色とスタイルのアノテーションを含めることができます：

# Heading {color="blue"}
Some text {color="red"} and {bold="true"}

検索とナビゲーション

Notion を検索

const results = await notion_notion-search({
  query: "search term",
  query_type: "internal"  // またはユーザー検索の場合は "user"
});

// 作成日で絞り込み
const filtered = await notion_notion-search({
  query: "recent docs",
  filters: {
    created_date_range: {
      start_date: "2025-01-01",
      end_date: "2025-01-31"
    }
  }
});

チームとユーザーの取得

// チームを一覧表示
const teams = await notion_notion-get-teams({
  query: "engineering"  // オプションの検索
});

// ユーザーを一覧表示
const users = await notion_notion-get-users({
  query: "john",  // オプションの検索
  page_size: 100
});

// 特定のユーザーを取得
const user = await notion_notion-get-users({
  user_id: "user-id-or-self"
});

エラーハンドリング

一般的なエラーと解決策

「Invalid multi_select value」

原因: オプション名が存在しないか、フォーマットが間違っている 解決策:

1. データベースを取得して有効なオプションを確認
2. 正確なオプション名を使用
3. 配列ではなく文字列として渡す

「Invalid input」/ 検証エラー

原因: 不正なプロパティフォーマットまたは型 解決策:

1. データベーススキーマでプロパティ型を確認
2. 正しいフォーマットを使用（例：日付プロパティは date:Property:start フォーマットが必要）
3. 特別な名前が userDefined: プレフィックスを使用していることを確認

「Page not found」

原因: ID が間違っているか、権限不足 解決策:

1. ページ/データベース ID が正しいことを確認
2. リソースへのアクセス権があることを確認
3. ID が機能しない場合はフルURL を使用

「Unauthorized」

原因: Notion インテグレーションに権限がない 解決策:

1. インテグレーションがデータベース/ページと共有されていることを確認
2. Notion の設定でインテグレーション スコープを確認
3. 必要に応じて再認証

ベストプラクティス

1. 常に最初に取得: データベースにコンテンツを作成する前に、データベースを取得してスキーマを理解
2. オプション名を検証: マルチセレクト オプションは厳密に検証されるため、正確なスペルをチェック
3. データベースに data_source_id を使用: データベースに複数のデータソースがある場合は、親として database_id の代わりに data_source_id を使用
4. ID を柔軟に処理: ほとんどのツールはダッシュの有無にかかわらずページ ID を受け入れます
5. コンテンツのインデント: トグル/折りたたみコンテンツはタブまたはスペースでインデントする必要があります
6. 複雑な更新を分割: 大きなコンテンツ更新は、小さな操作に分割した方がより安全
7. シンプルなケースで最初にテスト: 複雑な自動化の前に、単一のページ/フィールドでテスト
8. 環境を文書化: Notion インテグレーション トークンは安全に保存し、git には含めない

高度なパターン

詳細については references/advanced-patterns.md を参照してください：

• バッチ操作とパフォーマンス最適化
• 外部データを Notion に同期
• 動的データベースとビューの作成
• リレーションシップとロールアップの処理
• 複雑なフィルタリングとソート