【ガルーン活用】VBSやVBAからSOAP APIを実行しメッセージを送信してみよう

ガルーン活用
2022.01.23
スポンサーリンク

今回の記事では、サイボウズ社のグループウェア「ガルーン」のSOAP APIを利用して、VBScriptやVBAから「メッセージ」を送信する処理のサンプルコードを紹介していきます。

尚、以前に当ブログでは、同様にVBScriptやVBAでSOAP APIを実行し、ログイン処理やユーザーの登録処理に関するサンプルプログラムも紹介しています。

よろしければこちらも参考にしてください。

【ガルーン活用】VBSやVBAからSOAP APIを実行してユーザー登録を自動化【前編】
今回の記事では、ガルーンの「SOAP API」を利用して、ガルーンへのログインからユーザー登録の一連の流れをVBScri...
www.depthbomb.net
2021.12.01

 

メッセージ送信APIの概要

ガルーンの「メッセージ」はガルーンが提供しているSOAP APIを利用することで、メッセージの送信(登録)、更新、削除や情報の取得が可能です。
このAPIを活用することで、外部のプログラムやアプリケーションにAPI実行処理を組み込み、ガルーンのメッセージへ自動登録させたり、大量のメッセージを一括登録するようなことも可能になります。

今回のサンプルプログラムで利用するのは、ガルーンSOAP APIのAPI名「MessageCreateThreads」です。

詳しい仕様はガルーンAPIの公式デベロッパーサイトをご確認ください。

メッセージを送信、更新または削除する
メッセージを送信、更新または削除します。
cybozu.dev

尚、当ブログで以前に紹介したユーザー登録APIを利用するサンプルプログラムでは、処理が複雑になってしまっていたので、今回の記事では可能な限りシンプルなコードを掲載しようと思います。

中の人
中の人

VBAやVBSの言語仕様上、XMLを簡潔に作成する仕組みが用意されていないため、どうしてもコードが汚くなってしまうのですが・・・。

 

サンプルプログラムの処理概要

今回紹介するサンプルプログラムでは、以下の工程の処理を実装します。

  1. メッセージ用xmlリクエストを作成してAPIにPOST
  2. API実行結果のレスポンスを受け取りxmlを解析

この流れで実装します。
 

メッセージ送信APIを実行するサンプルプログラム

当項では、実際にメッセージ送信用APIをVBScriptから実行する際のサンプルプログラムを紹介します。
尚、VBAはVBScriptと言語仕様が共通しており、当サンプルプログラムをVBAにコピペして実装してもらえれば動きます。

次項からは、当処理で使用するFunctionプロシージャを分割して紹介していきます。
 

リクエスト用xml作成共通処理

当項では、各API実行時に共通で使用するリクエスト用xmlのヘッダー部分の作成処理を紹介します。
後、リクエスト時にxmlのパラメーターとして設定するセッションの有効期間の文字列を生成する処理も共通化しています。
 

リクエストxmlヘッダー作成共通処理

'リクエストで使用するXMLヘッダーの文字列を生成して返します。
Function Get_CreateXML_Header(API_Name)

  Dim sEnv
    sEnv = "<?xml version=""1.0"" encoding=""UTF-8""?>"
    sEnv = sEnv & "<soap:Envelope xmlns:soap=""http://www.w3.org/2003/05/soap-envelope"">"
    sEnv = sEnv & "  <soap:Header>"
    sEnv = sEnv & "    <Action>" & API_Name & "</Action>"
    sEnv = sEnv & "    <Security>"
    sEnv = sEnv & "     <UsernameToken>"
    sEnv = sEnv & "       <Username>" & LOGIN_USERNAME & "</Username>"
    sEnv = sEnv & "       <Password>" & LOGIN_PASSWORD & "</Password>"
    sEnv = sEnv & "     </UsernameToken>"
    sEnv = sEnv & "    </Security>"
    sEnv = sEnv & "    <Timestamp>"
    sEnv = sEnv & "      <Created>" & Get_forTimestampDate(0) & "</Created>"
    sEnv = sEnv & "      <Expires>" & Get_forTimestampDate(15) & "</Expires>"
    sEnv = sEnv & "    </Timestamp>"
    sEnv = sEnv & "    <Locale>jp</Locale>"
    sEnv = sEnv & "  </soap:Header>"

    Get_CreateXML_Header = sEnv

End Function

