【API入門】LanScopeのAPIをVBScriptやVBAで実行するサンプルスクリプト

今回の記事では、IT資産管理ツールで有名なMOTEX社のLanScopeが提供しているAPIをVBScriptやVBAで実行するサンプルプログラムを紹介します。

APIの詳しい説明はLanScopeの公式マニュアルで確認できますが、プログラミングに不慣れな人であれば、そのAPIを実行する具体的なサンプルプログラムが欲しいものです。
今回の記事では、その習得の手助けになれば幸いです。

LanScope APIの大まかな仕様

当項では、LanScopeが提供しているAPIの大まかな仕様を紹介していきます。
 

使用するHTTPメソッドは三種類

LanScopeで提供しているAPIでは、三種類のHTTPメソッドを使用します。

一般的な「HTTPメソッド」の説明としては以下のリンク先をご参照ください。

HTTP リクエストメソッド - HTTP | MDN

HTTP では、リソースに対して実行したいアクションを示す一連のリクエストメソッドを定義しています。リクエストメソッドは HTTP 述語と呼ばれることがありますが、名詞も存在します。それぞれのメソッドがさまざまな意味を持っていますが、いくつかの共通的な機能が、メソッドのグループで共有されています。例えば、リクエストメソ...

developer.mozilla.org

LanScopeでは、「GET」「PUT」「POST」の三種類のメソッドを使用します。
LanScopeにおける各HTTPメソッドの使い分け方法は以下になります。

レスポンスは「JSON」形式

一般的なWeb APIでは、API実行後の処理結果をXML形式かJSON形式のどちらかのデータフォーマットを使用して返します。
LanScopeのAPIで採用している処理結果(レスポンス)のデータフォーマットは「JSON」です。

「JSON」は「JavaScript Object Notation」の略称であり、データ交換用のフォーマットの一つです。

一般的な「JSON」の説明としては以下のリンク先にあるWikipediaの記事をご参照ください。

JavaScript Object Notation - Wikipedia

ja.wikipedia.org

認証は「トークン」を使用

Web APIでは、一般的に、そのAPIを実行できるユーザーやアクセス元を何らかの方法で制限します。
特にインターネット上に公開しているサービスで提供しているようなAPIでは、制限を掛けておかないと、第三者から不正にAPIを実行できてしまいます。

Web APIでは幾つかの認証方式がありますが、LanScopeでは「トークン」を使用します。

トークンの説明としては以下のリンク先にあるWikipediaの記事をご参照ください。

OAuth - Wikipedia

ja.wikipedia.org

LanScopeで使用するトークンは、LanScopeのサーバー内に作成したユーザーごとにコンソールで生成する認証用の文字列です。

LanScopeでは、APIのリクエストをクライアントが送信する際に、httpリクエストのヘッダー部分にこのトークンを埋め込みます。
LanScopeのサーバー側では、このトークンを見て、許可されたユーザーで生成したトークンか否かを判定します。

トークンとLanScope内のユーザーとは紐付くため、そのトークンを作成したユーザーに割り当てられている権限で許可された機能に関連するAPIしか実行できません。
 

当APIの解説とVBSとVBAのサンプルコード

当項では、今回の記事で紹介するサンプルコードの簡単な解説と、VBScript及びVBAのコードの実装サンプルを紹介していきます。
 

実装内容の解説

処理の流れは以下です。

VBSで記述したコードとVBAのコードは、両言語の言語仕様や構文が似ているため、殆ど同じです。

VBA側のコードでは、Subプロシージャとして処理を作っているのと、処理の途中でプログラムの実行を停止する記述をSubプロシージャ用に書き換えた程度です。

当サンプルでは、LanScopeが提供しているAPI「ハードウェア資産情報一覧の取得」を呼び出します。
これは、LanScopeに登録された端末の「ハードウェア資産情報」の一覧を取得します。

このAPIが配置されているAPI用URLは、末尾が「/assets/hardwares」です。

APIの種類や詳しいAPIの仕様については、MOTEX社が提供しているマニュアルをご確認ください。

また、以下の紹介しているサンプルコード内に、対象のAPIに渡すパラメーターの値の種類をコメントとして記載しております。
 

「GET」メソッドでのパラメータの渡し方

HTTPメソッドにおける「GET」では、URLのなかに、APIのパラメータを埋め込みます。
その埋め込み方にはルールがあります。

URLの末尾に「?」を付与します。
この「?」は、以降がウェブページに渡すパラメータだよと言う意味になります。

