Garoon SOAP APIの共通仕様

Garoon SOAP APIの概要

Garoon SOAP APIでは、SOAPを使用してガルーンと他システムの連携を行います。Garoon SOAP APIの定義は、WSDL（Web Service Definition Language）によって記述されています。ガルーンが既定のディレクトリにインストールされている場合、下記のURLで確認できます。

• クラウド版 Garoon： https://（サブドメイン名）.cybozu.com/g/index.csp?WSDL
• パッケージ版 Windows 環境：http://（インストールしたサーバーの IP アドレスまたはホスト名）/scripts/（インストール識別子）/grn.exe?WSDL
• パッケージ版 Linux 環境：http://（インストールしたサーバーの IP アドレスまたはホスト名）/cgi-bin/（インストール識別子）/grn.cgi?WSDL

Garoon SOAP APIでは、SOAPとWSDLの次のバージョンを使用します。

SOAP では、XML に基づいたメッセージを通信します。 Garoon SOAP APIでのリクエストとレスポンスの例を以下に示します。

例：リクエスト

POST /g/cbpapi/base/api.csp HTTP/1.1
Host: {subdomain}.cybozu.com
Content-Type: text/xml; charset=UTF-8

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
    <Action>
      BaseGetApplicationStatus
    </Action>
    <Security>
      <UsernameToken>
        <Username>xxxxxxxxxx</Username>
        <Password>xxxxxxx</Password>
      </UsernameToken>
    </Security>
    <Timestamp>
      <Created>2010-08-12T14:45:00Z</Created>
      <Expires>2037-08-12T14:45:00Z</Expires>
    </Timestamp>
    <Locale>jp</Locale>
  </soap:Header>
  <soap:Body>
    <BaseGetApplicationStatus>
      <parameters></parameters>
    </BaseGetApplicationStatus>
  </soap:Body>
</soap:Envelope>

例：レスポンス

HTTP/1.1 200 OK
Date: Tue, 03 Sep 2013 05:44:26 GMT
Server: Apache
Strict-Transport-Security: max-age=315360000
X-Content-Type-Options: nosniff
X-Cybozu-Forward: 1
X-Cybozu-Product-Id: 00
X-Cybozu-Reminder-Whatsnew: https://{subdomain}.cybozu.com/g/reminder/whatsnew_notifier.csp?
X-Cybozu-Reminder-Schedule: https://{subdomain}.cybozu.com/g/reminder/schedule_notifier.csp?
X-Cybozu-Reminder-Mail: https://{subdomain}.cybozu.com/g/reminder/mail_notifier.csp?
X-Cybozu-User: 10
Content-Type: application/soap+xml; charset="utf-8"
Set-Cookie: CBSESSID=841s3liopdjo47vib0ddc08u3al7r6vl; path=/; secure; HttpOnly
Set-Cookie: GRN_Account=deleted; expires=Thu, 01-Jan-1970 00:00:01 GMT; path=/; secure; httponly
Vary: Accept-Encoding,User-Agent
X-UA-Compatible: IE=Edge,chrome=IE7
Transfer-Encoding: chunked

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:base="http://wsdl.cybozu.co.jp/base/2008">
  <soap:Header>
    <vendor>Cybozu</vendor>
    <product>Garoon</product>
    <product_type>2</product_type>
    <version>3.8.0</version>
    <apiversion>1.3.0</apiversion>
  </soap:Header>
  <soap:Body>
    <base:BaseGetApplicationStatusResponse>
      <returns>
        <application code="portal" status="active"/>
        <application code="space" status="active"/>
        <application code="link" status="active"/>
        <application code="schedule" status="active"/>
        <application code="message" status="active"/>
        <application code="bulletin" status="active"/>
        <application code="cabinet" status="active"/>
        <application code="memo" status="active"/>
        <application code="phonemessage" status="active"/>
        <application code="timecard" status="active"/>
        <application code="todo" status="active"/>
        <application code="address" status="active"/>
        <application code="mail" status="active"/>
        <application code="workflow" status="active"/>
        <application code="report" status="active"/>
        <application code="cbwebsrv" status="active"/>
        <application code="rss" status="active"/>
        <application code="cbdnet" status="active"/>
        <application code="presence" status="active"/>
        <application code="star" status="active"/>
        <application code="notification" status="active"/>
        <application code="kunai" status="active"/>
        <application code="favour" status="deactive"/>
      </returns>
    </base:BaseGetApplicationStatusResponse>
  </soap:Body>
</soap:Envelope>

認証

Garoon SOAP APIを使用するには、ガルーンに登録したユーザーで認証する必要があります。認証には、Cookieを使用した方式と、WebServicesSecurity（WS-Security）を使用した方式があります。
APIを高頻度で実行する場合は「Cookieを用いた認証方式」をご利用下さい。

