Skip to end of metadata
Go to start of metadata

REST API

Icon

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

Сервер MailArchiva предлагает API веб-служб. API обеспечивает программный доступ ко многим функциям продукта; в том числе: проведение поиска, извлечение и импорт данных, обход структур папок, отправка данных, управление тегами и удержаниями. В приведенном ниже руководстве приведены практические примеры того, как запрашивать и извлекать данные с сервера. Кроме того, в нем описывается, как создать интерфейс клиента на выбранном языке программирования и получить доступ к полной документации REST API.

Обязательные требования

  • Пользователь должен быть создан в MailArchiva/AD/LDAP для доступа к API.
  • Пользователю должна быть назначена роль с минимальным разрешением web services и view status. 
  • Пользователю должны быть назначены разрешения, связанные с вызываемой функцией API.
  • Если планируется выполнение функции поиска убедитесь, что роль, назначенная пользователю, имеет пустой или соответствующий фильтр.
  • При вызове API заголовок HTTP Authorization должен быть установлен следующим образом:

Безопасность

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

REST API

Генерация хеша заголовка авторизации

Где ROOT - имя приложения для On Premise версий, admin - имя пользователя, test - пароль. 

Для выполнения базового поиска:

Результат будет JSON-документ, содержащий результаты поиска.

Чтобы проиллюстрировать поиск с помощью разбиения на страницы, сохраните следующее как файл paginate с разрешениями execute

Для извлечения файлы с ID 9ba167074a9474f32869b0ada582b944 в тому 187c1693-2855-4586-aa74-c2d8f7e648f4

Результатом будет сообщение в формате RFC822.

В Linux версии MailArchiva, есть несколько примеров сценариев внутри каталога /opt/mailarchiva/server/ws. Эти сценарии можно легко адаптировать в Windows, так как они просто обертывают команду curl, как показано выше.

Перед запуском скриптов отредактируйте сценарий setvars с помощью текстового редактора с правильным именем и паролем учётной записи.

Создание клиентского интерфейса с помощью Swagger

Для удобства, в каждый дистрибутив мы включили автоматически обновляемый swagger.json файл с помощью которого возможно создать интерфейс клиента для доступа к REST API на любом языке. Для этого откройте Редактор Swagger и загрузите swagger.json. Например, чтобы создать интерфейс клиента Python, загрузите файл JSON в Редактор Swagger, затем щелкните создать клиент и выберите Python в качестве языка. Файл swagger.json находится в каждом дистрибутиве. 

Icon

Чтобы избежать ошибки , перед отправкой swagger.json в Редакторе Swagger откройте файл с помощью текстового редактора и укажите имя хоста API в записи хоста.

"host""host": : "mailarchiva.company.local""mailarchiva.company.local",,

Документация REST API

Для удобства, в каждый дистрибутив мы включили автоматически обновляемую документацию. Документацию можно запустить открыв файл server/ws/index.html.