🗒️

NotionのデータベースにAPI経由でレコードを一括インポートしたメモ

2023/10/16に公開2件

Notion

Notion API

tech

備忘録です。

やりたかったこと

Notion内のデータベースにCSVでレコードを一括投入したかった
が、Notion標準の「CSV取り込み」機能だと少なくともマルチセレクト、リレーション、本文をCSVで取り込むことができなかった（実験結果。公式見解は見当たらず）
しかたなくAPI経由でCSVの中身をインポートする機能を実装することにした

APIの利用に際して前提として必要なこと

https://www.notion.so/my-integrations にてインテグレーションを作成する
- このインテグレーションのシークレットをAPIエンドポイントへの認証に使用する
Notion上で、APIによるアクセスが必要なページ・データベースに対して、上記のインテグレーションにアクセス権を付与する
- 画面右上の ... → コネクトの追加 → インテグレーションを選択

データベースの様子

プロパティ名	種類
名前	タイトル
種別	セレクト
タグ	マルチセレクト
プロジェクト	`プロジェクト` データベースへのリレーション
担当者	`従業員` データベースへのリレーション
依頼者	`従業員` データベースへのリレーション
日付	日付
ステータス	ステータス

CSVの様子

名前	種別	タグ	プロジェクト	担当者	依頼者	日付	ステータス	本文	リンク先ページ名
レコードの名前1	種別1	タグ1,タグ2	プロジェクト名1	従業員名1	従業員名2	2023-10-16
レコードの名前2	種別2	タグ1,タグ3	プロジェクト名2	従業員名2	従業員名3	2023-10-16,2023-10-18	完了	必要に応じて本文を書く	ページ名1

プロジェクト、担当者、依頼者には、データベースIDではなくデータベース名を書けるようにしたかった
任意の本文に加えて、本文内に任意のページへのリンクを記載できるようにしたかった
日付は1日指定と期間指定のどちらもできるようにしたかった

ちなみにNotion標準のCSV取り込み機能だとできなかったこと

あくまで記事執筆時点の実験結果です。そのうち機能が改善されたりするかもしれません。

CSV内に同一の「名前」の行があると正常に取り込めなかった
マルチセレクトの項目にはどのような書き方をしても値をセットすることができなかった
リレーションの項目にはどのような書き方をしても値をセットすることができなかった
日付の項目は yyyy-mm-dd 書式でないと正常に取り込めなかった
- 少なくとも yyyy/m/d などはダメだった
- ので、Excelとの相性が悪い
レコード（ページ）の本文に値をセットする手段は存在しなかった

実装

PHPで symfony/http-client というHTTPクライアントライブラリを使って実装したコードを示します。適当に読み替えながら参考にしていただければ🙏

なお、CSVをパースする処理についてはここでは割愛します。

あと、社内ツールにつきまあまあ雑な実装なのでご注意ください。

CSVの行データを表すValueObject

<?php

declare(strict_types=1);

namespace App\Notion;

readonly class Row
{
    public function __construct(
        public string $name,

        public string $type,

        public string $ownerName,

        public \DateTimeInterface $startedDate,

        /** @var array<string> */
        public array $tags = [],

        public ?string $projectName = null,

        public ?string $ordererName = null,

        public ?\DateTimeInterface $endedDate = null,

        public ?string $status = null,

        public ?string $body = null,

        public ?string $linkPageName = null,
    ) {
    }
}

プロジェクト名からプロジェクトIDを取得するメソッド

private static array $projectIds = []; // 一度APIで取得した情報は使い回す

public function getProjectId(string $projectName): ?string
{
    if ($projectId = self::$projectIds[$projectName] ?? null) {
        return $projectId;
    }

    $res = $this->notionClient->request('POST', sprintf('/v1/databases/%s/query', $this->projectDatabaseId), [
        'json' => [
            'filter' => [
                'and' => [
                    [
                        'property' => '名前',
                        'title' => [
                            'equals' => $projectName,
                        ],
                    ],
                ],
            ],
            'page_size' => 1,
        ],
    ]);
    if (400 === $res->getStatusCode()) {
        return null;
    }
    $res = json_decode($res->getContent(), flags: JSON_THROW_ON_ERROR);
    $projectId = $res->results[0]?->id ?? null;

    if ($projectId) {
        self::$projectIds[$projectName] = $projectId;
    }

    return $projectId;
}

インテグレーションに プロジェクト データベースへのアクセス権を渡しておくのを忘れずに

従業員名から従業員IDを取得するメソッド

private static array $staffIds = []; // 一度APIで取得した情報は使い回す

public function getStaffId(string $staffName): ?string
{
    if ($staffId = self::$staffIds[$staffName] ?? null) {
        return $staffId;
    }

    $res = $this->notionClient->request('POST', sprintf('/v1/databases/%s/query', $this->staffDatabaseId), [
        'json' => [
            'filter' => [
                'and' => [
                    [
                        'property' => '氏名',
                        'title' => [
                            'equals' => $staffName,
                        ],
                    ],
                ],
            ],
            'page_size' => 1,
        ],
    ]);
    if (400 === $res->getStatusCode()) {
        return null;
    }
    $res = json_decode($res->getContent(), flags: JSON_THROW_ON_ERROR);
    $staffId = $res->results[0]?->id ?? null;

    if ($staffId) {
        self::$staffIds[$staffName] = $staffId;
    }

    return $staffId;
}

インテグレーションに 従業員 データベースへのアクセス権を渡しておくのを忘れずに

ページ名からリンク先ページのページIDを取得するメソッド

