【Notion APIの基本操作】データ操作の基本と実践方法

Notion APIの概要

Notion APIは、Notionのデータベースやページとプログラムでやりとりするためのツールです。

これにより、Notionの情報を他のアプリケーションと連携させたり、自動化したりすることができます。

Notion APIは、プログラムを通じてNotionのデータにアクセスし、操作することを可能にするインターフェースです。

実行可能なこととしては、以下のことが挙げられます。

• データベースの作成、読み取り、更新(削除)
• ページの作成、更新(削除)
• ユーザー情報（プロファイルと権限）にアクセス
• ページコメントとインラインコメントを処理
• ワークスペースのコンテンツを検索
• 認証で、OAuth2.0による安全な統合
• 共有時にリンクがどのように表示されるかをカスタマイズ

※これらの機能を使うには、「インテグレーション」と呼ばれる接続設定を作成する必要があります。

Notion APIのセットアップ

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

Notion APIを利用するにあたって、まずはインテグレーションを作成します。

インテグレーションをすることによって、Notionのワークスペースのデータを他のアプリケーションにリンクさせたり、Notion内でワークフローを自動化したりすることが可能です。

インテグレーションの手順は以下となります。

1. NotionのMy Integrationsページにアクセス

   

2. 「新しいインテグレーション」をクリック
3. 名前を付け、関連するワークスペースを選択し、保存
4. 作成完了

APIトークンの取得

インテグレーション作成後、作成したインテグレーションをクリック。

すると、「内部インテグレーションシークレット」という形でAPIトークンが表示されます。

※このトークンはAPIを叩くときに使用するので、安全に保管してください。

NotionのデータベースIDを取得

今回は、Notion APIを使ってあるデータベースの期間内の値を取得し、他のページのデータベースにデータを作成する実装を通して、Notion APIの基本的な操作を紹介します。

※ページ構造は以下です。

これにあたって、データを取得するデータベースIDとデータを作成するページIDが必要です。

データベースIDは以下の手順で取得します。

1. Notionで対象のデータベースを開く
2. データベースの…をクリックし、ビューのリンクをコピー

   

3. URLから以下の形式のIDを見つける

→https://www.notion.so/<データベースID>?v=... となっているため、<データベースID> の値を取得

NotionのページIDを取得

ページIDの取得もデータベースIDの取得と同様です。

1. Notionで対象のページを開く
2. ページの…をクリックし、リンクをコピー

   

3. URLから以下の形式のIDを見つける

→https://www.notion.so/<ページID>?pvs=... となっているため、<ページID> の値を取得

これで、NotionのデータベースIDとページIDを取得する操作は以上です。

Notionのページにインテグレーションを追加

Notion APIを利用するためには、ページにインテグレーションを追加する必要があります。

Notionのページにインテグレーションを追加する方法は簡単です。

まず、Notion APIを利用したいページの…をクリックします。

そして、コネクト/先ほど作成したインテグレーションを選択。

以下のようなダイアログが表示されるので、”はい”をクリック。

インテグレーションの追加が完了すると、”コネクト”の部分に接続したインテグレーションが表示されます。

これで、完了です！

Notion APIを利用

Notion APIのセットアップが完了したので、実行していきます。

実行内容としては、

• データベースから値を取得(条件：期間内)
  • ページネーションを利用

• ページにデータを追加
• データを削除（おまけ）

を行います。

今回の実装は、Node.jsでNotion APIを実行していくので、予め以下の項目を行いました。

• @notionhq/client をインストール
  • notionClientを定義

 export const notionClient = new Client({ auth: process.env.NOTION_TOKEN })

• .envファイルにNotion APIを定義
  • インテグレーション一覧画面から、該当のインテグレーションを選択し”内部インテグレーションシークレット”をコピーして、.envファイルに定義

  NOTION_TOKEN="内部インテグレーションシークレットの値"

​データベースから値を取得

データベースから値を取得する実装を行います。

データベースの取得は、Clientのretrieve メソッドを使用します。

実装例は以下です。

const db = await notionClient.databases.retrieve({
      database_id: ”エニテック テスト用データのデータベースID”,
    })

次に、データベースの値を取得する実装を行います。

今回は、プロパティとして作業名(テキスト)、開始(日付)、作業時間(h:数値)のデータを実験用に123件作成しました。

データベースから、データを取得するには、Clientのqueryを使用します。

実装例は以下です。

const rowsQuery = await notionClient.databases.query({
      database_id: ”エニテック テスト用データのデータベースID",
      filter: {
        and: [
          {
            property: '開始',
            date: { on_or_after: startDate.toISOString() },
          },
          {
            property: '開始',
            date: {
              on_or_before: endDate.toISOString(),
            },
          },
        ],
      },
      sorts: [{ property: '開始', direction: 'descending' }],
      page_size: 100,
    })

今回は、指定した期間内のデータのみを取得できるようにandを実行しました。

ページを作成

続いて、取得したデータを別のページのデータベース内に作成する実装をします。

ページの作成は、Clientのcreateを使用します。

実装例は以下です。

await notionClient.pages.create({
      parent: { database_id: "エニテック 実行後のデータのデータベースID" },
      properties: {
        ...rowsQuery.results,
      },
    })

これで、データベースのデータを取得から、別のデータベース上に作成する実装を行いました。

実行した結果が以下です。

※ 今回は、curl http://localhost:8080で実行しました。

取得されたデータを元に、別のデータベース上にデータを作成していることがわかります。

実行後のデータが以下です。

今回の実行で、データベース上に100件データが作成されていることがわかります。

しかし、元のデータベース上には123件のデータが存在しており、全てのデータを取得できていません。

これは、.create の page_size の取得の最大値が100件(デフォルト：100件)となっているからです。

Notion APIIntroduction​

そのため、100件以上のデータを取得するためには、ページネーションを実装する必要があります。

ページネーションを実装

Notion APIにはページネーションが実装されています。

has_moreやnext_cursorを使用して、ページネーションを実装します。

Notion APIIntroduction​

ページネーションの実装例は以下です。

 let allRows: PageObjectResponse[] = []
    let hasMore = true
    let startCursor: string | undefined = undefined

    while (hasMore) {
      const rowsQuery = await notionClient.databases.query({
        database_id: "エニテック テスト用データのデータベースID",
        filter: {
          and: [
            {
              property: "開始",
              date: { on_or_after: startDate.toISOString() },
            },
            {
              property: "開始",
              date: {
                on_or_before: endDate.toISOString(),
              },
            },
          ],
        },
        sorts: [{ property: "開始", direction: 'descending' }],
        page_size: 100,
        start_cursor: startCursor,
      })

      allRows = allRows.concat(rowsQuery.results as PageObjectResponse[])
      hasMore = rowsQuery.has_more
      startCursor = rowsQuery.next_cursor || undefined
    }

    return allRows

その実行結果が以下となります。

このように、page_sizeのデフォルトで最大値である100件以上のデータを取得できていることが分かります。

これで、Notion APIを使って、データベースから値の取得からページの作成まで実装することができました！

おまけ：ページの削除

Notion APIでデータを削除するときは、archived:trueでデータを削除することができます。

これによって、archived されたデータは、ゴミ箱に移動されるため、復元することも可能です。

実装例は以下です。

await notionClient.pages.update({
  ...
  archived: true
})