Zenn
📦

Box API使ってみた（個人アカウント無料プラン→エンタープライズPlus/ BoxAI機能無効版）

に公開
Python
Box
tech

Box APIと格闘した1ヶ月：個人無料プランとエンタープライズプランでの試行錯誤メモ

こんにちは！今回は、2025年2月15日から3月15日にかけて、個人でBox APIの検証を行った際の記録をまとめたいと思います。Box APIに興味がある方、これから使ってみようと思っている方の参考になれば幸いです。

きっかけ

ある案件がきっかけでBox APIを操作する必要が生じ、調査を開始しました。まずは手軽に試せる個人アカウントの無料プランからスタートし、その後エンタープライズプラスアカウントでも検証を行いました。

1. 個人アカウント（無料プラン）での挑戦

まず、個人アカウント（無料プラン）でAPIを試してみました。認証方式としては、JWT、OAuth 2.0、そして開発者トークンが利用できるようです。

認証の壁：JWTはエンタープライズ向け

最初にJWT認証を試みましたが、どうやらうまくいきません。調べてみると、JWT認証を利用するにはエンタープライズライセンスが必要とのこと。個人アカウントの無料プランでは認証が通らないことが分かりました。（これはドキュメントにも記載されています。）

OAuth 2.0や開発者トークン（有効期間が短いテスト用）での認証は可能でした。しかし、無料プランでどこまでAPIを利用できるのか、ドキュメントだけでは判別が難しい部分がありました。
また、OAuth 2.0は認証の都度コールバックURLへ遷移する必要があり、開発者トークンは1時間で有効期限が切れてしまうため、頻繁な再認証が煩わしく感じました。そこで、OAuth 2.0認証時に発行されたアクセストークンをローカルストレージに保存し、これを利用することでスムーズに検証を進められました。

結論として、個人アカウントで継続的に検証を行う場合は、OAuth 2.0で取得したトークンをローカルストレージなどに保存して利用する方法がおすすめです。

検証方法

検証はCursorとPython SDKを組み合わせて行い、気になるAPIを実際に実装して動作を確認しながら理解を深めていきました。

利用したSDKはこちらです:
https://github.com/box/box-python-sdk-gen

このときの注意点としては、以下の2点がありました。

  • Python SDKには2種類あり、Generated (gen) という表記がある方が現行版で、box-python-sdk（無印）は廃止予定である点に注意が必要です。
    • 余談ですが、Generated という名前から自動生成された補助的なものかと思いきや、こちらが正式版であることに最初は少し戸惑いました。なぜこの名前なのでしょうか…
  • Cursorのドキュメント機能でSDKを登録しただけでは上手く補完などが機能しない実装があったため、GitHubリポジトリの docs/md ディレクトリをローカルに保存し、直接参照させることで対応しました。

開発者コンソールへのアクセス

謎のメッセージ
Boxの開発者コンソールにアクセスした際、開発者アカウントでサインアップ・ログインしているにも関わらず、「開発者コンソールのすべての機能にアクセスするには、Box Developerアカウントにログインまたはサインアップしてください。」というメッセージが表示されることがありました。他のブログ記事などでも同様の現象が報告されていたため、もしかしたら一時的な問題や、特定の操作に対する仕様なのかもしれません。

利用できなかったAPI

※自分が検証した範囲での結果であり、誤りがある可能性もあります。

無料プランでは、残念ながら利用できない、または権限不足エラーとなるAPIがいくつかありました。

  • Box AI API: これは予想通りですが、利用できませんでした。エンタープライズプランであっても、Box AI機能自体が有効になっていないアカウントでは権限不足エラーとなるようです。
  • Classification API: ファイルの分類に関するAPIも利用できませんでした。
  • メタデータからの検索: 特定のメタデータを持つファイルを検索する機能も、無料プランでは制限があるようでした。（ファイル名での検索は可能でした。）
  • Webhook: 設定したWebhookが期待通りにトリガーされませんでした。Boxのインサイト（アクティビティログのようなもの）にも、API経由での操作が反映されませんでした。
    • そもそもWebhookは管理コンソールのGUIからも設定できるようなのですが、無料プランのアカウントでは管理コンソールにWebhookの設定項目自体が見当たりませんでした。API経由でWebhookを作成すること自体はできましたが、結果的にトリガーされなかったため、無料プランでは利用できない仕様なのかもしれません。

ハマったポイント：ファイルの新規作成

地味にハマったのが、SDK経由でのファイルの新規作成方法です。ファイル操作なので files というメソッド群を使うのかと思いきや、正しくは uploads メソッドを利用する必要がありました。これはAPIリファレンスをよく読めば分かるのですが、思い込みで少し時間を取られてしまいました。

2. エンタープライズプラスアカウントでの試行

次に、エンタープライズプラスアカウントで、より多くの機能、特に管理系の操作を試してみました。ここでは主にBox CLI（コマンドラインインターフェース）を利用しました。

CLIのインストールと認証

Box CLIのインストール自体はスムーズでしたが、CLIの認証設定で少しつまづきました。

  • OAuth認証でのコールバックURL: マニュアルに従ってOAuth認証を設定しようとしたところ、コールバックURLがうまく機能せず、認証プロセスを完了できませんでした。
  • JWT認証への切り替え: OAuthがうまくいかなかったため、JWT認証に切り替えたところ、こちらは問題なく設定できました。エンタープライズアカウントであればJWT認証が利用できるため、CLIでもこちらを使うのが確実かもしれません。

管理者権限での操作 (--as-user オプション)

CLIを使って特定のフォルダ情報を取得しようとした際、そのままコマンドを実行するとエラーになりました。

# そのまま実行するとエラーになるケースがあった
box folders:get <フォルダID>

# --as-user オプションでユーザーIDを指定すると成功
box folders:get <フォルダID> --as-user <ユーザーID>

まとめ

今回の検証を通して、Box APIは非常に多機能である一方、アカウントのプランによって利用できる機能や認証方式に違いがあることがよく分かりました。

  • 個人無料プラン: 簡単なファイル操作（アップロード、ダウンロードなど）は可能ですが、JWT認証や高度な機能（メタデータ検索、Webhook、AI、分類など）には制限があります。まずはAPIの雰囲気を掴む、という目的であれば十分試せます。
  • エンタープライズプラン: JWT認証が利用可能になり、管理機能を含めたほぼ全てのAPIが利用できるようになります。CLIを使った操作も強力です。ただし、管理者として操作する場合は --as-user オプションの指定が必要になる場面があります。また、エンタープライズプランの中でもAI機能の利用可否など、契約内容によって利用できる機能が変わる点にも注意が必要です。

ドキュメントだけでは分かりにくい部分もあり、実際に手を動かしてみることで多くの学びがありました。特に認証周りとプランによる機能差は、最初にしっかり確認しておくべきポイントだと感じました。

これからBox APIを触ってみる方は、まずご自身のアカウントプランで何ができるのかを確認し、小さな機能から試していくのがおすすめです。

Discussion