開発部の脇野です。

Garoonを外部のプログラムから利用するために用意されているSOAP（Simple Object Access Protocol）形式のインターフェイスを利用してデータの送受信処理を実現してみたいと思います。

DataSpiderにはSOAP形式の通信を行うために「Webサービスアダプタ」が用意されているのですが、現時点（2017年7月現在）の仕様はSOAPバージョン1.1に対応したもので、GaroonのSOAPバージョン1.2では利用することができません。

そこで登場するのが『RESTアダプタ』です。かなり万能なRESTアダプタは私のお気に入りアダプタのひとつです。

事前準備から

では早速。

Garoon SOAP APIの定義はWSDLに記載されているので、WSDLを確認していきます。WSDLは以下に記載されたURLにアクセスすることで確認することができます。

▼Garoon SOAP APIの概要（https://developer.cybozu.io/hc/ja/articles/202228464）

中を見ていくといくつかのサービスが存在しているのを確認できます。

この<service name="XXXXXXX">が以下の「スケジュール」「掲示板」「メール」といった各機能カテゴリに該当するので、どの機能カテゴリのサービスを利用したいのかによってアクセスするパスが変わるということになります。

アクセスするパスは「soap12:address location=」以降に記載されています。WSDLは後ほど利用するので一旦テキストにでも保存しておきます。

次にリクエストしてみたいAPIの情報を確認しておきます。今回は「連携API」から「API実行ユーザーのユーザーIDを取得する」というAPIを実行することにしました。サイドバーのメニューリンクをクリックして詳細を確認します。

API名、リクエストパラメータ、レスポンスパラメータを確認することができました。

• API名：UtilGetLoginUserId
• リクエストパラメータ：なし
• レスポンスパラメータ：user_id/text()

最後にリクエストする際のデータの雛形を用意します。これもGaroon SOAP APIの概要に表示されていますので、「<?xml」以降「/soap:Envelope」までをコピーして任意の名称で保存しておきます。ここでは「garoon_soap.xml」としておきました。

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

 ※今回はログイン名とパスワードをSOAPヘッダに含めることによって認証を行うWS-Securityを用いた認証方式を採用しています。

各種設定

グローバルリソースの設定

ここは「soap12:address location=」に記載されているホスト名（or アドレス）を指定します。

アダプタの設定

RESTアダプタの「POST実行」を利用します。

必須設定

接続先は先程設定したグローバルリソースを選択し、パスには「soap12:address location=」のホスト名以降を入力します。今回はUtilServiceで試しているので以下の値が設定しました。

▼WSDL

リクエスト設定

SOAPエンベロープはXMLベースなのでデータ形式にXMLを選択します。

レスポンス設定

ファイルに出力してみるのでデータ出力先をファイルにします。

ヘッダ設定

Content-Typeに「text/xml; charset=UTF-8」を設定します。

マッパーの設定

ドキュメントMapperを使ってSOAPリクエストに必要なパラメータの設定を行います。

配置したばかりはスキーマが設定されていないので、事前に用意したxmlファイルを読み込んで設定します。

設定されたらそれぞれの値を設定していきます。

まずはSOAPヘッダから。

「Action」には事前に取得したAPI名を。

「Username」「Password」にはGaroonにログインするユーザの情報を。

「Created」「Expires」にはログインの有効期限を「2009-06-08T16:00:00Z」という形式で。

次にSOAPボディの設定です。

これは選択するAPIによって設定値が異なるので、その条件に応じてスキーマを追加することになります。今回選択したAPI「UtilGetLoginUserId」にはリクエストパラメータが不要なのでここでは何も設定していません。

処理の実行

シンプルですが処理は完成しましたので実行してみます。

以下の通り ドキュメントに記載されている通りの結果を取得することができました。

<returns>
<user_id>67</user_id>
</returns>

最後に

今回はリクエストパラメータが不要なAPIでしたが、必要な場合は以下のようにスキーマを変更します。

例：ログイン処理を行う

API名

• UtilLogin

リクエストパラメータ

• login_name/text()
• password/text()

設定イメージ