フォルダを更新

put

https://api.box.com/2.0

/folders/:folder_id

フォルダを更新します。フォルダの移動、共有リンクの作成、コラボレーションの更新といった目的にも使用できます。

関連するガイド

リクエスト

AuthorizationBearer [ACCESS_TOKEN]

Content-Typeapplication/json

パスパラメータ

folder_id stringパス内必須

例"12345"

フォルダを表す一意の識別子。

フォルダIDを確認するには、ウェブアプリケーションでこのフォルダにアクセスして、URLからIDをコピーします。たとえば、URLがhttps://*.app.box.com/folder/123の場合、folder_idは123です。

Boxアカウントのルートフォルダは常にID 0で表されます。

クエリパラメータ

fields string arrayクエリ内省略可能

例id,type,name

レスポンスに含める属性のカンマ区切りリスト。このパラメータを使用すると、標準のレスポンスには通常含まれないフィールドをリクエストできます。

このパラメータを指定すると、明示的に指定しない限り標準フィールドはレスポンスに含まれず、リクエストしたフィールドのほかには、Mini版の表示のフィールドしか返されないことに注意してください。

リクエスト本文

can_non_owners_invite boolean本文内省略可能

例true

フォルダの所有者ではないユーザーがそのフォルダに新しいコラボレータを招待できるかどうかを指定します。

can_non_owners_view_collaborators boolean本文内省略可能

例true

このフォルダの所有者ではないコラボレータがこのフォルダのその他のコラボレータを表示できないように制限します。

この制限を有効にした場合は、所有者ではないユーザーが新しいコラボレータを招待することも制限されます。

このフィールドをfalseに設定する場合は、can_non_owners_invite_collaboratorsもfalseに設定する必要があります (まだ設定されていない場合)。

collections object array本文内省略可能

このフォルダをメンバーとして追加するコレクションの配列。現時点では、favoritesコレクションのみがサポートされています。

コレクションのIDを取得するには、すべてのコレクションのリストを取得エンドポイントを使用します。

空の配列[]またはnullを渡すと、すべてのコレクションからこのフォルダが削除されます。

[collections].id string本文内省略可能

例"11446498"

このオブジェクトの一意の識別子

[collections].type string本文内省略可能

例"file"

このオブジェクトのタイプ

description string本文内省略可能

例"Legal contracts for the new ACME deal"最大長256

このフォルダの説明 (省略可)

folder_upload_email object本文内

このオブジェクトを設定するとアップロードメールアドレスが有効になります。

ユーザーはこのメールアドレスを使用することにより、メールを介してフォルダにファイルを直接アップロードできます。

値をnullに設定するとアップロードメールアドレスは無効になります。

folder_upload_email.access string本文内省略可能

例"open"

このパラメータが設定されている場合、ユーザーは、このフォルダに対して自動的に作成されたメールアドレスにメールでファイルを送信できます。

メールアドレスを作成するには、フォルダを作成するとき、または更新するときにこのプロパティを設定します。

collaboratorsに設定すると、コラボレータの登録済みメールアドレスからのメールのみが受け入れられます。これには、ユーザーが登録しているすべてのメールエイリアスも含まれます。

openに設定すると、どのメールアドレスからのメールでも受け入れられます。

次の値のいずれか1つ: open,collaborators

is_collaboration_restricted_to_enterprise boolean本文内省略可能

例true

このフォルダへの招待を社内のユーザーのみに限定するかどうかを指定します。既存のコラボレーションには影響しません。

name string本文内省略可能

例"New Folder"

このフォルダの新しい名前 (省略可)。

parent object本文内

このフォルダの親フォルダ。フォルダを移動したり、ごみ箱からフォルダを復元したりするときに使用します。

parent.id string本文内省略可能

例"0"

新しい親フォルダのID

shared_link object本文内

フォルダの共有リンクの作成を有効にします。

shared_link.access string本文内省略可能

例"open"

共有リンクのアクセスレベル。これは、リンクを知っている全員 (open)、会社内のユーザーのみ (company)、フォルダに招待されたユーザーのみ (collaborators) のいずれかに制限できます。

設定しなかった場合、このフィールドは、デフォルトで、企業の管理者が指定したアクセスレベルになります。このデフォルトの設定で共有リンクを作成するには、{ "shared_link": {} }のように、accessフィールドを指定せずにshared_linkオブジェクトを渡します。

companyアクセスレベルは、有料アカウントのみで使用できます。

次の値のいずれか1つ: open,company,collaborators

shared_link.password string本文内省略可能

例"do-not-use-this-password"

共有リンクへのアクセスに必要なパスワード。パスワードをnullに設定するとパスワードが削除されます。

パスワードはaccessがopenに設定されている場合にのみ設定できます。

shared_link.permissions object本文内

permissions.can_download boolean本文内省略可能

例true

共有リンクからのファイルのダウンロードが許可されているかどうか。accessがopenまたはcompanyに設定されている場合にのみ設定できます。

shared_link.unshared_at string / date-time本文内省略可能

