Notion’s Developer Platform

Что такое платформа разработчиков Notion?

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

Её основная цель — подключать внешние системы к Notion (например, обновлять Notion Database из другого источника) и расширять Notion Agents с помощью специализированных действий и интерфейсов инструментов.

Ключевые возможности

• Непрерывный upsert внешних записей в Notion Database с помощью Workers, декларативной схемы и постоянного курсора, чтобы обновления можно было возобновлять между запусками.
• Запланированная синхронизация внешнего набора данных в Notion (например, установка графика синхронизации, как 5m в примере).
• Пользовательские инструменты для Notion Agents, которые генерируют выводы (например, ассеты) и взаимодействуют с внешними API или живыми данными.
• Структурированные интерфейсы инструментов, определяющие схему входных данных инструмента (например, строка pageId для создания презентации или строка SQL query для выполнения запроса к хранилищу данных).
• Оркестрация workflow на основе webhook, которая слушает входящие webhook от других приложений и запускает workflow Notion с Notion Agents, страницами, базами данных и вызовами внешних API.

Как использовать платформу разработчиков Notion

1. Создайте или выберите Notion Database и определите схему сопоставления между этой базой и полями ваших внешних данных.
2. Создайте Worker для синхронизации данных: настройте управляемое подключение к базе данных, укажите начальную схему/первичный ключ и напишите функцию синхронизации, которая возвращает изменения записей (например, сопоставление полей источника с свойствами Notion).
3. Установите график синхронизации и стабильный идентификатор (первичный ключ), чтобы записи upsert'ились, а не дублировались.
4. Опционально добавьте пользовательские инструменты для ваших Notion Agents, регистрируя инструменты с именем, описанием, схемой входных данных и обработчиком выполнения, который выполняет действия (например, генерация ассета .pptx из страницы Notion и загрузка его обратно на страницу).
5. Для событийно-ориентированной автоматизации настройте слушатели webhook, которые запускают workflow Notion с агентами и вызовами внешних API.

Примеры использования

• Интеграция тикетов поддержки в Notion: Непрерывная синхронизация тикетов из внешней системы helpdesk в Notion Database с помощью Worker, upsert по ID тикета и сопоставлением полей вроде темы, CSAT и тегов.
• Автоматическая генерация ассетов из контента Notion: Создайте пользовательский инструмент (например, createPresentation), который читает страницу Notion как markdown, преобразует заголовки в слайды, генерирует .pptx и прикрепляет его к странице.
• Запросы к хранилищу данных из инструмента агента: Определите инструмент (например, queryRevenue), который принимает строку SQL-запроса, выполняет её на таблице хранилища и возвращает результаты в workflow агента.
• Workflow действий, запускаемые внешними событиями: Создайте workflow на основе webhook, который слушает события из любого приложения, а затем запускает workflow Notion с Notion Agents, страницами/базами данных и вызовами внешних API.
• Действия браузерного приложения, управляемые инструментом агента: Реализуйте инструмент агента, использующий провайдера автоматизации браузера для выполнения многоэтапных задач во внешнем приложении (пример: просмотр сохранённых блюд, подтверждение заказа и проверка статуса доставки).

FAQ

Поддерживает ли платформа синхронизацию Notion Database со временем?

Да. Примеры описывают Workers, которые непрерывно upsert'ают внешние записи в Notion Database, используя постоянный курсор для возобновления обновлений.

Какие выводы могут генерировать пользовательские инструменты?

В примерах показана генерация PowerPoint (.pptx) из контента страницы Notion и загрузка его обратно на страницу.

Могут ли инструменты агентов запрашивать живые внешние системы?

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

Как работают событийно-ориентированные автоматизации?

Страница описывает прослушивание входящих webhook из любого приложения и запуск workflow Notion с Notion Agents, страницами, базами данных и вызовами внешних API.

Что нужно для upsert записей в Notion?

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

Альтернативы

• Универсальные инструменты ETL/ELT (только для синхронизации данных): Если ваша основная цель — перемещение и преобразование данных в базу данных, инструменты ETL справятся с периодической загрузкой, в то время как Notion Developer Platform также охватывает инструменты для агентов и оркестрацию workflow.
• Платформы автоматизации workflow (для триггеров и оркестрации): Инструменты этой категории могут координировать вебхуки и действия между приложениями, но могут не обеспечивать такую же тесную интеграцию с Notion Agents, работающими с Notion-страницами и базами данных.
• Фреймворки для инструментов агентов с внешними интеграциями (для вызова пользовательских инструментов): Если вы уже создаёте системы агентов, вы можете использовать фреймворк инструментов для вызова API и генерации активов; платформа Notion специально ориентирована на взаимодействия агентов и синхронизацию данных вокруг рабочих пространств Notion.