ガルーンで使用されるSOAP APIを実行する際にAPIに渡すxmlのヘッダー部分は記述は同じであるため、Functionプロシージャ化してこの処理を各API実行時に呼び出します。
処理のなかで使用している変数はグローバルな定数です。
 

リクエストxmlのパラメーターに指定するセッション有効期間を生成する処理

'xmlに設定するセッション有効期間の文字列を生成して返します。
'引数に与えた数値で生成する時間を調整します。値が0の場合は現在の日時
Function Get_forTimestampDate(add_Minutes)
  Dim wkNow
    'yyyy-mm-ddThh:mm:ssZの書式に変換します。
    wkNow = Year(Dateadd("n",add_Minutes,Now()))
    wkNow = wkNow & "-" & Right("0" & Month(Dateadd("n",add_Minutes,Now())) , 2)
    wkNow = wkNow & "-" & Right("0" & Day(Dateadd("n",add_Minutes,Now())) , 2)
    wkNow = wkNow & "T" & Right("0" & Hour(Dateadd("n",add_Minutes,Now())) , 2)
    wkNow = wkNow & ":" & Right("0" & Minute(Dateadd("n",add_Minutes,Now())) , 2)
    wkNow = wkNow & ":" & Right("0" & Second(Dateadd("n",add_Minutes,Now())) , 2)
    wkNow = wkNow & "Z"

    Get_forTimestampDate = wkNow
End Function

 
 

ガルーンのメッセージ送信APIを呼び出して実行する処理

今回の記事の主題であるメッセージ送信用APIを実行するサンプルコードを紹介します。
尚、実際にメッセージ送信APIの「MessageCreateThreads」では様々なパラメーターを渡してメッセージを作成できます。
ただ今回はガルーンのSOAP APIのデベロッパーサイトで紹介されているリクエスト例に準じたパラメーターを生成します。

'ガルーンのAPI(MessageCreateThreads)を実行し、メッセージを登録します。
'※ガルーン内に存在しなければ、-1を返し、エラーが出た場合は0を返します。
Function ExeAPI_MessageCreateThreads()

  Dim objHTTP
  Dim Full_URL
  Dim sEnv
  Dim ReqXML
  Dim objXML
  Dim elm
  Dim rtnVal
  Dim i
  Dim attr

    sEnv = sEnv & "<soap:Body> "
    sEnv = sEnv & "    <MessageCreateThreads> "
    sEnv = sEnv & "        <parameters> "
    sEnv = sEnv & "            <create_thread> "
    sEnv = sEnv & "              <thread id=""dummy"" version=""dummy"" subject=""APIテストメッセージ"" confirm=""false""> "
    sEnv = sEnv & "                <addressee user_id=""1"" name=""dummy"" deleted=""false""></addressee> "
    sEnv = sEnv & "                <content body=""テストメッセージ""></content> "
    sEnv = sEnv & "                <folder id=""dummy""></folder> "
    sEnv = sEnv & "              </thread> "
    sEnv = sEnv & "            </create_thread>"
    sEnv = sEnv & "        </parameters> "
    sEnv = sEnv & "    </MessageCreateThreads> "
    sEnv = sEnv & "</soap:Body> "
    sEnv = sEnv & "</soap:Envelope> "

    Full_URL = BASE_URL & ACTION_API_DIR1
    Set objHTTP = CreateObject("MSXML2.ServerXMLHTTP")
    objHTTP.Open "POST", Full_URL, False

    ReqXML = Get_CreateXML_Header("MessageCreateThreads") & vbcrlf & sEnv

    'パラメーターを渡します。
    objHTTP.send ReqXML

    If objHTTP.Status <> 200 Then
      'httpレスポンスコードが異常な場合は戻り値に0を返します。
      ExeAPI_MessageCreateThreads = 0
      Set objHTTP = Nothing
      Exit Function
    End If

    'XML解析用のオブジェクトを生成します。
    Set objXML = CreateObject("MSXML2.DOMdocument")
    'レスポンスをxmlで読み込みます。
    objXML.LoadXML(objHTTP.ResponseText)

    rtnVal = 0
    'レスポンスxmlの要素thread内の属性idの値を取得して戻り値にセットします。
    For Each elm In objXML.getElementsByTagName("thread")
      For Each attr In elm.attributes
        If attr.name = "id" Then
          rtnVal = attr.text
        End If
      Next
    Next

    ExeAPI_MessageCreateThreads = rtnVal
    Set objHTTP = Nothing
    Set objXML = Nothing