Cookieを用いた認証方式

セッションIDをCookieとしてリクエストに含めることで、認証を行います。 セッションIDの取得には以下の2つの方法があります。

1. Util APIのUtilLoginでログインし、セッションIDを取得する
2. ブラウザでガルーンにログインし、セッションIDを取得する 

下記に、UtilLoginでセッションIDを取得する際のリクエスト例とレスポンス例を示します。 ※UtilLoginの詳細については、「連携API」を参照してください。

例：リクエスト

POST /g/util_api/util/api.csp HTTP/1.1
Host: {subdomain}.cybozu.com
Content-Type: text/xml; charset=UTF-8

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
    <Action>UtilLogin</Action>
    <Security></Security>
    <Timestamp>
      <Created>2010-08-12T14:45:00Z</Created>
      <Expires>2037-08-12T14:45:00Z</Expires>
    </Timestamp>
    <Locale>jp</Locale>
  </soap:Header>
  <soap:Body>
    <UtilLogin>
      <parameters>
        <login_name>xxxxxxxxxx</login_name>
        <password>xxxxxxx</password>
      </parameters>
    </UtilLogin>
  </soap:Body>
</soap:Envelope>

例：レスポンス

HTTP/1.1 200 OK
Date: Tue, 03 Sep 2013 08:10:54 GMT
Server: Apache
Strict-Transport-Security: max-age=315360000
X-Content-Type-Options: nosniff
X-Cybozu-Forward: 1
X-Cybozu-Product-Id: 00
X-Cybozu-Reminder-Whatsnew: https://{subdomain}.cybozu.com/g/reminder/whatsnew_notifier.csp?
X-Cybozu-Reminder-Schedule: https://{subdomain}.cybozu.com/g/reminder/schedule_notifier.csp?
X-Cybozu-Reminder-Mail: https://{subdomain}.cybozu.com/g/reminder/mail_notifier.csp?
X-Cybozu-User: 10
Content-Type: application/soap+xml; charset="utf-8"
Set-Cookie: CBSESSID=bmun236bhoifeu2cov6badrh0cs0s1af; path=/; secure; HttpOnly
Set-Cookie: GRN_Account=deleted; expires=Thu, 01-Jan-1970 00:00:01 GMT; path=/; secure; httponly
Vary: Accept-Encoding,User-Agent
X-UA-Compatible: IE=Edge,chrome=IE7
Transfer-Encoding: chunked

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:admin="http://wsdl.cybozu.co.jp/admin/2008">
  <soap:Header>
    <vendor>Cybozu</vendor>
    <product>Garoon</product>
    <version>3.8.0</version>
    <apiversion>1.3.0</apiversion>
  </soap:Header>
  <soap:Body>
    <admin:LoginResponse>
      <returns>
        <login_name>xxxxxxxxxx</login_name>
        <status>Login</status>
        <cookie>CBSESSID=bmun236bhoifeu2cov6badrh0cs0s1af; path=/</cookie>
      </returns>
    </admin:LoginResponse>
  </soap:Body>
</soap:Envelope>

レスポンス内の「CBSESSID」がCookie名、及び「bmun236bhoifeu2cov6badrh0cs0s1af」がCookie値です。Garoon SOAP APIのリクエストにCookieを含めることで、WS-Securityによる認証は不要になり、リクエストからログイン名とパスワードを省けます。

Garoon SOAP APIリクエストにCookieを含める場合、Cookie名は以下です。

また、Garoon SOAP APIのリクエストにCookieを含める場合は、以下のようにリクエストヘッダに含めます。

例:クラウド版 Garoonで、「UtilGetREquestToken」を実行した場合の例

POST /g/util_api/util/api.csp HTTP/1.1
Host: {subdomain}.cybozu.com 
Content-Type: text/xml; charset=UTF-8 
Cookie: JSESSIONID=smbrfjktphvuc9a1c0er2dpk3e76psj2; 
 
<?xml version="1.0" encoding="UTF-8"?> 
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> 
    <soap:Header> 
        <Action>UtilGetRequestToken</Action> 
        <Security> 
            <UsernameToken> 
                <Username></Username>  
                <Password></Password> 
            </UsernameToken> 
        </Security> 
        <Timestamp> 
            <Created>2010-08-12T14:45:00Z</Created> 
            <Expires>2037-08-12T14:45:00Z</Expires> 
        </Timestamp> 
        <Locale>jp</Locale> 
    </soap:Header> 
    <soap:Body> 
        <UtilGetRequestToken> 
            <parameters></parameters> 
        </UtilGetRequestToken> 
    </soap:Body> 
</soap:Envelope> 

WS-Securityを用いた認証方式

ログイン名とパスワードを SOAP ヘッダに含めることによって認証を行います。 この認証方式では、リクエストごとに認証を行う必要があります。下記例の「Security」要素が該当の箇所です。

