Как и практически любой современный веб-сервис, Zimbra OSE имеет интерфейсы обмена данных, которые позволяют получать доступ к различным функциям сервера и хранящимся на нем данным. API используются для разработки различных приложений и для интеграции Zimbra с другими корпоративными системами. Zimbra OSE поддерживает REST API и SOAP API. В данной статье мы разберем отличия, сферы применения и примеры использования SOAP и REST API в Zimbra OSE.
SOAP и REST API — в чем различия?
Несмотря на то, что SOAP API и REST API фактически выполняют одну и ту же функцию, различий между ними больше, чем сходств, и начинаются эти различия с определения. Так, если SOAP — это протокол, который призван стандартизировать обмен данными между веб-сервисами, независимо от того, на каком языке они написаны, то REST — это архитектурный стиль веб-сервиса, подразумевающий ряд ограничений, в соответствии с которым создается веб-сервис.
Конкретно в Zimbra REST API и SOAP API различаются сферами применения. REST API здесь используется только для CRUD-операций, то есть для создания, чтения, обновления и удаления объектов на сервере. Поэтому используется REST API в основном для создания простых интеграций со сторонними системами, так как он позволяет выгружать из Zimbra данные в различных форматах, таких как xml, json, rss, html, zip, tar, tgz, ics, ifb, csv и других, а также импортировать данные в Zimbra. SOAP API помимо управления данными почтовых ящиков может быть использован для других операций. Существенным отличием также является то, что REST менее безопасен чем SOAP.
От командной строки, которая в Zimbra OSE обладает даже большей функциональностью и поддерживает формирование bash-скриптов, API отличается тем, что для их работы не требуется доступ к системной учетной записи Zimbra на почтовом сервере.
REST API
REST API представлен в Zimbra OSE набором методов для работы с почтой, календарями, задачами и контактами. Среди них:
- Get Folder — экспортировать содержимое почтовой папки
- Import Message — импортировать сообщение в почтовую папку
- Get Contacts — экспортировать контакты
- Import Contacts — импортировать контакты
- Get Calendar — экспортировать календарь
- Get FreeBusy — экспортировать данные о занятости
- Import Appointments — импортировать данные о встрече
- Get Tasks — экспортировать задачи
- Get Item — экспортировать элемент
Все перечисленные методы требуют аутентификации пользователя. Осуществить её можно с помощью добавления аутентификационных данных в строку запроса, а также получив токен аутентификации, использовать его для входа на сервер. Получить токен можно введя аутентификационные данные администратора сервера, а также введя аутентификационные данные пользователя, для которого выпускается токен:
curl --user 'admin:p@$$w0rD' -k 'https://example.ru/home/user@example.ru/Inbox/?fmt=sync&auth=sc' -c '~/token.txt'
curl --user 'user:qwerty123' -k 'https://example.ru/home/user@example.ru/Inbox/?fmt=sync&auth=sc' -c '~/token.txt'
Результатом этой команды будет создание файла token.txt в домашней папке пользователя, который будет содержать токен аутентификации. Обращаем ваше внимание на то, что данный токен имеет ограниченный срок годности и по истечении этого срока потребуется выпустить новый токен для доступа к почтовому ящику Zimbra по REST-запросам. Сам токен представляет из себя строку длиной 313 символов, начинающуюся с '0_'.
Скопировав данный токен можно использовать его для доступа к данным почтового ящика через REST API. Например, можно получить содержимое папки «Входящие» пользователя Zimbra с помощью команды вида curl -k 'https://example.ru/home/user@example.ru/Inbox/?fmt=rss&auth=qp&zauthtoken=0_xxx' > ~/inbox xml, где 0_xxx — это токен аутентификации, auth=qp — это метод аутентификации по токену, fmt=rss — формат вывода данных, а ~/inbox xml — это файл, в который будет экспортировано содержимое папки «Входящие».
Добавляя различные аргументы к REST-запросу можно частично экспортировать данные из папки «Входящие». Например:
- example.ru:7070/home/user@example.ru/inbox?fmt=xml&query=договор — эта ссылка в REST-запросе позволить получить в виде xml-файла все письма пользователя из папки «Входящие», содержащие слово «Договор»
- example.ru:7070/home/user@example.ru/inbox?fmt=xml&query=subject: договор — позволит получить в виде xml-файла все письма пользователя из папки «Входящие», в теме которых содержится слово «Договор»
- example.ru:7070/home/user@example.ru/inbox?fmt=xml&query=is:unread — позволит получить в виде xml-файла все непрочитанные письма пользователя из папки «Входящие»
Для того, чтобы экспортировать контакты пользователя, используйте ссылку на его папку контактов curl -k 'https://example.ru:7070/home/user@example.ru/contacts?fmt=csv&auth=qp&zauthtoken=0_xxx' > ~/contacts.csv
Для импортирования контактов также используется CURL. К примеру, c помощью команды curl -k --upload-file ~/contacts.csv 'https://example.ru:7070/home/user@example.ru/contacts?fmt=csv&auth=qp&zauthtoken=0_xxx можно импортировать CSV-файл с контактами.
Основная ценность REST API в том, что все операции, которые осуществляются с помощью него отлично поддаются автоматизации при помощи обычных bash-скриптов. Например, если получить весь список пользователей с помощью команды zmprov -l gaa > users.txt, то можно будет использовать полученный файл для последовательного выполнения рутинной операции. Например для импорта контактов в адресную книгу, экспорта электронных писем и так далее. Поэтому REST API может использоваться для написания простейших простейших CRUB-приложений для синхронизации данных между различными информационными системами на предприятиях. Для создания программ на базе REST API рекомендуем использовать свободную и бесплатную программу SoapUI, которая позволяет в наглядном виде создавать SOAP и REST-запросы и просматривать ответы на них.