Использование Notion в качестве базы данных

Notion — это один из самых влиятельных инструментов повышения производительности, появившихся за последние несколько лет. Он обеспечивает единое рабочее пространство для каждой команды. Это больше, чем документ или таблица, он позволяет вам настраивать свое рабочее пространство так, чтобы оно работало на вас.

В марте этого года Notion API официально вышел из бета-версии, поэтому давайте попробуем его на практике, создав страницу «Связаться с нами».

Мы будем использовать React, Next.js, Mantine и Notion (в качестве базы данных). Мы не будем интегрировать аутентификацию для этого проекта, специально, чтобы устранить любые трения и позволить любому отправить сообщение «Свяжитесь с нами».

Это живая демонстрация (так что не стесняйтесь оставить мне комментарий и попробовать ее), и вот как запустить наш проект:

# React Typescript Next.js
$ npx create-next-app@latest --typescript
# Next.js Sass Support
$ npm i --save-dev sass
# Mantine
$ npm i @mantine/hooks @mantine/core @mantine/next @mantine/notifications
# React Icons
$ npm i react-icons --save
# Notion SDK for JavaScript
$ npm i @notionhq/client
Войти в полноэкранный режим Выйти из полноэкранного режима

Не стесняйтесь идти вперед и взять копию GitHub Repo демо-версии. Там нет начального проекта, но вы можете взять все, что вам нужно для начала работы.

Создайте свою форму

Вам нужно будет создать форму для сбора контактных данных пользователя. Я решил предоставить поля для: (a) Имя пользователя, (b) Электронная почта и (c) Комментарий. Для управления состоянием формы я использую API React useState(). Подробнее об этом можно узнать здесь. Структура данных формы, которую я использую, выглядит следующим образом:

type FormType {
    user: string;
    email: string;
    comment: string;
}
Вход в полноэкранный режим Выход из полноэкранного режима

Когда форма создана, давайте сосредоточимся на ее отправке. Давайте посмотрим, что происходит, когда пользователь отправляет форму:

const handleSubmit = async (e) => {
    /** Let's use this method to explicitly control the submission event */
    e.preventDefault();

    /** Email validation using a Regular Expression */
    let validation = formValidation(`${entry.email}`);

    /** If validation passes, send a POST request  */
    /** Our Next.js API will handle sending the data to Notion  */
    if (validation) {
        try {
            await fetcher("/api/contact", {
                method: "POST",
                body: JSON.stringify(entry),
            });
            /** Set form to initial state after form submission  */
            setEntry({ user: "", email: "", comment: "" });
        } catch (error) {
            console.log(error);
        }
    }
};
Вход в полноэкранный режим Выход из полноэкранного режима

Валидация формы

Валидация формы происходит только на уровне электронной почты. В наших интересах, чтобы пользователь указал правильный адрес электронной почты, и самый простой способ проверить это — использовать регулярное выражение.

const formValidation = (email) => {
    /** The test() method executes a search for a match and returns true or false */
    let emailValidation = /^[w-.]+@([w-]+.)+[w-]{2,4}$/g.test(email);

    /** If email validation fails set a state to pass a message to the form's field */
    !emailValidation &&
        setError({
            email: `Sorry! Looks like "${email}" is probably not a valid email!`,
        });

    /** Return the boolean results to continue/stop form submission */
    return emailValidation;
};
Вход в полноэкранный режим Выход из полноэкранного режима

Этот шаг совершенно необязателен, но я бы настоятельно рекомендовал убедиться, что форма, по крайней мере, имеет действительную структуру электронной почты перед отправкой. Регулярное выражение проверяет следующее:

  1. Первый набор (до @): Находит любой символ слова (буквенно-цифровой символ и символ подчеркивания), - и .,
  2. Находит символ @,
  3. Второй набор (после @): Находит любой символ слова и -,
  4. Находит символ .,
  5. Третий набор (после .): Находит любой символ слова и - длиной от 2 до 4 символов.

Конечно, вы можете изменить это выражение и решить, что считать правильной структурой электронной почты. Не стесняйтесь играть с выражением здесь.

Настройка интеграции с Notion

Прежде чем мы обсудим, как наш обработчик Next.js API отправляет данные формы в Notion. Давайте рассмотрим, как мы настраиваем нашу интеграцию и что нам для этого нужно.

  1. Зайдите на сайт Notion Developers и нажмите на правую верхнюю ссылку View my integrations.
  2. Там нажмите на Создать новую интеграцию
  3. Заполните необходимую информацию и не забудьте включить все возможности содержимого (чтение, обновление, вставка). Вам может понадобиться существующее рабочее пространство Notion, если у вас его нет, смотрите здесь.
  4. После отправки формы вы получите доступ к внутреннему интеграционному токену вашей интеграции, именно его мы определим и сохраним в переменных окружения нашего проекта как NOTION_KEY. Запишите это в файл .env.local, здесь вы найдете больше информации о том, как установить переменные окружения в вашем проекте Next.js.
NOTION_KEY=<YOUR_INTERNAL_INTEGRATION_NOTION_KEY>
Вход в полноэкранный режим Выход из полноэкранного режима

Переменные окружения — это способ идентификации и аутентификации нашего API-обработчика для отправки данных в Notion. NOTION_KEY будет аутентифицировать наше приложение для отправки HTTP-запросов в Notion. Помимо этого, нам также необходимы: Родитель базы данных (здесь обозначается как NOTION_CONTACT_DATABASE_ID) и ID пользователя (который я рекомендую использовать для присвоения записи определенному пользователю и получения уведомлений о заполнении формы). Итак, давайте посмотрим, как получить эти два ида:

Родитель базы данных

Вот краткое руководство по созданию базы данных. После создания базы данных вам необходимо получить ее ID, а также включить ее (Share it) в вашу интеграцию. В опциях базы данных вы можете нажать на Copy link to view и из этого URL вы можете извлечь ID вашей базы данных, вот пример того, как это выглядит, это должен быть первый путь перед параметром URL v:

https://www.notion.so/<NOTION_CONTACT_DATABASE_ID>?v=<...>
Войти в полноэкранный режим Выйти из полноэкранного режима

Если пути и параметры выглядят для вас одинаково, вы можете обратиться к этой статье: Анатомия URL-адреса.

Идентификатор пользователя (необязательно)

Обновления и уведомления помогают вам оставаться на вершине работы, требующей вашего внимания, и изменений, внесенных в страницы и проекты, которые вам небезразличны. Итак, для того чтобы назначенный пользователь получил уведомление о приходе формы, нам нужен ID этого пользователя, который будет включен в список пользователей рабочей области.

Мы воспользуемся фрагментом Shell из List all users, чтобы сделать запрос и получить идентификатор пользователя.

curl 'https://api.notion.com/v1/users' 
  -H 'Authorization: Bearer '"$NOTION_KEY"'' 
  -H "Notion-Version: 2022-02-22"
Вход в полноэкранный режим Выход из полноэкранного режима

Если вам нужна помощь в выполнении этого запроса, ознакомьтесь с моим руководством для начинающих по работе с API. Здесь я рекомендую использовать Postman и сделать следующее:

  1. Импортируйте сниппет cUrl,
  2. Добавьте свой $NOTION_API_KEY,
  3. Отправьте запрос на получение идентификатора пользователя.

Ответ должен выглядеть примерно так:

{
    "object": "list",
    "results": [
        {
            "object": "user",
            "id": "<NOTION_ADMIN_ID>",
            {...}
            "type": "person",
        },
        {...}
    ],
    {...}
}
Вход в полноэкранный режим Выход из полноэкранного режима

Вы должны убедиться, что назначили пользователя типа Person и определили его ID в переменных окружения как NOTION_ADMIN_ID (или предпочитаемое вами имя переменной).

В качестве итога, вот как должен выглядеть ваш файл .env.local:

NOTION_KEY=<YOUR_NOTION_KEY>
NOTION_CONTACT_DATABASE_ID=<YOUR_NOTION_CONTACT_DATABASE_ID>
NOTION_ADMIN_ID=<YOUR_NOTION_ADMIN_ID>
Вход в полноэкранный режим Выход из полноэкранного режима

Создание обработчика API Next.js

В каталоге вашего проекта должна быть папка с именем ‘API’. Здесь мы создадим папку ‘Contact’ и, наконец, файл index.ts (расширение зависит от вашего языка). Каждый раз, когда будет вызываться API-маршрут /api/contact, этот файл будет обрабатывать HTTP-запрос. Вот что вам там нужно:

/** Import Notion SDK for JavaScript */
import { Client } from "@notionhq/client";

export default async function handler(req, res) {
    /** Check the request's method before processing */
    if (req.method === "POST") {
        /** Parse the request body to access your data */
        const data = JSON.parse(req.body);
         /** Create your entry data using the required structure */
        const entry: any = {
            parent: {
                database_id: `${process.env.NOTION_CONTACT_DATABASE_ID}`,
            },
            properties: {
                Name: {
                    title: [
                        {
                            text: {
                                content: `Contact Entry`,
                            },
                        },
                    ],
                },
                User: {
                    rich_text: [
                        {
                            text: {
                                content: `${data.user}`,
                            },
                        },
                    ],
                },
                Email: {
                    email: `${data.email}`,
                },
                Comment: {
                    rich_text: [
                        {
                            text: {
                                content: `${data.comment}`,
                            },
                        },
                    ],
                },
                /** I'm using Tags to change entries state in Notion */
                Tags: {
                    type: "select",
                    select: {
                        name: "New",
                        color: "yellow",
                    },
                },
                /** Optional if you want to assign the entry to a user */
                Assigned: {
                    type: "people",
                    people: [
                        {
                            object: "user",
                            id: `${process.env.NOTION_ADMIN_ID}`,
                        },
                    ],
                },
            },
        };
        /** Authenticate your request */
        const notion = new Client({ auth: `${process.env.NOTION_KEY}` });
        const response = await notion.pages.create(entry);
        /** If the request is successful notify back */
        res.status(200).json(response);
    }
}
Войти в полноэкранный режим Выйти из полноэкранного режима

Вот документация Notion по созданию страницы. В двух словах, мы используем созданную нами базу данных Notion для создания в ней страницы и заполнения наших данных в свойствах страницы. Давайте посмотрим, как это будет выглядеть из Notion после успешного выполнения нашего запроса.

Заключение

Это отличный рабочий процесс для быстрой настройки комментариев, форм обратной связи, контактных форм, подписки на рассылку и многого другого. Сообщите мне ваши мысли о возможностях этого стека, и если у вас есть вопросы или предложения, обращайтесь!

Спасибо за чтение!

Оцените статью
Procodings.ru
Добавить комментарий