Clever Geek Handbook

Comment utiliser les API REST et SOAP dans Zimbra OSE

Comme presque tous les services Web modernes, Zimbra OSE dispose d'interfaces d'échange de données qui vous permettent d'accéder à diverses fonctions du serveur et aux données qui y sont stockées. Les API sont utilisées pour développer diverses applications et pour intégrer Zimbra à d'autres systèmes d'entreprise. Zimbra OSE prend en charge l'API REST et l'API SOAP. Dans cet article, nous analyserons les différences, les étendues et les exemples d'utilisation de SOAP et de l'API REST dans Zimbra OSE.



image



API SOAP et REST - quelles sont les différences ?



Bien que l'API SOAP et l'API REST remplissent en fait la même fonction, il existe plus de différences que de similitudes entre elles, et ces différences commencent par la définition. Ainsi, si SOAP est un protocole conçu pour standardiser l'échange de données entre les services Web, quelle que soit la langue dans laquelle ils sont écrits, alors REST est un style architectural d'un service Web, ce qui implique un certain nombre de restrictions selon lesquelles un service web est créé...



Plus précisément, l'API REST Zimbra et l'API SOAP ont une portée différente. L'API REST est utilisée ici uniquement pour les opérations CRUD, c'est-à-dire pour créer, lire, mettre à jour et supprimer des objets sur le serveur. Par conséquent, l'API REST est principalement utilisée pour créer des intégrations simples avec des systèmes tiers, car elle vous permet de télécharger des données depuis Zimbra dans différents formats, tels que xml, json, rss, html, zip, tar, tgz, ics, ifb , csv et autres, et également importer des données dans Zimbra. L'API SOAP peut être utilisée pour d'autres opérations en plus de la gestion des données de boîte aux lettres. Une autre différence significative est que REST est moins sécurisé que SOAP.



L'API diffère de la ligne de commande, qui dans Zimbra OSE a encore plus de fonctionnalités et prend en charge la formation de scripts bash, en ce que leur fonctionnement ne nécessite pas d'accès au compte système Zimbra sur le serveur de messagerie.



API REST L'API



REST est représentée dans Zimbra OSE par un ensemble de méthodes pour travailler avec le courrier, les calendriers, les tâches et les contacts. Parmi eux:



  • Get Folder - exporte le contenu d'un dossier de messagerie
  • Importer un message - importer un message dans un dossier de messagerie
  • Obtenir des contacts - exporter des contacts
  • Importer des contacts - importer des contacts
  • Obtenir le calendrier - exporter le calendrier
  • Obtenez FreeBusy - Exportez des données d'occupation gratuites
  • Importer des rendez-vous - importer des données de réunion
  • Obtenir des tâches - exporter des tâches
  • Obtenir l'article - exporter l'article


Toutes les méthodes ci-dessus nécessitent une authentification de l'utilisateur. Cela peut être fait en ajoutant des données d'authentification à la chaîne de requête, ainsi qu'en ayant reçu un jeton d'authentification, utilisez-le pour vous connecter au serveur. Vous pouvez obtenir un token en saisissant les données d'authentification de l'administrateur du serveur, ainsi qu'en saisissant les données d'authentification de l'utilisateur pour lequel le token est émis : 



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'


Le résultat de cette commande sera la création d'un fichier token.txt dans le dossier de départ de l'utilisateur qui contiendra le jeton d'authentification. Veuillez noter que ce jeton a une date d'expiration limitée et qu'après cette période, vous devrez émettre un nouveau jeton pour accéder à la boîte aux lettres Zimbra via des requêtes REST. Le jeton lui-même est une chaîne de 313 caractères commençant par « 0_ ».







Après avoir copié ce jeton, vous pouvez l'utiliser pour accéder aux données de la boîte aux lettres via l'API REST. Par exemple, vous pouvez obtenir le contenu de la boîte de réception de l'utilisateur Zimbra à l'aide d'une commande telle que curl -k 'https://example.ru/home/user@example.ru/Inbox/?fmt=rss&auth=qp&zauthtoken=0_xxx'> ~ / boîte de réception xml, où 0_xxx est le jeton d'authentification, auth = qp est la méthode d'authentification du jeton, fmt = rss est le format de sortie et ~ / inbox xml est le fichier dans lequel le contenu de la boîte de réception sera exporté.



En ajoutant divers arguments à la demande REST, vous pouvez exporter partiellement les données de la boîte de réception. Par example:



  • example.ru : 7070/home/user@example.ru/inbox? fmt = xml & query = agreement - ce lien dans la requête REST vous permettra de recevoir sous forme de fichier xml toutes les lettres des utilisateurs du dossier Inbox contenant le mot « Accord »
  • example.ru : 7070/home/user@example.ru/inbox? fmt = xml & query = subject: agreement - vous permet de recevoir sous forme de fichier xml toutes les lettres de l'utilisateur du dossier Inbox, dont le sujet contient le mot « Accord »
  • example.ru:7070/home/user@example.ru/inbox?fmt=xml&query=is:unread — xml- «»


