Clever Geek Handbook

Como usar REST e SOAP API no Zimbra OSE

Como quase qualquer serviço web moderno, o Zimbra OSE tem interfaces de troca de dados que permitem acessar várias funções do servidor e dados armazenados nele. As APIs são usadas para desenvolver vários aplicativos e para integrar o Zimbra a outros sistemas corporativos. Zimbra OSE suporta REST API e SOAP API. Neste artigo, iremos analisar as diferenças, âmbitos e exemplos de utilização de SOAP e REST API no Zimbra OSE.



imagem



SOAP e REST API - quais são as diferenças?



Embora a API SOAP e a API REST realmente executem a mesma função, há mais diferenças do que semelhanças entre elas e essas diferenças começam com a definição. Portanto, se o SOAP é um protocolo projetado para padronizar a troca de dados entre os serviços da web, independentemente da linguagem em que são escritos, o REST é um estilo de arquitetura de um serviço da web, o que implica uma série de restrições de acordo com as quais um serviço da web é criado ...



Especificamente, Zimbra REST API e SOAP API diferem em escopo. A API REST é usada aqui apenas para operações CRUD, ou seja, para criar, ler, atualizar e excluir objetos no servidor. Portanto, a API REST é usada principalmente para criar integrações simples com sistemas de terceiros, pois permite baixar dados do Zimbra em vários formatos, como xml, json, rss, html, zip, tar, tgz, ics, ifb , csv e outros, e também importar dados para o Zimbra. A API SOAP pode ser usada para outras operações, além de gerenciar dados de caixa de correio. Outra diferença significativa é que REST é menos seguro que SOAP.



A API difere da linha de comando, que no Zimbra OSE tem ainda mais funcionalidade e suporta a formação de scripts bash, pois seu funcionamento não requer acesso à conta do sistema Zimbra no servidor de e-mail.



API REST A API



REST é representada no Zimbra OSE por um conjunto de métodos para trabalhar com correio, calendários, tarefas e contatos. Entre eles:



  • Obter pasta - exportar o conteúdo de uma pasta de e-mail
  • Importar mensagem - importar uma mensagem para uma pasta de e-mail
  • Obter contatos - exportar contatos
  • Importar contatos - importar contatos
  • Obter calendário - exportar calendário
  • Get FreeBusy - Exportar dados do Free Busy
  • Importar compromissos - importar dados da reunião
  • Obter tarefas - exportar tarefas
  • Obter item - exportar item


Todos os métodos acima requerem autenticação do usuário. Isso pode ser feito adicionando dados de autenticação à string de consulta, bem como tendo recebido um token de autenticação, use-o para fazer login no servidor. Você pode obter um token inserindo os dados de autenticação do administrador do servidor, bem como inserindo os dados de autenticação do usuário para o qual o token foi emitido: 



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'


O resultado desse comando será a criação de um arquivo token.txt na pasta pessoal do usuário que conterá o token de autenticação. Observe que este token tem uma data de expiração limitada e, após esse período, você precisará emitir um novo token para acessar a caixa de correio Zimbra por meio de solicitações REST. O token em si é uma string de 313 caracteres começando com '0_'.







Depois de copiar esse token, você pode usá-lo para acessar os dados da caixa de correio por meio da API REST. Por exemplo, você pode obter o conteúdo da caixa de entrada do usuário Zimbra usando um comando como curl -k 'https://example.ru/home/user@example.ru/Inbox/?fmt=rss&auth=qp&zauthtoken=0_xxx'> ~ / inbox xml, onde 0_xxx é o token de autenticação, auth = qp é o método de autenticação de token, fmt = rss é o formato de saída e ~ / inbox xml é o arquivo para o qual o conteúdo da caixa de entrada será exportado.



Ao adicionar vários argumentos à solicitação REST, você pode exportar dados parcialmente da caixa de entrada. Por exemplo:



  • example.ru : 7070/home/user@example.ru/inbox? fmt = xml & query = agreement - este link na solicitação REST permitirá que você receba na forma de um arquivo xml todas as cartas do usuário da pasta Caixa de entrada contendo a palavra "Acordo"
  • example.ru : 7070/home/user@example.ru/inbox? fmt = xml & query = subject: agreement - permite que você receba na forma de um arquivo xml todas as cartas do usuário da pasta Inbox, cujo assunto contém a palavra "Acordo"
  • example.ru:7070/home/user@example.ru/inbox?fmt=xml&query=is:unread — xml- «»


