概要
コメント は Notion 内のページとブロックに存在します。ユーザはページにコメントを追加したり、テキストやその他のブロックなどにコメントを追加できます。このガイドでは、API でコメントを操作する方法を示します。
現在、インテグレーションは次の作業を行うことができます。
- ページにコメントを追加
- 既存のディスカッションスレッドにコメントを追加
- ブロックやページのコメントを取得
コメントAPIの制限
- API は現在、ブロックに新しいコメントやディスカッションスレッドを作成する機能をサポートしていません。
- API を使ってコメントを更新することはできません。
- API を使って解決済みのコメントを取得することはできません。
機能
パブリックAPIでコメントを操作するには、インテグレーションがコメント機能を構成している必要があります。さらに、コメントするページはインテグレーションに共有されている必要があります。
現在、関連する機能は2つあります。一つはコメントを読み込むためのもので、もう一つはコメントを挿入するためのものです。この機能は https://notion.so/my-integrations で編集できます。より詳しい情報については、機能 に関するリファレンスガイドを参照してください。
ページにコメントを追加する
add comment to page エンドポイントに rich text 本文を指定することで、ページ上部にコメントを追加できます。
curl -X POST https://api.notion.com/v1/comments \ -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ -H "Content-Type: application/json" \ -H "Notion-Version: 2022-06-28" \ --data ' { "parent": { "page_id": "59e3eb41-33b2-4151-b05b-31115a15e1c2" }, "rich_text": [ { "text": { "content": "Hello from my integration." } } ] } '
この応答として、作成された comment object を受け取ります。もし、コメント書き込み機能のみで読み込み機能がなかった場合には、応答は
id と object フィールドのみを持つ部分オブジェクトになります。コメントは、統合の名前とアイコンを用いてページに表示されます。
ページまたはブロックのコメントを一覧表示する
retrieve comments エンドポイントを利用して、ページまたはブロックの未解決のコメントを全て一覧表示できます。どちらの場合でもクエリパラメータには
block_id を使います(なぜなら ページもブロックだからです)。フラットリストは常に返されます。しかし、いくつかのブロックタイプは、複数のデイスカッションスレッドをサポートする場合があります(すなわち、テキストブロックのさまざまなセッションにコメントする)。その場合、全てのディスカッションスレッドからのコメントは、時系列の昇順でインターリーブされて返されます)。ただし、コメントオブジェクトの
discussion_id フィールドをチェックすることでスレッドを区別することができます。curl 'https://api.notion.com/v1/comments?block_id=5c6a28216bb14a7eb6e1c50111515c3d'\ -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ -H "Notion-Version: 2022-06-28"
このエンドポイントからの応答は最大100件取得できます。さらに多くのアイテムを取得するには pagination を使います。
ディスカッションスレッドへの返信
ブロックのディスカッションスレッドに返信することもできます。このフォームでは、
parent の代わりに discussion_id パラメータを指定します。discussion_id は retrieve comments エンドポイントの応答で取得できます。 discussion_id を手動で取得する場合はいずれかのコメントで Copy link to discussion をクリックします https://notion.so/Something-something-a8d5215b89ae464b821ae2e2916ab9ce?d=5e73b63447c2428fa899e906b1f1d20e#b3e87b2b5e114cbd99f96288c22bacceのような URL が取得できた時、d の後ろが discussion_id になります。curl -X POST https://api.notion.com/v1/comments \ -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ -H "Content-Type: application/json" \ -H "Notion-Version: 2022-06-28" \ --data ' { "discussion_id": "59e3eb41-33b2-4151-b05b-31115a15e1c2", "rich_text": [ { "text": { "content": "Hello from my integration." } } ] } '
結論
このガイドでは、Notion API を用いてページおよびブロックレベルのコメントを操作する方法を学びました。このタイプのインタラクションこのタイプのインタラクションには多くの潜在的なユースケースがあります。関連するプルリクエストがマージされた時にタスクにコメントしたり、 Query a database でページを取得した後に特定の条件を満たすページにリマインダを貼り付けたりできます。あなたが思いついたものを見て興奮しています。
次のステップ
- API reference documentation を参照してください。
- notion-sdk-typescript-starter テンプレートリポジトリを取得します。