また、パラメータは「パラメータ名」と「値」が常に対になり、この「パラメータ名」と「値」は「=」で繋げます。
パラメータが複数ある場合は、個々のパラメータを「&」で繋げます。

Web APIでGETメソッドを扱うときには、必ずこのルールでパラメータを渡すことになるので、必ず覚えておいてください。
 

VBSのサンプルコード

VBScript用のサンプルコードです。
尚、定数「JSON_FILE_PATH」で定義しているjsonファイルの出力先ですが、パソコンのセキュリティ設定によってはCドライブ直下だとファイルの書き出しが出来ない可能性もあるため、必要によってCドライブ直下から別の場所に変更してください。

定数「BASE_URI」はLanScopeのサーバーのURLを指定します。
TargetServer と記載してある部分は、利用しているLanScopeサーバーのホスト名に書き換えてください。

定数「APP_URI」は、個々のAPIが配置されているURLの末尾の部分を指定します。
LanScopeの別のAPIを試したい場合は、この定数の値をマニュアルを確認しながら書き換えます。

また、APIに渡すパラメーターの「パソコン周辺機器のタイプ」については、先頭パラメーターの「ハードウェア資産情報のタイプ」が3を選択した場合のみ指定できます。
よって、当サンプルコードではコメントアウトしております。
必要によって書き換えてください。
 

  Option Explicit

  CONST JSON_FILE_PATH = "c:\result.json"
  CONST BASE_URI = "http://TargetServer/catapisrv/api/v1"
  CONST APP_URI = "assets/hardwares"
  CONST TOKEN = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

  Dim Target_URI
  Dim objHTTP
  Dim retCd
  Dim Para(2,2)
  Dim FullPara
      
      'パラメーターを定義します。
      'ハードウェア資産情報のタイプ
      Para(0,0) = "hardware_asset_type"
      '1:スタンドアロンMR以外のMR 2:スタンドアロンMR 3:パソコン周辺機器
      Para(0,1) = "1"

      'グループID
      Para(1,0) = "group_id"
      '[MRのタイプ]：[グループNo]
      'MRのタイプ　1:スタンドアロンMR以外のMR 2:スタンドアロンMR
      'グループNo　対象のグループNo
      Para(1,1) = "1:1"

      'パソコン周辺機器のタイプ ※hardware_asset_type = 3の場合のみ使用可
      'Para(2,0) = "peripheral_type"
      '1:パソコン 2:プリンター 3:ルータ、HUB 4:入力機器 5:スマートデバイス 6:その他 
      'Para(2,1) = "1"

      'URLに渡すパラメーターを作成します。
      FullPara = Para(0,0) & "=" & Para(0,1) & "&" & Para(1,0) & "=" & Para(1,1)

      'パラメータ付きURLを作成します。
      Target_URI = BASE_URI & "/" & APP_URI & "?" & FullPara

      Set objHTTP = CreateObject("MSXML2.ServerXMLHTTP")

      objHTTP.Open "GET", Target_URI, False
      'httpヘッダを定義します。
      objHTTP.SetRequestHeader "accept", "application/json"
      objHTTP.SetRequestHeader "Accept-Language", "ja-JP"
      objHTTP.SetRequestHeader "Authorization", "Bearer " & TOKEN

      'リクエストを送信します。
      objHTTP.send

      'レスポンスコードを取得します。
      retCd = objHTTP.Status

      'レスポンスコードが異常か否かを判定します。
      If retCd <> 200 Then
          msgbox "error:" & retCd
          WScript.Quit
      End If

      'レスポンスのJSONをファイルに書き出します。
      Call OutputTextFile(objHTTP.ResponseText,JSON_FILE_PATH)

      Set objHTTP = Nothing


  '引数で渡されたテキストデータと出力先ファイルパスを元にファイルを出力します。
  Sub OutputTextFile(WriteData,FullFileName)

      Dim objStrm

          Set objStrm = CreateObject("ADODB.Stream")

          objStrm.Open
          'テキストデータ
          objStrm.Type = 2
          '文字コード
          objStrm.Charset = "UTF-8"
          '行区切り文字(LF)
          objStrm.LineSeparator = 10
          'ストリームオブジェクトに書き込みます。
          objStrm.WriteText WriteData, 1
          'ストリーム内容をファイルに保存します。
          objStrm.SaveToFile FullFileName, 2
          'ストリームを閉じます。
          objStrm.Close

          Set objStrm = Nothing

  End Sub

VBAのサンプルコード

VBA用のサンプルコードです。
こちらもVBScriptのコードと同様にCドライブ直下にJSONファイルを出力するように実装していますが、必要によって変更してください。
また、各オブジェクトの生成では、遅延バインディングで実装しております。
よって参照設定は不要です。

