Object Storage Service:Multipart upload (PHP SDK V1)

Multipart upload process

A multipart upload consists of the following three steps:

1. Initialize a multipart upload event.

   Call the `$ossClient->initiateMultipartUpload` method to obtain a globally unique `uploadId` from OSS.

2. Upload parts.

   Call the `$ossClient->uploadPart` method to upload part data.

   Note

   • In a multipart upload task, part numbers are used to identify the relative positions of the parts in an object. If you upload a part that has the same part number as an existing part, the existing part is overwritten by the uploaded part.

   • OSS includes the MD5 hash of each uploaded part in the ETag header in the response.

   • OSS calculates the MD5 hash of the uploaded parts and compares the MD5 hash with the MD5 hash that is calculated by OSS SDK for Java. If the two hashes are different, OSS returns the InvalidDigest error code.

3. Complete the multipart upload.

   Call the `$ossClient->completeMultipartUpload` method to combine all parts into a complete file.

Complete multipart upload example

The following sample code provides an example on how to implement a multipart upload task by following the multipart upload process:

<?php if (is_file(__DIR__ . '/../autoload.php')) { require_once __DIR__ . '/../autoload.php'; } if (is_file(__DIR__ . '/../vendor/autoload.php')) { require_once __DIR__ . '/../vendor/autoload.php'; } use OSS\Credentials\EnvironmentVariableCredentialsProvider; use OSS\OssClient; use OSS\CoreOssException; use OSS\Core\OssUtil; // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. $provider = new EnvironmentVariableCredentialsProvider(); // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint. $endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'; // Specify the bucket name. For example, examplebucket. $bucket= 'examplebucket'; // Specify the full path of the object. Do not include the bucket name in the full path. For example, exampledir/exampleobject.txt. $object = 'exampledir/exampleobject.txt'; // Specify the full path of the local file. $uploadFile = 'D:\\localpath\\examplefile.txt'; $initOptions = array( OssClient::OSS_HEADERS => array( // Specify the web page caching behavior when the object is downloaded. // 'Cache-Control' => 'no-cache', // Specify the name of the object when it is downloaded. // 'Content-Disposition' => 'attachment;filename=oss_download.jpg', // Specify the expiration time in milliseconds. // 'Expires' => 150, // Specify whether to overwrite an existing object that has the same name when you initialize the multipart upload. In this example, this parameter is set to true to prevent overwriting. //'x-oss-forbid-overwrite' => 'true', // Specify the server-side encryption method for each part of the object. // 'x-oss-server-side-encryption'=> 'KMS', // Specify the encryption algorithm for the object. // 'x-oss-server-side-data-encryption'=>'SM4', // Specify the customer master key (CMK) that is managed by KMS. //'x-oss-server-side-encryption-key-id' => '9468da86-3509-4f8d-a61e-6eab1eac****', // Specify the storage class of the object. // 'x-oss-storage-class' => 'Standard', // Specify object tags. You can specify multiple tags at a time. // 'x-oss-tagging' => 'TagA=A&TagB=B', ), ); /** * Step 1: Initialize a multipart upload event and obtain the uploadId. */ try{ $config = array( "provider" => $provider, "endpoint" => $endpoint, "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4, "region"=> "cn-hangzhou" ); $ossClient = new OssClient($config); // The uploadId is returned. The uploadId is the unique identifier of the multipart upload event. You can use the uploadId to perform operations, such as aborting the multipart upload event and querying the multipart upload. $uploadId = $ossClient->initiateMultipartUpload($bucket, $object, $initOptions); print("initiateMultipartUpload OK" . "\n"); // Use the uploadId to abort the multipart upload event or list uploaded parts. // To abort a multipart upload event based on the uploadId, obtain the uploadId after you call the InitiateMultipartUpload operation to initialize the multipart upload. // To list uploaded parts based on the uploadId, obtain the uploadId after you call the InitiateMultipartUpload operation to initialize the multipart upload and before you call the CompleteMultipartUpload operation to complete the multipart upload. //print("UploadId: " . $uploadId . "\n"); } catch(OssException $e) { printf($e->getMessage() . "\n"); return; } /* * Step 2: Upload parts. */ // The minimum part size is 100 KB, and the maximum part size is 5 GB. The last part can be smaller than 100 KB. $partSize = 10 * 1024 * 1024; $uploadFileSize = sprintf('%u',filesize($uploadFile)); $pieces = $ossClient->generateMultiuploadParts($uploadFileSize, $partSize); $responseUploadPart = array(); $uploadPosition = 0; $isCheckMd5 = true; foreach ($pieces as $i => $piece) { $fromPos = $uploadPosition + (integer)$piece[$ossClient::OSS_SEEK_TO]; $toPos = (integer)$piece[$ossClient::OSS_LENGTH] + $fromPos - 1; $upOptions = array( // Upload the file. $ossClient::OSS_FILE_UPLOAD => $uploadFile, // Set the part number. $ossClient::OSS_PART_NUM => ($i + 1), // Specify the start position of the multipart upload. $ossClient::OSS_SEEK_TO => $fromPos, // Specify the file length. $ossClient::OSS_LENGTH => $toPos - $fromPos + 1, // Specify whether to enable MD5 validation. Set the value to true to enable MD5 validation. $ossClient::OSS_CHECK_MD5 => $isCheckMd5, ); // Enable MD5 validation. if ($isCheckMd5) { $contentMd5 = OssUtil::getMd5SumForFile($uploadFile, $fromPos, $toPos); $upOptions[$ossClient::OSS_CONTENT_MD5] = $contentMd5; } try { // Upload the part. $responseUploadPart[] = $ossClient->uploadPart($bucket, $object, $uploadId, $upOptions); printf("initiateMultipartUpload, uploadPart - part#{$i} OK\n"); } catch(OssException $e) { printf("initiateMultipartUpload, uploadPart - part#{$i} FAILED\n"); printf($e->getMessage() . "\n"); return; } } // $uploadParts is an array that consists of the ETag and part number of each part. $uploadParts = array(); foreach ($responseUploadPart as $i => $eTag) { $uploadParts[] = array( 'PartNumber' => ($i + 1), 'ETag' => $eTag, ); } /** * Step 3: Complete the upload. */ $comOptions['headers'] = array( // Specify whether to overwrite an existing object that has the same name when the multipart upload is complete. In this example, this parameter is set to true to prevent overwriting. // 'x-oss-forbid-overwrite' => 'true', // If you set x-oss-complete-all to yes, OSS lists all parts that are uploaded for the current uploadId, sorts the parts by part number, and then runs the CompleteMultipartUpload operation. // 'x-oss-complete-all'=> 'yes' ); try { // When you run the completeMultipartUpload operation, you must provide all valid $uploadParts. After OSS receives the submitted $uploadParts, it verifies the validity of each part. After all data parts are verified, OSS combines these parts into a complete file. $ossClient->completeMultipartUpload($bucket, $object, $uploadId, $uploadParts,$comOptions); printf( "Complete Multipart Upload OK\n"); } catch(OssException $e) { printf("Complete Multipart Upload FAILED\n"); printf($e->getMessage() . "\n"); return; } 

