コラボレーションを更新

put

https://api.box.com/2.0

/collaborations/:collaboration_id

コラボレーションを更新します。項目の所有者を変更したり、コラボレーションへの招待を承認したりする場合に使用します。

リクエスト

authorizationbearer [ACCESS_TOKEN]

content-typeapplication/json

パスパラメータ

collaboration_id stringパス内必須

例"1234"

コラボレーションのID

リクエスト本文

can_view_path boolean本文内省略可能

例true

招待されたユーザーが招待に関連付けられているフォルダへの親パス全体を見ることができるかどうかを示します。招待されたユーザーには親フォルダ内の権限が付与されないため、自身が参加しているコラボレーションに関係しないコンテンツを閲覧することはできません。

これにより、招待されたユーザーの [すべてのファイル] ページの読み込みに必要な時間が有意に増加することに注意してください。can_view_pathが有効になっているコラボレーションの数を1ユーザーあたり1,000に制限することをお勧めします。

can_view_pathがtrueに設定されているコラボレータを招待できるのは、所有者と共同所有者のみです。

can_view_pathは、フォルダのコラボレーションのみに使用できます。

expires_at string / date-time本文内省略可能

例"2019-08-29T23:59:00-07:00"

コラボレーションの有効期限を更新します。この日付になると、項目から自動的にコラボレーションが削除されます。

この機能が動作するのは、管理コンソールの [Enterprise設定] で [招待したコラボレータを自動的に削除する] の [フォルダの所有者に有効期限の延長を許可する] の設定が有効になっている場合のみです。この設定が有効になっていない場合、コラボレーションに有効期限を設定できず、このフィールドの値によってエラーが返されます。

さらに、コラボレーションに有効期限を指定できるのは、[招待したコラボレータを自動的に削除する] の設定を有効にした後に作成した場合のみです。

role string本文内必須

例"editor"

付与されるアクセスレベル。

次の値のいずれか1つ: editor,viewer,previewer,uploader,previewer uploader,viewer uploader,co-owner,owner

status string本文内省略可能

例"accepted"

コラボレーション招待のステータスとして、保留中 (pending)、承認、拒否のいずれかを設定します。

次の値のいずれか1つ: pending,accepted,rejected

レスポンス

200application/jsonCollaboration

所有者が変わっていない限り、更新されたコラボレーションオブジェクトを返します。

204application/jsonCollaboration

ロールがownerに変更されるとコラボレーションが削除されて、新しいコラボレーションが作成されます。古いコラボレーションのownerは、新しいコラボレーションのco-ownerになります。

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

認証済みユーザーにコラボレーションを更新するための適切な権限がない場合にエラーを返します。

さらに、このエラーは、企業の管理ダッシュボードで [招待したコラボレータを自動的に削除する] の [フォルダの所有者に有効期限の延長を許可する] の設定が有効になっていないコラボレーションのexpires_atフィールドを更新しようとすると発生する可能性があります。

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

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

put

コラボレーションを更新

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

ログイン

リクエストの例

cURL

curl -i -X PUT "https://api.box.com/2.0/collaborations/1234" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "role": "viewer"
     }'

.NET

BoxCollaborationRequest requestParams = new BoxCollaborationRequest()
{
    Id = "12345",
    Role = "viewer"
};
BoxCollaboration collab = await client.CollaborationsManager.EditCollaborationAsync(requestParams);

Java

// Accept all pending collaborations
Collection<BoxCollaboration.Info> pendingCollaborations = BoxCollaboration.getPendingCollaborations(api);
for (BoxCollaboration.Info collabInfo : pendingCollaborations) {
    collabInfo.setStatus(BoxCollaboration.Status.ACCEPTED);
    collabInfo.getResource().updateInfo(collabInfo);
}

Python

from boxsdk.object.collaboration import CollaborationRole

collaboration_update = {'role': CollaborationRole.EDITOR, 'can_view_path': False}
collaboration = client.collaboration(collab_id='12345')
updated_collaboration = collaboration.update_info(data=collaboration_update)

Node

client.collaborations.update('11111', {role: client.collaborationRoles.PREVIEWER})
	.then(collaboration => {
		/* collaboration -> {
			type: 'collaboration',
			id: '11111',
			created_by: 
			{ type: 'user',
				id: '22222',
				name: 'Inviting User',
				login: 'inviter@example.com' },
			created_at: '2015-11-03T18:36:37-08:00',
			modified_at: '2016-11-16T21:01:19-08:00',
			expires_at: null,
			status: 'accepted',
			accessible_by: 
			{ type: 'user',
				id: '33333',
				name: 'Collaborated User',
				login: 'collaborator@example.com' },
			role: 'previewer',
			acknowledged_at: '2015-11-03T18:36:37-08:00',
			item: 
			{ type: 'folder',
				id: '44444',
				sequence_id: '1',
				etag: '1',
				name: 'Collaborated Folder' } }
	 */
	});

iOS

client.collaborations.update(collaborationId: "12345", role: .viewer) { (result: Result<Collaboration, BoxSDKError>) in
    guard case let .success(collaboration) = result else {
        print("Error updating collaboration")
        return
    }

    print("Updated collaboration")
}

レスポンスの例

{
  "id": "12345678",
  "type": "collaboration",
  "acceptance_requirements_status": {
    "strong_password_requirement": {
      "enterprise_has_strong_password_required_for_external_users": true,
      "user_has_strong_password": true
    },
    "terms_of_service_requirement": {
      "is_accepted": true,
      "terms_of_service": {
        "id": "11446498",
        "type": "terms_of_service"
      }
    },
    "two_factor_authentication_requirement": {
      "enterprise_has_two_factor_auth_enabled": true,
      "user_has_two_factor_authentication_enabled": true
    }
  },
  "accessible_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "acknowledged_at": "2012-12-12T10:55:20-08:00",
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": [
    {
      "id": 33224412
    },
    {
      "type": "user"
    },
    {
      "login": "dylan@example.com"
    },
    {
      "name": "Dylan Smith"
    }
  ],
  "expires_at": "2012-12-26T10:53:43-08:00",
  "invite_email": "john@example.com",
  "item": {
    "id": "12345",
    "type": "file",
    "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": "Contract for Q1 renewal",
    "etag": "1",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "item_status": "active",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "login": "ceo@example.com",
      "name": "Aaron Levie"
    },
    "name": "Contract.pdf",
    "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
    },
    "purged_at": "2012-12-12T10:53:43-08:00",
    "sequence_id": "3",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
    "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,
    "trashed_at": "2012-12-12T10:53:43-08:00"
  },
  "modified_at": "2012-12-12T10:53:43-08:00",
  "role": "editor",
  "status": "accepted"
}