PutSymlink

API description

The PutSymlink API is used to create a symlink for an existing target object (referred to as the "target object" in this document) in BOS. The target object can be accessed through the symlink.

Note:

• Symlink files and target objects can reside in different buckets within the same region. Setting x-bce-symlink-bucket indicates cross-bucket symlink creation, where the x-bce-symlink-bucket specifies the bucket containing the target object.
• Symlinks can now be created for object files in standard storage, infrequent access storage, cold storage, and archive storage. However, symlink files do not support the ARCHIVE storage class. If the ARCHIVE class is specified or omitted while the bucket's default storage class is ARCHIVE, a CODE_INVALID_ARGUMENT error will be returned.
• When this API is called to create a symlink, it does not verify whether the target file exists or whether there is permission to access it. However, when the GetObject API is called via the symlink, it checks if the user has read permission for both the symlink and the target file, as well as whether the target file exists.
• Creating a symlink requires the appropriate write permission.
• If the "x-bce-forbid-overwrite" header is not specified and there is an existing object file with the same name as the symlink, the existing object will be overwritten by default during symlink creation.
• Secondary symlinks are not supported. While no checks are performed when creating a secondary symlink, users will not be able to access the target object data through it.
• To download a target file via a symlink, read permissions are required for both the symlink and the target file.

Request

• Request syntax

1PUT /<ObjectName>?symlink HTTP/1.1
2Host: <BucketName>.bj.bcebos.com
3Date: <Date>
4Authorization: <AuthorizationString>
5x-bce-symlink-target: <TargetObjectName>
6x-bce-symlink-bucket: <TargetBucketName>
7x-bce-forbid-overwrite: false

• Request parameters

  No special parameters

• Request headers

  Name	Types	Description	Required or not
  x-bce-symlink-target	String	The naming rules for the target file of a symlink are the same as those for objects. However, the target file of a symlink cannot itself be a symlink file.	Yes
  x-bce-symlink-bucket	String	Specify the bucket where the symlink target file resides. If not specified, the created symlink and its target file will reside in the same bucket.	No
  x-bce-forbid-overwrite	String	Specify whether to overwrite an object with the same name when creating a symlink. By default, if x-bce-forbid-overwrite is not specified, overwriting is allowed. If set to true, overwriting is prohibited; if set to false, overwriting is allowed.	No
  x-bce-meta-*	String	User-defined meta	No
  x-bce-storage-class	String	Specify the storage class for the symlink file. STANDARD represents standard storage, STANDARD_IA represents infrequent access storage, and COLD represents cold storage. If not specified, the symlink file will default to the bucket's storage class. Symlink files are not compatible with the ARCHIVE storage class.	No
  x-bce-acl	String	This header is supported by CannedACL. Users can set permissions for symlinks with values such as private or public-read.	No
  x-bce-grant-read	String	This header is supported by CannedACL. Users can configure read permissions for symlinks, supporting multiple IDs separated by commas.	No
  x-bce-grant-full-control	String	This header is supported by CannedACL. Users can assign FULL_CONTROL permissions for symlinks, supporting multiple IDs separated by commas.	No

Response

• Response headers

  Name	Types	Description
  ETag	String	The HTTP protocol entity tag of symlink target object

• Response element

  No special elements

Example

• Request example

1PUT /<ObjectName>?symlink HTTP/1.1
2Host: <BucketName>.bj.bcebos.com
3Date: <Date>
4Authorization: <AuthorizationString>
5x-bce-symlink-target: <TargetObjectName>
6x-bce-forbid-overwrite: false
7x-bce-grant-read:id="e13bxxxxxxxxxxxxxxxxxxxxxxxx87b8",id="8c47xxxxxxxxxxxxxxxxxxxxxxxx4c94"

• Response example

1HTTP/1.1 200 OK
2x-bce-request-id: 4db4b34d-653d-4d9a-b49b-3049ca786409
3Date: Wed, 31 May 2018 08:34:40 GMT
4ETag: "1b2cf535f27731c974343645a3985328"
5Server: BceBos