Начало работы с Notion API и его SDK для JavaScript

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

Notion представила миру свой API в виде открытой бета-версии. У него отличная документация, к нему действительно легко получить доступ, и, что более важно для нас, разработчиков JavaScript, он также предлагает SDK для JavaScript. 🎉

Хотя для работы с этой статьей не требуется никаких предварительных знаний (я предоставлю все необходимые шаги), мы будем иметь дело с клиентским и внутренним кодом, поскольку здесь задействована небольшая часть установки Node.js и Express.

Установка

Наша установка будет разделена на две части. Первый будет охватывать шаги, которые нам нужно выполнить в отношении программного обеспечения и API Notion. Во втором мы получим код, инициализировав папку, добавив зависимость Notion и создав начальную index.jsи отредактировав, package.jsonчтобы все работало.

Чтобы продолжить, вам понадобится учетная запись Notion, а также последняя копия.

Идея установки

Если у вас еще нет учетной записи Notion, создайте ее, перейдя по этой ссылке. У него очень щедрый уровень бесплатного пользования, и вам не нужно добавлять информацию об оплате!

После создания учетной записи и входа в систему создайте новую страницу, выбрав » Добавить страницу» и дайте ей имя. Для этого урока мы выберем Tableбазу данных. Это даст нам пустую таблицу, а это именно то, что мы хотим!

Следующий шаг — создать несколько столбцов на нашем сайте databaseи заполнить их фиктивными данными. Для этого урока мы будем работать только с Nameи Roleполей, как будто мы работаем с базой данных сотрудников в компании.

Теперь перейдем на сайт документации. В верхнем углу вы увидите ссылку » Мои интеграции«. Если вы нажмете на нее, вы попадете на экран с надписью «Мои интеграции», и ваш, конечно же, будет пустым.

Нажмите Создать новую интеграцию, введите свой заголовок и обязательно выберите свой Associated workspace(он будет выбран по умолчанию, но убедитесь в этом). Нажмите » Отправить», и вы будете перенаправлены на новую страницу с Internal Integration Token(мы будем использовать это в нашем коде) и с двумя полями для выбора того, где вы хотите использовать свою интеграцию. Вам не нужно ничего делать на этой странице, кроме копирования tokenи нажатия Сохранить изменения.

Теперь вернитесь в рабочее пространство Notion. В нашей недавно созданной базе данных мы хотим нажать » Поделиться», а затем » Пригласить». Затем вы сможете выбрать свою недавно созданную интеграцию. Выберите его и нажмите » Пригласить «, и настройка Notion завершена. Отличная работа! 🙌

Настройка кода

Теперь давайте напишем код. Откройте свой терминал и сделайте mkdir notion-api-test(это создаст папку с именем notion-api-test) в выбранном вами месте, а затем войдите в свою папку с помощью cd notion-api-testи сделайте npm init -y(эта команда создаст файл package.jsonс некоторыми базовыми настройками, а -yфлаг автоматически отвечает на некоторые запросы, чтобы вы не не надо с ними возиться).

Как я упоминал ранее, мы собираемся использовать notion-sdk-js, и для этого нам нужно установить его как зависимость, так что мы и сделаем npm install @notionhq/client.
Теперь откройте notion-api-testв вашем редакторе кода и создать начальную index.jsна rootи отредактировать package.json scripts, заменив то, что там со следующими:

"scripts": {
    "start": "node index"
},

Давайте также создадим.gitignoreфайл и еще один с именем.env. Это.gitignoreпозволяет вам помещать внутри разные имена файлов / папок, а это означает, что эти файлы / папки не будут добавлены в ваше репо, когда вы нажмете код. Это очень важно, потому что наш integration token(помните?) Будет внутри.envфайла, например:

NOTION_API_KEY = YOUR_TOKEN_HERE

Это означает, что внутри.gitignoreвы должны добавить это в первую строку:

.env

Теперь, когда у нас есть.envфайл, мы также должны добавить новую зависимость dotenv, чтобы вы могли загрузить свою NOTION_API_KEYпеременную. Вы можете сделать это, делая npm install dotenv.

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

Получение данных из Notion API

Теперь, когда скучная часть закончилась, перейдем к хорошему! Нашим index.jsфайлом будет файл Node.js, а следующий блок кода показывает наш начальный код и то, что именно делает каждая строка!

// this will allow us to import our variable
require("dotenv").config();
// the following lines are required to initialize a Notion client
const { Client } = require("@notionhq/client");
// this line initializes the Notion Client using our key
const notion = new Client({ auth: process.env.NOTION_API_KEY });

