Notion DataBaseをAPIから操作する際の用途別リクエスト構成についてまとめてみた

Notionの操作をAPIで行っていると、ブロック要素はページにもなり、データベースにもなる点で使うべきAPIの選択で悩まされます。公式ドキュメントを見る限り一つのAPIを元に操作することを予想するのですが、実際には用途でそれぞれAPIが異なります。

データベースにレコードを追加するときにはDataBase APIは使わなかったりと、設計意図に振り回されることも多々あります。どの操作をどのAPIが担当しているのか、今回はDataBaseに絞って確認してみました。

データベース作成時の念頭事項

重要なのは以下の点です。

• 何らかの親ページが必要になる
• レコード追加はページ用API

一番の悩みはプロパティ設計時のパラメータ指定になるでしょう。

各オブジェクト毎に必要なパラメータは示されているものの、肝心なJSON形式でのサンプルが含まれていないためです。

データベース作成時

リクエストに用いるURLはhttps://api.notion.com/v1/databasesとなります。MethodはPOST。

Create a DataBaseのBodyParamsへの指定にはDataBase Objectに記載されている項目も一部指定可能です。インラインの場合は"is_inline": trueが必須になります。なお、作成時に"archived": trueを指定してもエラーにはなりませんがアーカイブはされません。

プロパティは基本的に以下の組み合わせになります。

{
    "プロパティ名": {
      "プロパティタイプ": 追加構成
    }
}

"type": "プロパティタイプ"の指定はせずとも処理されます。追加構成を受け付けないプロパティはProperty Schema Objectにて

Created time database property schema objects have no additional configuration within the XXXX property.

と記載があります。この場合はkeyやvalueを含めず{}で指定します。一つも指定が要らないのなら省けるのでは、と考えがちですがバージョン2022-06-28の時点ではvalidation_errorとなります。

以下の構成は、タイトルがtestの、プロパティにTitleとCreatedがあるインラインのDataBaseを作ります。

   {
    "parent":
      {
        "type": "page_id",　//なくてもOK
        "page_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
      },
    "is_inline": true,
    "title":
      [{
          "type": "text",　//なくてもOK
          "text": {'content': "test"}
      }],
    "properties": 
      {
        "Title": {
          "type": 'title',　//なくてもOK
          "title": {}
        },
        "Created": {
          "type": 'created_time',　//なくてもOK
          "created_time": {}
        }
      }
  }

データベースへのレコード追加時

リクエストに用いるURLはhttps://api.notion.com/v1/pagesとなります。MethodはPOST。指定するプロパティ設定はProperties valuesに準拠します。

created_timeのような自動指定される、設定要素がないものについてはプロパティの指定から外しても問題ありません。

 {
    "parent":
      {
        "type": "database_id",　//なくてもOK
        "database_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
      },
    "properties": 
      {
        "Title": {
          "title": [
            { "text": {"content": "aaa"} }
          ]
        }
      }
  })

レコードの削除

リクエストに用いるURLはhttps://api.notion.com/v1/pages/page_idとなります。MethodがPATCHになる点も要注意。アーカイブフラグを立てることによりブラウザ上で削除する場合と同じ状態にします。削除する方法という形で公式にドキュメント化はされていません。

レコードのIDをpage_idとして指定します。URL(https://api.notion.com/v1/pages/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX)とJSONの両方に指定が必要です。

  {
    "parent":
      {
        "type": "page_id",　//なくてもOK
        "page_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
      },
    "archived": true
  }

あとがき

用途毎のURLと必要なパラメータ指定について公式ドキュメントを辿ると中々の手間だったので、独自にまとめてみました。

なお、今回はあくまでDataBaseのプロパティのみ操作しており、ページの本文ブロック要素にはノータッチです。プロパティのみで構成しているページをマクロ等で自動操作する際の参考になれば幸いです。