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のシークレットダッシュボードでBoxアカウントを接続してください。BOX_OAUTH シークレットが作成され、アクセストークンの有効期限切れ時にはプラットフォームが自動的にトークンを更新します。ツールconfigでは以下の例のようにトークンを参照します。

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

​

使用例

​

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

- 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}}"

​

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

- 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が受け付けるのは上記のロールのみです。