private static array $pageIds = []; // 一度APIで取得した情報は使い回す

public function getPageId(string $pageName, string $ancestorPageId = null): ?string
{
    if ($pageId = self::$pageIds[$pageName] ?? null) {
        return $pageId;
    }

    $res = $this->notionClient->request('POST', '/v1/search', [
        'json' => [
            'query' => $pageName,
            'filter' => [
                'value' => 'page',
                'property' => 'object',
            ],
        ],
    ]);
    // この時点では検索にヒットした全ページが結果に含まれている（ページ名完全一致以外のページやアーカイブ済みのページも含まれる）
    $res = json_decode($res->getContent(), flags: JSON_THROW_ON_ERROR);

    foreach ((array) $res->results as $result) {
        if (($result->archived ?? null) || !($result->properties?->title?->title ?? null)) {
            continue;
        }
        if (($result->properties->title->title[0]?->text?->content ?? null) === $pageName) {
            $pageId = $result->id ?? null;
            break;
        }
    }

    if ($pageId) {
        self::$pageIds[$pageName] = $pageId;
    }

    return $pageId;
}

インテグレーションに検索対象のフォルダ（ページ）へのアクセス権を渡しておくのを忘れずに
- 意外と気付きにくくてちょっとハマりました・・
- Notion API search method returns nothing - Stack Overflow
今回は手抜きで、見つかったページのうちページ名が完全に一致していてアーカイブ済みでないページがもし複数あった場合は、最初に見つかったものが採用される仕様にしています

レコードを挿入するメソッド

public function insert(Row $row): void
{
    // プロジェクトのIDを取得
    $projectId = $row->projectName ? $this->getProjectId($row->projectName) : null;

    // 担当者のIDを取得
    $ownerId = $this->getStaffId($row->ownerName);
    if (!$ownerId) {
        throw new \RuntimeException('指定された担当者が見つかりませんでした。');
    }

    // 依頼者のIDを取得
    $ordererId = $row->ordererName ? $this->getStaffId($row->ordererName) : null;
    if ($row->ordererName && !$ordererId) {
        throw new \RuntimeException('指定された発注者が見つかりませんでした。');
    }

    // リンク先ページのIDを取得
    $linkPageId = $row->linkPageName ? $this->getPageId($row->linkPageName) : null;

    $options = [
        'json' => [
            'parent' => [
                'database_id' => $this->targetDatabaseId,
            ],
            'properties' => [
                '名前' => ['title' => [['text' => ['content' => $row->name]]]],
                '種別' => ['select' => ['name' => $row->type]],
                'タグ' => ['multi_select' => array_map(fn (string $tag) => ['name' => $tag], $row->tags)],
                'プロジェクト' => ['relation' => [['id' => $projectId]]],
                '担当者' => ['relation' => [['id' => $ownerId]]],
                '依頼者' => ['relation' => [['id' => $ordererId]]],
                '日付' => ['date' => [
                    'start' => $row->startedDate->format('Y-m-d'),
                    'end' => $row->endedDate?->format('Y-m-d'),
                ]],
            ],
        ],
    ];
    
    if ($row->status) {
        $options['json']['properties']['ステータス'] = ['status' => ['name' => $row->status]];
    }
    
    $bodyBlocks = $row->body ? [[
        'object' => 'block',
        'type' => 'paragraph',
        'paragraph' => [
            'rich_text' => [
                [
                    'type' => 'text',
                    'text' => [
                        'content' => $row->body,
                    ],
                ],
            ],
        ],
    ]] : [];

    $linkPageBlocks = $linkPageId ? [
        [
            'object' => 'block',
            'type' => 'heading_1',
            'heading_1' => [
                'rich_text' => [[
                    'type' => 'text',
                    'text' => [
                        'content' => '関連ページ',
                    ],
                ]],
            ],
        ],
        [
            'object' => 'block',
            'type' => 'link_to_page',
            'link_to_page' => [
                'type' => 'page_id',
                'page_id' => $linkPageId,
            ],
        ],
    ] : [];

    if ($children = array_filter(array_merge($bodyBlocks, $linkPageBlocks)) ?: null) {
        $options['json']['children'] = $children;
    }

    // レコードを挿入
    $res = $this->notionClient->request('POST', '/v1/pages', $options);

    if (201 === $res->getStatusCode()) {
        throw new \RuntimeException($res->getContent(false));
    }
}

CSVの「本文」カラムに @ページ名 とか書けば自動でパースしてリンクにしてくれるようにする、とかもできそうですが面倒だったのでやりませんでした

ちなみにリクエスト制限について

Request limits
Notion APIのLimit（リクエスト制限）で気になったことまとめ
平均3リクエスト/秒 までOKで、1時間や1日単位での制限は記事執筆時点でなし

参考リンク

Notion API を使用してデータベースを操作する
Notion APIリファレンス
Notion公式ドキュメント
- Synced Block, Link to Page and Template block types are now supported in the API #link-to-page-block-type

GitHubで編集を提案

Discussion

koni

有用な記事ありがとうございます！

ちなみにNotion標準のCSV取り込み機能だとできなかったこと
あくまで記事執筆時点の実験結果です。そのうち機能が改善されたりするかもしれません。
マルチセレクトの項目にはどのような書き方をしても値をセットすることができなかった

同じ目的のためにNotionにCSV取り込みしたところ、マルチセレクトのプロパティにもともとあるオプションの値は入れられるようでした！オプションとして入っていない項目は空のままでした。

もしかしたら記事執筆後改善されたのかもしれません。

ttskch

追加情報ありがとうございます！