Copying an Object

Function

This API copies an object stored in OBS to another path. You can copy an object of up to 5 GB in a single operation.

You can use this API to create a copy for an object in a specified bucket.

Restrictions

To copy an object, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
You must have the read permission for the source object.
The object copy request contains the information about the source bucket and object to be copied in the header field. The message body cannot be contained.
Cross-bucket replication in the same region is supported, but cross-region replication is not supported.
The target object size ranges from 0 to 5 GB. If the source object size exceeds 5 GB, you must use a multipart copying API by referring to Performing a Multipart Copy.
If the source object is in the Cold storage class, you must restore it first.

Method

ObsClient->copyObject(array $parameter)

Request Parameters

**Table 1** List of request parameters
Parameter	Type	Mandatory (Yes/No)	Description
Bucket	string	Yes	Definition: Destination bucket name. Restrictions: A bucket name must be unique across all accounts and regions. A bucket name: Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed. Cannot be formatted as an IP address. Cannot start or end with a hyphen (-) or period (.). Cannot contain two consecutive periods (..), for example, my..bucket. Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket. If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request. Default value: None
Key	string	Yes	Definition: Target object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path of the object that does not contain the bucket name. Value range: The value must contain 1 to 1,024 characters. Default value: None
CopySource	string	Yes	Definition: Parameter used to specify the source bucket, source object, and source object version ID (optional). Restrictions: Format: Source bucket name/Source object name?versionId=Source object version ID Default value: None
ACL	string	No	Definition: ACL specified for the object. You can use either a pre-defined or a user-defined ACL. Value range: To use a pre-defined ACL, see Table 2 for the available options. Default value: AccessControlList.REST_CANNED_PRIVATE
StorageClass	string	No	Definition: Object storage class. Value range: See Table 3. Default value: None. If this parameter is not specified, the storage class of the bucket is used as that of the object.
CopySourceIfMatch	string	No	Definition: If the ETag of the source object is the same as the one specified by this parameter, it is copied. Otherwise, an error is returned. Default value: None
CopySourceIfNoneMatch	string	No	Definition: If the ETag of the source object is different from the one specified by this parameter, it is copied. Otherwise, an error is returned. Default value: None
CopySourceIfUnmodifiedSince	string or \DateTime	No	Definition: If the source object has not been modified since the specified time, it is copied. Otherwise, an exception is thrown. Default value: None
CopySourceIfModifiedSince	string or \DateTime	No	Definition: If the source object has been modified since the specified time, it is copied. Otherwise, an exception is thrown. Default value: None
CacheControl	string	No	Definition: Rewrites the Cache-Control header in the response. Default value: None
ContentDisposition	string	No	Definition: Rewrites the Content-Disposition header in the response. Default value: None
ContentEncoding	string	No	Definition: Rewrites the Content-Encoding header in the response. Default value: None
ContentLanguage	string	No	Definition: Rewrites the Content-Language header in the response. Default value: None
ContentType	string	No	Definition: Rewrites the Content-Type header in the response. Default value: None
Expires	string	No	Definition: Rewrites the Expires header in the response. Default value: None
MetadataDirective	string	No	Definition: Policy for copying the source object's attributes. Value range: See Table 4. Default value: None
Metadata	associative array	No	Definition: Custom metadata of the target object. You can add a header starting with x-obs-meta- in the request to define metadata. The custom metadata will be returned in the response when you retrieve the object or query the object metadata. Restrictions: The custom metadata cannot exceed 8 KB in total. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values. 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. Default value: None
WebsiteRedirectLocation	string	No	Definition: If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL. To another object in the same bucket: WebsiteRedirectLocation:/anotherPage.html To an external URL: WebsiteRedirectLocation:http://www.example.com/ OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation. Restrictions: The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB. OBS only supports redirection for objects in the root directory of a bucket. Default value: None

