Initializing a Multipart Upload

Before upload, you need to notify OBS of initializing a multipart upload. This operation will return an upload ID (globally unique identifier) created by the OBS server to identify the multipart upload. You can use this upload ID to initiate related operations, such as aborting a multipart upload, listing multipart uploads, and listing uploaded parts.

You can call ObsClient->initiateMultipartUpload to initialize a multipart upload.

// 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([
       'key' => '*** Provide your Access Key ***',
       'secret' => '*** Provide your Secret Key ***',
       'endpoint' => 'https://your-endpoint'
]);

$resp = $obsClient->initiateMultipartUpload([
       'Bucket' => 'bucketname',
       'Key' => 'objectname',
       'ContentType' => 'text/plain',
       'Metadata' => ['property' => 'property-value']
]);

printf("RequestId:%s\n",$resp['RequestId']);
printf("UploadId:%s\n",$resp['UploadId']);

• When initializing a multipart upload, you can use the ContentType and Metadata parameters to respectively set the MIME type and customize the metadata of an object, besides the object name and owning bucket.
• After the API for initializing a multipart upload is called, the upload ID will be returned. This ID will be used in follow-up operations.

Uploading a Part

After initializing a multipart upload, you can specify the object name and upload ID to upload a part. Each part has a part number (ranging from 1 to 10000). For parts with the same upload ID, their part numbers are unique and identify their comparative locations in the object. If you use the same part number to upload two parts, the latter one being uploaded will overwrite the former. Except for the part last uploaded whose size ranges from 0 to 5 GB, sizes of the other parts range from 100 KB to 5 GB. Parts are uploaded in random order and can be uploaded through different processes or machines. OBS will combine them into the object based on their part numbers.

You can call ObsClient->uploadPart to upload a part.

// 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([
       'key' => '*** Provide your Access Key ***',
       'secret' => '*** Provide your Secret Key ***',
       'endpoint' => 'https://your-endpoint'
]);

$resp = $obsClient->uploadPart([
       'Bucket' => 'bucketname',
       'Key' => 'objectname',
       // Set the part number, which ranges from 1 to 10000.
       'PartNumber' => 1,
       // Set the upload ID.
       'UploadId' => 'upload id from initiateMultipartUpload',
// Set the large file to be uploaded. localfile is the path of the local file to be uploaded. You need to specify the file name.
       'SourceFile' => 'localfile',
       // Set the part size.
       'PartSize' => 5 * 1024 * 1024,
       // Set the start offset.
       'Offset' => 0
]);

printf("RequestId:%s\n",$resp['RequestId']);
printf("ETag:%s\n",$resp['ETag']);

• Use the PartNumber parameter to specify the part number, the UploadId parameter to specify the globally unique ID, the SourceFile parameter to specify the to-be-uploaded file, the PartSize parameter to set the part size, and the Offset parameter to set the start offset of a part.
• Except the part last uploaded, other parts must be larger than 100 KB. Part sizes will not be verified during upload because which one is last uploaded is not identified until parts are combined.
• OBS will return ETags (MD5 values) of the received parts to users.
• You can use the ContentMD5 parameter to set the MD5 value of the uploaded data.
• Part numbers range from 1 to 10000. If the part number you set is out of this range, OBS will return error 400 Bad Request.
• The minimum part size supported by an OBS 3.0 bucket is 100 KB, and the minimum part size supported by an OBS 2.0 bucket is 5 MB. You are advised to perform multipart upload to OBS 3.0 buckets.

Combining Parts

After all parts are uploaded, call the API for combining parts to generate the object. Before this operation, valid part numbers and ETags of all parts must be sent to OBS. After receiving this information, OBS verifies the validity of each part one by one. After all parts pass the verification, OBS combines these parts to form the final object.

You can call ObsClient->completeMultipartUpload to combine parts.

// 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([
       'key' => '*** Provide your Access Key ***',
       'secret' => '*** Provide your Secret Key ***',
       'endpoint' => 'https://your-endpoint'
]);

$resp = $obsClient->completeMultipartUpload([
       'Bucket' => 'bucketname',
       'Key' => 'objectname',
       // Set the upload ID.
       'UploadId' => 'upload id from initiateMultipartUpload',
       'Parts' => [
                     ['PartNumber' => 1, 'ETag' => 'etag value from uploadPart']
       ]
]);

printf("RequestId:%s\n",$resp['RequestId']);

• Use the UploadId parameter to specify the globally unique identifier for the multipart upload and the Parts parameter to specify the list of part numbers and ETags. Content in the list is displayed in the ascending order by part number.
• Part numbers can be inconsecutive.

Aborting a Multipart Upload

After a multipart upload is aborted, you cannot use its upload ID to perform any operation and the uploaded parts will be deleted by OBS.

When an object is being uploaded in multi-part mode or an object fails to be uploaded, parts generated in the bucket. These parts occupy your storage space. You can cancel the multi-part uploading task to delete unnecessary parts, thereby saving the storage space.

You can call ObsClient->abortMultipartUpload to abort a multipart upload.

// 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([
       'key' => '*** Provide your Access Key ***',
       'secret' => '*** Provide your Secret Key ***',
       'endpoint' => 'https://your-endpoint'
]);

$resp = $obsClient->abortMultipartUpload([
       'Bucket' => 'bucketname',
       'Key' => 'objectname',
       // Set the upload ID.
       'UploadId' => 'upload id from initiateMultipartUpload'
]);

printf("RequestId:%s\n",$resp['RequestId']);

