Help Center/ Object Storage Service/ API Reference/ Object APIs/ Symbolic Links/ Creating a Symbolic Link
Updated on 2026-09-11 GMT+08:00
View PDF
Share

Creating a Symbolic Link

Function

This API creates a symbolic link for a specified object. You can access the target object through the symbolic link.

Important Notes

  • If versioning is not enabled, when you create a symbolic link with the same name as an existing symbolic link in the same path, the new link will overwrite the existing one. If versioning is enabled, the existing link will become a historical version, and the newly uploaded symbolic link will become the current version.
  • If versioning is not enabled, when you create a symbolic link with the same name as an existing object (not a link) in the same path, the object will be overwritten by the symbolic link. If versioning is enabled, the existing object will become a historical version, and the newly uploaded symbolic link will become the current version.

Versioning

After versioning is enabled, a target object may have multiple versions (for example, v1 and v2). A symbolic link can only point to the latest version of the target object.

After versioning is enabled, a symbolic link can have multiple versions. Each version has its own version ID and can point to a different target object.

Authorization

To call this API, you must be the bucket owner or have the permission to create a symbolic link. You are advised to use IAM or bucket policies for authorization. For details about OBS authorization methods, see Differences Between OBS Permissions Control Methods.

  • If you use IAM for authorization, you need to use either role/policy-based authorization or identity policy-based authorization and configure the required permissions:
    • If you use role/policy-based authorization (IAM v3 APIs in the old IAM version), you must have the obs:object:PutObject permission. For details, see Creating a Custom IAM Policy.
    • If you use identity policy-based authorization (IAM v5 APIs in the new IAM version), you must have the obs:object:putObject permission, as shown in the following table. For details, see Creating a Custom IAM Identity Policy.

      Action

      Access Level

      Resource Type (*: Required)

      Condition Key

      Alias

      Dependencies

      obs:object:putObject

      Permission_management

      object *

      g:EnterpriseProjectId

      -
      • kms:cmk:create
      • kms:cmk:list
      • kms:cmk:createDataKey
      • functiongraph:function:invokeAsync
      • functiongraph:workflow:invoke
      • smn:topic:publish

      -
      • obs:EpochTime
      • obs:SourceIp
      • obs:TlsVersion
      • obs:CustomDomain
      • obs:x-obs-acl
  • If you use bucket policies for authorization, you must have the obs:object:PutObject permission. For details, see Creating a Custom Bucket Policy.

URI

PUT /

Calling Method

For details, see Calling APIs. Before calling this API, calculate the API signature and add it to the request.

Request Syntax

PUT /objectName?symlink HTTP/1.1
Host: bucketname.obs.region.myhuaweicloud.com 
Date: Date
Authorization: SignatureValue
x-obs-symlink-target: TargetObjectName

URI Parameters

Table 1 URI parameters

Parameter

Mandatory

Type

Description

symlink

Yes

String

Definition

An identifier that marks this API as related to symbolic link objects.

Constraints

When calculating the signature, add /BucketName/ObjectName?symlink to CanonicalizedResource. For details, see Using an Authorization Header.

Range

symlink

Default Value

N/A

Request Headers

Table 2 lists the request headers.

Table 2 Request Headers

Header

Type

Mandatory

Description

x-obs-acl

String

No

Definition

Used to set a predefined ACL when creating a symbolic link.

Constraints

Predefined policies must be displayed in character strings.

Range

  • private
  • public-read
  • public-read-write

For details, see ACLs.

Default Value

private

x-obs-symlink-target

String

Yes

Definition

Target object that the symbolic link points to.

Constraints

The target object name needs to be URL-encoded.

Range

1 to 1,024 characters

Default Value

N/A

x-obs-storage-class

String

No

Definition

Storage class of the symbolic link.

Constraints

You are not advised to set the storage class of the symbolic link to COLD or DEEP_ARCHIVE.

Range

  • STANDARD: Standard storage class
  • WARM: Infrequent Access storage class
  • COLD: Archive storage class
  • DEEP_ARCHIVE: Deep Archive storage class

Default Value

If this parameter is not specified, the symbolic link inherits the storage class of the bucket by default.

x-obs-meta-*

String

No

Definition

Custom metadata of the symbolic link. When creating a symbolic link, you can use a header starting with x-obs-meta- to customize metadata in an HTTP request. The custom metadata will be returned in the response when you retrieve the symbolic link or query its metadata. For details, see Custom Object Metadata.

Constraints

  • A symbolic link can have custom metadata. The total size of all custom metadata cannot exceed 8 KB.
  • The custom metadata keys are case insensitive, but are stored in lowercase in OBS. The key values are case sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.

Range

N/A

Default Value

N/A

Response Syntax

1
2
3
 
HTTP/1.1 status_code
Content-Length: length
Content-Type: type

Response Headers

This response uses common headers. For details, see Table 1.

Sample Request: Creating a Symbolic Link

PUT /link-to-obs.jpg?symlink HTTP/1.1 
User-Agent: curl/7.29.0
Host: bucketname.obs.region.myhuaweicloud.com 
Cache-control: no-cache 
Content-Disposition: attachment;filename=obs_download.jpg 
Date: Tue, 08 Nov 2016 02:00:25 GMT 
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:gYqplLq30dEX7GMi2qFWyjdFsyw=
x-obs-symlink-target: target-object-name
x-obs-storage-class: Standard

Sample Response: Creating a Symbolic Link

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BB7800000164845759E4F3B39ABEE55E
ETag: "d41d8cd98f00b204e9800998ecf8427e"
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSReVRNuas0knI+Y96iXrZA7BLUgj06Z
Date: Wed, 01 Jul 2015 04:13:55 GMT
Content-Length: 0

Sample Request: Setting an ACL When Creating a Symbolic Link

PUT /link-to-obs.jpg?symlink HTTP/1.1 
User-Agent: curl/7.29.0
Host: bucketname.obs.region.myhuaweicloud.com 
Cache-control: no-cache 
Content-Disposition: attachment;filename=obs_download.jpg 
Date: Tue, 08 Nov 2016 02:00:25 GMT 
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:gYqplLq30dEX7GMi2qFWyjdFsyw=
x-obs-symlink-target: target-object-name
x-obs-acl: private

Sample Response: Setting an ACL When Creating a Symbolic Link

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BB7800000164845759E4F3B39ABEE55E
ETag: "d41d8cd98f00b204e9800998ecf8427e"
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSReVRNuas0knI+Y96iXrZA7BLUgj06Z
Date: Wed, 01 Jul 2015 04:13:55 GMT
Content-Length: 0

Sample Request: Setting Custom Metadata When Creating a Symbolic Link

PUT /link-to-obs.jpg?symlink HTTP/1.1 
User-Agent: curl/7.29.0
Host: bucketname.obs.region.myhuaweicloud.com 
Cache-control: no-cache 
Content-Disposition: attachment;filename=obs_download.jpg 
Date: Tue, 08 Nov 2016 02:00:25 GMT 
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:gYqplLq30dEX7GMi2qFWyjdFsyw=
x-obs-symlink-target: target-object-name
Content-Type:application/zip
x-obs-meta-test:meta

Sample Response: Setting Custom Metadata When Creating a Symbolic Link

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BB7800000164845759E4F3B39ABEE55E
ETag: "d41d8cd98f00b204e9800998ecf8427e"
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSReVRNuas0knI+Y96iXrZA7BLUgj06Z
Date: Wed, 01 Jul 2015 04:13:55 GMT
Content-Length: 0
Parent Topic: Symbolic Links