**Table 2** Pre-defined ACL
Access Method	Type	Description
ObsClient::AclPrivate	string	Private read and write.
ObsClient::AclPublicRead	string	Public read.
ObsClient::AclPublicReadWrite	string	Public read and write.
ObsClient::AclPublicReadDelivered	string	Public read on a bucket as well as the objects in the bucket.
ObsClient::AclPublicReadWriteDelivered	string	Public read and write on a bucket as well as the objects in the bucket.

**Table 3** Storage classes
Access Method	Type	Description
ObsClient::StorageClassStandard	string	Standard storage class.
ObsClient::StorageClassWarm	string	Warm storage class.
ObsClient::StorageClassCold	string	Cold storage class.

**Table 4** Metadata replication policies
Access Method	Type	Description
ObsClient::CopyMetadata	string	Copies metadata.
ObsClient::ReplaceMetadata	string	Replaces metadata.

Responses

**Table 5** Responses
Parameter	Type	Description
HttpStatusCode	integer	Definition: HTTP status code. Value range: A status code is a group of digits that can be 2xx (indicating successes) or 4xx or 5xx (indicating errors). It indicates the status of a response. Default value: None
Reason	string	Definition: Reason description. Default value: None
RequestId	string	Definition: Request ID returned by the OBS server. Default value: None
ETag	string	Definition: Base64-encoded, 128-bit MD5 value of an object. ETag is the unique identifier of the object contents and is used to determine whether the contents of an object are changed. For example, if the ETag value is A when an object is uploaded and is B when the object is downloaded, this indicates the contents of the object are changed. The ETag reflects changes only to the contents of an object, not its metadata. Objects created by the upload and copy operations have unique ETags after being encrypted using MD5. Restrictions: If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object. Value range: The value must contain 32 characters. Default value: None
LastModified	string	Definition: Time when the target object was last modified, in UTC. Value range: UTC time Default value: None
VersionId	string	Definition: Version ID of the target object. Value range: The value must contain 32 characters. Default value: None
CopySourceVersionId	string	Definition: Version ID of the source object. Value range: The value must contain 32 characters. Default value: If versioning is not enabled for the source bucket, this parameter is left blank.

Copying an Object in Simple Mode

Sample code:

// Import the dependency library.
require 'vendor/autoload.php';
// Import the SDK code library during source code installation.
// require 'obs-autoloader.php';
// Declare the namespace.
use Obs\ObsClient;
// Create an instance of ObsClient.
$obsClient = new ObsClient ( [ 
      //Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
      //Obtain an AK/SK pair on the management console.
      'key' => getenv('ACCESS_KEY_ID'),
      'secret' => getenv('SECRET_ACCESS_KEY'),
      'endpoint' => 'https://your-endpoint',
      'signature' => 'obs'
] );

$resp = $obsClient->copyObject ( [ 
      'Bucket' => 'destbucketname',
      'Key' => 'destobjectname',
      'CopySource' => 'sourcebucketname/sourceobjectname'
] );
printf ( "RequestId:%s\n", $resp ['RequestId'] );

Use the CopySource parameter to specify the information about the source object.

Rewriting Object Properties

Sample code:

// Import the dependency library.
require 'vendor/autoload.php';
// Import the SDK code library during source code installation.
// require 'obs-autoloader.php';
// Declare the namespace.
use Obs\ObsClient;
// Create an instance of ObsClient.
$obsClient = new ObsClient ( [ 
      //Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
      //Obtain an AK/SK pair on the management console.
      'key' => getenv('ACCESS_KEY_ID'),
      'secret' => getenv('SECRET_ACCESS_KEY'),
      'endpoint' => 'https://your-endpoint',
      'signature' => 'obs'
] );

$resp = $obsClient->copyObject ( [ 
       'Bucket' => 'destobjectname',
       'Key' => 'destobjectname',
       'CopySource' => 'sourcebucketname/soureobjectname',
       'ContentType' => 'image/jpeg',
       'StorageClass' => ObsClient::StorageClassWarm,
       'Metadata' => ['property' => 'property-value'],
       'MetadataDirective' => ObsClient::ReplaceMetadata
] );
printf ( "RequestId:%s\n", $resp ['RequestId'] );