End Function

上記コードの20行目では、user_id に1を指定しています。
user_idが1はガルーンで最初から存在しているユーザーの「Administrator」です。
この場合、Administratorに対してメッセージが送信されます。

この「user_id」はガルーンで内部的に使用しているユーザーごとのID番号で、ガルーンの管理画面などでは一切表示されません。
そのため、このIDを取得するには、ガルーンの「ログイン名」からuser_idを取得するAPIの「AdminGetUserIdByLoginName」を利用する必要があります。
詳しくは以下のデベロッパーサイトをご確認ください。

ユーザー情報を取得する
ユーザー情報を取得します。
cybozu.dev

今回の記事では「AdminGetUserIdByLoginName」を呼び出してガルーンの「ログイン名」からuser_idを取得する処理は省略していますが、実際にシステム間の連携処理を作り込む場合はこのAPIも利用する必要があります。
今回紹介する一連の処理で言えば、まずメッセージ送信対象のユーザーのuser_idを取得するために「AdminGetUserIdByLoginName」を実行して、その後、前処理で取得したuser_idを元に「MessageCreateThreads」を実行する流れになります。
 
 

サンプルプログラム全体

前項で紹介した各Functionプロシージャを使用して、ガルーンのメッセージを登録する一連の処理全体のサンプルプログラムを紹介します。

尚、処理は長いのですが、処理の冒頭で宣言している定数の「BASE_URL」と「LOGIN_USERNAME」、「LOGIN_PASSWORD」をご使用している環境に合わせて書き換えてもらえれば、VBScriptの場合はこのままコピペでも動きます。
VBAの場合でも各Functionプロシージャはこのままコピペで動きますが、冒頭の処理は環境に合わせて修正してください。

定数の「LOGIN_USERNAME」は、ガルーンで認証するログインユーザー名を指定しますが、ここで指定したユーザーがメッセージの送信者になります。
また、このユーザーはAPIの実行権限が必要です。

Option Explicit

CONST BASE_URL = "http://example.com/scripts/cbgrn/grn.exe/"
CONST LOGIN_API_DIR = "util_api/util/api?"
CONST LOGIN_API_NAME = "UtilLogin"
'ログインで使用する「ログインユーザー名」を指定
'※このユーザーでメッセージを送信する。
CONST LOGIN_USERNAME = "99999"
CONST LOGIN_PASSWORD = "xxxxxx"
CONST ACTION_API_DIR = "cbpapi/message/api?"