Upload a local file using multipart upload

The following code shows how to upload a local file to OSS using multipart upload.

<?php if (is_file(__DIR__ . '/../autoload.php')) { require_once __DIR__ . '/../autoload.php'; } if (is_file(__DIR__ . '/../vendor/autoload.php')) { require_once __DIR__ . '/../vendor/autoload.php'; } use OSS\Credentials\EnvironmentVariableCredentialsProvider; use OSS\OssClient; use OSS\CoreOssException; // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. $provider = new EnvironmentVariableCredentialsProvider(); // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint. $endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'; // Specify the bucket name. For example, examplebucket. $bucket= 'examplebucket'; // Specify the full path of the object. Do not include the bucket name in the full path. For example, exampledir/exampleobject.txt. $object = 'exampledir/exampleobject.txt'; // Specify the full path of the local file. $file = 'D:\\localpath\\examplefile.txt'; $options = array( OssClient::OSS_CHECK_MD5 => true, OssClient::OSS_PART_SIZE => 1, ); try{ $config = array( "provider" => $provider, "endpoint" => $endpoint, "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4, "region"=> "cn-hangzhou" ); $ossClient = new OssClient($config); $ossClient->multiuploadFile($bucket, $object, $file, $options); } catch(OssException $e) { printf(__FUNCTION__ . ": FAILED\n"); printf($e->getMessage() . "\n"); return; } print(__FUNCTION__ . ": OK" . "\n"); 

Upload a directory (PHP SDK V1)

The following code shows how to upload a local directory, including all the files in it, to OSS using multipart upload.

<?php if (is_file(__DIR__ . '/../autoload.php')) { require_once __DIR__ . '/../autoload.php'; } if (is_file(__DIR__ . '/../vendor/autoload.php')) { require_once __DIR__ . '/../vendor/autoload.php'; } use OSS\Credentials\EnvironmentVariableCredentialsProvider; use OSS\OssClient; use OSS\CoreOssException; // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. $provider = new EnvironmentVariableCredentialsProvider(); // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint. $endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'; // Specify the bucket name. For example, examplebucket. $bucket= 'examplebucket'; // Specify the full path of the local directory to upload. $localDirectory = "D:\\localpath"; // Specify the prefix of the directory in OSS. $prefix = "samples/codes/"; try { $config = array( "provider" => $provider, "endpoint" => $endpoint, "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4, "region"=> "cn-hangzhou" ); $ossClient = new OssClient($config); $ossClient->uploadDir($bucket, $prefix, $localDirectory); } catch(OssException $e) { printf(__FUNCTION__ . ": FAILED\n"); printf($e->getMessage() . "\n"); return; } print(__FUNCTION__ . ": OK" . "\n"); 

Abort a multipart upload event (PHP SDK V1)

You can call the `$ossClient->abortMultipartUpload` method to abort a multipart upload event. After a multipart upload event is aborted, you can no longer use its `uploadId` for any operations. The uploaded parts are deleted.

