Zimbra OSE で REST および SOAP API を使用する方法

ほとんどの最新の Web サービスと同様に、Zimbra OSE にはデータ交換インターフェースがあり、さまざまなサーバー機能やそこに保存されているデータにアクセスできます。API は、さまざまなアプリケーションを開発し、Zimbra を他の企業システムと統合するために使用されます。Zimbra OSE は REST API と SOAP API をサポートしています。この記事では、Zimbra OSE での SOAP および REST API の使用の違い、範囲、および例を分析します。

SOAP と REST API - 違いは何ですか?

SOAP API と REST API は実際には同じ機能を実行しますが、それらの間には類似点よりも多くの違いがあり、それらの違いは定義から始まります。したがって、SOAP が Web サービス間のデータ交換を標準化するように設計されたプロトコルである場合、それらが記述されている言語に関係なく、REST は Web サービスのアーキテクチャ スタイルです。 Web サービスが作成されます...



具体的には、Zimbra REST API と SOAP API は範囲が異なります。ここでは、REST API は CRUD 操作、つまりサーバー上のオブジェクトの作成、読み取り、更新、および削除にのみ使用されます。したがって、REST API は、xml、json、rss、html、zip、tar、tgz、ics、ifb などのさまざまな形式で Zimbra からデータをダウンロードできるため、主にサードパーティ システムとの単純な統合を作成するために使用されます。 、csv など、およびデータを Zimbra にインポートします。 SOAP API は、メールボックス データの管理に加えて、他の操作にも使用できます。もう 1 つの大きな違いは、REST は SOAP よりも安全性が低いことです。



API は、Zimbra OSE ではさらに多くの機能があり、bash スクリプトの形成をサポートするコマンド ラインとは異なり、メール サーバー上の Zimbra システム アカウントへのアクセスを必要としない操作です。



REST API



REST API は、メール、カレンダー、タスク、および連絡先を操作するための一連のメソッドによって Zimbra OSE で表されます。その中で：

• フォルダーの取得 - メール フォルダーの内容をエクスポートします
• メッセージのインポート - メッセージをメール フォルダーにインポートします
• 連絡先の取得 - 連絡先のエクスポート
• 連絡先のインポート - 連絡先のインポート
• カレンダーの取得 - カレンダーのエクスポート
• FreeBusy を取得 - フリー ビジー データのエクスポート
• 予定のインポート - 会議データのインポート
• タスクの取得 - タスクのエクスポート
• アイテムの取得 - アイテムのエクスポート

上記のすべての方法では、ユーザー認証が必要です。これは、クエリ文字列に認証データを追加することで実行でき、認証トークンを受け取ったら、それを使用してサーバーにログインします。サーバー管理者の認証データを入力するか、トークンを発行するユーザーの認証データを入力することでトークンを取得できます。

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 ファイルがユーザーのホーム フォルダーに作成されます。このトークンには有効期限があり、この期間が過ぎると、REST リクエストを介して Zimbra メールボックスにアクセスするには、新しいトークンを発行する必要があることに注意してください。トークン自体は、「0_」で始まる 313 文字の文字列です。







このトークンをコピーしたら、それを使用して REST API を介してメールボックス データにアクセスできます。たとえば、curl -k 'https://example.ru/home/user@example.ru/Inbox/?fmt=rss&auth=qp&zauthtoken=0_xxx'> ~ のようなコマンドを使用して、Zimbra ユーザーの受信トレイの内容を取得できます。 / インボックス XML、ここで 0_xxx は認証トークン、auth = qp はトークン認証方法、fmt = rss は出力形式、~ / inbox xml は受信トレイのコンテンツがエクスポートされるファイルです。



REST リクエストにさまざまな引数を追加することで、受信トレイからデータを部分的にエクスポートできます。例えば：

• example.ru : 7070/home/user@example.ru/inbox? fmt = xml & query = agreement - REST リクエストのこのリンクを使用すると、受信トレイ フォルダーからのすべてのユーザーの手紙を xml ファイルの形式で受信できます。 「合意」という言葉
• example.ru : 7070/home/user@example.ru/inbox? fmt = xml & query = subject: agreement - 受信トレイ フォルダーからのすべてのユーザーの手紙を 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'> ~ /連絡先 .csv CURL は、連絡先の



インポートにも使用されます。たとえば、コマンド 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 に基づいてプログラムを作成するには、SOAP および REST リクエストを視覚的に作成し、それらに対するレスポンスを表示できる無料で無料のSoapUIプログラムを使用することをお勧め します。



SOAP API



SOAP API は、REST API よりも操作がはるかに複雑ですが、より多くの機能があります。サーバーに保存されているデータの管理に加えて、SOAP API を使用すると、アカウントやドメインを管理でき、実際には Zimbra のすべての機能にアクセスできます。これが、SOAP API を使用してより複雑なクライアント アプリケーションを作成する理由です。たとえば、アカウント設定を変更するため、より高度なアプリケーションを作成するために使用されます。たとえば、Zimbra OSE Web クライアントは SOAP API を使用してサーバーと通信します。



前述のように、SOAP は厳密に構造化された xml メッセージを交換するためのプロトコルであり、1 つのアプリケーションが別のアプリケーションにデータを送信できます。 SOAP メッセージを送信するためのトランスポートは通常、HTTP です。



Zimbra OSE の SOAP API は、いくつかの構成要素に分かれています。その中で：

• zimbraAccount - ユーザー アカウントとのやり取りを担当する一連の SOAP メソッド
• zimbraAdmin - 管理アクションの実行を担当する一連の SOAP メソッド
• ZimbraMailは、サーバー上のデータの管理を担当する一連の SOAP メソッドです。

SOAP API を適切に使用するには、Zimbra で使用可能な SOAP メソッドを記述した WSDL: xml ファイルが必要です。次のリンクを使用して、サーバーから直接ダウンロードできます。

• zimbraAdmin の WSDL -あなたのサーバー / サービス / wsdl / ZimbraAdminService.wsdl
• zimbraAccount の WSDL -あなたのサーバー / サービス / wsdl / ZimbraUserService.wsdl
• すべての SOAP API メソッドの WSDL - YOUR SERVER / service / wsdl / ZimbraService.wsdl

SOAP API のさまざまなセクションの説明を含む xsd ファイルも必要になります。次のリンクを使用してサーバーからダウンロードすることもできます。

• あなたのサーバー / サービス / wsdl / zimbra.xsd
• あなたのサーバー / サービス / wsdl / zimbraAdmin.xsd
• あなたのサーバー / サービス / wsdl / zimbraAdminExt.xsd
• あなたのサーバー / サービス / wsdl / zimbraMail.xsd
• あなたのサーバー / サービス / wsdl / zimbraRepl.xsd
• あなたのサーバー / サービス / wsdl / zimbraSync.xsd
• あなたのサーバー / サービス / 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>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

これには、フィールド内の認証トークン、ミリ秒単位のこのトークンの有効期限 (ライフタイム)、および使用されたスキンの名前が含まれます。







たとえば、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 フィールドには、レターの件名とテキスト、送信者と受信者のアカウントと名前を指定する必要があります。



この場合、Zimbra のいくつかの SOAP および REST リクエストを手動でコンパイルしました。ただし、それらの形成は、さまざまなプログラミング言語でスクリプトを作成することで自動化できます。これについては、次の記事で説明します。