はじめに
NotionRubyMapping 解説の第3回目です。インテグレーションキーも用意したので、早速ページにアクセスしてみます。今回から、毎回ページを用意してそこで作業を行います。
ページの取得
今回の連載では、NotionRubyMapping の解説を行うということで、Notion API や payload の JSON などの解説はせず、あくまでオブジェクトから見える世界のみを解説していきます。Rails であまり SQL の話などをしないのと同様です。当然、SQL を知っている方がうまく Rails を使えますし、API のことを知っている方が Notion API をうまく使えます。ある程度使ってみたくなったら、API リファレンスを読んでみるといいでしょう。先ほどのデータベースに「ページの取得(3)」というページを作ってみました。公開 URL は以下のようになります。
https://hkob.notion.site/3-cb058e00917e4b2bb6818e1b89fab4b8?pvs=4
早速 irb を起動して、初期設定を行います。
irb irb(main):001> load "/Users/hkob/bin/nrm_init.rb" => true
NotionRubyMapping では Page クラスの find クラスメソッドで Notion ページを取得できます。Rails ではデータベースの主キーである数値 ID を渡しますが、NotionRubyMapping では page_id を渡します。page_id は先ほどの URL の ? の前にある32桁の16進数です。上の例では cb058e00917e4b2bb6818e1b89fab4b8 に相当します。ただし、いちいちこの ID を取り出すのは面倒なので、上の URL をそのまま渡しても自動的に page_id を取り出してくれます。ここでは、以下のコマンドで page を取得してみます。page_id や page_url は文字列なので、 "" でくくってください。
irb(main):002> page = Page.find "https://hkob.notion.site/3-cb058e00917e4b2bb681 8e1b89fab4b8?pvs=4" => NotionRubyMapping::Page-cb058e00917e4b2bb6818e1b89fab4b8
NotionRubyMapping::Page のオブジェクトが取得できていることがわかります。
ページオブジェクトに対するメソッド
Rails がデータベースのエンティティを Ruby のオブジェクトに Object-Relation Mapping しているのと同様に、NotionRubyMapping では Notion のブロックを Ruby のオブジェクトに Mapping しています。Ruby のオブジェクトに変換されているので、このオブジェクトにメソッドを送ると Notion のブロックの情報をいくつか取得したり、変更したりすることができます。ここでは代表的なものを紹介してみます。
1. title: ページタイトルを取得
title はページのテキスト情報のみを取得するメソッドです。
irb(main):003> page.title => "ページの取得 (3)"
2. parent_id: 親の ID を取得
parent_id はページの親の ID を取得するメソッドです。
irb(main):004> page.parent_id => "f50fe9be-119c-41d1-b2e0-b99bbab471a8"
3. parent: 親の Notion オブジェクトを取得
parent はページの親のオブジェクトを取得するメソッドです。
irb(main):005> page.parent => NotionRubyMapping::Database-f50fe9be119c41d1b2e0b99bbab471a8
4. created_time: 作成時刻プロパティを取得
created_time はページの作成時刻プロパティを取得するメソッドです。このオブジェクトは inspect を実装していないので、中身のインスタンス変数が見えてしまっていてカッコ悪いですね。時間がある時に直しておきましょう。
irb(main):006> page.created_time => #<NotionRubyMapping::CreatedTimeProperty:0x000000012bc12d08 @base_type=:page, @create=false, @json="2024-02-25T11:23:00.000Z", @name="__timestamp__", @new_name=nil, @property_cache=nil, @property_id=nil, @query=nil, @remove=false, @will_update=false>
5. last_edited_time: 更新時刻プロパティを取得
last_edited_time はページの更新時刻プロパティを取得するメソッドです。
irb(main):007> page.last_edited_time => #<NotionRubyMapping::LastEditedTimeProperty:0x000000012be1ca90 @base_type=:page, @create=false, @json="2024-02-25T11:26:00.000Z", @name="__timestamp__", @new_name=nil, @property_cache=nil, @property_id=nil, @query=nil, @remove=false, @will_update=false>
6. page?, database?, block?
page?, database?, block? はそのオブジェクトが page なのか、database なのか、block なのかを聞くメソッドです。今回の場合、page? のみが true を返します。
irb(main):008> page.page? => true irb(main):009> page.database? => false irb(main):010> page.block? => false
7. new_record?
new_record? は Rails と同じで Notion 側に存在しない Page オブジェクトである時に true を返すメソッドです。基本的には Page.new で作成したオブジェクトの時 true になります。これは後日解説します。
irb(main):011> page.new_record? => nil
8. properties
properties は page のプロパティをまとめて管理する PropertyCache オブジェクトを返します。こちらについては、後日プロパティの解説の時に説明します。
irb(main):012> page.properties => PropertyCache
9. icon
icon はページアイコンの内容を示すハッシュを返すメソッドです。このページはアイコンがないので、nil になっています。
irb(main):014> page.icon => nil
10. set_icon emoji: a_emoji または set_icon url: a_url
set_icon は絵文字または外部 URL によりアイコンを設定するメソッドです。ただし、オブジェクトの設定をするだけで、後述する save をした時に初めて Notion にデータが送られて変更されます。
irb(main):015> page.set_icon emoji: "1️⃣" => NotionRubyMapping::Page-cb058e00917e4b2bb6818e1b89fab4b8
11. save または save dry_run: true
save は上記のようにページ情報を変更した後で Notion データを書き換えるものです。Rails の場合もオブジェクトの内容を変更しても、save するまではデータベースが書き変わりませんでした。NotionRubyMapping もさまざまな情報を変更した上で、save した時に page に関する全ての変更情報を更新します。なお、上級者向けに dry_run: true とすると、Notion API の payload を含めたシェルスクリプトを表示します。iOS などのショートカットアプリの JSON を手書きしたくない人はこちらを使ってください。ちなみに、今回の場合にはこんなスクリプトが表示されます。
irb(main):017> print page.save dry_run: true
#!/bin/sh
curl -X PATCH 'https://api.notion.com/v1/pages/cb058e00917e4b2bb6818e1b89fab4b8' \
-H 'Notion-Version: 2022-06-28' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H 'Content-Type: application/json' \
--data '{"icon":{"type":"emoji","emoji":"1️⃣"}}'=> nil
page.save とすると Notion のページアイコンが変更されました。
irb(main):018> page.save => NotionRubyMapping::Page-cb058e00917e4b2bb6818e1b89fab4b8
保存した後、Notion API はページ情報を返却してくれます。NotionRubyMapping では返却された情報で page オブジェクトの内容を再度アップデートします。このため、ここで page.icon とすると変更されたアイコンの情報が正しく入っていることがわかります(先ほど取得した時は nil でした)。
irb(main):019> page.icon
=> {"type"=>"emoji", "emoji"=>"1️⃣"}
おわりに
取り急ぎ、ページに関するメソッドを紹介してみました。ページの作成やページ内のブロックの追加などもありますが、それらは後日解説していきます。
Page クラスに関するマニュアルはこちら → hkob.notion.site
