Как и практически любой современный веб-сервис, Zimbra OSE имеет интерфейсы обмена данных, которые позволяют получать доступ к различным функциям сервера и хранящимся на нем данным. API используются для разработки различных приложений и для интеграции Zimbra с другими корпоративными системами. Zimbra OSE поддерживает REST API и SOAP API. В данной статье мы разберем отличия, сферы применения и примеры использования SOAP и REST API в Zimbra OSE.
Несмотря на то, что 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 набором методов для работы с почтой, календарями, задачами и контактами. Среди них:
Все перечисленные методы требуют аутентификации пользователя. Осуществить её можно с помощью добавления аутентификационных данных в строку запроса, а также получив токен аутентификации, использовать его для входа на сервер. Получить токен можно введя аутентификационные данные администратора сервера, а также введя аутентификационные данные пользователя, для которого выпускается токен:
Результатом этой команды будет создание файла 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-запросу можно частично экспортировать данные из папки «Входящие». Например:
Для того, чтобы экспортировать контакты пользователя, используйте ссылку на его папку контактов 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-запросы и просматривать ответы на них.
SOAP API
SOAP API значительно сложнее в работе, чем REST API, но при этом имеет гораздо больше возможностей. Помимо управления данными, хранящимися на сервере, SOAP API позволяет управлять учетными записями, доменами, фактически предоставляя доступ ко всей функциональности Zimbra. Именно поэтому SOAP API используется для написания более сложных клиентских приложений. Например для изменения настроек учетной записи и поэтому используется для создания более продвинутых приложений. Например, веб-клиент Zimbra OSE обменивается информацией с сервером, используя SOAP API.
Как уже говорилось выше, SOAP представляет из себя протокол обмена жестко структурированными xml-сообщениями, в которых одно приложение может передавать данные другому. Транспортом для передачи SOAP-сообщений обычно является HTTP.
SOAP API в Zimbra OSE разбито на несколько составляющих частей. Среди них:
Для нормальной работы с SOAP API, вам потребуются WSDL-файлы: xml, в которых описываются SOAP-методы, доступные для Zimbra. Загрузить их можно прямо со своего сервера по ссылкам:
Также вам потребуются xsd-файлы с описаниями для различных разделов SOAP API. Загрузить их также можно с вашего сервера по следующим ссылкам:
После импорта WSDL в SoapUI, в нем появляется панель инструментов с методами для Zimbra OSE и можно из них составлять различные приложения. Учитывая то, какие обширные возможности предоставляет SOAP API, появляется возможность создать приложения не только для автоматизации задач по управлению контентом пользователей, но и по автоматизации редактирования различных настроек, созданию, удалению и изменению доменов, пользователей и классов обслуживания.
Для выполнения большинства SOAP-запросов необходимо пройти аутентификацию. Для этого существуют SOAP-методы Auth в zimbraAdmin и zimbraAccount. Пример SOAP-запроса для аутентификации будет выглядеть следующим образом
В данном примере user@example.ru — это имя пользователя, а qwerty123 — его пароль. Также в адресной строке запроса не забудьте указать в качестве способа соединения https, так как иначе можно столкнуться с разрывом соединения со стороны Zimbra. Ответ от сервера будет выглядеть следующим образом:
В нем содержится токен аутентификации в поле , срок годности данного токена (lifetime) в миллисекундах, а также название используемой темы оформления.
Для примера создадим запрос на отправку электронного письма в Zimbra OSE. Пример соответствующего SOAP-запроса будет выглядеть так:
Здесь в поле authToken необходимо указать полученный ранее токен аутентификации, в поле SendMsgRequest указать тему и текст письма, а также учетные записи и имена отправителя и получателя.
В данном случае мы вручную составили несколько SOAP- и REST-запросов для Zimbra. Однако и их формирование можно автоматизировать за счет создания скриптов на различных языках программирования. Об этом в одной из наших следующих статей.
Эксклюзивный дистрибьютор Zextras SVZcloud. По вопросам тестирования и приобретения Zextras Carbonio обращайтесь на электронную почту: sales@svzcloud.ru
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-запросы и просматривать ответы на них.
SOAP API
SOAP API значительно сложнее в работе, чем REST API, но при этом имеет гораздо больше возможностей. Помимо управления данными, хранящимися на сервере, SOAP API позволяет управлять учетными записями, доменами, фактически предоставляя доступ ко всей функциональности Zimbra. Именно поэтому SOAP API используется для написания более сложных клиентских приложений. Например для изменения настроек учетной записи и поэтому используется для создания более продвинутых приложений. Например, веб-клиент Zimbra OSE обменивается информацией с сервером, используя SOAP API.
Как уже говорилось выше, SOAP представляет из себя протокол обмена жестко структурированными xml-сообщениями, в которых одно приложение может передавать данные другому. Транспортом для передачи SOAP-сообщений обычно является HTTP.
SOAP API в Zimbra OSE разбито на несколько составляющих частей. Среди них:
- zimbraAccount — набор SOAP-методов, отвечающих за взаимодействие с учетными записями пользователей
- zimbraAdmin — набор SOAP-методов, отвечающих за выполнение администраторских действий
- ZimbraMail — набор SOAP-методов, отвечающих за управление данными на сервере.
Для нормальной работы с SOAP API, вам потребуются WSDL-файлы: xml, в которых описываются SOAP-методы, доступные для Zimbra. Загрузить их можно прямо со своего сервера по ссылкам:
- WSDL для zimbraAdmin — ВАШ-СЕРВЕР/service/wsdl/ZimbraAdminService.wsdl
- WSDL для zimbraAccount — ВАШ-СЕРВЕР/service/wsdl/ZimbraUserService.wsdl
- WSDL для всех методов SOAP API — ВАШ-СЕРВЕР/service/wsdl/ZimbraService.wsdl
Также вам потребуются xsd-файлы с описаниями для различных разделов SOAP API. Загрузить их также можно с вашего сервера по следующим ссылкам:
- ВАШ-СЕРВЕР/service/wsdl/zimbra.xsd
- ВАШ-СЕРВЕР/service/wsdl/zimbraAdmin.xsd
- ВАШ-СЕРВЕР/service/wsdl/zimbraAdminExt.xsd
- ВАШ-СЕРВЕР/service/wsdl/zimbraMail.xsd
- ВАШ-СЕРВЕР/service/wsdl/zimbraRepl.xsd
- ВАШ-СЕРВЕР/service/wsdl/zimbraSync.xsd
- ВАШ-СЕРВЕР/service/wsdl/zimbraVoice.xsd
После импорта WSDL в SoapUI, в нем появляется панель инструментов с методами для Zimbra OSE и можно из них составлять различные приложения. Учитывая то, какие обширные возможности предоставляет SOAP API, появляется возможность создать приложения не только для автоматизации задач по управлению контентом пользователей, но и по автоматизации редактирования различных настроек, созданию, удалению и изменению доменов, пользователей и классов обслуживания.
Для выполнения большинства SOAP-запросов необходимо пройти аутентификацию. Для этого существуют SOAP-методы Auth в zimbraAdmin и zimbraAccount. Пример SOAP-запроса для аутентификации будет выглядеть следующим образом
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:zimbra" xmlns:urn1="urn:zimbraAccount">
<soapenv:Header>
<urn:context xmlns:urn="urn:zimbra"/>
</soapenv:Header>
<soapenv:Body>
<urn1:AuthRequest xmlns:urn1="urn:zimbraAccount">
<urn1:account by="name">user@example.ru</urn1:account>
<urn1:password>qwerty123</urn1:password>
</urn1:AuthRequest>
</soapenv:Body>
</soapenv:Envelope>В данном примере user@example.ru — это имя пользователя, а qwerty123 — его пароль. Также в адресной строке запроса не забудьте указать в качестве способа соединения https, так как иначе можно столкнуться с разрывом соединения со стороны Zimbra. Ответ от сервера будет выглядеть следующим образом:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<context xmlns="urn:zimbra">
<change token="5489"/>
</context>
</soap:Header>
<soap:Body>
<AuthResponse xmlns="urn:zimbraAccount">
<authToken>0_xxx</authToken>
<lifetime>172799986</lifetime>
<skin>zextras</skin>
</AuthResponse>
</soap:Body>
</soap:Envelope>В нем содержится токен аутентификации в поле , срок годности данного токена (lifetime) в миллисекундах, а также название используемой темы оформления.
Для примера создадим запрос на отправку электронного письма в Zimbra OSE. Пример соответствующего SOAP-запроса будет выглядеть так:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:zimbra" xmlns:urn1="urn:zimbraMail">
<soapenv:Header>
<context xmlns="urn:zimbra">
<authToken>0_xxx</authToken>
</context>
</soapenv:Header>
<soapenv:Body>
<SendMsgRequest xmlns="urn:zimbraMail">
<m su="Тест">
<content>Тест</content>
<e a="admin@example.ru" t="f" p="admin" />
<e a="ivanov@example.ru.com" t="t" p="Ivanov" />
</m>
</SendMsgRequest>
</soapenv:Body>
</soapenv:Envelope>Здесь в поле authToken необходимо указать полученный ранее токен аутентификации, в поле SendMsgRequest указать тему и текст письма, а также учетные записи и имена отправителя и получателя.
В данном случае мы вручную составили несколько SOAP- и REST-запросов для Zimbra. Однако и их формирование можно автоматизировать за счет создания скриптов на различных языках программирования. Об этом в одной из наших следующих статей.
Эксклюзивный дистрибьютор Zextras SVZcloud. По вопросам тестирования и приобретения Zextras Carbonio обращайтесь на электронную почту: sales@svzcloud.ru