Здесь нам также понадобится дополнительная вещь, а именно идентификатор базы данных, которую мы создали в нашей рабочей области Notion. Его можно получить из адресной строки браузера. Он идет после имени вашей рабочей области (если она у вас есть), косой черты ( myworkspace/) и перед вопросительным знаком ( ?). Идентификатор состоит из 32 символов и состоит из букв и цифр.

https://www.notion.so/myworkspace/a8aec43384f447ed84390e8e42c2e089?v=...
                                  |--------- Database ID --------|

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

NOTION_API_KEY = YOUR_TOKEN_HERE
NOTION_API_DATABASE = YOUR_DATABASE_ID_HERE

Затем мы импортируем его в наш index.jsс помощью этого:

const databaseId = process.env.NOTION_API_DATABASE;

Теперь, чтобы убедиться, что наш API работает, давайте создадим функцию, которая обращается к нашей базе данных. Для этого мы создадим async function:

const getDatabase = async () => {
  const response = await notion.databases.query({ database_id: databaseId });

  console.log(response);
};

getDatabase();

Если вы теперь запустите npm startсвой терминал, вы должны увидеть журнал objectсо resultsсвойством, имеющим массив. Этот массив содержит записи в вашей базе данных. Чтобы изучить их, мы можем сделать следующее:

const getDatabase = async () => {
  const response = await notion.databases.query({ database_id: databaseId });

  const responseResults = response.results.map((page) => {
    return {
      id: page.id,
      name: page.properties.Name.title[0]?.plain_text,
      role: page.properties.Role.rich_text[0]?.plain_text,
    };
  });

  // this console.log is just so you can see what we're getting here
  console.log(responseResults);
  return responseResults;
};

Приведенный выше код сопоставляется с нашим results(сопоставлением записей в нашей базе данных), и мы сопоставляем пути для различных свойств с именами, которые мы выбираем (в данном случае id, nameи role). Обратите внимание, насколько конкретен путь к объекту. Я использовал необязательную цепочку для учета пустых строк в базе данных или строк, в которых одно или другое из этих полей не заполнено.

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

Если console.log()вам не нравится изучать каждое свойство и использовать его, вы всегда можете использовать Postman для проверки ответа. К сожалению, это выходит за рамки данного руководства, но вы можете проверить публикацию » Как освоить рабочий процесс API с помощью Postman «, чтобы попробовать!

Еще одно важное замечание: обратите внимание на notion.databases.queryто, что мы использовали. Если вы посмотрите документацию по API Notion, вы увидите, что мы используем POST | Query a database. Мы могли бы использовать просто GET | Retrieve a database, но здесь я хотел бы попросить вас прочитать документацию и попытаться отсортировать список по-другому!

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

exports.getDatabase = async function () {
  const response = await notion.databases.query({ database_id: databaseId });

  const responseResults = response.results.map((page) => {
    return {
      id: page.id,
      name: page.properties.Name.title[0]?.plain_text,
      role: page.properties.Role.rich_text[0]?.plain_text,
    };
  });

  return responseResults;
};

Настройка экспресс-сервера

Сделав предыдущий шаг, мы теперь можем успешно получить наши результаты. Но чтобы иметь возможность использовать их должным образом, нам нужно создать сервер, и самый простой способ сделать это — поскольку мы используем Node.js — использовать Express. Итак, мы начнем с запуска npm install expressи создания нового файла в корне с именем server.js.

Если expressвас смущает, не волнуйтесь. Мы будем использовать его, чтобы облегчить нашу работу и создать быструю внутреннюю часть и сервер для нашего приложения. Без него мы не смогли бы правильно получить наши данные, поскольку мы инициализируем наш клиент Notion в нашем коде.

В нашем server.jsфайле мы начнем с импорта expressмодуля, в котором у нас есть наш код ( index.js), наша getDatabaseфункция, номер порта и переменная для инициализации нашей expressфункции:

const express = require("express");
// our module
const moduleToFetch = require("./index");
// our function
const getDatabase = moduleToFetch.getDatabase;

const port = 8000;
const app = express();

// this last command will log a message on your terminal when you do `npm start`
app.listen(port, console.log(`Server started on ${port}`));

Поскольку теперь мы импортируем наш код в новый файл, server.jsмы должны изменить нашу startкоманду на package.jsonпоиск server, чтобы она выглядела так:

"scripts": {
    "start": "node server"
},

Если вы сейчас запустите npm start, вы увидите Server started on 8000сообщение, которое означает, что наша установка работает должным образом! Отличная работа!

Теперь, когда наше expressприложение работает, нам нужно заставить нашу базу данных работать с ним, и мы можем сделать это с помощью app.get(). Этому методу нужен путь (в нашем случае это не имеет значения) и функция обратного вызова (которая вызовет нашу getDatabaseфункцию):

