HCL Notes でBox APIを利用する（5）

2024年8月19日 20:03

第5回は、いよいよBox APIを利用するプログラムの解説です。
とはいえ、プログラム自体は、アクセストークン取得時のエージェントの内容と大差ありません。

処理の流れ

基本的には、HTTPリクエストを送信し、そのレスポンス（JSON）を解析して、必要なデータをNotesで活用します。

■HTTPリクエストの送信
NotesアプリケーションからBoxへ送信するHTTPリクエストですが、ヘッダー情報に、資格情報としてアクセストークンを含める必要があります。

また、HTTPリクエストの送信については、今回はLotusScriptのNotesHttpRequestクラスを利用しますが、MSXMLオブジェクトやJavaなど、その他の通信方法を選択することも可能です。
LotusScriptの場合、変数の64KBの制限がある為、ファイルのアップロードやダウンロードなど、データサイズが64KBを超える場合などは、Javaを採用する等、状況に応じた通信方法を選択してます。

■レスポンスの解析
Box APIでは、HTTPリクエストの戻り値としてJSON形式のデータが返ってくる為、それをLotesScriptで解析し、目的のデータを抽出します。
当然、実行するBox APIの処理により、このレスポンスのJSONの内容は変わってきますので、事前にBox APIのリファレンスで確認してください。

解説するBox APIのサンプル処理について

今回作成するサンプルでは、Box上の指定したフォルダ内のフォルダやファイルの一覧を取得します。

今回は、以下のフォルダの情報を取得します。
このフォルダには、「Folder」という名称のフォルダと「test.txt」、「test2.txt」というファイルが存在しています。

今回はこのフォルダに含まれる情報をBox APIで取得し、種類（ファイルかフォルダ）および名称をメッセージボックスで表示します。

HTTPリクエストの内容

今回の処理では、フォルダ内の項目情報を取得する、以下のリクエストを利用します。

リクエスト形式はGET、URLは上記の赤字箇所には、対象のフォルダIDを指定します。フォルダのIDは、実際にBoxでそのフォルダを表示したURLに含まれる「folder/」の後の数字となります。

例：https://app.box.com/folder/123456789012
（「123456789012」がフォルダID）

ヘッダー情報には、Authorizationに、”Bearer”という固定値とアクセストークンを指定します。Content-Typeついては、「application/json」を指定します。今回は、リクエストの本文は不要です。

Notesエージェント

続いてBox APIを起動するNotes側のエージェントを作成します。
エージェントの主な設定は、以下の通りです。
※LotusScriptのエージェントとして作成します。

■処理の流れ
前回のアクセストークン取得のエージェントと同様に、NotesHTTPRequestクラスでHTTPリスエストを送信し、レスポンス（JSON）をについては、LotusScriptのJSON関連のクラスを利用して解析していきます。

■ サンプルコード

Dim ns	        As New NotesSession
Dim nHttp	    As NotesHTTPRequest
Dim njNav	    As NotesJSONNavigator
Dim nje_Ent	    As NotesJSONElement
Dim nja  	    As NotesJSONArray
Dim nje_Val	    As NotesJSONElement
Dim njo	        As NotesJSONObject
Dim sURL	    As String
Dim strType	    As String
Dim strTitle	As String
Dim msg	        As String

Const FolderId = "フォルダID"
Const AccToken = "アクセストークン"
sURL = "https://api.box.com/2.0/folders/" & FolderId & "/items"

Set nHttp = ns.CreateHTTPRequest()
Call nHttp.SetHeaderField("Authorization", "Bearer " & AccToken)
Call nHttp.SetHeaderField("Content-Type", "application/json")

nHttp.PreferJSONNavigator = True
Set njNav = nHttp.Get(sURL)

'以降JSONの解析
Set nje_Ent = njNav.GetElementByPointer("/entries")
Set nja = nje_Ent.value
Set nje_Val = nja.GetFirstElement()
While Not (nje_Val Is nothing)
    Set njo = nje_Val.Value
    strType = njo.GetElementByName("type").value
    strTitle = njo.GetElementByName("name").value
    msg = msg & "種類：" & strType & " | " & "名称：" & strTitle & Chr(13) & Chr(10)

    Set nje_Val = nja.GetNextElement()
Wend

MsgBox msg, 64, "ファイル一覧"

今回のレスポンスのJSONデータは、アクセストークンの取得時より
複雑なものが返ってきますので、プログラムも若干複雑になります。
その為、JSONの構造とLotusScriptの各クラスを意識する必要があります。

HTTPリクエストからのレスポンスは、NotesJSONNavigatorクラスとして取得されます。フォルダ内の情報は、「Entries」にあり、これはNotesJSONElement型で取得できます。また、このEntriesは、対象フォルダに含まれるファイルやフォルダ情報であり、角括弧で囲まれていることから配列と分かります。その為、NotesJSONArrayで取得します。

配列の各要素は、NotesJSONElement型で取得します。これが、ファイルやフォルダ単位の情報です。また、この要素には、中括弧で囲まれたオブジェクトが含まれている為、NotesJSONObject型で取得後、さらに種別や名前などの各要素をNotesJSONElement型で取得することで、ようやく種類や名称などの情報が取得できます。

LotusScriptには、いくつものJSON関連のクラスがある為、慣れるまでは、少し難しく感じるかもしれません。
プログラミングのコツとしては、実際のJSONを書き出して、括弧や記号を意識すると、どのクラスを利用すべきか理解しやすくなると思います。
ただし、最終的には、デバッグを有効にしてTry ＆ Errorを繰り返すことが
習得の早道でしょう。

以上で、今回のシリーズは終了です。