<?php if (is_file(__DIR__ . '/../autoload.php')) { require_once __DIR__ . '/../autoload.php'; } if (is_file(__DIR__ . '/../vendor/autoload.php')) { require_once __DIR__ . '/../vendor/autoload.php'; } use OSS\Credentials\EnvironmentVariableCredentialsProvider; use OSS\OssClient; use OSS\CoreOssException; // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. $provider = new EnvironmentVariableCredentialsProvider(); // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint. $endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'; // Specify the bucket name. For example, examplebucket. $bucket= 'examplebucket'; // Specify the full path of the object. Do not include the bucket name in the full path. For example, exampledir/exampleobject.txt. $object = 'exampledir/exampleobject.txt'; // Specify the uploadId. For example, 0004B999EF518A1FE585B0C9360D****. The uploadId is returned after you call the InitiateMultipartUpload operation to initialize the multipart upload. $upload_id = '0004B999EF518A1FE585B0C9360D****'; try{ $config = array( "provider" => $provider, "endpoint" => $endpoint, "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4, "region"=> "cn-hangzhou" ); $ossClient = new OssClient($config); $ossClient->abortMultipartUpload($bucket, $object, $upload_id); } catch(OssException $e) { printf(__FUNCTION__ . ": FAILED\n"); printf($e->getMessage() . "\n"); return; } print(__FUNCTION__ . ": OK" . "\n"); 

List uploaded parts (PHP SDK V1)

You can call the `listParts` method to list all parts that have been successfully uploaded for a specified `uploadId`.

<?php if (is_file(__DIR__ . '/../autoload.php')) { require_once __DIR__ . '/../autoload.php'; } if (is_file(__DIR__ . '/../vendor/autoload.php')) { require_once __DIR__ . '/../vendor/autoload.php'; } use OSS\Credentials\EnvironmentVariableCredentialsProvider; use OSS\OssClient; use OSS\CoreOssException; // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. $provider = new EnvironmentVariableCredentialsProvider(); // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint. $endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'; // Specify the bucket name. For example, examplebucket. $bucket= 'examplebucket'; // Specify the full path of the object. Do not include the bucket name in the full path. For example, exampledir/exampleobject.txt. $object = 'exampledir/exampleobject.txt'; // Specify the uploadId. For example, 0004B999EF518A1FE585B0C9360D****. The uploadId is returned after you call the InitiateMultipartUpload operation to initialize the multipart upload and before you call the CompleteMultipartUpload operation to complete the multipart upload. $upload_id = '0004B999EF518A1FE585B0C9360D****'; try{ $config = array( "provider" => $provider, "endpoint" => $endpoint, "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4, "region"=> "cn-hangzhou" ); $ossClient = new OssClient($config); $listPartsInfo = $ossClient->listParts($bucket, $object, $uploadId); foreach ($listPartsInfo->getListPart() as $partInfo) { print($partInfo->getPartNumber() . "\t" . $partInfo->getSize() . "\t" . $partInfo->getETag() . "\t" . $partInfo->getLastModified() . "\n"); } } catch(OssException $e) { printf(__FUNCTION__ . ": FAILED\n"); printf($e->getMessage() . "\n"); return; } print(__FUNCTION__ . ": OK" . "\n"); 

List multipart upload events (PHP SDK V1)

You can call the `listMultipartUploads` method to list all in-progress multipart upload events. In-progress multipart upload events are events that have been initialized but are not yet completed or aborted.

<?php if (is_file(__DIR__ . '/../autoload.php')) { require_once __DIR__ . '/../autoload.php'; } if (is_file(__DIR__ . '/../vendor/autoload.php')) { require_once __DIR__ . '/../vendor/autoload.php'; } use OSS\Credentials\EnvironmentVariableCredentialsProvider; use OSS\OssClient; use OSS\CoreOssException; // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. $provider = new EnvironmentVariableCredentialsProvider(); // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint. $endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'; // Specify the bucket name. For example, examplebucket. $bucket= 'examplebucket'; $options = array( 'delimiter' => '/', 'max-uploads' => 100, 'key-marker' => '', 'prefix' => '', 'upload-id-marker' => '' ); try { $config = array( "provider" => $provider, "endpoint" => $endpoint, "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4, "region"=> "cn-hangzhou" ); $ossClient = new OssClient($config); $listMultipartUploadInfo = $ossClient->listMultipartUploads($bucket, $options); } catch(OssException $e) { printf(__FUNCTION__ . ": listMultipartUploads FAILED\n"); printf($e->getMessage() . "\n"); return; } printf(__FUNCTION__ . ": listMultipartUploads OK\n"); $listUploadInfo = $listMultipartUploadInfo->getUploads(); var_dump($listUploadInfo); 

The following table describes the parameters in `$options`.

References

• For the complete sample code for multipart upload, see the GitHub example.

• A multipart upload involves three API operations. For more information about the operations, see the following topics:

  • InitiateMultipartUpload

  • UploadPart

  • CompleteMultipartUpload

• For information about the API operation that you can call to cancel a multipart upload task, see AbortMultipartUpload.

• For information about the API operation that you can call to list uploaded parts, see ListParts.

• For information about the API operation that you can call to list all ongoing multipart upload tasks, see ListMultipartUploads.