例

<soap:Header> 
  <Action>BaseGetUserVersions</Action>
  <Security> 
    <UsernameToken> 
      <Username>sato</Username> 
      <Password>PASSWORD</Password> 
    </UsernameToken> 
  </Security> 
  <Timestamp> 
    <Created>2009-06-08T16:08:00Z</Created> 
    <Expires>2016-06-09T16:08:00Z</Expires> 
  </Timestamp> 
</soap:Header>

SAML認証設定時の利用について

SAML認証設定時に、cybozu.comのログイン名とパスワードによる認証でGaroon SOAP APIを利用できます。

Basic認証

// ログイン名が「Administrator」、パスワードが「cybozu」の場合
X-Cybozu-Authorization:QWRtaW5pc3RyYXRvcjpjeWJvenU=

<soap:Header> 
  <Action>BaseGetUserVersions</Action>
  <Security> 
    <UsernameToken> 
      <Username>sato</Username> 
      <Password>PASSWORD</Password> 
    </UsernameToken> 
  </Security> 
  <Timestamp> 
    <Created>2009-06-08T16:08:00Z</Created> 
    <Expires>2016-06-09T16:08:00Z</Expires> 
  </Timestamp> 
  <Locale>ja</Locale> 
</soap:Header>

<parameters> 
  <user_item id="1" version="1245375234" />
  <user_item id="2" version="1245323905" />
  <user_item id="3" version="1245315235" />
</parameters>

<returns> 
  <user_item id="1" version="1245376338" operation="modify" />
  <user_item id="2" version="1245327097" operation="modify" />
  <user_item id="3" version="1245327110" operation="modify" />
  <user_item id="4" version="1245715417" operation="add" />
  <user_item id="5" version="1245715429" operation="add" />
</returns>

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
 xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
 xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <soap:Header>
    <vendor>Cybozu</vendor>
    <product>Garoon</product>
    <product_type>2</product_type>
    <version>3.8.0</version>
    <apiversion>1.3.0</apiversion>
  </soap:Header>
  <soap:Body>
    <soap:Fault>
      <soap:Code>
        <soap:Value>soap:Receiver</soap:Value>
      </soap:Code>
      <soap:Reason>
        <soap:Text>リクエストパラメータが不足しています。</soap:Text>
      </soap:Reason>
      <soap:Detail>
        <code>GRN_CBPAPI_63004</code>
        <diagnosis>リクエストパラメータが不足しています。</diagnosis>
        <cause>&quot;user_id&quot;パラメータが必要です。</cause>
        <counter_measure>サイボウズオフィシャルパートナー、または販売元にお問い合わせください。</counter_measure>
              </soap:Detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

[API roles] 
sysapi_roles = "roleA" 
papi_roles = "roleA, roleB"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:base="http://wsdl.cybozu.co.jp/base/2008">
  <soap:Header>
    <vendor>Cybozu</vendor>
    <product>Garoon</product>
    <product_type>2</product_type>
    <version>3.8.0</version>
    <apiversion>1.3.0</apiversion>
  </soap:Header>
  <soap:Body>
    <base:BaseGetUserVersionsResponse>
      <returns>
        <user_item id="1" version="1363009269" operation="add"/>
        <user_item id="2" version="1377680211" operation="add"/>
        <user_item id="3" version="1359593131" operation="add"/>
      </returns>
    </base:BaseGetUserVersionsResponse>
  </soap:Body>
</soap:Envelope>

<?xml version="1.0" encoding="utf-8" ?>  
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> 
  <soap:Header> 
    <Action>BaseGetUserVersions</Action>  
    <Security> 
      <UsernameToken> 
        <Username>Administrator</Username>  
        <Password>123456</Password>  
      </UsernameToken> 
    </Security> 
    <Timestamp> 
      <Created xmlns="">2009-06-08T16:00:00Z</Created>  
      <Expires xmlns="">2016-06-09T16:00:00Z</Expires>  
    </Timestamp> 
  </soap:Header> 
  <soap:Body> 
    <BaseGetUserVersions> 
      <parameters> 
        <user_item id="1" version="11" />  
      </parameters> 
    </BaseGetUserVersions> 
  </soap:Body> 
</soap:Envelope>

<?xml version="1.0" encoding="utf-8" ?>  
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"  
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
 xmlns:base="http://wsdl.cybozu.co.jp/base/2008"> 
  <soap:Body> 
    <base:BaseGetUserVersionsResponse> 
      <returns> 
        <user_item id="1" version="1245376338" operation="modify" />  
        <user_item id="2" version="1245327097" operation="add" />  
      </returns> 
    </base:BaseGetUserVersionsResponse> 
  </soap:Body> 
</soap:Envelope>