また、変数宣言における型の指定も省略しています。
VBSのコードをコピペしたコードなので型の指定は省略しているのですが、本来は型を適切に指定するほうが望ましいです。

コードの冒頭の定数についてはVBScriptのコードで説明した内容と同じです。
 

  Sub test1()

  Const JSON_FILE_PATH = "c:\result.json"
  Const BASE_URI = "http://TargetServer/catapisrv/api/v1"
  Const APP_URI = "assets/hardwares"
  Const TOKEN = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

  Dim Target_URI
  Dim objHTTP
  Dim retCd
  Dim Para(2, 2)
  Dim FullPara
      
      'パラメーターを定義します。
      'ハードウェア資産情報のタイプ
      Para(0, 0) = "hardware_asset_type"
      '1:スタンドアロンMR以外のMR 2:スタンドアロンMR 3:パソコン周辺機器
      Para(0, 1) = "1"

      'グループID
      Para(1, 0) = "group_id"
      '[MRのタイプ]：[グループNo]
      'MRのタイプ　1:スタンドアロンMR以外のMR 2:スタンドアロンMR
      'グループNo　対象のグループNo
      Para(1, 1) = "1:1"

      'パソコン周辺機器のタイプ ※hardware_asset_type = 3の場合のみ使用可
      'Para(2,0) = "peripheral_type"
      '1:パソコン 2:プリンター 3:ルータ、HUB 4:入力機器 5:スマートデバイス 6:その他
      'Para(2,1) = "1"

      'URLに渡すパラメーターを作成します。
      FullPara = Para(0, 0) & "=" & Para(0, 1) & "&" & Para(1, 0) & "=" & Para(1, 1)

      'パラメータ付きURLを作成します。
      Target_URI = BASE_URI & "/" & APP_URI & "?" & FullPara

      Set objHTTP = CreateObject("MSXML2.ServerXMLHTTP")

      objHTTP.Open "GET", Target_URI, False
      'httpヘッダを定義します。
      objHTTP.SetRequestHeader "accept", "application/json"
      objHTTP.SetRequestHeader "Accept-Language", "ja-JP"
      objHTTP.SetRequestHeader "Authorization", "Bearer " & TOKEN

      'リクエストを送信します。
      objHTTP.send

      'レスポンスコードを取得します。
      retCd = objHTTP.Status

      'レスポンスコードが異常か否かを判定します。
      If retCd <> 200 Then
          MsgBox "error:" & retCd
          Exit Sub
      End If

      'レスポンスのJSONをファイルに書き出します。
      Call OutputTextFile(objHTTP.ResponseText, JSON_FILE_PATH)

      Set objHTTP = Nothing

  End Sub

  '引数で渡されたテキストデータと出力先ファイルパスを元にファイルを出力します。
  Sub OutputTextFile(WriteData, FullFileName)

      Dim objStrm

          Set objStrm = CreateObject("ADODB.Stream")

          objStrm.Open
          'テキストデータ
          objStrm.Type = 2
          '文字コード
          objStrm.Charset = "UTF-8"
          '行区切り文字(LF)
          objStrm.LineSeparator = 10
          'ストリームオブジェクトに書き込みます。
          objStrm.WriteText WriteData, 1
          'ストリーム内容をファイルに保存します。
          objStrm.SaveToFile FullFileName, 2
          'ストリームを閉じます。
          objStrm.Close

          Set objStrm = Nothing

  End Sub

最後に

今回の記事では、MOTEX社のLanScopeが提供しているAPIをVBScriptで呼び出す実装サンプルを紹介しました。
ただ、残念なことに、VBScriptやVBAでは、JSONデータを解析して値を取り出すといった処理(パース：parse)を標準機能として持っていません。
VBScriptやVBAからJSONをパースする場合、色々な方法がありますが、主だったものだと以下かなと思います。

どれも一長一短があります。
例えばVBScriptでAPIを実行する際に、レスポンスで戻ってくるJSONをパースしたい場合は、素直にいったんJSONをテキストファイルに出力した後、PowerShellなどのJSONのパースに対応した別のスクリプトでパースした方が無難かなと思います。

以下の記事でPowerShellを使用してJSONファイルをパースするコマンドやその解説を紹介しています。
併せてご一読ください。

【PowerShell入門】PowerShellでJSONファイルを読み込んでパース

今回の記事では、PowerShell初心者向けとして、JSONファイルを読み込んでパースするコマンドを解説も交えて紹介し...

www.depthbomb.net

2022.06.20

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