はじめに
今回はHULFT Squareを使ってBOX APIに接続します。HULFT SquareにはBOXコネクタがございます。そのため、基本的なファイルやユーザ操作にはAPIを使わずとも、GUI上での設定に対応しております。ただ、権限の問題やAPIにしかない機能を使いたい際には、BOX APIに接続する必要があるかと思います。その際の一助になれば幸いです。
今回は専用コネクタとも機能がかぶってしまいますが、わかりやすさ重視で、ファイルの自動ダウンロードのスクリプトを作成していきます。
接続の流れ
１．BOX上に接続のためのアプリケーションを作成
２．HULFT Square上で接続のための設定
３．スクリプト作成
１．BOX上に接続のためのアプリケーションを作成
BOXには「Postmanを使用したAPIコール」のクイックスタートガイドがございますので、こちらに沿って進めていきます。
もちろん今回接続するのはPostmanではなくHULFT Squareのため、Postmanの設定部分は飛ばしていただいて問題ございません。開発者コンソールで１から作成するのと比べ、こちらの手順は画面に沿って進めていくだけで準備が簡単ですので、おすすめの方法です。
途中で取得できる「リフレッシュトークン」、「クライアントID」、「クライアントシークレット」は控えておくようにしてください。
２．HULFT Square上で接続のための設定
２－１．コネクション作成
ではまず、HULFT Squareのマネジメント画面上で接続のための「コネクション」を作成します。
左側メニューから「メイン」-「コネクション」-「追加」と押下していき、「REST」を選択します。
任意の「名前」と「ワークスペース」を設定します。
下記を設定します。
URL：https://api.box.com
「プロファイル」も任意のものを設定し、「完了」を押下します。
２－２．リフレッシュトークンのファイル作成
後工程で使用するため、リフレッシュトークンだけを記載したCSVファイルを作成します。[リフレッシュトークン]の部分は、実際のリフレッシュトークンの文字列を記載します。作成しましたら、HULFT Squareのストレージにアップしておきます。
２－３．スキーマの登録
次にアクセストークン更新APIのJSON形式をスキーマに登録します。下記をJSON形式としてスキーマに登録してください。
{
"access_token": "[アクセストークン]",
"expires_in": 3457,
"restricted_to": [],
"refresh_token": "[リフレッシュトークン]",
"token_type": "bearer"
}
##３．スクリプト作成
スクリプト変数作成
それではスクリプトを作成していきます。まずは、下記のようにスクリプト変数を2つ作成しておきます。
ここで、[ダウンロードしたいファイルのファイルID]にはファイルIDを初期値として格納します。実際は別のシステムから連携されたものを格納したりするかと思いますが、今回はファイルIDを画面から取得します。ファイルIDはBOXをウェブブラウザ上で開き、該当のファイルを開いた際にURL末尾の記載される数列です。
https://[テナント名].ent.box.com/file/[ここがファイルIDです]
注意
URLに「?」が含まれる場合、「?」以降はURLパラメータのため、今回は「?」以降の文字列はないものとして考えてください。
例 https://[テナント名].ent.box.com/file/[ファイルID]?s=XXX
この場合「?s=XXX」は気にせず、その前が「ファイルID」となります。
リフレッシュトークンファイル読み込み
次に先ほど作成したリフレッシュトークンのCSVファイル読み込みを作成します。ツールパレットから「ファイル」-「CSV」-「CSVファイル読み取り」を配置します。
➀「必須設定」タブ
ファイル：[リフレッシュトークン.csvの配置パス]
列一覧：リフレッシュトークン
BOX APIへアクセスするためアクセストークンの取得/更新
次はBOX APIへアクセスするためにアクセストークンの取得/更新を行います。ツールパレットの「ネットワーク」-「REST」-「POST実行」を配置します。
➀「必須設定」タブ
接続先：「作成したRESTコネクション」 ※「２－１．コネクション作成」
パス：/oauth2/token
②「リクエスト設定」タブ
データ入力元：データ
データ形式：フォーム
フォーム設定：下記4項目を追加します
「grant_type」、「client_id」、「client_secret」、「refresh_token」
③「レスポンス設定」タブ
データ出力先：データ
データ形式：JSON
次回用にリフレッシュトークンの書き出し
上記のBOX APIアクセストークンの更新を行うと、併せてリフレッシュトークンも更新される仕様となっております。そのため、アクセストークン更新後には以前のリフレッシュトークンはもう利用できなくなってしまいます。そのため、次回以降のアクセストークン更新処理を行うために更新されたリフレッシュトークンのファイルを更新しておきます。
（私は、一度リフレッシュトークンが更新されていることに気づけず、リフレッシュトークンを失念し、BOXアプリケーションを再作成となってしまいました。。。）
➀「必須設定」タブ
ファイル：[リフレッシュトークン.csvの配置パス]
列一覧：リフレッシュトークン
②「書き込み設定」タブ
上書き：☑
ファイルダウンロードAPIのコール
最後にファイルダウンロードのBOX APIのコールを行うアイコンを配置します。ツールパレットの「ネットワーク」-「REST」-「GET実行」を配置します。
①「リクエスト設定」タブ
接続先：「作成したRESTコネクション」 ※「２－１．コネクション作成」
パス：/2.0/files/${ファイルID}/content
クエリパラメータ：access_token：${アクセストークン}
②「レスポンス設定」タブ
データ出力先：ファイル
ファイルパス：[ファイルの保存先/保存名]
自動でリダイレクトする：☑
フロー
下記のようにフローを引きます。
「①リフレッシュトークン読み出しのCSV読み取り」⇒「②アクセストークン更新のPOST実行」⇒「③リフレッシュトークン書き出し」⇒「④目的のBOX API実行」
またその際に、①⇒②、②⇒③ではMappingも追加しておきます。
下記の画像のようなフローになれば正解です。
Mapping(①リフレッシュトークン読み出しのCSV読み取り⇒②アクセストークン更新のPOST実行)
こちらではアクセストークン更新APIに必要な情報をマッピングしていきます。BOXアプリケーション作成時に控えておいた、「クライアントID」、「クライアントシークレット」を利用します。下記のようにMappingします。（｛｝で表現しているものは単一文字列定数アイコンで該当の文字列のアイコンを作成してください）
・｛refresh_token｝⇒grant_type - value
・｛[クライアントID]｝⇒client_id - value
・｛[クライアントシークレット]｝⇒client_secret - value
・リフレッシュトークン⇒refresh_token - value
Mapping（②アクセストークン更新のPOST実行⇒③リフレッシュトークン書き出し）
こちらではアクセストークン更新時に更新されたリフレッシュトークンを退避しておきます。まずは入力データ「POST実行」のアイコンを右クリックし、リソースから２－３．で作成したスキーマを呼び出します。またスクリプト変数の「アクセストークン」に更新したアクセストークンを格納しておきます。下記のようにMappingします。
・access_token⇒アクセストークン（スクリプト変数）
・refresh_token⇒リフレッシュトークン
これでスクリプトが完成です。実行すると、保存先のファイルパスにファイルがダウンロードされます。
最後に
今回はHULFT SquareのREST APIコネクタを使って、BOX APIと接続しました。BOX APIの各種機能と連携できることで、よりBOXとの連携の幅が増えることかと存じます。ここまで読んでいただきありがとうございました。
HULFT Squareについて知りたい方はこちら