例"2012-12-12T10:53:43-08:00"

この共有リンクの有効期限が切れる日時のタイムスタンプ。このフィールドを設定できるのは、有料アカウントを持つユーザーのみです。

shared_link.vanity_name string本文内省略可能

例"my-shared-link"

共有リンクのURLで使用するカスタムバニティ名を定義します (例: https://app.box.com/v/my-shared-link)。

バニティURLは通常の共有リンクよりもかなり推測しやすいため、機密性の高いコンテンツを共有する場合は、カスタムURLを使用しないでください。

sync_state string本文内省略可能

例"synced"

フォルダをユーザーのデバイスに同期する必要があるかどうかを指定します。これはBox Sync (廃止済み) で使用され、Box Driveでは使用されません。

次の値のいずれか1つ: synced,not_synced,partially_synced

tags string array本文内省略可能

例["approved"]

この項目のタグ。これらのタグはBoxウェブアプリおよびモバイルアプリで項目の横に表示されます。

タグを追加または削除するには、項目の現在のタグを取得して変更してから、このフィールドを更新します。

タグの数は、1項目あたり100個までに制限され、一意のタグは会社あたり10,000個までに制限されます。

リクエストヘッダー

if-match stringヘッダー内省略可能

例"1"

変更を加える前にこの項目が最近変更されていないことを確認します。

その項目の最後に認識されたetag値をこのヘッダーに渡すと、それ以降に項目が変更されている場合、エンドポイントは412 Precondition Failedを返して失敗します。

レスポンス

200application/jsonフォルダ (Full)

更新されたフォルダのフォルダオブジェクトを返します

使用可能なすべてのフィールドがデフォルトで返されるとは限りません。特定のフィールドを明示的にリクエストするには、fieldsクエリパラメータを使用します。

この呼び出しは同期的に復帰します。これは、すべての子孫に大量の項目が含まれているフォルダを移動する場合にも当てはまります。つまり、非常に大きいフォルダの場合は、この呼び出しが復帰するまでに数分または数時間かかる場合があります。

400application/jsonクライアントエラー

一部のパラメータが指定されていないか無効な場合、またはフォルダロックにより移動操作ができなくなっている場合はエラーを返します。

bad_request - パラメータが指定されていないか誤っている場合に返されます。このエラーは、アクセスタイプがopenの共有リンクにパスワードが設定されている場合にも発生します。
item_name_too_long - フォルダ名が長すぎる場合に返されます。
item_name_invalid - フォルダ名に無効な文字が含まれている場合に返されます。

403application/jsonクライアントエラー

ユーザーにこのアクションを実行するためのアクセス権限がない場合はエラーを返します。

access_denied_insufficient_permissions: ユーザーにフォルダまたは親フォルダへのアクセス権限がない場合か、移動できないようにフォルダロックが適用されているのにフォルダが移動されている場合に返されます。
insufficient_scope: アプリケーションにフォルダを更新するための適切なスコープがない場合に返されます。Boxに格納されているすべてのファイルとフォルダに対して読み取りと書き込みを行えるようにアプリケーションが設定されていることを確認してください。
forbidden: ユーザーが他のユーザーに対してこのアクションを実行することが許可されていない場合に返されます。これには、アクセスレベルがcompanyに設定されている共有リンクを無料アカウントで作成するアクションも含まれます。
forbidden_by_policy: 情報バリアの制限によりフォルダのコピーが禁止されている場合に返されます。

リクエスト本文に含まれる操作が多すぎる場合にエラーを返します。

operation_limit_exceeded: ユーザーがリクエスト本文でparent.idに加えてパラメータを渡したときに返されます。このエンドポイントに対する呼び出しは分割する必要があります。最初の呼び出しにはparent.idだけを含める必要があります。次の呼び出しには他のパラメータを含めることができます。

404application/jsonクライアントエラー

フォルダまたは親フォルダが見つからないか、認証済みユーザーがどちらのフォルダにもアクセスできない場合はエラーを返します。

not_found - 認証済みユーザーがフォルダまたは親フォルダにアクセスできない場合に返されます。

409application/jsonクライアントエラー

operation_blocked_temporary: 別の移動、コピー、削除、または復元操作が進行中であるために宛先フォルダまたは元のフォルダがロックされている場合に返されます。

操作は後で再試行することができます。
item_name_in_use: この名前のフォルダがすでに親フォルダ内に存在している場合に返されます。

412application/jsonクライアントエラー

If-Matchヘッダーがフォルダの現在のetag値と一致しない場合はエラーを返します。これは、フォルダが前回リクエストされたときから変更されていることを示します。

503application/jsonクライアントエラー

操作の処理時間が60秒を超えるとエラーを返します。このレスポンスが返された後も操作は続行されます。

defaultapplication/jsonクライアントエラー

予期しないクライアントエラー。

put

フォルダを更新

このドキュメント内で一部のAPIを試せるようになりました。

ログイン

リクエストの例

cURL

curl -i -X PUT "https://api.box.com/2.0/folders/4353455" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "New folder name"
     }'