Para exportar os contatos do usuário, use o link para sua pasta de contatos curl -k 'https://example.ru:7070/home/user@example.ru/contacts?fmt=csv&auth=qp&zauthtoken=0_xxx'> ~ / contatos .csv CURL



também é usado para importar contatos. Por exemplo, usando o comando curl -k --upload-file ~ / contacts.csv 'https://example.ru:7070/home/user@example.ru/contacts?fmt=csv&auth=qp&zauthtoken=0_xxx você pode importar CSV - arquivo com contatos.



O principal valor da API REST é que todas as operações realizadas por meio dela se prestam bem à automação por meio de scripts bash comuns. Por exemplo, se você obtiver a lista inteira de usuários com o comando zmprov -l gaa>users.txt, então você pode usar o arquivo resultante para execução sequencial de operações de rotina. Por exemplo, para importar contatos para o catálogo de endereços, exportar e-mails e assim por diante. Portanto, a API REST pode ser usada para escrever os aplicativos CRUB mais simples e simples para sincronização de dados entre vários sistemas de informação nas empresas. Para criar programas baseados na API REST, recomendamos o uso do programa SoapUI gratuito , que permite criar visualmente solicitações SOAP e REST e visualizar as respostas a elas.



API SOAP



A API SOAP é muito mais complexa de se trabalhar do que a API REST, mas tem muito mais recursos. Além de gerenciar os dados armazenados no servidor, a API SOAP permite gerenciar contas, domínios, de fato, proporcionando acesso a todas as funcionalidades do Zimbra. É por isso que a API SOAP é usada para escrever aplicativos de cliente mais complexos. Por exemplo, para alterar as configurações da conta e, portanto, é usado para criar aplicativos mais avançados. Por exemplo, o cliente Web Zimbra OSE se comunica com o servidor usando a API SOAP.



Conforme mencionado acima, SOAP é um protocolo para a troca de mensagens xml rigidamente estruturadas, em que um aplicativo pode transmitir dados para outro. O transporte para transmissão de mensagens SOAP geralmente é HTTP.



A API SOAP no Zimbra OSE é dividida em várias partes constituintes. Entre eles:



  • zimbraAccount - um conjunto de métodos SOAP responsáveis ​​por interagir com contas de usuário
  • zimbraAdmin - um conjunto de métodos SOAP responsáveis ​​por realizar ações administrativas
  • ZimbraMail é um conjunto de métodos SOAP responsáveis ​​pelo gerenciamento de dados no servidor.


Para funcionar corretamente com a API SOAP, você precisa dos arquivos WSDL: xml, que descrevem os métodos SOAP disponíveis para Zimbra. Você pode baixá-los diretamente de seu servidor usando os links:





Você também precisará de arquivos xsd com descrições para as várias seções da API SOAP. Você também pode baixá-los de seu servidor usando os seguintes links:





Depois de importar WSDL para SoapUI, uma barra de ferramentas aparece nela com métodos para Zimbra OSE e você pode compor vários aplicativos a partir deles. Considerando os extensos recursos fornecidos pela API SOAP, torna-se possível criar aplicativos não apenas para automatizar tarefas de gerenciamento de conteúdo do usuário, mas também para automatizar a edição de várias configurações, criar, excluir e alterar domínios, usuários e classes de serviço.



A maioria das solicitações SOAP requer autenticação. Existem métodos de autenticação SOAP no zimbraAdmin e no zimbraAccount para isso. Um exemplo de solicitação SOAP para autenticação seria semelhante a este 



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


Neste exemplo, user@example.ru é o nome de usuário e qwerty123 é sua senha. Além disso, na barra de endereço da solicitação, não se esqueça de especificar https como o método de conexão, caso contrário, você pode encontrar uma desconexão do lado do Zimbra. A resposta do servidor será assim: 



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


Ele contém o token de autenticação no campo, a data de expiração desse token (tempo de vida) em milissegundos e o nome do skin usado.







Por exemplo, vamos criar uma solicitação para enviar um e-mail para o Zimbra OSE. Um exemplo de solicitação SOAP correspondente seria assim: 



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


Aqui, no campo authToken, você deve especificar o token de autenticação recebido anteriormente, no campo SendMsgRequest, especificar o assunto e o texto da carta, bem como as contas e nomes do remetente e do destinatário.



Neste caso, compilamos manualmente várias solicitações SOAP e REST para o Zimbra. No entanto, sua formação pode ser automatizada pela criação de scripts em várias linguagens de programação. Sobre isso em um de nossos próximos artigos.


More articles:


All Articles