Box Platform APIエージェントプレイブック

​

ベースURL

https://api.box.com/2.0/

https://upload.box.com/api/2.0/

​

認証

curl https://api.box.com/2.0/users/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

​

メソッド

​

トークンのライフサイクル

• アクセストークンは、60分 (レスポンス内のexpires_in) 後に期限切れになります。
• OAuth 2.0から更新トークン (60日間有効、1回のみ使用可能) が返されます。期限切れになる前に交換してください。
• CCGおよびJWTアプリが、同じ資格情報で新しいトークンをリクエストします。
• すべてのメソッドが、POST https://api.box.com/oauth2/tokenにトークンをリクエストします。

​

主要エンドポイント

​

レート制限と再試行戦略

1. すべてのレスポンスで429ステータスを確認します。
2. retry-afterヘッダー値を読みます。
3. ヘッダー値の秒数以上待ってから再試行します。
4. 同時に実行されるリクエスト用にジッターによる指数バックオフを使用します。
5. 同じリクエストでの再試行が5回を超えないようにしてください。

​

エラー処理

{
  "type": "error",
  "status": 409,
  "code": "item_name_in_use",
  "message": "Item with the same name already exists."
}

​

一般的なステータスコード

​

ページネーション

​

オフセットベース (ほとんどのリストエンドポイントでのデフォルト設定)

curl "https://api.box.com/2.0/folders/0/items?offset=0&limit=100" \
  -H "Authorization: Bearer ACCESS_TOKEN"

​

マーカーベース

curl "https://api.box.com/2.0/folders/0/items?usemarker=true&limit=1000" \
  -H "Authorization: Bearer ACCESS_TOKEN"

​

SDK

​

よくある落とし穴

• フォルダ0はルートです。すべてのフォルダツリーがID 0から開始されます。その他のフォルダIDの存在を想定しないようにしてください。
• サービスアカウントは、最初は空の状態です。既存のコンテンツにアクセスできるようにするには、コラボレータとして招待します。
• トークンはスコープによって制限されます。ユーザーがファイルへのアクセス権限を持っていても、アプリに必須スコープが設定されていない場合、トークンは失敗します。
• アップロードには異なるドメインが使用されます。使用されるのはupload.box.comであり、api.box.comではありません。
• 分割アップロードには、正確なパーツサイズが必要です (最後のパーツを除く)。
• Webhookハンドラは、30秒以内に2xxを返す必要があります。必要に応じて、イベントを非同期で処理してください。
• Webhookは順不同で配信されます。冪等性のある方法でイベントを処理してください。
• インスタンスをファイルに適用する前に、メタデータテンプレートが存在している必要があります。
• メタデータクエリのテンプレートキーとフィールド名では、大文字と小文字が区別されます。
• Box AIエンドポイントを使用するには、アプリで [AIを管理する] スコープが有効になっている必要があります。

​

OpenAPI仕様

• ソース: box-openapi
• バンドルされたJSON: openapi.json

​

クイックリンク