Notion-Version 2022-06-28 がリリースされました。今回は、後方互換性のないリリースになります。特にクエリなどで取得したページコンテンツをそのまま利用している場合には、スクリプトに修正が必要となりますのでご注意ください。以下、概要説明すると同時にバージョンの違いを検証します。
概要説明
今日、我々は以下の後方互換性のない変更を加えた Notion-Version
2022-06-28 をリリースします。- ページプロパティは、ページプロパティエンドポイントを使用して取得する必要があります。
- 親が常に直接の親になりました。ブロックに parent field が追加されました(訳注: ブロックも親になれるようになりました)。
- データベースのリレーションが
single_propertyとdual_propertyの型を持てるようになりました。
それぞれの変更点については、以下をご覧ください。
ページプロパティは、ページプロパティエンドポイントを使用して取得する必要があります
以前、データベースクエリエンドポイントや検索エンドポイントから取得される ページオブジェクト は、ページの全てのプロパティをその値とともに含むプロパティフィールドを返していました。
"properties": { "Name": { "id": "title", "type": "title", "title": [ { "type": "text", "text": { "content": "Avocado", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "Avocado", "href": null } ] } }
これは便利な反面、全てのプロパティに対して正確な結果を返すため、大規模なデータベースやメンションの多いページではパフォーマンスが低下し、タイムアウトが発生していました。このパフォーマンスに対する対策として、3月1日にページオブジェクトが他のオブジェクトに対して 25 件以上メンションしているページについては、正確な結果を返さなくなるという免責事項を追加しました(これらは
title, rich_text, relation, people, rollup, そして formulaに影響します)。2021年10月に我々は、retrieve a page property item endpoint を介して、より正確な個々のページプロパティを取得する方法を導入しました。このエンドポイントを使用すると、追加のルックアップを伴う複雑なプロパティを処理することができます。
Notion-Version
2022-06-28ではページオブジェクトから 型 と プロパティ 値が削除されました。したがって、今後全てのプロパティ値は、ページのプロパティ項目を取得するエンドポイントを通じて行わなければなりません。"properties": { "Name": { "id": "title" } }
ページプロパティを項目を取得するエンドポイントの使用例として、 SDK examples がページプロパティ項目を取得するエンドポイントを用いる方法に更新されています。
ページプロパティが複雑な理由については、ブログ記事である “Creating the Notion API” を参照してください。
親が常に直接の親になりました。ブロックに parent field が追加されました
これまで、データベースやページの親にアクセスする場合、親は常にページ、データベース、またはワークスペースのいずれかでした。これは、Notion の実際のデータモデルに忠実ではなく、親が他のブロックになることもありました。例えば、トグルブロックの下にページをネストすることもできました。
ページとデータベースの親フィールドが変更され、常にそのページやデータベースの直接の親となるようになり、新しい親タイプとして
block_id が追加されました。さらに、ブロックオブジェクトに
parent フィールドが追加されました。これらの変更により、Notion のツリーを完全に横断できるようになりました。ページ、データベース、ワークスペースを取得するというこれまでの振る舞いをエミュレートするためには、ブロック取得のエンドポイントを用いて、ツリーを横断することができます。すなわち、親がそれらのタイプになるまで親を繰り返し取得していけばよいです。
親タイプについて詳しく知りたい場合は ここを読んでください。
データベースのリレーションが single_property と dual_propertyの型を持てるようになりました。
データベースオブジェクトのリレーションプロパティに
single_property と dual_propertyという二つの型が追加されました。これらを使用して、データベース間の一方向リレーションと双方向リレーションを作成することができます。New version of the JavaScript SDK
これからの変更に合わせて、Notion JavaScript SDK.の新しいメジャーバージョン (v2.0.0) をリリースしました。この新しいバージョンにアップデートするには、リポジトリ内から
npm install @notionhq/client@latest または yarn upgrade --latest @notionhq/client を実行してください。検証
今回の変更はかなり大きいので、NotionRubyMapping もメジャーアップデートする必要があります。とりあえず、現在のリリース版である 0.5.5 と、
NOTION_VERSION だけ上げた 0.6.0 開発版とで結果を比較してみようと思います。左が 2022-02-22 (前回のリリース) で、右が 2022-06-28(今回のリリース)になっています。バージョン確認
ひとまず読み込んでバージョンを確認します。
require "notion_ruby_mapping" => true include NotionRubyMapping => Object NotionRubyMapping::VERSION => "0.5.5" NotionRubyMapping::NOTION_VERSION => "2022-02-22" NotionCache.instance.create_client ENV["NOTION_API_KEY"] => NotionCache
require_relative "lib/notion_ruby_mapping" => true include NotionRubyMapping => Object NotionRubyMapping::VERSION => "0.6.0" NotionRubyMapping::NOTION_VERSION => "2022-06-28" NotionCache.instance.create_client ENV["NOTION_API_KEY"] => NotionCache
ページの取得
このページを取得してみます。
2022-02-22 では値が入っていますが、2022-06-28 では確かに値が入っていません。Property の値を持ってくるためには、個々に API を呼び出さないといけないのですね。NotionRubyMapping では値の取得はメソッドにしているので、その部分でフックする形になりそうです。少し大きな修正になりそうです。逆にユーザスクリプトには影響させずにすみそうです。page = Page.find "41aea942888641d8b96e5a955a28694e" => NotionRubyMapping::Page-41aea942888641d8b96e5a955a28694e page.json => {"object"=>"page", "id"=>"41aea942-8886-41d8-b96e-5a955a28694e", "created_time"=>"2022-07-08T05:50:00.000Z", "last_edited_time"=>"2022-07-08T08:36:00.000Z", "created_by"=>{"object"=>"user", "id"=>"2200a911-6a96-44bb-bd38-6bfb1e01b9f6"}, "last_edited_by"=>{"object"=>"user", "id"=>"2200a911-6a96-44bb-bd38-6bfb1e01b9f6"}, "cover"=>nil, "icon"=>nil, "parent"=>{"type"=>"database_id", "database_id"=>"c63c00ad-201d-4bed-82b0-18dfca9b6ba0"}, "archived"=>false, "properties"=> {"開示?"=>{"id"=>"%3BfBx", "type"=>"checkbox", "checkbox"=>false}, "日付"=>{"id"=>"%3CWbe", "type"=>"date", "date"=>nil}, "原題"=> {"id"=>"%3FMR%7D", "type"=>"rich_text", "rich_text"=> [{"type"=>"text", "text"=>{"content"=>"Releasing Notion-Version 2022-06-28", "link"=>nil}, "annotations"=>{"bold"=>false, "italic"=>false, "strikethrough"=>false, "underline"=>false, "code"=>false, "color"=>"default"}, "plain_text"=>"Releasing Notion-Version 2022-06-28", "href"=>nil}]}, "Number"=>{"id"=>"ANbi", "type"=>"number", "number"=>nil}, "作成日"=>{"id"=>"%60%40%3C%5C", "type"=>"created_time", "created_time"=>"2022-07-08T05:50:00.000Z"}, "URL"=>{"id"=>"o%3A~F", "type"=>"url", "url"=>"https://developers.notion.com/changelog/releasing-notion-version-2022-06-28"}, "タグ"=>{"id"=>"tUJV", "type"=>"multi_select", "multi_select"=>[{"id"=>"05f3b6b1-b6f1-49a2-bbdb-955cfb4d36f4", "name"=>"IMPROVED", "color"=>"gray"}]}, "経過日数"=>{"id"=>"~Xof", "type"=>"formula", "formula"=>{"type"=>"number", "number"=>nil}}, "名前"=> {"id"=>"title", "type"=>"title", "title"=> [{"type"=>"text", "text"=>{"content"=>"Notion-Version 2022-06-28 のリリース", "link"=>nil}, "annotations"=>{"bold"=>false, "italic"=>false, "strikethrough"=>false, "underline"=>false, "code"=>false, "color"=>"default"}, "plain_text"=>"Notion-Version 2022-06-28 のリリース", "href"=>nil}]}}, "url"=>"https://www.notion.so/Notion-Version-2022-06-28-41aea942888641d8b96e5a955a28694e"}
page = Page.find "41aea942888641d8b96e5a955a28694e" => NotionRubyMapping::Page-41aea942888641d8b96e5a955a28694e page.json => {"object"=>"page", "id"=>"41aea942-8886-41d8-b96e-5a955a28694e", "created_time"=>"2022-07-08T05:50:00.000Z", "last_edited_time"=>"2022-07-08T08:40:00.000Z", "created_by"=>{"object"=>"user", "id"=>"2200a911-6a96-44bb-bd38-6bfb1e01b9f6"}, "last_edited_by"=>{"object"=>"user", "id"=>"2200a911-6a96-44bb-bd38-6bfb1e01b9f6"}, "cover"=>nil, "icon"=>nil, "parent"=>{"type"=>"database_id", "database_id"=>"c63c00ad-201d-4bed-82b0-18dfca9b6ba0"}, "archived"=>false, "properties"=> {"開示?"=>{"id"=>"%3BfBx"}, "日付"=>{"id"=>"%3CWbe"}, "原題"=>{"id"=>"%3FMR%7D"}, "Number"=>{"id"=>"ANbi"}, "作成日"=>{"id"=>"%60%40%3C%5C"}, "URL"=>{"id"=>"o%3A~F"}, "タグ"=>{"id"=>"tUJV"}, "経過日数"=>{"id"=>"~Xof"}, "名前"=>{"id"=>"title"}}, "url"=>"https://www.notion.so/Notion-Version-2022-06-28-41aea942888641d8b96e5a955a28694e"}
トグルブロック内のページの取得
テストトグル
↑ににトグル内にページを作成してみました。このページの親を確認します。
2022-02-22 では遡ってこのページの id が page_id として入っています。一方で、2022-06-28 では block_id が取得されています。その後、Block を取得してみると、ちゃんと ToggleBlock が親になっていることがわかります。page2 = Page.find "96caabe3fb2e4a7aab57aa30f6c7ef72" => NotionRubyMapping::Page-96caabe3fb2e4a7aab57aa30f6c7ef72 page2.json => {"object"=>"page", "id"=>"96caabe3-fb2e-4a7a-ab57-aa30f6c7ef72", "created_time"=>"2022-07-08T08:48:00.000Z", "last_edited_time"=>"2022-07-08T08:48:00.000Z", "created_by"=>{"object"=>"user", "id"=>"2200a911-6a96-44bb-bd38-6bfb1e01b9f6"}, "last_edited_by"=>{"object"=>"user", "id"=>"2200a911-6a96-44bb-bd38-6bfb1e01b9f6"}, "cover"=>nil, "icon"=>nil, "parent"=>{"type"=>"page_id", "page_id"=>"41aea942-8886-41d8-b96e-5a955a28694e"}, "archived"=>false, "properties"=> {"title"=> {"id"=>"title", "type"=>"title", "title"=> [{"type"=>"text", "text"=>{"content"=>"トグル内のページ", "link"=>nil}, "annotations"=>{"bold"=>false, "italic"=>false, "strikethrough"=>false, "underline"=>false, "code"=>false, "color"=>"default"}, "plain_text"=>"トグル内のページ", "href"=>nil}]}}, "url"=>"https://www.notion.so/96caabe3fb2e4a7aab57aa30f6c7ef72"}
page2 = Page.find "96caabe3fb2e4a7aab57aa30f6c7ef72" => NotionRubyMapping::Page-96caabe3fb2e4a7aab57aa30f6c7ef72 page2.json => {"object"=>"page", "id"=>"96caabe3-fb2e-4a7a-ab57-aa30f6c7ef72", "created_time"=>"2022-07-08T08:48:00.000Z", "last_edited_time"=>"2022-07-08T08:48:00.000Z", "created_by"=>{"object"=>"user", "id"=>"2200a911-6a96-44bb-bd38-6bfb1e01b9f6"}, "last_edited_by"=>{"object"=>"user", "id"=>"2200a911-6a96-44bb-bd38-6bfb1e01b9f6"}, "cover"=>nil, "icon"=>nil, "parent"=>{"type"=>"block_id", "block_id"=>"d73f7328-ec27-4bf7-8558-f33c48132ef8"}, "archived"=>false, "properties"=>{"title"=>{"id"=>"title"}}, "url"=>"https://www.notion.so/96caabe3fb2e4a7aab57aa30f6c7ef72"} Block.find "d73f7328-ec27-4bf7-8558-f33c48132ef8" => NotionRubyMapping::ToggleBlock-d73f7328ec274bf78558f33c48132ef8
ブロックの親の取得
さらにブロックの親を取得してみます。ここでは、一つ上の右側のコードブロックを取得してみます。確かに parent に block_id が出てくるようになりました。ただ、これは
2022-02-22 のバージョンでも出てきているので、バックポートされているようです。block = Block.find "f68023f51efc448fa7cf96752ca1ad40" => NotionRubyMapping::CodeBlock-f68023f51efc448fa7cf96752ca1ad40 block.json => {"object"=>"block", "id"=>"f68023f5-1efc-448f-a7cf-96752ca1ad40", "parent"=>{"type"=>"block_id", "block_id"=>"0c8c27e0-2515-4773-9143-e2bc93fa2527"}, "created_time"=>"2022-07-08T08:49:00.000Z", "last_edited_time"=>"2022-07-08T08:54:00.000Z", "created_by"=>{"object"=>"user", "id"=>"2200a911-6a96-44bb-bd38-6bfb1e01b9f6"}, "last_edited_by"=>{"object"=>"user", "id"=>"2200a911-6a96-44bb-bd38-6bfb1e01b9f6"}, "has_children"=>false, "archived"=>false, "type"=>"code", "code"=> {"caption"=> [{"type"=>"text", "text"=>{"content"=>"2022-06-28 (v0.6.0)", "link"=>nil}, "annotations"=>{"bold"=>false, "italic"=>false, "strikethrough"=>false, "underline"=>false, "code"=>false, "color"=>"default"}, "plain_text"=>"2022-06-28 (v0.6.0)", "href"=>nil}], "rich_text"=> [{"type"=>"text", "text"=> {"content"=> "page2 = Page.find \"96caabe3fb2e4a7aab57aa30f6c7ef72\"\n=> NotionRubyMapping::Page-96caabe3fb2e4a7aab57aa30f6c7ef72\npage2.json\n=> \n{\"object\"=>\"page\", \n \"id\"=>\"96caabe3-fb2e-4a7a-ab57-aa30f6c7ef72\", \n \"created_time\"=>\"2022-07-08T08:48:00.000Z\", \n \"last_edited_time\"=>\"2022-07-08T08:48:00.000Z\", \n \"created_by\"=>{\"object\"=>\"user\", \"id\"=>\"2200a911-6a96-44bb-bd38-6bfb1e01b9f6\"},\n \"last_edited_by\"=>{\"object\"=>\"user\", \"id\"=>\"2200a911-6a96-44bb-bd38-6bfb1e01b9f6\"},\n \"cover\"=>nil, \n \"icon\"=>nil, \n \"parent\"=>{\"type\"=>\"block_id\", \"block_id\"=>\"d73f7328-ec27-4bf7-8558-f33c48132ef8\"},\n \"archived\"=>false, \n \"properties\"=>{\"title\"=>{\"id\"=>\"title\"}}, \n \"url\"=>\"https://www.notion.so/96caabe3fb2e4a7aab57aa30f6c7ef72\"}\n\nBlock.find \"d73f7328-ec27-4bf7-8558-f33c48132ef8\"\n=> NotionRubyMapping::ToggleBlock-d73f7328ec274bf78558f33c48132ef8", "link"=>nil}, "annotations"=>{"bold"=>false, "italic"=>false, "strikethrough"=>false, "underline"=>false, "code"=>false, "color"=>"default"}, "plain_text"=> "page2 = Page.find \"96caabe3fb2e4a7aab57aa30f6c7ef72\"\n=> NotionRubyMapping::Page-96caabe3fb2e4a7aab57aa30f6c7ef72\npage2.json\n=> \n{\"object\"=>\"page\", \n \"id\"=>\"96caabe3-fb2e-4a7a-ab57-aa30f6c7ef72\", \n \"created_time\"=>\"2022-07-08T08:48:00.000Z\", \n \"last_edited_time\"=>\"2022-07-08T08:48:00.000Z\", \n \"created_by\"=>{\"object\"=>\"user\", \"id\"=>\"2200a911-6a96-44bb-bd38-6bfb1e01b9f6\"},\n \"last_edited_by\"=>{\"object\"=>\"user\", \"id\"=>\"2200a911-6a96-44bb-bd38-6bfb1e01b9f6\"},\n \"cover\"=>nil, \n \"icon\"=>nil, \n \"parent\"=>{\"type\"=>\"block_id\", \"block_id\"=>\"d73f7328-ec27-4bf7-8558-f33c48132ef8\"},\n \"archived\"=>false, \n \"properties\"=>{\"title\"=>{\"id\"=>\"title\"}}, \n \"url\"=>\"https://www.notion.so/96caabe3fb2e4a7aab57aa30f6c7ef72\"}\n\nBlock.find \"d73f7328-ec27-4bf7-8558-f33c48132ef8\"\n=> NotionRubyMapping::ToggleBlock-d73f7328ec274bf78558f33c48132ef8", "href"=>nil}], "language"=>"ruby"}}
block = Block.find "f68023f51efc448fa7cf96752ca1ad40" => NotionRubyMapping::CodeBlock-f68023f51efc448fa7cf96752ca1ad40 block.json => {"object"=>"block", "id"=>"f68023f5-1efc-448f-a7cf-96752ca1ad40", "parent"=>{"type"=>"block_id", "block_id"=>"0c8c27e0-2515-4773-9143-e2bc93fa2527"}, "created_time"=>"2022-07-08T08:49:00.000Z", "last_edited_time"=>"2022-07-08T08:54:00.000Z", "created_by"=>{"object"=>"user", "id"=>"2200a911-6a96-44bb-bd38-6bfb1e01b9f6"}, "last_edited_by"=>{"object"=>"user", "id"=>"2200a911-6a96-44bb-bd38-6bfb1e01b9f6"}, "has_children"=>false, "archived"=>false, "type"=>"code", "code"=> {"caption"=> [{"type"=>"text", "text"=>{"content"=>"2022-06-28 (v0.6.0)", "link"=>nil}, "annotations"=>{"bold"=>false, "italic"=>false, "strikethrough"=>false, "underline"=>false, "code"=>false, "color"=>"default"}, "plain_text"=>"2022-06-28 (v0.6.0)", "href"=>nil}], "rich_text"=> [{"type"=>"text", "text"=> {"content"=> "page2 = Page.find \"96caabe3fb2e4a7aab57aa30f6c7ef72\"\n=> NotionRubyMapping::Page-96caabe3fb2e4a7aab57aa30f6c7ef72\npage2.json\n=> \n{\"object\"=>\"page\", \n \"id\"=>\"96caabe3-fb2e-4a7a-ab57-aa30f6c7ef72\", \n \"created_time\"=>\"2022-07-08T08:48:00.000Z\", \n \"last_edited_time\"=>\"2022-07-08T08:48:00.000Z\", \n \"created_by\"=>{\"object\"=>\"user\", \"id\"=>\"2200a911-6a96-44bb-bd38-6bfb1e01b9f6\"},\n \"last_edited_by\"=>{\"object\"=>\"user\", \"id\"=>\"2200a911-6a96-44bb-bd38-6bfb1e01b9f6\"},\n \"cover\"=>nil, \n \"icon\"=>nil, \n \"parent\"=>{\"type\"=>\"block_id\", \"block_id\"=>\"d73f7328-ec27-4bf7-8558-f33c48132ef8\"},\n \"archived\"=>false, \n \"properties\"=>{\"title\"=>{\"id\"=>\"title\"}}, \n \"url\"=>\"https://www.notion.so/96caabe3fb2e4a7aab57aa30f6c7ef72\"}\n\nBlock.find \"d73f7328-ec27-4bf7-8558-f33c48132ef8\"\n=> NotionRubyMapping::ToggleBlock-d73f7328ec274bf78558f33c48132ef8", "link"=>nil}, "annotations"=>{"bold"=>false, "italic"=>false, "strikethrough"=>false, "underline"=>false, "code"=>false, "color"=>"default"}, "plain_text"=> "page2 = Page.find \"96caabe3fb2e4a7aab57aa30f6c7ef72\"\n=> NotionRubyMapping::Page-96caabe3fb2e4a7aab57aa30f6c7ef72\npage2.json\n=> \n{\"object\"=>\"page\", \n \"id\"=>\"96caabe3-fb2e-4a7a-ab57-aa30f6c7ef72\", \n \"created_time\"=>\"2022-07-08T08:48:00.000Z\", \n \"last_edited_time\"=>\"2022-07-08T08:48:00.000Z\", \n \"created_by\"=>{\"object\"=>\"user\", \"id\"=>\"2200a911-6a96-44bb-bd38-6bfb1e01b9f6\"},\n \"last_edited_by\"=>{\"object\"=>\"user\", \"id\"=>\"2200a911-6a96-44bb-bd38-6bfb1e01b9f6\"},\n \"cover\"=>nil, \n \"icon\"=>nil, \n \"parent\"=>{\"type\"=>\"block_id\", \"block_id\"=>\"d73f7328-ec27-4bf7-8558-f33c48132ef8\"},\n \"archived\"=>false, \n \"properties\"=>{\"title\"=>{\"id\"=>\"title\"}}, \n \"url\"=>\"https://www.notion.so/96caabe3fb2e4a7aab57aa30f6c7ef72\"}\n\nBlock.find \"d73f7328-ec27-4bf7-8558-f33c48132ef8\"\n=> NotionRubyMapping::ToggleBlock-d73f7328ec274bf78558f33c48132ef8", "href"=>nil}], "language"=>"ruby"}}
データベースのリレーション
↑このように One-way と Two-way のリレーションを持ったデータベースを作成しました。
2022-02-22 では双方向のリレーションのみ表示されています。2022-06-28 では一方向のリレーションも表示されており、type にsingle_property が設定されています。双方向の方には、dual_property が設定されています。db1 = Database.find "1dd7b510e60349be87419375f0909478" => NotionRubyMapping::Database-1dd7b510e60349be87419375f0909478 db1.properties => #<NotionRubyMapping::PropertyCache:0x000000010e5ffe38 @base_type=:database, @json= {"Two-way"=> {"id"=>"%3E%3Ed%5C", "name"=>"Two-way", "type"=>"relation", "relation"=>{"database_id"=>"c3a1950f-b65d-4bd9-971f-e49238750c07", "synced_property_name"=>"Two-way-back", "synced_property_id"=>"sf_e"}}, "Name"=>{"id"=>"title", "name"=>"Name", "type"=>"title", "title"=>{}}}, @properties={}>
db1 = Database.find "1dd7b510e60349be87419375f0909478" => NotionRubyMapping::Database-1dd7b510e60349be87419375f0909478 db1.properties => #<NotionRubyMapping::PropertyCache:0x0000000112e3f3d8 @base_type=:database, @json= {"Two-way"=> {"id"=>"%3E%3Ed%5C", "name"=>"Two-way", "type"=>"relation", "relation"=> {"database_id"=>"c3a1950f-b65d-4bd9-971f-e49238750c07", "type"=>"dual_property", "dual_property"=>{"synced_property_name"=>"Two-way-back", "synced_property_id"=>"sf_e"}}}, "One-Way"=> {"id"=>"%60Nno", "name"=>"One-Way", "type"=>"relation", "relation"=>{"database_id"=>"c3a1950f-b65d-4bd9-971f-e49238750c07", "type"=>"single_property", "single_property"=>{}}}, "Name"=>{"id"=>"title", "name"=>"Name", "type"=>"title", "title"=>{}}}, @properties={}>
検証は以上です。これから、これまでテストで使っていた
2022-02-22 のレスポンスを 2022-06-28 のものに差し替えるので、テストがほぼ全滅するはずです。これからテストが通るように v0.6.0 の実装を書き換える処理に入ります。リリースは少しお待ちください。