Инструменты разработчика

Инструменты разработчика

Раздел Инструменты разработчика используется для интеграции, расширения и автоматизации ONLYOFFICE Docs и Apps: подключайте редакторы к своей платформе с помощью Docs Connect, встраивайте ONLYOFFICE Apps в собственное веб-приложение с помощью SDK для встраивания, используйте Плагин SDK, вебхуки, добавляйте приложения OAuth и ключи API.

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

По умолчанию доступ к разделу Инструменты разработчика включен для всех пользователей, кроме гостей, поэтому любой пользователь может открыть эту страницу и, соответственно, создавать собственные вебхуки или собственные приложения OAuth 2.0 и т. д. Если вы хотите, чтобы страница «Инструменты разработчика» была доступна только владельцу и администраторам рабочего пространства, отключите параметр Раздел «Инструменты разработчика» в разделе Безопасность.

Docs Connect

Раздел Docs Connect позволяет запустить движок редактирования документов ONLYOFFICE в облаке и встроить его в собственный продукт. Вместо того чтобы устанавливать и обслуживать ONLYOFFICE Docs на собственном сервере, вы создаете экземпляр, который размещается для вас и предоставляет вашим пользователям редакторы документов, таблиц, презентаций и PDF.

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

Dev Pack расширяет экземпляр Automation API для автоматизации действий в редакторах и параметрами брендинга, позволяющими заменить брендинг по умолчанию на собственный. Используйте ссылку Read API documentation, чтобы открыть документацию для разработчиков с подробностями об интеграции.

Экземпляр можно бесплатно протестировать в течение 30 дней, с включенными функциями Dev Pack и без ввода платежных данных. Чтобы создать свой первый экземпляр, нажмите кнопку Start free 30-day trial.

Обратите внимание

Docs Connect также можно активировать в разделе Биллинг -> Add-ons.

После создания экземпляра становятся доступны вкладки Статистика, Настройки и Просмотр. Пока действует пробный период, рядом с заголовком Docs Connect отображается количество оставшихся бесплатных дней. Используйте кнопку Subscribe, чтобы перейти на платную подписку до окончания пробного периода.

Используйте значок параметров рядом с заголовком Docs Connect, чтобы скопировать секретный ключ, обновить подписку или просмотреть историю транзакций.

Статистика

На вкладке Статистика отображается информация о вашем экземпляре:

• System overview — Адрес экземпляра, JWT header и Секретный ключ. Используйте соответствующие значки, чтобы скопировать значения или показать скрытый секретный ключ.
• License — дата начала действия лицензии, дата, до которой лицензия действительна, и количество оставшихся дней.
• Build — тип сборки, версия и дата выпуска.
• User activity in the last month — активность уникальных пользователей для Editors (редакторы документов с полными правами) и Live Viewer (просмотрщики документов только для чтения). Для каждого из них отображаются использование, а также количество активных, внутренних, внешних и оставшихся пользователей.

Нажмите кнопку Загрузить отчет, чтобы скачать отчет об активности пользователей.

Настройки

Вкладка Настройки позволяет настроить ваш экземпляр. В разделе Общие доступны следующие параметры:

• JWT header, Секретный ключ — просмотрите или измените заголовок JWT и секретный ключ. Используйте соответствующие значки, чтобы показать скрытый секретный ключ или скопировать его.
• WOPI — включите переключатель Enable WOPI protocol, чтобы разрешить интеграцию с WOPI-совместимыми поставщиками хранилищ.
• Anonymous support — выберите Да, чтобы разрешить пользователям без аутентификации доступ к документам, или Нет, если документы могут открывать только аутентифицированные пользователи.
• File size limits — укажите максимальное количество байт, которое можно скачать для обработки документа (например, 104857600 = 100 МБ).

Нажмите кнопку Сохранить, чтобы применить изменения, или кнопку Отменить, чтобы отклонить их.

