Box API を叩くその前に

APIリファレンス

英語：https://developer.box.com/reference
日本語：https://ja.developer.box.com/reference

日本語はところどころ崩れてるので、英語版を参照したほうがいいです(2018/10現在)

認証方式

ざっくり。

• OAuth 2 と、OAuth 2 with JWT がある
• OAuth 2 と、OAuth 2 with JWT では、扱うユーザータイプが異なる
• OAuth 2
  • 管理対象ユーザー[Managed Users ]、外部ユーザー[External Users]
  • 次の場合は、認証方法としてOAuth 2を選択する(抜粋)
    • 既存のBoxアカウントを持っているユーザとだけ作業する
    • すべてのコンテンツをユーザーのボックスアカウントで管理し、アプリケーションでは管理しないようにする
• OAuth 2 with JWT
  • アプリユーザー[App Users]
  • JWTを使用することにより、アプリをダイレクトに認証させることができる(ユーザのログイン不要)
  • 次の場合は、認証方法としてJWTを使用してOAuth 2を選択する(抜粋)
    • ユーザーはBoxアカウントや、資格情報を持たない
    • 認証するために、ユーザーがBoxにログインすることを望まない

参考： Picking an Auth Type
https://developer.box.com/docs/authentication-types-and-security
★2つの認証方式の違いによる認証フローや比較表が記載されています

参考：User Types
https://developer.box.com/docs/user-types
★基本設定では、JWTベースのアプリでは、管理対象ユーザにアクセスできない(設定変更すればOK)
★APIを使用して[外部ユーザー]を作成または管理することはできない

JWT Application Setup

↑基本的な流れは上記の通り

1. Box Developersにアクセスし、「アプリの新規作成」ボタンをクリック
   https://hoge.app.box.com/developers/console
2. アプリの種類を聞かれるので、「カスタムアプリ」を選択、次へ
3. 「JWTを使用したOAuth2.0(サーバー認証)」を選択、次へ
4. 「アプリの表示」をクリック
5. 「構成」ページの中ほどにある「アプリケーションアクセス」の中、[Enterprise]にチェックを入れる
6. 「構成」ページの中ほどにある「公開/秘密キーペアを生成」ボタンをクリック
7. 「この操作を実行するには、2段階認証を有効にする必要があります」を注意文が表示されるのでアカウント画面へ遷移する
8. 「認証」のところの「未承認のログインに対しては2段階認証を必須にする」をクリック
   • https://hoge.app.box.com/account
9. 携帯電話番号入力、SMSで届いた認証コードを入力
10. 「変更を保存」、「開発者コンソールに戻る」をクリック
11. 先ほど作成したアプリをクリックし、左メニュー「構成」から、「公開/秘密キーペアを生成」ボタンをクリック
12. JSONファイルがダウンロードされる
13. ここで決定した「公開キーID」は、プログラム中の[jwt_key_id]として必要なので、控えておく
14. 「管理コンソール」画面へ行き、「アプリ」タブをクリック
    https://hoge.app.box.com/master
15. 画面中ほどの「カスタムアプリケーション」内、「新しいアプリケーションを承認」をクリック
16. アプリの「クライアントID」を入力(Box Developersのページの「構成」ページに記載されている)
    注意書きが表示されるので「承認」をクリック

★注意★

Pythonを使う場合は、「公開/秘密キーペアを生成」ではなく、「公開キーを追加」ボタンをクリック
[Generate Keys Manually] の説明の通り手動で作成したキーを登録する
ここで決定した「公開キーID」は、プログラム中の[jwt_key_id]として必要なので、控えておく

Install SDK

https://developer.box.com/docs/install-the-sdk
↑記述の通りで特筆すべきことはなし

Authenticate with JWT (SDK)

https://developer.box.com/docs/authenticate-with-jwt
↑記述の通り。

試したのはPythonとNode.
Pythonでの注意点は、[rsa_private_key_file_sys_path]は、ダウンロードしたJSONファイル内に記載されているRSA KEYではなく
手動で生成したprivate.pemのパスを指定する。(ページ中の[Generate Keys Manually]部分)
ここを間違えると、認証エラーになる。

APIを叩く前に

トークン取得

Boxオブジェクト生成

まずは設定ファイルを読み込む。ここらへんは各種SDKのREADME参照。
以下はC#の例。

BoxAPi.cs

IBoxConfig config = null;
using (FileStream fs = new FileStream ("./Box.config.json", FileMode.Open)) {
    config = BoxConfig.CreateFromJsonFile (fs);
}

// Create JWT auth using config file
var boxJWT = new BoxJWTAuth (config);

管理者ユーザのトークン取得

• このトークン生成の仕方で、コンテンツをアップロードした場合、アプリユーザ配下にコンテンツができる
• 全ユーザーのコンテンツ検索も可能

BoxAPi.cs

// Create Admin client
var adminToken = boxJWT.AdminToken();
client = boxJWT.AdminClient(adminToken);

一般(?)ユーザートークン取得

• これをやるには、高度な機能をONにすること
• アプリを作成したユーザー配下にコンテンツができる
• ユーザー配下のフォルダしか見れない

BoxAPi.cs

// Create user client
var userToken = boxJWT.UserToken (ID);
client = boxJWT.UserClient (userToken, ID);

IDは、ユーザーIDを指定(数値)

対象ユーザにチェンジ！

対象のユーザーIDがわかれば、下記のように操作clientをチェンジできる。

BoxAPi.cs

var userToken = boxJWT.UserToken(ID);
client = boxJWT.UserClient(userToken, ID);

さあ、APIを叩いてみよう！（叩くまでが長い）

雑感

• 最初はとにかくユーザーのタイプが多くて理解に苦しんだ
  • コメントで補足いただいたので助かります
• GUIでの設定も重要なんだけど、なかなか紐付かなくて悩んだ