.NET

var requestParams = new BoxFolderRequest()
{
    Id = "11111",
    Name = "My Documents (2017)"
};
BoxFolder updatedFolder = await client.FoldersManager.UpdateInformationAsync(requestParams);

Java

BoxFolder folder = new BoxFolder(api, "id");
BoxFolder.Info info = folder.new Info();
info.setName("New Name");
folder.updateInfo(info);

Python

updated_folder = client.folder(folder_id='22222').update_info(data={
    'name': '[ARCHIVED] Planning documents',
    'description': 'Old planning documents',
})
print('Folder updated!')

Node

client.folders.update('11111', {name: 'Pictures from 2017'})
    .then(updatedFolder => {
        /* updatedFolder -> {
            type: 'folder',
            id: '11111',
            sequence_id: '1',
            etag: '1',
            name: 'Pictures from 2017',
            created_at: '2012-12-12T10:53:43-08:00',
            modified_at: '2012-12-12T11:15:04-08:00',
            description: 'Some pictures I took',
            size: 629644,
            path_collection: 
            { total_count: 1,
                entries: 
                [ { type: 'folder',
                    id: '0',
                    sequence_id: null,
                    etag: null,
                    name: 'All Files' } ] },
            created_by: 
            { type: 'user',
                id: '22222',
                name: 'Example User'
                login: 'user@example.com' },
            modified_by: 
            { type: 'user',
                id: '22222',
                name: 'Example User',
                login: 'user@example.com' },
            owned_by: 
            { type: 'user',
                id: '22222',
                name: 'Example User',
                login: 'user@example.com' },
            shared_link: null,
            parent: 
            { type: 'folder',
                id: '0',
                sequence_id: null,
                etag: null,
                name: 'All Files' },
            item_status: 'active',
            item_collection: 
            { total_count: 1,
                entries: 
                [ { type: 'file',
                    id: '33333',
                    sequence_id: '3',
                    etag: '3',
                    sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc',
                    name: 'tigers.jpeg' } ],
                offset: 0,
                limit: 100 } }
        */
    });

レスポンスの例

{
  "id": "12345",
  "type": "folder",
  "allowed_invitee_roles": [
    "editor"
  ],
  "allowed_shared_link_access_levels": [
    "open"
  ],
  "can_non_owners_invite": true,
  "can_non_owners_view_collaborators": true,
  "classification": {
    "color": "#FF0000",
    "definition": "Content that should not be shared outside the company.",
    "name": "Top Secret"
  },
  "content_created_at": "2012-12-12T10:53:43-08:00",
  "content_modified_at": "2012-12-12T10:53:43-08:00",
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "description": "Legal contracts for the new ACME deal",
  "etag": "1",
  "folder_upload_email": {
    "access": "open",
    "email": "upload.Contracts.asd7asd@u.box.com"
  },
  "has_collaborations": true,
  "is_accessible_via_shared_link": true,
  "is_collaboration_restricted_to_enterprise": true,
  "is_externally_owned": true,
  "item_collection": {
    "entries": [
      {
        "id": "12345",
        "etag": "1",
        "type": "file",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        }
      }
    ],
    "limit": 1000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "total_count": 5000
  },
  "item_status": "active",
  "metadata": {
    "enterprise_27335": {
      "marketingCollateral": {
        "$canEdit": true,
        "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
        "$parent": "folder_59449484661",
        "$scope": "enterprise_27335",
        "$template": "marketingCollateral",
        "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
        "$typeVersion": 2,
        "$version": 1
      }
    }
  },
  "modified_at": "2012-12-12T10:53:43-08:00",
  "modified_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "name": "Contracts",
  "owned_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "parent": {
    "id": "12345",
    "type": "folder",
    "etag": "1",
    "name": "Contracts",
    "sequence_id": "3"
  },
  "path_collection": {
    "entries": [
      {
        "id": "12345",
        "etag": "1",
        "type": "folder",
        "name": "Contracts",
        "sequence_id": "3"
      }
    ],
    "total_count": 1
  },
  "permissions": {
    "can_delete": true,
    "can_download": true,
    "can_invite_collaborator": true,
    "can_rename": true,
    "can_set_share_access": true,
    "can_share": true,
    "can_upload": true
  },
  "purged_at": "2012-12-12T10:53:43-08:00",
  "sequence_id": "3",
  "shared_link": {
    "access": "open",
    "download_count": 3,
    "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
    "effective_access": "company",
    "effective_permission": "can_download",
    "is_password_enabled": true,
    "permissions": {
      "can_download": true,
      "can_edit": false,
      "can_preview": true
    },
    "preview_count": 3,
    "unshared_at": "2018-04-13T13:53:23-07:00",
    "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
    "vanity_name": "my_url",
    "vanity_url": "https://acme.app.box.com/v/my_url/"
  },
  "size": 629644,
  "sync_state": "synced",
  "tags": [
    "approved"
  ],
  "trashed_at": "2012-12-12T10:53:43-08:00",
  "watermark_info": {
    "is_watermarked": true
  }
}