Notion API エンドポイント全て使ってみる「Databases」編
はじめに
最近 Notion API を利用した開発をするようになり、その中でもよく利用する Databases 周りに関する情報をとありあえずまとめてみた記事です。
対象
- Notion API を普段から利用している方
- Notion API の詳細が気になるけど調べるのが面倒な方
- Notion API でどんな機能があるのか気になる方
概要
Notion API では様々なエンドポイントが用意されています。
その中でも今回は「Databases」に関する機能にフォーカルを当て
Todoリストを作成していきます。
※今回はAPIをPostman経由でたたいております。
Notion API とは
今回は普段利用されている前提
詳細は下記公式ページを参照ください
Databasesで用意されているエンドポイント
- Create a databases
- Filter database entries
- Sort databases entries
- Query a database
- Retrieve a database
- Update a database
- (Update database properties)
以降はそれぞれのエンドポイントに関する概要と
実際のNotionイメージと共にまとめていきます。
Create a database
指定した親ページの子ページとしてデータベース自体を作成することが可能なAPIとのこと。
さっそくNotion上に親ページを作成し、子ページとしてデータベースを作成していきます。
今回はインライン化した状態で作成したかったのでis_inlineオプションなど利用しています。
他にもたくさんプロパティが用意されているのでまた別の記事で作成しようかなと思います。
リクエストに使用したJSON
{
"parent": {
"type": "page_id",
"page_id": "hogehogehogehogehogehogehogehoge"
},
"is_inline": true,
"icon": {
"type": "emoji",
"emoji": "📝"
},
"cover": {
"type": "external",
"external": {
"url": "https://images.unsplash.com/photo-1484480974693-6ca0a78fb36b?ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&w=1744&q=80"
}
},
"title": [
{
"type": "text",
"text": {
"content": "Todo List",
"link": null
}
}
],
"properties": {
"Title": {
"title": {}
},
"Description": {
"rich_text": {}
},
"Status": {
"select": {
"options": [
{
"name": "Not Started",
"color": "red"
},
{
"name": "In Progress",
"color": "yellow"
},
{
"name": "Complete",
"color": "green"
}
]
}
},
"Created time": {
"id": "AJP%7D",
"name": "Created time",
"type": "date",
"date": {}
}
}
}
実際に上記リクエストで作成されたDatabase
セレクトの値なども入力した通り登録されている
Filter database entries
指定した条件でデータを取得できるか確認し対時に利用するAPIです。
先ほど作成したDatabaseに動作確認用の新規レコードを追加しておきます。
画面のイメージではFilterの条件を下記に設定した状態と同等のレスポンスとなります。
- StatusプロパティがComplete
リクエストに直すと下記JSONのようになります
{
"filter": {
"property": "Status",
"select": {
"equals": "Complete"
}
}
}
Sort database entries
任意のプロパティに対し、昇順・降順を指定できるAPIです。
作成したTodo Listを作成日の降順で表示させた場合の画面のイメージ
リクエストに直すと下記JSONのようになります
{
"sorts": [
{
"property": "Created time",
"direction": "descending"
}
]
}
Query a database
リクエストで指定されたフィルタ条件とソート条件によりデータベースのレコードを取得するAPIです。
レスポンスの next_cursor という値は page_size で指定した数よりも対象となるレコードが多い場合に値がセットされます。その場合は next_cursor にセットされた値を利用し、反復処理を行うことで残りのデータを取得することができます。
今回取得する情報について
- Filter：StatusがComplete
- Sort：Created timeの降順
画面イメージ
リクエスト
{
"filter": {
"property": "Status",
"select": {
"equals": "Complete"
}
},
"sorts": [
{
"property": "Created time",
"direction": "descending"
}
]
}
Retrieve a database
指定されたデータベース ID のデータベースオブジェクト（データベースの構造とカラムを記述する情報）を取得するAPIです。
Query a database との違い
- DBの行を取得したい場合：Query a database
- DBの列（カラム情報）をお取得したい場合： Retrieve a database
取得される情報のイメージ（赤枠で囲っているカラムの情報）
Update a database
Databaseのタイトルをはじめ、指定したプロパティを更新するAPIです。
更新する前のDatabase
今回は下記項目を更新していきます。
- Database名
- Description（Daytabaseの詳細）
- Statusプロパティに
Stopを追加
更新用のリクエスト
{
"title": [
{
"text": {
"content": "Databases Todo List"
}
}
],
"description": [
{
"text": {
"content": "Databases のエンドポイントを全て使ってみる"
}
}
],
"properties": {
"Status": {
"select": {
"options": [
{
"name": "Not Started",
"color": "red"
},
{
"name": "In Progress",
"color": "yellow"
},
{
"name": "Complete",
"color": "green"
},
{
"name": "Stop",
"color": "gray"
}
]
}
}
}
}
実際に更新処理を実行するとDatabase名とStatusプロパティにStopが追加され、説明も追加されます。
Update database properties
プロパティの削除やプロパティ名の更新する場合について
Remove a property
プロパティの削除は プロパティのValueをnullにすると削除できます。
Rename a property
プロパティ名の更新は NameKeyを利用して更新することができます。
今回はCreated timeプロパティをCreated atに更新し、Descriptionプロパティを削除していきます。
更新前のDatabase
実際のリクエスト
{
"properties": {
"Created time": {
"name": "Created at"
},
"Description": null
}
}
更新後のDatabase
さいごに
今回はDatabasesにフォーカスをしていきましたが
Notion上でDatabaseを操作するように Notion API も基本的な操作はできるなと感じました。
詳細の部分はまだ見きれていないところもあるので
また別の記事とかでまとめていこうと思います。
Discussion