Listing Uploaded Parts

You can call ObsClient->listParts to list successfully uploaded parts of a multipart upload.

The following table describes the parameters involved in this API.

• Listing parts in simple mode

// 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 ( [ 
      'key' => '*** Provide your Access Key ***',
      'secret' => '*** Provide your Secret Key ***',
      'endpoint' => 'https://your-endpoint'
] );

$resp = $obsClient->listParts ( [ 
      'Bucket' => 'bucketname',
      'Key' => 'objectname',
      'UploadId' => 'upload id from initiateMultipartUpload' 
] );

printf ( "RequestId:%s\n", $resp ['RequestId'] );
foreach ( $resp ['Parts'] as $index => $part ) {
       printf ( "Parts[%d]\n", $index + 1 );
        // Part number, specified upon uploading
       printf ( "PartNumber:%s\n", $part ['PartNumber'] );
        // Time when the part was last uploaded
       printf ( "LastModified:%s\n", $part ['LastModified'] );
        // Part ETag
       printf ( "ETag:%s\n", $part ['ETag'] );
       // Part size
       printf ( "Size:%s\n", $part ['Size'] );
}

• A maximum of 1000 parts can be listed each time. If an upload of the specific upload ID contains more than 1000 parts and IsTruncated is true in the returned result, not all parts are listed. In such cases, you can use NextPartNumberMarker to obtain the start position for next listing.
• If you want to obtain all parts involved in a specific upload ID, you can use the paging mode for listing.

• Listing all parts

If the number of parts of a multipart upload is larger than 1000, you can use the following sample code to list all parts.

// 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 ( [ 
      'key' => '*** Provide your Access Key ***',
      'secret' => '*** Provide your Secret Key ***',
      'endpoint' => 'https://your-endpoint'
] );

$partNumberMarker = null;
$index = 1;
do{
       $resp = $obsClient->listParts ( [ 
             'Bucket' => 'bucketname',
             'Key' => 'objectname',
             'UploadId' => 'upload id from initiateMultipartUpload',
             'PartNumberMarker' => $partNumberMarker
       ] );
       
       printf ( "RequestId:%s\n", $resp ['RequestId'] );
       foreach ( $resp ['Parts'] as $part ) {
              printf ( "Parts[%d]\n", $index );
              // Part number, specified upon uploading
              printf ( "PartNumber:%s\n", $part ['PartNumber'] );
              // Time when the part was last uploaded
              printf ( "LastModified:%s\n", $part ['LastModified'] );
              // Part ETag
              printf ( "ETag:%s\n", $part ['ETag'] );
              // Part size
              printf ( "Size:%s\n", $part ['Size'] );
              $index ++;
       }
       
       $partNumberMarker = $resp['NextPartNumberMarker'];
       
}while($resp['IsTruncated']);

Listing Multipart Uploads

You can call ObsClient->listMultipartUploads to list multipart uploads. The following table describes related parameters.

• Listing multipart uploads in simple mode

// 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 ( [ 
      'key' => '*** Provide your Access Key ***',
      'secret' => '*** Provide your Secret Key ***',
      'endpoint' => 'https://your-endpoint'
] );

$resp = $obsClient->listMultipartUploads ( [ 
      'Bucket' => 'bucketname' 
] );

printf ( "RequestId:%s\n", $resp ['RequestId'] );
foreach ( $resp ['Uploads'] as $index => $upload ) {
       printf ( "Uploads[%d]\n", $index + 1 );
       printf ( "Key:%s\n", $upload ['Key'] );
       printf ( "UploadId:%s\n", $upload ['UploadId'] );
       printf ( "Initiated:%s\n", $upload ['Initiated'] );
       printf ( "Owner[ID]:%s\n", $upload ['Owner'] ['ID'] );
       printf ( "StorageClass:%s\n", $upload ['StorageClass'] );
}

• Information about a maximum of 1000 multipart uploads can be listed each time. If a bucket contains more than 1000 multipart uploads and IsTruncated is true in the returned result, not all uploads are listed. In such cases, you can use NextKeyMarker and NextUploadIdMarker to obtain the start position for next listing.
• If you want to obtain all multipart uploads in a bucket, you can list them in paging mode.

• Listing all multipart uploads

// 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 ( [ 
      'key' => '*** Provide your Access Key ***',
      'secret' => '*** Provide your Secret Key ***',
      'endpoint' => 'https://your-endpoint'
] );

$keyMarker = null;
$uploadIdMarker = null;
$index = 1;
do{
       $resp = $obsClient->listMultipartUploads ( [ 
             'Bucket' => 'bucketname',
             'KeyMarker' => $keyMarker,
             'UploadIdMarker' => $uploadIdMarker
       ] );
       
       printf ( "RequestId:%s\n", $resp ['RequestId'] );
       foreach ( $resp ['Uploads'] as $index => $upload ) {
              printf ( "Uploads[%d]\n", $index );
              printf ( "Key:%s\n", $upload ['Key'] );
              printf ( "UploadId:%s\n", $upload ['UploadId'] );
              printf ( "Initiated:%s\n", $upload ['Initiated'] );
              printf ( "Owner[ID]:%s\n", $upload ['Owner'] ['ID'] );
              printf ( "StorageClass:%s\n", $upload ['StorageClass'] );
              $index ++;
       }
       $keyMarker = $resp['NextKeyMarker'];
       $uploadIdMarker = $resp['NextUploadIdMarker'];
}while ($resp['IsTruncated']);