Call GaroonAPI_Executor

  Sub GaroonAPI_Executor()

    'メッセージを書き込みます。
    If ExeAPI_MessageCreateThreads = 0 Then
      MsgBox = "メッセージの登録に失敗しました。"
    End If

  End Sub

  'ガルーンのAPI(MessageCreateThreads)を実行し、メッセージを登録します。
  '引数1：無し
  '戻り値：メッセージのid(数値)※失敗した場合は0を返します。
  Function ExeAPI_MessageCreateThreads()

    Dim objHTTP
    Dim Full_URL
    Dim sEnv
    Dim ReqXML
    Dim objXML
    Dim elm
    Dim rtnVal
    Dim i
    Dim attr

      sEnv = sEnv & "<soap:Body> "
      sEnv = sEnv & "    <MessageCreateThreads> "
      sEnv = sEnv & "        <parameters> "
      sEnv = sEnv & "            <create_thread> "
      sEnv = sEnv & "              <thread id=""dummy"" version=""dummy"" subject=""APIテストメッセージ"" confirm=""false""> "
      sEnv = sEnv & "                <addressee user_id=""1"" name=""dummy"" deleted=""false""></addressee> "
      sEnv = sEnv & "                <content body=""テストメッセージ""></content> "
      sEnv = sEnv & "                <folder id=""dummy""></folder> "
      sEnv = sEnv & "              </thread> "
      sEnv = sEnv & "            </create_thread>"
      sEnv = sEnv & "        </parameters> "
      sEnv = sEnv & "    </MessageCreateThreads> "
      sEnv = sEnv & "</soap:Body> "
      sEnv = sEnv & "</soap:Envelope> "

      Full_URL = BASE_URL & ACTION_API_DIR1
      Set objHTTP = CreateObject("MSXML2.ServerXMLHTTP")
      objHTTP.Open "POST", Full_URL, False

      ReqXML = Get_CreateXML_Header("MessageCreateThreads") & vbcrlf & sEnv

      'パラメーターを渡します。
      objHTTP.send ReqXML

      If objHTTP.Status <> 200 Then
        'httpレスポンスコードが異常な場合は戻り値に0を返します。
        ExeAPI_MessageCreateThreads = 0
        Set objHTTP = Nothing
        Exit Function
      End If

      'XML解析用のオブジェクトを生成します。
      Set objXML = CreateObject("MSXML2.DOMdocument")
      'レスポンスをxmlで読み込みます。
      objXML.LoadXML(objHTTP.ResponseText)

      rtnVal = 0
      'レスポンスxmlの要素thread内の属性idの値を取得して戻り値にセットします。
      For Each elm In objXML.getElementsByTagName("thread")
        For Each attr In elm.attributes
          If attr.name = "id" Then
            rtnVal = attr.text
          End If
        Next
      Next

      ExeAPI_MessageCreateThreads = rtnVal
      Set objHTTP = Nothing
      Set objXML = Nothing

  End Function

  'xmlに設定するセッション有効期間の文字列を生成して返します。
  '引数に与えた数値で生成する時間を調整します。値が0の場合は現在の日時
  Function Get_forTimestampDate(add_Minutes)
    Dim wkNow
      'yyyy-mm-ddThh:mm:ssZの書式に変換します。
      wkNow = Year(Dateadd("n",add_Minutes,Now()))
      wkNow = wkNow & "-" & Right("0" & Month(Dateadd("n",add_Minutes,Now())) , 2)
      wkNow = wkNow & "-" & Right("0" & Day(Dateadd("n",add_Minutes,Now())) , 2)
      wkNow = wkNow & "T" & Right("0" & Hour(Dateadd("n",add_Minutes,Now())) , 2)
      wkNow = wkNow & ":" & Right("0" & Minute(Dateadd("n",add_Minutes,Now())) , 2)
      wkNow = wkNow & ":" & Right("0" & Second(Dateadd("n",add_Minutes,Now())) , 2)
      wkNow = wkNow & "Z"

      Get_forTimestampDate = wkNow
  End Function

  'リクエストで使用するXMLヘッダーの文字列を生成して返します。
  '引数1：実行対象のAPI名
  '戻り値：リクエスト用xmlヘッダー文字列
  Function Get_CreateXML_Header(API_Name)

    Dim sEnv
      sEnv = "<?xml version=""1.0"" encoding=""UTF-8""?>"
      sEnv = sEnv & "<soap:Envelope xmlns:soap=""http://www.w3.org/2003/05/soap-envelope"">"
      sEnv = sEnv & "  <soap:Header>"
      sEnv = sEnv & "    <Action>" & API_Name & "</Action>"
      sEnv = sEnv & "    <Security>"
      sEnv = sEnv & "     <UsernameToken>"
      sEnv = sEnv & "       <Username>" & LOGIN_USERNAME & "</Username>"
      sEnv = sEnv & "       <Password>" & LOGIN_PASSWORD & "</Password>"
      sEnv = sEnv & "     </UsernameToken>"
      sEnv = sEnv & "    </Security>"
      sEnv = sEnv & "    <Timestamp>"
      sEnv = sEnv & "      <Created>" & Get_forTimestampDate(0) & "</Created>"
      sEnv = sEnv & "      <Expires>" & Get_forTimestampDate(15) & "</Expires>"
      sEnv = sEnv & "    </Timestamp>"
      sEnv = sEnv & "    <Locale>jp</Locale>"
      sEnv = sEnv & "  </soap:Header>"

      Get_CreateXML_Header = sEnv

  End Function

 

最後に

今回の記事では、ガルーンのSOAP APIを利用して、「メッセージ」をVBScriptから送信する一連のサンプルプログラムを紹介しました。
メッセージ送信では、送信元となるユーザーがAPIを利用できる権限が必要になるため、メッセージ送信専用ユーザーを作成して、そのユーザーでAPIを実行するような使い方がセキュリティ的には望ましいと思います。

ガルーンでは色々なAPIが用意されており、様々な操作を自動化させることが可能です。
是非今回の記事を参考に色々試してみてください。

今回も長々と読んでいただきましてありがとうございました。
それでは皆さまごきげんよう！

タイトルとURLをコピーしました