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 のツリーを完全に横断できるようになりました。