> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Box

> Box クラウドストレージのファイル・フォルダを管理

## 概要

Boxツールを使用すると、フローからBoxクラウドストレージを操作できます。ファイルの一覧取得・検索、アップロード・ダウンロード、フォルダの作成・コピー、共有リンクやコラボレータによる共有、アイテムの削除に対応しています。

## 主な機能

* `BOX_LIST_FILES`
  * Boxフォルダ内のファイル・フォルダを簡易形式(ID、名前、種別、サイズ、更新日時)で一覧取得します。
  * 入力: `folder_id`(デフォルトはルートフォルダ `"0"`)、`limit`(1〜1000、デフォルト100)
* `BOX_LIST_FOLDER_ITEMS`
  * ページング情報(`total_count`、`offset`、`next_marker`)付きでBoxフォルダ内のファイル・フォルダを一覧取得します。
  * 入力: `folder_id`、`limit`、`offset`(オフセット方式のページング)、`marker` と `use_marker_based_paging`(マーカー方式のページング)、`fields`(取得するBoxフィールドをカンマ区切りで指定)
* `BOX_SEARCH`
  * Box内のファイル・フォルダをキーワードで検索します。
  * 入力: `query`、`file_extensions`(任意、例: `"pdf,docx"`)、`ancestor_folder_ids`(任意、検索対象フォルダの絞り込み)、`limit`(1〜200、デフォルト30)
* `BOX_GET_FILE_INFO`
  * Boxのファイルまたはフォルダのメタデータを取得します。共有リンク情報も取得できます。
  * 入力: `item_id`、`item_type`(`file` または `folder`、デフォルト `file`)、`fields`
* `BOX_DOWNLOAD_FILE`
  * Boxからファイルをダウンロードし、base64エンコードされた内容とファイル名・サイズを返します。
  * 入力: `file_id`。最大50MBのファイルに対応しています。
* `BOX_UPLOAD_FILE`
  * Boxにファイルをアップロードします。base64文字列、データURL(`data:<mime>;base64,...`)、HTTPS URLのいずれかを指定できます。
  * 入力: `file`、`filename`(任意、省略時はファイルURLから抽出)、`folder_id`(デフォルトはルート `"0"`)。新しい `file_id` と `name` を返します。
* `BOX_CREATE_FOLDER`
  * Boxに新しいフォルダを作成します。
  * 入力: `name`、`parent_folder_id`(デフォルトはルート `"0"`)
* `BOX_COPY_FOLDER`
  * フォルダを別の場所にコピーします。名前の変更も可能です。Boxの非同期コピーには完了までのポーリングで対応します。
  * 入力: `source_folder_id`、`parent_folder_id`(デフォルト `"0"`)、`name`(任意)、`wait_for_completion`(デフォルト `true`)、`max_poll_attempts`(0〜30、デフォルト10)、`poll_interval_ms`(0〜30000、デフォルト1000)
* `BOX_ADD_COLLABORATOR`
  * Boxのファイルまたはフォルダにユーザーやグループをコラボレータとして招待します。
  * 入力: `item_id`、`item_type`(デフォルト `folder`)、`login`(招待するメールアドレス)または `accessible_by_id`(既存のBoxユーザー/グループID)、`accessible_by_type`(`user` または `group`)、`role`(`editor`(デフォルト)、`viewer`、`previewer`、`uploader`、`previewer uploader`、`viewer uploader`、`co-owner`)、`notify`(デフォルト `true`)
* `BOX_CREATE_SHARED_LINK`
  * Boxのファイルまたはフォルダの共有リンクを作成します。
  * 入力: `item_id`、`item_type`(デフォルト `file`)、`access`(任意、`open` / `company` / `collaborators`)、`password`(任意)、`unshared_at`(任意、ISO形式の有効期限日時)、`can_download`(任意)
* `BOX_DELETE_ITEM`
  * Boxのファイル・フォルダを1件または複数件削除します。
  * 入力: `item_id` と `item_type` による単一指定、`ids` と `types` による複数指定、または `{ "id": "...", "type": "file|folder" }` の配列を渡す `items`。`recursive`(デフォルト `false`)を有効にすると空でないフォルダも削除できます。`deleted_items` と `failed_items` を返します。

