Перейти до вмісту
Blackbird API

Notion

View on Github

Notion — це платформа для створення нотаток та організації ідей. Цей додаток Notion в основному зосереджений на управлінні сторінками та базами даних.

Перед налаштуванням

Перш ніж підключитися, переконайтеся, що:

  • У вас є обліковий запис Notion
  • У вас достатньо дозволів у робочому просторі, який ви хочете підключити до Blackbird.

Підключення

  1. Перейдіть до додатків і знайдіть Notion.
  2. Натисніть Add Connection.
  3. Назвіть своє підключення для подальшого використання, наприклад, “Моє підключення до Notion”.
  4. Натисніть Authorize connection.
  5. У спливаючому вікні виберіть робочий простір, до якого ви хочете підключитися, у верхньому правому куті.
  6. Натисніть Select pages
  7. Вручну виберіть усі сторінки, до яких ви хочете надати доступ Blackbird.
  8. Натисніть Allow access
  9. Переконайтеся, що з’явилося підключення і його статус — Connected.

Якщо пізніше ви захочете надати Blackbird доступ до інших сторінок, ви можете зробити це вручну через опції сторінки в Notion.

Actions

Blocks

  • Search block’s children повертає всіх нащадків вказаного блоку. Замість блоку ви можете ввести ID Page, щоб повернути всі блоки, що належать цій сторінці.
  • Get/Delete block

Comments

  • Search comments повертає список коментарів, доданих до вказаного Block.
  • Add comment додає коментар до вказаної Page або Discussion.

Databases

  • Search databases повертає список усіх баз даних у робочому просторі. Ви можете фільтрувати список за часом створення/редагування.
  • Search pages in database повертає список усіх дочірніх Pages у базі даних. Ви можете фільтрувати список за часом створення/редагування.
  • Create/Get database

Pages

  • Search pages повертає список усіх сторінок у робочому просторі. Ви можете фільтрувати список за часом створення/редагування.
  • Get page as HTML повертає вміст вказаної сторінки як HTML-файл.
  • Create/Update page from HTML створює/оновлює сторінку з HTML-файлу. Ми рекомендуємо використовувати дію “Create page from HTML”, оскільки вона не впливає на існуючий вміст. З іншого боку, дія “Update page from HTML” впливає на існуючий вміст. Оскільки Notion не дозволяє безпосередньо оновлювати блоки, спочатку буде видалено весь вміст сторінки, а потім додано вміст з HTML-файлу.
  • Get page string/number/date/boolean/files/multiple property повертає значення властивості запису бази даних певного типу.
  • Set page string/number/boolean/files/multiple property оновлює значення властивості запису бази даних певного типу.
  • Set page property as empty
  • Create/Get/Archive page

Для дій “Create page” та “Create page from HTML” необхідно вказати батьківську сторінку або базу даних, де буде створена нова сторінка. Якщо не вказано, дія завершиться помилкою.

Users

  • Search users повертає список користувачів, що належать до робочого простору.
  • Get users повертає детальну інформацію про вказаного користувача.

Events

Pages

  • On pages created Відстежує сторінки, які були створені у вказаний проміжок часу. Щоб надати Blackbird доступ до новостворених сторінок, ви повинні зробити це вручну через опції сторінки в Notion
  • On pages updated Відстежує сторінки, які були оновлені у вказаний проміжок часу.
  • On pages status changed Відстежує базу даних на наявність сторінок, статус яких змінився на бажане значення у вказаний проміжок часу.
  • On button clicked спрацьовує, коли користувач натискає кнопку в Notion. Дивіться інструкції з налаштування нижче.

Налаштування події при натисканні кнопки

  1. Створіть Bird, який починається з події On button clicked
  2. Налаштуйте Bird і опублікуйте його.

1737728505623

  1. Скопіюйте URL веб-хука внизу панелі подій.
  2. Створіть кнопку в Notion. Ви можете зробити це або всередині вмісту сторінки, або як властивість сторінки.

1737728586269

  1. Натисніть на Edit automation. Потім натисніть + New action і виберіть Send webhook

1737728711506

  1. Вставте URL, який ви скопіювали з Blackbird, у поле URL і натисніть Done.

1737728748357

  1. Перевірте кнопку, натиснувши на неї!

Конвертація HTML

Blackbird може конвертувати вміст Page в HTML-файл і назад, що дозволяє автоматично перекладати вміст Notion через Blackbird. Наприклад, ви можете налаштувати такий робочий процес: “Notion: Get page as HTML” → “DeepL: Translate” → “Notion: Update page from HTML.”

Вміст, який не можна перекласти, також буде передано, з деякими винятками. До них належать:

  • Попередній перегляд посилань
  • Файли, розміщені в Notion (такі як PDF, аудіо, відео чи зображення; однак зовнішні URL-адреси працюватимуть нормально)

Наразі ці типи не будуть передані. Ми постійно працюємо над удосконаленням цього процесу.

Переклад дочірніх сторінок і дочірніх баз даних повністю підтримується. Ви можете перекладати дочірні сторінки та/або дочірні бази даних, встановивши опціональні параметри ‘Include child pages’ та ‘Include child databases’ у значення true для дії ‘Get page as HTML’. Якщо ці параметри не встановлені або встановлені як false, ми не будемо витягувати чи перекладати дочірні сторінки/бази даних, і нова (або оновлена) сторінка не включатиме ці дочірні сторінки/бази даних.

Зауважте, що API Notion дозволяє створювати сторінки або бази даних, тільки коли їхнім батьківським елементом є сторінка або база даних. Це означає, що якщо ви вкладете підсторінку або базу даних всередину стовпця (або будь-якого іншого блоку), операція завершиться помилкою, схожою на:
Pages and databases cannot be nested inside other blocks. Page or database ('Page name or ID') has parent type 'block_id'. Please move it to the root level.
Щоб вирішити цю проблему, переконайтеся, що всі підсторінки та підбази даних розміщені на кореневому рівні і не вкладені в інші блоки.

Обмеження

Під час вдосконалення додатку Notion, виправлення помилок та покращення повідомлень про помилки ми виявили кілька обмежень API, які впливають на функціональність:

  1. Бази даних з властивостями status не можна створити через API Notion (Посилання). Крім того, API не дозволяє зберігати властивості статусу на сторінці. В результаті, після повторного створення стовпці типу “status” будуть втрачені.

  2. Через API доступний лише табличний перегляд бази даних. API не розрізняє елемент дошки та базу даних і не надає жодної інформації про різні перегляди в базі даних. В результаті перегляди не можуть бути відтворені, і доступний лише табличний перегляд.

  3. Сторінки та бази даних можна створювати лише під існуючою сторінкою або базою даних. API не дозволяє розміщувати підсторінку або базу даних всередині стовпця чи будь-якого іншого блоку. Підсторінки та бази даних повинні бути створені безпосередньо під сторінкою або базою даних і не можуть бути вкладені в інші блоки вмісту (Посилання).

  4. Неможливо повторно додати файли, розміщені в Notion

Зворотній зв’язок

Хочете використовувати цей додаток або маєте відгуки щодо нашої реалізації? Зв’яжіться з нами через встановлені канали або створіть issue.