Pour exporter les contacts de l'utilisateur, utilisez le lien vers son dossier de contacts curl -k 'https://example.ru:7070/home/user@example.ru/contacts?fmt=csv&auth=qp&zauthtoken=0_xxx'> ~ / contacts .csv CURL est



également utilisé pour importer des contacts. Par exemple, en utilisant la commande curl -k --upload-file ~ / contacts.csv 'https://example.ru:7070/home/user@example.ru/contacts?fmt=csv&auth=qp&zauthtoken=0_xxx vous pouvez importer CSV -fichier avec contacts.



La principale valeur de l'API REST est que toutes les opérations effectuées à l'aide de celle-ci se prêtent bien à l'automatisation à l'aide de scripts bash ordinaires. Par exemple, si vous obtenez la liste complète des utilisateurs avec la commande zmprov -l gaa>utilisateurs.txt, vous pouvez utiliser le fichier résultant pour l'exécution séquentielle des opérations de routine. Par exemple, pour importer des contacts dans le carnet d'adresses, exporter des e-mails, etc. Par conséquent, l'API REST peut être utilisée pour écrire les applications CRUB les plus simples et les plus simples pour la synchronisation des données entre divers systèmes d'information dans les entreprises. Pour créer des programmes basés sur l'API REST, nous vous recommandons d'utiliser le programme gratuit et gratuit SoapUI , qui vous permet de créer visuellement des requêtes SOAP et REST et d'afficher les réponses qui y sont apportées.



API SOAP



L'API SOAP est beaucoup plus complexe à utiliser que l'API REST, mais elle a beaucoup plus de fonctionnalités. En plus de gérer les données stockées sur le serveur, l'API SOAP permet de gérer des comptes, des domaines, en fait, donnant accès à toutes les fonctionnalités de Zimbra. C'est pourquoi l'API SOAP est utilisée pour écrire des applications clientes plus complexes. Par exemple, pour modifier les paramètres du compte et est donc utilisé pour créer des applications plus avancées. Par exemple, le client Web Zimbra OSE communique avec le serveur à l'aide de l'API SOAP.



Comme mentionné ci-dessus, SOAP est un protocole d'échange de messages XML à structure rigide, dans lequel une application peut transmettre des données à une autre. Le transport pour la transmission des messages SOAP est généralement HTTP.



L'API SOAP dans Zimbra OSE est décomposée en plusieurs parties constitutives. Parmi eux:



  • zimbraAccount - un ensemble de méthodes SOAP chargées d'interagir avec les comptes d'utilisateurs
  • zimbraAdmin - un ensemble de méthodes SOAP chargées d'effectuer des actions administratives
  • ZimbraMail est un ensemble de méthodes SOAP chargées de gérer les données sur le serveur.


Pour fonctionner correctement avec l'API SOAP, vous avez besoin des fichiers WSDL : xml, qui décrivent les méthodes SOAP disponibles pour Zimbra. Vous pouvez les télécharger directement depuis votre serveur en utilisant les liens :





Vous aurez également besoin de fichiers xsd avec des descriptions pour les différentes sections de l'API SOAP. Vous pouvez également les télécharger depuis votre serveur en utilisant les liens suivants :





Après avoir importé WSDL dans SoapUI, une barre d'outils apparaît avec des méthodes pour Zimbra OSE et vous pouvez composer diverses applications à partir d'elles. Compte tenu des capacités étendues fournies par l'API SOAP, il devient possible de créer des applications non seulement pour automatiser les tâches de gestion du contenu utilisateur, mais également pour automatiser l'édition de divers paramètres, créer, supprimer et modifier des domaines, des utilisateurs et des classes de service.



La plupart des requêtes SOAP nécessitent une authentification. Il existe des méthodes SOAP Auth dans zimbraAdmin et zimbraAccount pour cela. Un exemple de demande d'authentification SOAP ressemblerait à ceci 



<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>


Dans cet exemple, user@example.ru est le nom d'utilisateur et qwerty123 est son mot de passe. Aussi, dans la barre d'adresse de la requête, n'oubliez pas de spécifier https comme méthode de connexion, sinon vous risquez de rencontrer une déconnexion du côté de Zimbra. La réponse du serveur ressemblera à ceci : 



<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>


Il contient le jeton d'authentification dans le champ, la date d'expiration de ce jeton (durée de vie) en millisecondes, et le nom du skin utilisé.







Par exemple, créons une demande pour envoyer un e-mail à Zimbra OSE. Un exemple de requête SOAP correspondante ressemblerait à ceci : 



<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>


Ici, dans le champ authToken, vous devez spécifier le jeton d'authentification précédemment reçu, dans le champ SendMsgRequest, spécifiez l'objet et le texte de la lettre, ainsi que les comptes et les noms de l'expéditeur et du destinataire.



Dans ce cas, nous avons compilé manuellement plusieurs requêtes SOAP et REST pour Zimbra. Cependant, leur formation peut être automatisée en créant des scripts dans divers langages de programmation. À ce sujet dans un de nos prochains articles.


More articles:


All Articles