はじめに
NotionRubyMapping 解説の第5回目です。ブロックの種類はたくさんあるのですが、代表として段落ブロックを取り扱ってみます。こちらに作業ページのリンクを置いておきます。
段落ブロックの取得
上のページにこんな感じで段落ブロックを置いてみました。
このブロックでブロックのリンクを取得とすると以下のような URL になります。ここで # のすぐ後ろの32桁の16進数が block_id となります。なお、?pvs= の前はブロックの置かれているページの page_id になります。
https://www.notion.so/hkob/5-f5cbfddd05b44c98ad33102d55ffca37?pvs=4#bdad8b25676e46b882ae8643d2a1c4b5
NotionRubyMapping では Block クラスの find クラスメソッドで Notion ブロックを取得できます。ページやデータベースの取得と同様に block_id を取り出すのは面倒なので、上のデータベースの URL をそのまま渡しても自動的に block_id を取り出してくれます。ここでは、以下のコマンドでデータベースを取得してみます。block_id や block_url は文字列なので、 "" でくくってください。
irb(main):002> block = Block.find "https://www.notion.so/hkob/5-f5cbfddd05b44c98 ad33102d55ffca37?pvs=4#bdad8b25676e46b882ae8643d2a1c4b5" => NotionRubyMapping::ParagraphBlock-bdad8b25676e46b882ae8643d2a1c4b5
NotionRubyMapping::ParagraphBlock のオブジェクトが取得できていることがわかります。
データベースオブジェクトに対するメソッド
ページと同様にここでは代表的なメソッドを紹介してみます。
1. rich_text_array: リッチテキスト配列オブジェクトを取得
rich_text_array は本文のリッチテキストの配列を取得するメソッドです。RichTextArray クラスについては後日解説します。
irb(main):003> block.rich_text_array => #<NotionRubyMapping::RichTextArray:0x000000011e8bd7f0 @key="rich_text", @rich_text_objects= [#<NotionRubyMapping::TextObject:0x0000000102a2a9b0 @options= {"plain_text"=>"段落ブロック", "bold"=>true, "italic"=>false, "strikethrough"=>false, "underline"=>false, "code"=>false, "color"=>"default", "href"=>nil}, @text="段落ブロック", @type="text", @will_update=false>], @will_update=false>
2. parent_id: 親の ID を取得
parent_id はページの親の ID を取得するメソッドです。ブロックの親はページになるので、先ほどの URL にあった page_id が取得できています。
irb(main):004> block.parent_id => "f5cbfddd-05b4-4c98-ad33-102d55ffca37"
3. parent: 親のページオブジェクトを取得
parent はページの親のオブジェクトを取得するメソッドです。先ほど説明したように Page になっています。確認のため title を表示するとページのタイトルが表示されました。なお、最初の block.parent では Notion API のアクセスがあるため、少し時間がかかります。しかし、二回目の block.parent.title では即座に表示がされたと思います。NotionRubyMapping では Rails の ActiveRecord と同様に内部で API が返却した JSON データをキャッシュしております。そのため、同じ page_id, database_id, block_id でのアクセスがあった場合には、Notion API のアクセスを行わず、JSON キャッシュから Ruby オブジェクトの再構成を行います。
irb(main):005> block.parent => NotionRubyMapping::Page-f5cbfddd05b44c98ad33102d55ffca37 irb(main):006> block.parent.title => "段落ブロックの取得 (5)"
4. page?, database?, block?
page?, database?, block? はそのオブジェクトが page なのか、database なのか、block なのかを聞くメソッドです。今回の場合、block? のみが true を返します。
irb(main):008> block.page? => false irb(main):009> block.database? => false irb(main):010> block.block? => true
5. new_record?
new_record? は Rails と同じで Notion 側に存在しない Block オブジェクトである時に true を返すメソッドです。基本的には ParagraphBlock.new で作成したオブジェクトの時 true になります。これは後日解説します。
irb(main):012> block.new_record? => nil
6. color, color = color_string
color はブロックの色を示す文字列を返すメソッドです。上に示したように緑色の背景にしてみたので、green_background になっています。色を変更したいときは color = で変更できます。これも save で保存したときに Notion 側に反映します。
irb(main):012> block.color => "green_background"
11. save または save dry_run: true
ページと同様に save dry_run: true とすると実際に Notion に作業する代わりにスクリプトが表示されます。
irb(main):015> print block.save dry_run: true
#!/bin/sh
curl -X PATCH 'https://api.notion.com/v1/blocks/bdad8b25676e46b882ae8643d2a1c4b5' \
-H 'Notion-Version: 2022-06-28' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H 'Content-Type: application/json' \
--data '{"paragraph":{"color":"orange_background","rich_text":[{"type":"text","text":{"content":"段落ブロック","link":null},"plain_text":"段落ブロック","href":null,"annotations":{"bold":true,"italic":false,"strikethrough":false,"underline":false,"code":false,"color":"default"}}]}}'=> nil
db.save とすると背景色が変更されました。
irb(main):016> block.save => NotionRubyMapping::ParagraphBlock-bdad8b25676e46b882ae8643d2a1c4b5
保存した後、Notion API はページ情報を返却してくれます。NotionRubyMapping では返却された情報で block オブジェクトの内容を再度アップデートします。このため、ここで block.color とすると変更された色情報が正しく入っていることがわかります。
irb(main):018> block.color => "orange_background"
12. children
今回のブロックは子ブロックとしてさらに段落ブロックが存在しています。まだ解説していない List オブジェクトが返されました。こちらについては後日詳しく解説します。
irb(main):019> block.children => NotionRubyMapping::List-
List オブジェクトは first とすることで最初の子ブロックを取得できます。
irb(main):023> child = block.children.first => NotionRubyMapping::ParagraphBlock-d3132441e7ae446381e2c5239331d113
この子ブロックの rich_text_array を確認すると以下のようになりました。子ブロックという文字列が入っていました。
irb(main):029> child.rich_text_array => #<NotionRubyMapping::RichTextArray:0x00000001286f92c0 @key="rich_text", @rich_text_objects= [#<NotionRubyMapping::TextObject:0x000000012c1d6870 @options= {"plain_text"=>"子ブロック", "bold"=>false, "italic"=>false, "strikethrough"=>false, "underline"=>true, "code"=>false, "color"=>"default", "href"=>nil}, @text="子ブロック", @type="text", @will_update=false>], @will_update=false>
おわりに
ParagraphBlock を例にブロックの取得を解説しました。ParagraphBlock は Block を親にもつクラスです。さらに Block は Page や Database と同様に Base を親に持つクラスになります。このため、Page や Database と共通のメソッドもありますが、共通部分は少ないです。他にもブロックの追加などのメソッドはあるのですが、もう少し細かいオブジェクトなどの解説をしてからにしたいと思います。まずは、RichTextArray の要素となる RichTextObject について解説しておこうと思います。
段落オブジェクトのマニュアルはこちら。 hkob.notion.site