Раздел IP Filtering позволяет настроить Access Rules, определяющие, с каких адресов можно получить доступ к вашему экземпляру. Каждое правило разрешает или запрещает доступ для IP-адреса, диапазона IP-адресов или хоста и отображается в списке с его типом и значением.

Обратите внимание

По умолчанию список содержит единственное правило Разрешить со значением *, которое разрешает доступ с любого адреса.

Нажмите кнопку Add Rule, чтобы добавить новое правило. Чтобы удалить отдельное правило, используйте соответствующий значок справа.

Чтобы удалить сразу все правила, нажмите кнопку Сбросить и подтвердите действие в открывшемся окне Reset access rules. Все правила разрешения и запрета будут удалены безвозвратно, и доступ будет разрешен с любого IP-адреса, пока вы не добавите новые правила.

Просмотр

Вкладка Просмотр позволяет проверить, как работают редакторы:

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

SDK для встраивания

Используйте ONLYOFFICE Apps SDK на основе JavaScript, который позволяет разработчикам использовать все возможности ONLYOFFICE Apps с помощью api.js. Вы можете интегрировать ONLYOFFICE Apps в собственное веб-приложение, позволяя пользователям создавать и отправлять документы прямо с вашего сайта. Подробнее об использовании SDK для встраивания читайте в этом руководстве

Подробнее о SDK для встраивания см. на сайте api.onlyoffice.com.

Плагин SDK

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

Чтобы приступить к созданию собственного плагина, воспользуйтесь ссылкой Читать руководства на странице Плагин SDK, где вы найдете пошаговое руководство.

Обратите внимание

Примеры плагинов не включаются автоматически. Перейдите на страницу Плагины, чтобы включить их для вашего рабочего пространства.

Примеры плагинов

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

• codemirror — просмотр и редактирование файлов с программным кодом в самых разных форматах.
• markdown — просмотр, редактирование и создание файлов Markdown (.md) прямо в вашем рабочем пространстве.
• convert-to-markdown — преобразование файлов DOCX, TXT и HTML в формат Markdown, не покидая рабочее пространство.
• zip-archives — открытие и извлечение ZIP-архивов, хранящихся в вашем рабочем пространстве.
• speech-to-text — расшифровка аудио в текст с помощью распознавания речи прямо в вашем рабочем пространстве.
• pdf-converter — преобразование документов, электронных таблиц, презентаций и форм в формат PDF.
• url — создание, редактирование и открытие файлов URL с внешними ссылками прямо из списка файлов.
• book-reader — открытие поддерживаемых файлов в специальном полноэкранном режиме чтения.
• draw.io — создание и редактирование диаграмм с помощью инструмента draw.io.
• image-editor — редактирование изображений прямо в вашем рабочем пространстве.

Возможности плагинов

Плагины, созданные с помощью Плагин SDK, могут использовать следующие функции:

• Localization — плагины поддерживают несколько языков с помощью встроенного механизма локализации.
• CSS customization — применяйте собственные стили к интерфейсу плагина с помощью стандартного CSS.
• Group menu actions — добавляйте собственные действия в меню группового выбора для файлов, папок и комнат.
• Custom selectors — отображайте встроенные селекторы рабочего пространства (базовый, файлов, комнат, групп, пользователей) в вашем плагине.
• Floating action button — добавляйте собственные операции с пользовательскими значками в плавающую кнопку действия, включая индикатор выполнения.
• Sidebar slots — размещайте точки входа плагина на боковой панели с помощью значков 32×32 пикселя. Доступно до 5 слотов.
• Context menu actions — отображайте действия, специфичные для плагина, в контекстном меню для конкретного файла, папки или комнаты.
• Media viewer integration — встраивайте ваш плагин непосредственно во встроенный просмотрщик медиафайлов.
• UI components — используйте встроенные компоненты IconButton и Ссылка для единообразного внешнего вида.

Подробнее о Плагин SDK см. на сайте api.onlyoffice.com.

Вебхуки