Use the Metadata parameter to specify the object's customized metadata to be rewritten and the MetadataDirective parameter to specify the rewrite mode, which can be ObsClient::ReplaceMetadata (rewrite) or ObsClient::CopyMetadata (copy from the source object).

Copying an Object by Specifying Conditions

When copying an object, you can specify one or more restriction conditions. If the conditions are met, the object will be copied. Otherwise, an exception will be thrown.

You can set the following conditions:

Parameter	Description	Format
CopySourceIfModifiedSince	Copies the source object if it has been modified since the specified time; otherwise, an exception is thrown.	This parameter must conform to the HTTP time format specified in http://www.ietf.org/rfc/rfc2616.txt.
CopySourceIfUnmodifiedSince	Copies the source object if it has not been modified since the specified time; otherwise, an exception is thrown.	This parameter must conform to the HTTP time format specified in http://www.ietf.org/rfc/rfc2616.txt.
CopySourceIfMatch	Copies the source object if its ETag is the same as the one specified by this parameter; otherwise, an exception is thrown.	Character string
CopySourceIfNoneMatch	Copies the source object if its ETag is different from the one specified by this parameter; otherwise, an exception is thrown.	Character string

The ETag of the source object is the MD5 check value of the source object.
If the object copy request includes CopySourceIfUnmodifiedSince, CopySourceIfMatch, CopySourceIfModifiedSince, or CopySourceIfNoneMatch, and the specified condition is not met, the copy will fail and an exception will be thrown with HTTP status code 412 Precondition Failed returned.
CopySourceIfModifiedSince and CopySourceIfNoneMatch can be used together. So do CopySourceIfUnmodifiedSince and CopySourceIfMatch.

Sample code:

// Import the dependency library.
require 'vendor/autoload.php';
// Import the SDK code library during source code installation.
// require 'obs-autoloader.php';
// Declare the namespace.
use Obs\ObsClient;
// Create an instance of ObsClient.
$obsClient = new ObsClient ( [ 
      //Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
      //Obtain an AK/SK pair on the management console.
      'key' => getenv('ACCESS_KEY_ID'),
      'secret' => getenv('SECRET_ACCESS_KEY'),
      'endpoint' => 'https://your-endpoint',
      'signature' => 'obs'
] );

$resp = $obsClient->copyObject ( [ 
       'Bucket' => 'destobjectname',
       'Key' => 'destobjectname',
       'CopySource' => 'sourcebucketname/soureobjectname',
       'CopySourceIfModifiedSince' => 'Thu, 31 Dec 2015 16:00:00 GMT',    
       'CopySourceIfNoneMatch' => 'none-match-etag'
] );
printf ( "RequestId:%s\n", $resp ['RequestId'] );

Rewriting an Object ACL

Sample code:

// Import the dependency library.
require 'vendor/autoload.php';
// Import the SDK code library during source code installation.
// require 'obs-autoloader.php';
// Declare the namespace.
use Obs\ObsClient;
// Create an instance of ObsClient.
$obsClient = new ObsClient ( [ 
      //Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
      //Obtain an AK/SK pair on the management console.
      'key' => getenv('ACCESS_KEY_ID'),
      'secret' => getenv('SECRET_ACCESS_KEY'),
      'endpoint' => 'https://your-endpoint',
      'signature' => 'obs'
] );

$resp = $obsClient->copyObject ( [ 
       'Bucket' => 'destobjectname',
       'Key' => 'destobjectname',
       'CopySource' => 'sourcebucketname/soureobjectname',
       // Rewrite the object ACL to public read.
       'ACL' => ObsClient::AclPublicRead
] );
printf ( "RequestId:%s\n", $resp ['RequestId'] );

Use the ACL parameter to rewrite the object ACL.

Parent topic:Object Management

Previous topic: Deleting Objects

Next topic: Temporarily Authorized Access

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

For any further questions, feel free to contact us through the chatbot.

Chatbot