Notion API入門

この記事は、Notion APIドキュメントを独自翻訳し、筆者の言葉に直して非開発者でも理解できるよう編集したものです。

本記事は「Introduction to Notion’s API」のページを元にした解説しています。

また基本的な専門用語等の説明について、そのすべては解説していません。
その言葉の定義や概念が複雑な場合、または文章の前後を理解するにあたって説明が必要であると判断した場合など、筆者の判断にて補足説明するに留めています。

Notion APIでできること

仮にあなたが、Notion APIのプログラムを組み込んだコンテンツを作成するとしましょう。

Notion APIを利用すると、あなたの作ったコンテンツはユーザーのワークスペースにアクセスして情報をやり取りできるようになります。

Noton APIを利用するにあたり、以下の要件を意識する必要があります。

Notion APIは、プログラムがユーザーの情報にアクセスしてさまざまな作業を自動化できる便利なツールです。

しかしNotion APIによる自動化された作業は、所有権を持つユーザーの作業ではありません。よってNotion は、Notion APIがユーザーのワークスペース内情報へアクセスできるようにするため、API経由のリクエストをボットに帰属させることでそれを許可しています。

具体的には、開発者によるインテグレーションの構築と、ボットへのAPIリクエストの許可という2つのプロセスが必要です。

Notion APIを使用したコンテンツ開発は、Notionに用意された大規模なライブラリ（部品化されたプログラム）を利用することで実現します。

Notion APIのライブラリを利用するにあたり、「インテグレーション」は絶対に覚えてなければならない概念です。

Notion APIにおけるインテグレーションとは、ワークスペースや個別のページを接続するプログラムの概念です。（インテグレーションの日本語訳は「統合、一体化」）「Notion APIを使用するための設定」と考えても差し支えありません。

インテグレーションは「Internal（以下、「インターナル」）」と「Public（以下、「パブリック」）」の2種類に分かれています。

ワークスペース内のメンバーのみが使用できるインテグレーション。
インターナルインテグレレーションの作成や追加は、そのワークスペースのオーナーでなければいけません。

特定のワークスペース内でだけ使用するインターナルとは対照的に、どのワークスペースのNotionユーザーでも使用できるインテグレーション。

Notion APIは身内で使用するインターナルと、外部ユーザーも使用できるパブリックとで分かれています。それぞれインテグレーションの構築方法や利用までのプロセスは異なりますが、内部的な仕組みは基本的に同じです。

インテグレーションとNotion APIを理解するには、下図の4者をイメージすると良いでしょう。

Notion APIを組み込んだコンテンツ利用には、一般的に以下の4者間におけるプロセスを完了させる必要があります。

具体的な流れを掴むには、次回以降の記事を順番に読んでいただくことを推奨します。
よってここでは、全体的な流れのイメージ図のみ紹介させていただきます。

【Notion API利用までの流れ～前半～】

【Notion API利用までの流れ～後半～】

Notion APIは仕組みが意外と複雑なため、上図のように前半と後半で分けてイメージすると理解が深まるでしょう。（開発者なら常識の範囲かもしれませんね💦）

Notion APIの公式ドキュメントでは、データインテグレーションやリンクプレビューインテグレーション、アイデンティティ管理インテグレーションといった内容まで説明されています。しかし本記事では、特に非開発者向けの解説としては理解しづらい項目であると判断して省略いたしました。

この記事以降も、本ブログにおけるNoton APIの解説は非開発者向けとして省略、要約が行われますので、あらかじめご了承ください。