Используйте вебхуки, чтобы выполнять пользовательские действия на стороне любого приложения или веб-сайта, которым вы пользуетесь, на основе различных событий в ONLYOFFICE Apps. Вы можете создавать все свои вебхуки и управлять ими, настраивать их и просматривать историю каждого вебхука, чтобы проверять их работу. Подробнее об использовании вебхуков читайте в этом руководстве.

Чтобы создать вебхук, нажмите кнопку Создать вебхук и заполните форму:

• Имя вебхука — укажите имя вебхука.
• URL-адрес полезной нагрузки — укажите URL-адрес, на который будет отправляться полезная нагрузка вебхука.
• Секретный ключ — введите секретный ключ или воспользуйтесь ссылкой Сгенерировать, чтобы создать его автоматически.
• Проверка SSL-сертификатов — выберите вариант Использовать проверку SSL или вариант Отключить (не рекомендуется).
• Событие для запуска этого вебхука — выберите вариант Отправить все или Отдельные события, чтобы указать только нужные события.
• Целевой идентификатор — укажите целевой идентификатор.

Нажмите кнопку Создать.

Подробнее об API Apps см. на сайте api.onlyoffice.com.

OAuth 2.0

Используйте OAuth 2.0 для доступа к API ONLYOFFICE Apps с целью авторизации и дальнейших действий, таких как доступ к файлам и т. д.

Чтобы создать новое приложение,

1. Нажмите кнопку Зарегистрировать новое приложение. Откроется страница Новое приложение.

   

2. Заполните раздел Основные сведения:

   • Название приложения — название приложения, которое будет отображаться на всех экранах согласия и в списке приложений. Обязательный параметр.
   • URL-адрес вебсайта — ссылка на главную страницу сайта. Обязательный параметр.
   • Иконка приложения — изображение, которое будет отображаться на всех экранах согласия и в списке приложений. Используйте вариант Выбрать новое изображение, чтобы загрузить файл JPG, PNG или SVG размером 32x32. Обязательный параметр.
   • Описание — краткое описание приложения.
   • Метод аутентификации — метод проверки при получении токена JWT. Чтобы получить токен, необходимо отправить ключ SHA. При необходимости установите флажок Разрешить общедоступный клиент (PKCE).

3. Заполните раздел URL-адреса OAuth:

   • Перенаправляет URL-адреса — ссылки, на которые пользователь может быть перенаправлен после успешного прохождения экрана согласия. Введите адрес и нажмите кнопку «плюс». Можно добавить несколько ссылок, например для тестовой и рабочей версий. Обязательный параметр.
   • Разрешенные источники — URL-адреса источников, которые могут отправлять запросы к API Apps без блокировки CORS. Введите адрес и нажмите кнопку «плюс». Можно добавить несколько ссылок. Обязательный параметр.

4. В разделе Получить доступ к областям действия определите возможности стороннего приложения относительно API Apps. Области действия используются для ограничения доступа вашего приложения ко всем данным, связанным с пользователем, и позволяют точно указать, какой именно доступ вам нужен. Установите флажок Читать или Написать рядом с нужными вариантами. При выборе возможности записи данных автоматически включается чтение данных. Обязательный параметр.

   

   • Профиль — accounts.self:read для просмотра основной информации о вашем профиле, accounts.self:write для просмотра и управления основной информацией о вашем профиле.
   • Контакты — accounts:read для просмотра всех контактов, accounts:write для просмотра и управления всеми контактами.
   • Комнаты — rooms:read для просмотра всех комнат, rooms:write для просмотра и управления всеми комнатами.
   • Файлы и папки — files:read для просмотра всех файлов и папок, files:write для просмотра и управления всеми файлами и папками.
   • Open ID — openid для просмотра ваших персональных данных. Эта область действия доступна только для чтения.

5. Заполните раздел Поддержка и юридическая информация:

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

6. Нажмите кнопку Сохранить.

Созданными приложениями можно управлять в списке:

