[Notion]既存の本文要素を更新する手続きについてまとめてみた

Notionのページ本文をAPIで更新しようとした場合に掛かる制約や必要な手続きについてまとめてみました。
2022.11.29

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

NotionのAPIペースによる更新を試してみて、一番手間と理解に時間が掛かるのは既存要素のアップデートです。

データベースやページのプロパティについては割とシンプルに更新できることを確認しましたが、同じノリでブロック、つまり本文を扱おうとすると頭を抱えることになります。

公式ドキュメントをベースに、本文更新手続きについて書き出してみました。

公式ドキュメントでの解説

上記ドキュメントを読んでみると分かると思われますが、プロパティと本文でアップデートするAPIを変える必要があります。プロパティは直接書き換え可能ですが、本文で直接更新出来るのはタイプがテキストかToDoに現状限られます。

Currently only text (for supported block types) and checked (for to_do blocks) fields can be updated.

つまりそれ以外の本文要素は取得と追加、及びプロパティでのアーカイブ設定を組み合わせて利用する必要があります。

本文の更新

基本は既存本文を取得しつつ、テキストとToDo以外は差し替えといった手順となると挙げました。一番大事なポイントとして本文は差し込みができません。要は追加しかできません

察しがつく方もいるかと思われますが、ページ本文途中のテキスト系ではないコンテンツを差し替えたい場合は本文要素を一通り取得した後に全てアーカイブ処理を行い、且つ組み立てたい順番でAppend用APIを実行していく必要があります。

  1. https://api.notion.com/v1/blocks/{block_id}/children (Method:GET) Retrieve block children
  2. https://api.notion.com/v1/blocks/{block_id} (Method:DELETE) Delete a block
  3. https://api.notion.com/v1/blocks/{block_id}/children (Method:PATCH) Append block children

上記の順番で実施します。1で要素を取得し、2でarchivedフラグを立てて消し、3で追加し直すという流れになります。

なお、ブラウザやクライアントでの手作業が挟まれると処理が想定どおりにならない可能性があるため、事前にロックしておくことをおすすめします。

あとがき

今回は以前の記事と違って実装例を載せていませんが、パラメータや呼び出し処理についてはほぼ変わらないため過去記事を参照してください。

Notionの過去記事

正直なところ、CMS等を使ってページ更新を完全自動化など検討しない限りは、既存本文の更新をAPIで行うことは個人的には推奨しません。事前に取り決めた記事レイアウトに沿って一度限りの出力とした場合に限ってはメンテナンスコストも低いと思われます。

ページ本文更新をAPIで行いたい場合の参考になれば幸いです。