copy_part ( $source, $dest, $upload_id, $part_number, $opt )
Since Amazon S3’s standard copy_object()
operation only supports copying objects that are smaller than
5 GB, the ability to copy large objects (greater than 5 GB) requires the use of “Multipart Copy”.
Copying large objects requires the developer to initiate a new multipart “upload”, copy pieces of the
large object (specifying a range of bytes up to 5 GB from the large source file), then complete the
multipart “upload”.
NOTE: This is a synchronous operation, not an asynchronous operation, which means
that Amazon S3 will not return a response for this operation until the copy has completed across the Amazon
S3 server fleet. Copying objects within a single region will complete more quickly than copying objects
across regions. The synchronous nature of this operation is different from other services where
responses are typically returned immediately, even if the operation itself has not yet been completed on
the server-side.
Access
Parameters
Parameter |
Type |
Required |
Description |
$source
|
array
|
Required
|
The bucket and file name to copy from. The following keys must be set:
bucket - string - Required - Specifies the name of the bucket containing the source object.filename - string - Required - Specifies the file name of the source object to copy. |
$dest
|
array
|
Required
|
The bucket and file name to copy to. The following keys must be set:
bucket - string - Required - Specifies the name of the bucket to copy the object to.filename - string - Required - Specifies the file name to copy the object to. |
$upload_id
|
string
|
Required
|
The upload ID identifying the multipart upload whose parts are being listed. The upload ID is retrieved from a call to initiate_multipart_upload() . |
$part_number
|
integer
|
Required
|
A part number uniquely identifies a part and defines its position within the destination object. When you complete a multipart upload, a complete object is created by concatenating parts in ascending order based on part number. If you copy a new part using the same part number as a previously copied/uploaded part, the previously written part is overwritten. |
$opt
|
array
|
Optional
|
An associative array of parameters that can have the following keys:
ifMatch - string - Optional - The ETag header from a previous request. Copies the object if its entity tag (ETag) matches the specified tag; otherwise, the request returns a 412 HTTP status code error (precondition failed). Used in conjunction with ifUnmodifiedSince .ifUnmodifiedSince - string - Optional - The LastModified header from a previous request. Copies the object if it hasn’t been modified since the specified time; otherwise, the request returns a 412 HTTP status code error (precondition failed). Used in conjunction with ifMatch .ifNoneMatch - string - Optional - The ETag header from a previous request. Copies the object if its entity tag (ETag) is different than the specified ETag; otherwise, the request returns a 412 HTTP status code error (failed condition). Used in conjunction with ifModifiedSince .ifModifiedSince - string - Optional - The LastModified header from a previous request. Copies the object if it has been modified since the specified time; otherwise, the request returns a 412 HTTP status code error (failed condition). Used in conjunction with ifNoneMatch .range - string - Optional - The range of bytes to copy from the object. Specify this parameter when copying partial bits. The specified range must be notated with a hyphen (e.g., 0-10485759). Defaults to the byte range of the complete Amazon S3 object.versionId - string - Optional - The version of the object to copy. Version IDs are returned in the x-amz-version-id header of any previous object-related request.curlopts - array - Optional - A set of values to pass directly into curl_setopt() , where the key is a pre-defined CURLOPT_* constant.returnCurlHandle - boolean - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests. |
Returns
Examples
Copying a large object (5+ GB) using the "multipart" flow. Objects smaller than 5 GB should use copy_object()
instead.
- Initiate a new large object copy using
initiate_multipart_upload()
.
- Using the
copy_part()
method, copy the large object in 5 GB “parts” by specifying the range
option. The final part can be any size smaller than 5 GB.
- Complete the large object copy using
complete_multipart_upload()
.
// Define a gigabyte
define('GB', 1024 * 1024 * 1024);
// Instantiate the class
$s3 = new AmazonS3();
$bucket = 'my-bucket' . strtolower($s3->key);
// Copy a part. The source file MUST be larger than 5 GB.
$response = $s3->copy_part(
array( // Source
'bucket' => $bucket,
'filename' => 'movie.mp4'
),
array( // Destination
'bucket' => $bucket,
'filename' => 'file2.junk'
),
'f_JM_zwhU37pj1tS.F2BXVWUJtGcNso1WEikZImjrBCYUbUQwNnOUwX.Z00O1QmKQXAjqQBD4BVZRGmEXAMPLE--', // Upload ID
1, // Part Number
array(
'range' => '0-' . 5*GB
)
);
// Success?
var_dump($response->isOK());
Result:
bool(true)
Source
Method defined in services/s3.class.php | Toggle source view (49 lines) | View on GitHub
public function copy_part($source, $dest, $upload_id, $part_number, $opt = null)
{
if (!$opt) $opt = array();
// Add this to our request
$opt['verb'] = 'PUT';
$opt['resource'] = $dest['filename'];
$opt['uploadId'] = $upload_id;
$opt['partNumber'] = $part_number;
// Handle copy source
if (isset($source['bucket']) && isset($source['filename']))
{
$opt['headers']['x-amz-copy-source'] = '/' . $source['bucket'] . '/' . rawurlencode($source['filename'])
. (isset($opt['versionId']) ? ('?' . 'versionId=' . rawurlencode($opt['versionId'])) : ''); // Append the versionId to copy, if available
unset($opt['versionId']);
}
// Handle conditional-copy parameters
if (isset($opt['ifMatch']))
{
$opt['headers']['x-amz-copy-source-if-match'] = $opt['ifMatch'];
unset($opt['ifMatch']);
}
if (isset($opt['ifNoneMatch']))
{
$opt['headers']['x-amz-copy-source-if-none-match'] = $opt['ifNoneMatch'];
unset($opt['ifNoneMatch']);
}
if (isset($opt['ifUnmodifiedSince']))
{
$opt['headers']['x-amz-copy-source-if-unmodified-since'] = $opt['ifUnmodifiedSince'];
unset($opt['ifUnmodifiedSince']);
}
if (isset($opt['ifModifiedSince']))
{
$opt['headers']['x-amz-copy-source-if-modified-since'] = $opt['ifModifiedSince'];
unset($opt['ifModifiedSince']);
}
// Partial content range
if (isset($opt['range']))
{
$opt['headers']['x-amz-copy-source-range'] = 'bytes=' . $opt['range'];
}
// Authenticate to S3
return $this->authenticate($dest['bucket'], $opt);
}