Zenn
🗒️

ねんがんの Notion API を試していく

2021/05/14に公開
3件
Notion
tech

概要

2021年5月。ねんがんの Notion API がパブリックベータとして一般提供開始されたので、試していく。

資料

公式ドキュメント

https://developers.notion.com/docs

ここから、上記資料を元に実際に触っていく。

API を利用するための事前準備

公式ドキュメントの「Getting Started - Before we begin」に書かれていること。

  • Admin ユーザーで Notion ワークスペースにログインする
  • curl コマンドが使えるようになっていること
    • あくまでチュートリアル用で、SDK など別のクライアントを利用する場合は不要と思う

Integration を作る

公式ドキュメントの「Getting Started - Create a new integration」に書かれていること。

My integrations ページを開く！

「+ New integration」ボタンを押して…

  • Name: integration の名前 (公式ドキュメントでは Vacation Planner とあるのでそのままそれにしてみた)
  • Logo: 一旦未設定
  • Associated workspace: Admin としてログインした workspace

で、「Submit」。

Integration が作られると、「Internal Integration Token」というものが取得できる。この値が API リクエストのトークンになるのだろう。

また、新たに「Integration type」という項目が出現しており、

  • Internal integration
  • Public integration

が選択できるようになっている。デフォルトでは「Internal integration」になっている。

Public にするつもりは一旦ないのでこのままで。

なるほど、この integration というのが、Slack App だとか OAuth クライアントだとか、なんかそういうものをイメージすると近いような、API を実行するときのメインの単位になるのだな。

データベースを integration にシェアして API から使えるようにする

公式ドキュメントの「Getting Started - Share a database with your integration」に書かれていること。

まず、大事そうなことが書いてある。

  • Integrations built with the API follow a similar permission system to the sharing permissions for users. There's an important difference: integrations don't have access to any pages (or databases) in the workspace at first. A user must share specific pages with an integration in order for those pages to be accessed using the API. This helps keep you and your team's information in Notion secure.

Integration の権限管理の仕組みはユーザーのそれと似ているが違う点もあるとのこと。それが、

  • API でアクセスしたいページは、明示的に integration にシェアする必要がある ということ

らしい。

とりあえず試す用のページを作る

とりあえず作った。

Vacation Planner に引っ張られる形で「週末の過ごし方」というデータベース (テーブル) のページにしました。

シェアのしかたは普段ユーザーにシェアするときと同じ。「Share」ボタンを押すと、さっき作った Vacation Planner integration が出てくるので、それを invite する (権限は can edit しかない様子) 。

それと、公式ドキュメントの方に書かれているが、 integration に対してシェアをするのには Admin である必要はない 、とのこと。Integration を作るのは Admin しかできないが、一度作ったら、そのページに権限を持つユーザーなら誰でも integration に対してシェアできるということだろう。

データベースの ID を取得する

これから API でデータベースにアクセスするために、その ID を知る必要がある。

データベースのフルページをブラウザで開いてアドレスバーを見るか、Notion アプリだったら「Copy link」を押して URL をコピーして、例えば、

https://www.notion.so/06b91f353a3949cca30c45xxxxxxxxxx?v=...
                      |--------- Database ID --------|

であれば、 06b91... のところが ID になる。のでそれをメモ。

API でデータベースに項目を追加する

では準備ができたので、とうとう API でデータベースに項目を追加してみる。公式ドキュメントでは「Getting Started - Add an item to a database」のところ。

データベースの各項目は、Notion の単位としてはそれぞれページに対応している (実際にページとしても開ける) ので、「ページを作る」API エンドポイントを叩くことになります。

↓の curl コマンドで、

  • {MY_NOTION_TOKEN} を integration の「Internal Integration Token」
  • {DATABASE_ID} をデータベースの ID

それぞれ実際の値に変更して実行してみると…

curl -X POST https://api.notion.com/v1/pages \
  -H "Authorization: Bearer {MY_NOTION_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2021-05-13" \
  --data '{
    "parent": { "database_id": "{DATABASE_ID}" },
    "properties": {
      "Name": {
        "title": [
          {
            "text": {
              "content": "連休の予定"
            }
          }
        ]
      }
    }
  }'

おー、できた！

もし、API を実行したのに反映されないときは、以下をチェックしてみましょう、とのこと。

  • とりあえずブラウザとかをリロードしてみる
  • curl のレスポンスが {"object":"error",..., になっていないか？
    • なっていたら、リクエストがエラーになっているので設定などを再確認

API でデータベースのデータを変更してみる

ここまで、ただ公式の「Getting Started」ページをなぞってきたたけなので、データの変更くらいはやってみる。

さっき登録したデータ行のタイトルの変更やカラムの値の追加をしてみましょう。

「Update page properties」という API エンドポイントが使えそう…

なのだが、この API のエンドポイントは

である。つまり、データベースの ID ではなく、 データベースのデータ行のページの ID が必要となるはず。もちろん、↓のように直接そのデータ行のページにアクセスすればその URL から ID を知ることはできる。

だが、これだと外部から利用する API として使い勝手がよくないので、データベースのページから、例えば、 データ行の名前を元に更新したいページの ID を取得する ことができればよさそう。

これには「Query a database」API でデータベースをクエリできれば名前から ID が取れそうに思える。のでやってみる。

properties の Name でフィルタして結果を取得すればいいはずだから…こう。

curl -X POST 'https://api.notion.com/v1/databases/{DATABASE_ID}/query' \
  -H "Authorization: Bearer {MY_NOTION_TOKEN}" \
  -H 'Notion-Version: 2021-05-13' \
  -H "Content-Type: application/json" \
    --data '{
      "filter": {
        "property": "Name",
          "text": {
            "equals": "連休の予定"
          }
        }
      }'

すると、レスポンスの results という配列に見つかった結果が入っていた。クエリの結果は配列だが今回はとりあえず1件目決め打ちで取れば十分なので、 jq で ID だけ取りだすようにした。

| jq '.results[0].id'

すると期待通りに ID が取れたので、この ID のページを更新すれば、やりたかったデータ行の更新ができるはず。

取得したページの ID を指定したエンドポイントに対して、「Database object」とかでデータ型を調べながら、さきほどの追加のときと同じ要領で更新リクエストを飛ばしてみます。

curl https://api.notion.com/v1/pages/{DATA_ROW_PAGE_ID} \
  -H "Authorization: Bearer {MY_NOTION_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2021-05-13" \
  -X PATCH \
    --data '{
      "properties": {
        "Name": {
          "title": [
            {
              "text": {
                "content": "3連休の予定"
              }
            }
          ]
        },
        "やること！": {
          "rich_text": [
            {
              "text": {
                "content": "自粛"
              }
            }
          ]
        }
      }
    }'

期待した通りに更新できた！

まとめ

Notion API の基本的な使い方と、データベースの操作の基本はわかった。

次は、

あたりをやろうと思う。

Discussion

utahutah

すごい細い点で恐縮なのですが、最後の方に記載されている対象のページIDを指定して内容を更新している curl コマンドについて、ベタ貼りしてみたらうまく動かず、「Notion-Version」の後に「: (コロン)」が必要でした。

-H "Notion-Version 2021-05-13" \