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
https://developer.box.com/docs/setting-up-a-jwt-app

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

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#の例。

```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);
```

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

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

```c#:BoxAPi.cs
// Create Admin client
var adminToken = boxJWT.AdminToken();
client = boxJWT.AdminClient(adminToken);
```

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

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

```c#:BoxAPi.cs
// Create user client
var userToken = boxJWT.UserToken (ID);
client = boxJWT.UserClient (userToken, ID);
```

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

### 対象ユーザにチェンジ！

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

```c#:BoxAPi.cs
var userToken = boxJWT.UserToken(ID);
client = boxJWT.UserClient(userToken, ID);
```

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

# 雑感

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