Box CLI を使ってみる

Box CLI を Mac で使うまでの手順（メモ）

少しずつ追加する予定・・・

# 目的

Mac のターミナルから Box を操作するために CLI SDK 入れて動かす。

何が出来るのか一通り試すにはコマンドが一番手っ取り早いのでは？的な。

# セットアップ

[Box CLIのインストール](https://ja.developer.box.com/guides/tooling/sdks/cli/) に従ってセットアップ

基本的な流れは
1. CLI ツールをインストール
2. 設定ファイルを作成
という感じ。


## CLI をインストール

下記のURLからダウンロードできる。

https://github.com/box/boxcli/releases

## 設定ファイルを作成

[Box Developer Console](https://app.box.com/developers/console) で JWT認証を使った Boxアプリケーションをセットアップし、設定ページから JSON構成ファイルをダウンロードする、と言う流れ。

### カスタムアプリの作成

0. [Box Developer Console](https://app.box.com/developers/console) にアクセス
1. 「アプリの新規作成」をクリック
2. 「カスタムアプリ」を選択して「次へ」  
    <img width="1050" alt="dev-newapp.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84947/2a983785-c066-7f1d-49ce-5c12d75b7bfc.png">
3. 認証方法で「JWTを使用したOAuth 2.0（サーバー認証）」を選択して「次へ」  
    <img width="635" alt="dev-newapp-auth.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84947/1ca7c83b-fac7-56c3-496b-a826f8f038d4.png">
4. アプリに名前をつけて「アプリの作成」をクリック

### JWTキーペアを生成

1. アプリケーションの左側のサイドバーで[構成]オプションをクリック
2. [公開キーの追加と管理]セクションで[公開/秘密キーペアを生成]ボタンをクリック  
    <img width="1001" alt="dev-app-config.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84947/5a52f246-12f1-15bb-db4b-9f00c9c01396.png">
    1. 2要素認証の警告が出たら設定しておく  
        <img width="564" alt="warning-2fa.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84947/1e32cd22-a1ea-4eb6-dcc2-935c2c997804.png">
    2. 追加認証を有効に
        <img width="958" alt="dev-userconfig-2fa.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84947/44e8d47f-5329-209f-3355-4e239934814d.png">
3. 秘密鍵が含まれたJSONファイルが落ちてくるので保存

上記の手順を行わないで進めると構成ファイルのロード時にエラーになる。

```zsh
% box configure:environments:add 0__config.json 
Config object missing key boxAppSettings.appAuth.publicKeyID
```

### アプリの承認

1. アプリケーションの左側のサイドバーで[一般]リンクを選択
2. [アプリの承認]セクションで 「承認用に送信」を選択    
    <img width="460" alt="dev-app-auth.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84947/3695b412-7266-d07c-fa08-03dd99df5c77.png">
3. アプリの承認
    1. box管理画面の[アプリ > カスタムアプリ] で「新しいアプリケーションを承認」をクリック
    2. クライアントID（APIキー）を入力して「次へ」
    3. 確認画面が出るので「承認」  
        <img width="432" alt="admin-custom-apps-dl.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84947/af376f0f-b8c1-8953-d5fa-1865edd2c61b.png">


この手順を行わずに進めた場合、コマンド実行時に下記のエラーが発生する

```zsh
% box folders:get 0
Unexpected API Response [400 Bad Request] unauthorized_client - This app is not authorized by the enterprise admin
```

### 構成ファイルを CLI に設定する

ダウンロードした構成ファイルを指定してコマンドを実行して構成を追加

```zsh
% box configure:environments:add PATH_TO_CONFIG_FILE
Successfully added CLI environment "default"
```

Successfully となっていれば成功！

# 構成ファイルについて

CLI には複数の構成ファイルを読み込むことが可能。


## 構成ファイルの追加

複数の構成ファイルを読み込む場合には名前をつけて読み込む。

```zsh
% box configure:environments:add entgov_user1_app.json -n user1_app
Successfully added CLI environment "user1_app"
```
https://github.com/box/boxcli/blob/master/docs/configure.md#box-configureenvironmentsadd-path

## 構成ファイルの切り替え

[configure:environments:set-current](https://github.com/box/boxcli/blob/master/docs/configure.md#box-configureenvironmentsset-current-name) で切り替える環境の名前を渡せば切り替わる。

user1_app に切り替える場合は下記のコマンドを実行する。

```zsh
% box configure:environments:set-current user1_app
```

環境の一覧は下記のコマンドで取得可能

```zsh
% box configure:environments:get
```

# 実行ユーザー

上記の手順で作成した構成ファイルを使って Box CLI を実行した場合、デフォルトではサービスアカウントで実行される。

当然、権限はアプリの作成者とは関係ないので、CLI でコラボレータとして操作する場合、対象のファイルやフォルダに対してサービスアカウントに権限がないとエラーになる。

また、設定やオプションによって実行時のユーザーを切り替えることも可能なので、実際にコマンドを実行しているユーザーを確認しながら処理をする必要がある。

## 現在のユーザーを取得

下記のコマンドを実行して、 `Login: ` の値として返却される値が現在のアカウント。

```zsh
% box users:get me
```

何も設定してない場合にはサービスアカウントが返却されるはず。

## ユーザーを切り替える

デフォルトユーザーを切り替える方法と、実行時にユーザーを切り替えて実行する方法の二通りの方法がある。

### デフォルトユーザーの切替

このコマンドを実行すると以後、全てのコマンドがここで設定したユーザーで実行される。

```zsh
% box configure:environments:switch-user [USERID]
```

https://github.com/box/boxcli/blob/master/docs/configure.md#box-configureenvironmentsswitch-user-userid

明示的にユーザーを切り替えるまで mac を再起動しても引き継がれる。

#### サービスアカウントに戻す

```zsh
% box configure:environments:switch-user --default
```

### コマンド実行時に切り替える

コマンド実行時のみ特定のユーザーとして実行する場合はこっち。

```zsh
% box users:get --as-user=[USERID]
```

https://github.com/box/boxcli#usage

## ユーザーの一覧を取得

切替可能なユーザーの一覧を取得

```zsh
% box users
```

# token 周り

## token の取得

実行時に使われているトークンを表示する。

```zsh
% box tokens:get
```

これをコピって curl の実行などに利用可能。

たとえば、現在のユーザーを取得するためのエンドポイントに上記の結果を入れると、サービスアカウントの結果が取れる。

```zsh
% curl -i -X GET "https://api.box.com/2.0/users/me" \
     -H "Authorization: Bearer <ACCESS_TOKEN>"
```

## token のキャッシュを無効にする

CLI はデフォルトでトークンがキャッシュされる設定になっている。

通常は問題にならないが、開発者コンソールで設定を変更してアプリの再認証した時など、古い設定を引き継いでしまうので、設定を変えながらテストしたい時には無効にすると楽。

```zsh
% box configure:environments:update --no-cache-tokens
```


# 便利な設定など

## オートコンプリート

入力補完が使える様になって便利。

指示に従ってコマンドを打てば OK

```zsh
% box autocomplete                        
Building the autocomplete cache... done

Setup Instructions for BOX CLI Autocomplete ---

1) Add the autocomplete env var to your zsh profile and source it
$ printf "$(box autocomplete:script zsh)" >> ~/.zshrc; source ~/.zshrc

NOTE: After sourcing, you can run `$ compaudit -D` to ensure no permissions conflicts are present

2) Test it out, e.g.:
$ box <TAB>                 # Command completion
$ box command --<TAB>       # Flag completion

Enjoy!

```