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

第4回は、前回に引き続きアクセストークンの取得についての解説です。
今回は具体的なNotesのプログラムについてです。

「認証取得」ボタンの作成

Notesのビューアクションに「認証取得」ボタンを作成します。
このボタンでは、Webブラウザで次に作成する「pgAuthorize」ページを表示します。ボタンには、以下の式を設定します。

【式】
@URLOpen(“https://ホスト/DBパス/pgAuthorize?OpenPage")

「pgAuthorize」ページ

このページでは、Box のOAuth 2.0 認証画面に自動的に遷移するように、onLoad イベントに、以下のJavaScript を設定します。

var clientId = “クライアントID”;
var aUrl = "https://account.box.com/api/oauth2/authorize";
var type = "?response_type=code";
var cId = "&client_id=" + clientId;
var url = aUrl + type + cId;
window.open(url, "_self")

※クライアントIDには、Box アプリケーションの設定画面に表示されているクライアントIDを指定します。

Box アプリケーションの設定画面

「agGetAT」エージェント

Box で認証が完了した際、自動的にこのエージェントを実行するDomino URLに遷移されることで、アクセストークンを取得していきます。

エージェントの主な設定は、以下の通りです。
※LotusScriptのエージェントとして作成します。

「agGetAT」エージェント

■ コードの取得
エージェントを実行するURLは、以下のような形式です。
このURLに含まれているコードは、アクセストークンの取得に必要です。

URLについて

このコードは、以下のようなLotusScriptで取得可能です。

Set nd = ns.DocumentContext
qs = nd.Query_String_Decoded(0)
code = StrRight(qs, "&code=")

■ アクセストークンの取得
アクセストークンの取得は、以下のHTTPリクエストを送信し、そのレスポンスのJSONを解析することで、アクセストークンが取得可能です。

HTTPリクエストの送信は、NotesHTTPRequestクラスを利用することが可能です。アクセストークンの取得時は、POSTリクエストを送信し、その本文に必要な[CLIENT_ID]、[CLIENT_SECRET]は、Boxアプリケーションの設定画面のクライアントID、クライアントシークレット、[CODE] には、先に説明したコードを設定します。
※grant_typeは、固定値です

アクセストークンを取得する為のＨTTPリクエスト

Box アプリケーションの設定画面

レスポンスは、JSON形式のデータの為、NotesJSONNavigatorクラスなどを利用します。

■ サンプルコード

Dim ns	        As New NotesSession
Dim nd	        As NotesDocument
Dim nHttp	    As NotesHTTPRequest
Dim njNav	    As NotesJSONNavigator
Dim qs	        As String
Dim code	    As String
Dim strParam	As String
Dim accToken	As String
Dim refToken	As String

Const sURL = "https://api.box.com/oauth2/token"
Const ClientId = "クライアントID"
Const ClientSecret = "クライアントシークレット"

Set nd = ns.DocumentContext
qs = nd.Query_String_Decoded(0)
code = StrRight(qs, "&code=")

Set nHttp = ns.CreateHTTPRequest()
Call nHttp.SetHeaderField("Content-Type", "application/x-www-form-urlencoded")

strParam = "client_id=" & ClientId
strParam = strParam & "&client_secret=" & ClientSecret
strParam = strParam & "&code=" & code
strParam = strParam & “&grant_type=authorization_code"

nHttp.PreferJSONNavigator = True
Set njNav = nHttp.Post(sURL, strParam)

accToken = njNav.GetElementByPointer("/access_token").value
refToken = njNav.GetElementByPointer("/refresh_token").value

Print |アクセストークンの取得に成功しました|

※実際の運用では、クライアントIDやクライアントシークレットは、管理文書を準備して管理するとよいでしょう。
※変数「accToken」には、アクセストークン、「refToken」には更新トークンが取得されます。必要に応じて、notes.ini や文書などに保存します。
（更新トークンについては、別途解説します。）

Box アプリケーションの設定

Box の認証後に、「agGetAT」エージェントを実行させる為、Box アプリケーションの設定画面にて、リダイレクトURIに以下のURLを設定します。

https://ホスト名/DBパス/(agGetAT)?OpenAgent

※設定するURLは、Box の制限により「HTTPS」のURLである必要があります。その為、Domino サーバーもSSL対応がされている必要があります。

Box アプリケーションの設定画面

更新トークンを利用したアクセストークンの取得

更新トークンとは、アクセストークンの取得時に利用していたコードの代わりになるもので、アクセストークンの取得時に取得することが可能です。

更新トークンを利用すると、アクセストークンを取得する際、Box への認証処理を省略することができ、ユーザーの利便性が向上します。
また、更新トークンにも有効期限があり、最長60日、もしくは1回利用すると無効となります。

■ HTTPリクエストの送信内容
更新トークンを利用する場合も、HTTPリクエストの内容については、ほとんど同じです。リクエストの本文に含める、コードが更新トークンになり、grant_typeに設定する固定値を変更するだけです。

更新トークンを利用する際のHTTPリクエスト

■ サンプルコード

Dim ns	        As New NotesSession
Dim nHttp	    As NotesHTTPRequest
Dim njNav	    As NotesJSONNavigator
Dim strParam	As String
Dim accToken	As String
Dim refToken	As String

Const sURL = "https://api.box.com/oauth2/token"
Const ClientId = "クライアントID"
Const ClientSecret = "クライアントシークレット"
Const Token = "更新トークン"

Set nHttp = ns.CreateHTTPRequest()
Call nHttp.SetHeaderField("Content-Type", "application/x-www-form-urlencoded")

strParam = "client_id=" & ClientId
strParam = strParam & "&client_secret=" & ClientSecret
strParam = strParam & "&refresh_token=" & Token
strParam = strParam & “&grant_type=refresh_token"

nHttp.PreferJSONNavigator = True
Set njNav = nHttp.Post(sURL, strParam)

accToken = njNav.GetElementByPointer("/access_token").value
refToken = njNav.GetElementByPointer("/refresh_token").value

Print |アクセストークンの取得に成功しました|