• Просматривайте информацию о вашем приложении: название, создатель, дата изменения, области действия.
• Отключайте или включайте приложение с помощью переключателя Состояние.
• Щелкните приложение правой кнопкой мыши и выберите нужный вариант:
  • Редактировать — чтобы изменить некоторые параметры, такие как Название приложения, Иконка приложения, Описание, Метод аутентификации. На этой странице также можно скопировать Client ID и Secret или при необходимости сбросить секрет.
  • Кнопка аутентификации — чтобы просмотреть кнопку авторизации, скопировать код HTML, CSS или JavaScript для встраивания ее на ваш сайт, получить ссылку для авторизации или верификатор кода. Нажав кнопку авторизации, вы также можете пройти весь процесс целиком.
  • Информация — чтобы просмотреть информацию о приложении, такую как создатель, описание, веб-сайт, доступ, области действия, поддержка и юридическая информация, дата последнего изменения.
  • Сгенерировать токен — чтобы сгенерировать токен для разработки (чтобы не проходить процесс каждый раз). Сгенерированный токен имеет ограниченный срок действия и автоматически становится недействительным при создании нового.
  • Отозвать токен — чтобы отозвать сгенерированный токен.
  • Отключить — чтобы отключить приложение и завершить все активные сеансы.
  • Удалить — чтобы удалить приложение, завершить и удалить все активные сеансы.

При переходе по ссылке авторизации возможны 3 сценария:

1. Если пользователь еще не авторизован в рабочем пространстве, откроется форма авторизации. После успешной авторизации пользователь будет перенаправлен на шаг 2 или 3.
2. Если у пользователя более одного рабочего пространства, можно будет выбрать нужное.
3. Если пользователь уже авторизован в рабочем пространстве, он будет перенаправлен на страницу согласия, на которой отображаются возможности приложения, ссылки на политику безопасности и условия использования. Пользователь может нажать кнопку Allow или Отклонить, а также выбрать другой профиль.

Подробнее об API Apps см. на сайте api.onlyoffice.com.

Ключи API

Как владелец или администратор, вы можете просматривать все ключи API этого рабочего пространства и управлять ими. Чтобы узнать больше, воспользуйтесь ссылкой Read the API guide.

Обратите внимание

Храните ключи API в тайне — не передавайте их другим и не размещайте в браузере или другом клиентском коде.

Чтобы создать новый ключ API,

1. Нажмите кнопку Создать новый секретный ключ.
2. Заполните форму:

   • Имя — укажите имя секретного ключа.

   • Права доступа — выберите нужный вариант:

     • Все — включить права на чтение и запись для всех разделов.

       

     • Ограничено — включить права на чтение или запись для определенных разделов. В списке Получить доступ к областям действия установите флажок Читать или Написать рядом с нужными вариантами: Файлы и папки, Комнаты, Профиль, Контакты. При выборе возможности записи данных автоматически включается чтение данных. Кнопка Сгенерировать становится активной только после выбора хотя бы одной области действия.

       

     • Только чтение — включить права только на чтение для всех разделов.

       

   • Срок действия ключа — включите этот переключатель, чтобы автоматически деактивировать секретный ключ по истечении заданного периода, затем укажите количество дней (максимум 365). Срок действия отсчитывается с момента создания ключа.

3. Нажмите кнопку Сгенерировать.
4. В новом окне скопируйте созданный ключ и нажмите Готово.

Созданными ключами API можно управлять в списке:

• Просматривайте информацию о вашем ключе: имя, секретный ключ, дата создания, дата последнего использования, создатель, права доступа.
• Отключайте или включайте ключ с помощью переключателя Состояние.
• Щелкните ключ правой кнопкой мыши или используйте значок параметров справа и выберите нужный вариант:
  • Редактировать — чтобы изменить Имя и Права доступа ключа.
  • Удалить — чтобы удалить ключ.

Подробнее об API Apps см. на сайте api.onlyoffice.com.