app.get("/users", async (req, res) => {
  const users = await getDatabase();
  res.json(users);
});

В приведенном выше коде используется упомянутый app.getметод, и внутри нашей функции обратного вызова мы получаем результаты от нашей функции, и мы используем.json()функцию промежуточного программного обеспечения Express, которая анализирует запрос на читаемые и рабочие данные. (Вы можете узнать об этом немного больше в официальной документации.)

Это означает, что теперь мы успешно получаем доступ к нашим данным и создали маршрут для их «выборки». В качестве последнего шага мы должны добавить app.use(express.static(«public»));в наш server.jsфайл, чтобы конечный результат выглядел примерно так:

const express = require("express");
// our module
const moduleToFetch = require("./index");
// our function
const getDatabase = moduleToFetch.getDatabase;

const port = 8000;
const app = express();

// the code line we just added
app.use(express.static("public"));

app.get("/users", async (req, res) => {
  const users = await getDatabase();
  res.json(users);
});

app.listen(port, console.log(`Server started on ${port}`));

Этот последний фрагмент кода сообщает нашему бэкэнду useо конкретной папке, в которой мы создадим наш интерфейсный код, которым будет publicпапка. Здесь мы будем работать с нашими HTML, CSS и JavaScript, чтобы получить доступ к этому /usersмаршруту, который мы создали на нашем сервере. Давайте приступим к делу!

Отображение данных из Notion API

Мы начнем с создания в корне нашего проекта папки с именем public. Здесь будет жить наш интерфейсный код.

Части HTML и CSS просты, поэтому я в основном просто оставлю здесь код и сосредоточусь на части JavaScript, поскольку это то, для чего мы все здесь!

Наш HTML ( /public/index.html) будет выглядеть так:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Notion API Test</title>
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
    <div id="banner">Notion API Database Test</div>
    <div id="wrapper">
      <div id="container"></div>
    </div>

    <script type="module" src="./main.js"></script>
  </body>
</html>

И наш CSS ( /public/style.css) будет выглядеть так:

body,
html {
  padding: 0;
  margin: 0;

  height: 100vh;
  width: 100vw;
  font-family: Arial, Helvetica, sans-serif;

  position: relative;
}

#banner {
  height: 50px;

  display: flex;
  justify-content: center;
  align-items: center;

  background-color: #ef4444;
  color: white;
  font-weight: bold;
}

#wrapper {
  display: flex;
  justify-content: center;
  align-items: center;
  height: calc(100vh - 50px);
}

#container {
  width: 80vw;
  margin: auto;

  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
  grid-auto-rows: 200px;
  gap: 20px;
}

.userContainer {
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;

  box-shadow: rgba(149, 157, 165, 0.2) 0px 8px 24px;
  border-radius: 10px;
}

Если вы сейчас запустите npm startсвой проект и посетите http: // localhost: 8000, вы должны увидеть свой интерфейсный код.

Теперь о нашем public/main.jsфайле! Нашим первым шагом будет запрос к маршруту, который мы создали на бэкэнде ( /users/), что позволит нам получить информацию о нашей базе данных:

const getDataFromBackend = async () => {
  const rest = await fetch("http://localhost:8000/users");
  const data = await rest.json();

  return data;
};

// Note that top-level await is only available in modern browsers
// https://caniuse.com/mdn-javascript_operators_await_top_level
const res = await getDataFromBackend();
console.log(res);

Когда вы регистрируете возвращаемое значение этой функции, вы увидите в своих инструментах разработчика ту же информацию, которую мы раньше могли видеть только в терминале, а это означает, что теперь мы можем использовать наши данные во внешнем интерфейсе! Молодец! 🎉

Давайте теперь покажем эти данные внутри нашего <div id=»container»></div>, что будет очень легко. Мы начнем с выполнения a, getElementById чтобы получить нужный элемент, а затем создадим функцию, которая будет запускаться getDataFromBackend()и перебирать каждый объект внутри нашего dataмассива и помещать это содержимое в наш HTML. Вот мой подход к этому:

// Add data to HTML
const addData = async () => {
  const data = await getDataFromBackend();

  data.forEach((value) => {
    const div = document.createElement("div");
    div.classList.add("userContainer");
    div.innerHTML = `
        <h3>${value.name}</h3>
        <p>${value.role}</p>
    `;

    container.append(div);
  });
};

addData();

Итак, еще раз, наша dataпеременная (внутри addDataфункции) — это та же информация, которую мы могли видеть в журнале (массив объектов), и мы перебираем ее, создавая