## 認証

すべてのBoxツールは、Box OAuthアクセストークン(ツールconfigの `token`、シークレットタイプ `BOX_OAUTH`)を必要とします。

[Jinbaのシークレットダッシュボード](https://flow.jinba.io/workspace/secrets)でBoxアカウントを接続してください。`BOX_OAUTH` シークレットが作成され、アクセストークンの有効期限切れ時にはプラットフォームが自動的にトークンを更新します。ツールconfigでは以下の例のようにトークンを参照します。

**注意**: 認証情報は機密情報として扱い、公開リポジトリにコミットしないでください。

## 使用例

### 例: PDFを検索して最初の1件をダウンロード

```yaml theme={null}
- id: search_reports
  name: search_reports
  tool: BOX_SEARCH
  config:
    - name: token
      value: "{{secrets.BOX_OAUTH.access_token}}"
  input:
    - name: query
      value: "月次レポート"
    - name: file_extensions
      value: "pdf"
    - name: limit
      value: 10

- id: download_report
  name: download_report
  tool: BOX_DOWNLOAD_FILE
  config:
    - name: token
      value: "{{secrets.BOX_OAUTH.access_token}}"
  input:
    - name: file_id
      value: "{{steps.search_reports.result.entries[0].id}}"
```

### 例: プロジェクトフォルダを作成してファイルをアップロード・共有

```yaml theme={null}
- id: create_folder
  name: create_folder
  tool: BOX_CREATE_FOLDER
  config:
    - name: token
      value: "{{secrets.BOX_OAUTH.access_token}}"
  input:
    - name: parent_folder_id
      value: "0"
    - name: name
      value: "プロジェクトA 納品物"

- id: upload_file
  name: upload_file
  tool: BOX_UPLOAD_FILE
  config:
    - name: token
      value: "{{secrets.BOX_OAUTH.access_token}}"
  input:
    - name: file
      value: "{{steps.generate_report.result.url}}"
    - name: filename
      value: "deliverable.pdf"
    - name: folder_id
      value: "{{steps.create_folder.result.folder.id}}"

- id: share_file
  name: share_file
  tool: BOX_CREATE_SHARED_LINK
  config:
    - name: token
      value: "{{secrets.BOX_OAUTH.access_token}}"
  input:
    - name: item_id
      value: "{{steps.upload_file.result.file_id}}"
    - name: item_type
      value: "file"
    - name: access
      value: "company"
```

## 注意事項

* **ファイルサイズ制限**: `BOX_DOWNLOAD_FILE` と `BOX_UPLOAD_FILE` は最大50MBのファイルに対応しています。これを超えるファイルはエラーになります(Boxのチャンクアップロード APIには未対応です)。
* **ルートフォルダ**: BoxのルートフォルダのIDは常に `"0"` です。フォルダ関連の入力はデフォルトでルートを指します。
* **ページング**: `BOX_LIST_FILES` はページング情報を含まない簡易一覧を返します(最大1000件)。`total_count` やオフセット方式・マーカー方式(`next_marker`)のページングが必要な場合は `BOX_LIST_FOLDER_ITEMS` を使用してください。
* **検索件数の上限**: `BOX_SEARCH` は1回の呼び出しで最大200件まで返します。
* **フォルダコピーの非同期処理**: 大きなフォルダのコピーはBox側で非同期に処理されることがあります。`BOX_COPY_FOLDER` は完了まで(最大 `max_poll_attempts` 回)ポーリングし、完了しなかった場合は結果に `pending: true` が含まれます。
* **フォルダの削除**: 空でないフォルダは、`BOX_DELETE_ITEM` で `recursive` を `true` にした場合のみ削除できます。
* **コラボレータのロール**: `BOX_ADD_COLLABORATOR` では `owner` ロールを付与できません。コラボレーション作成時にBoxが受け付けるのは上記のロールのみです。