Object Storage Service (OSS) propose une fonctionnalité de téléchargement multipartie pour les objets volumineux. Ce processus consiste à diviser un objet volumineux en parties plus petites, à les télécharger indépendamment, puis à appeler l'API CompleteMultipartUpload pour assembler les parties en un seul objet. Cette méthode permet de reprendre les téléchargements interrompus.
Procédure
Pour télécharger un objet via un téléchargement multipartie, suivez les étapes ci-dessous :
-
Initialisez une tâche de téléchargement multipartie.
Appelez
$ossClient->initiateMultipartUploadpour obtenir un ID de téléchargement unique dans OSS. -
Téléchargez les parties.
Appelez
$ossClient->uploadPartpour télécharger les parties.RemarqueLe numéro de partie identifie la position d'une partie au sein de l'objet. Le téléchargement de données avec le même numéro de partie écrase la partie existante.
OSS renvoie le hachage MD5 des données de la partie reçues dans l'en-tête ETag de la réponse.
OSS calcule le hachage MD5 des données téléchargées et le compare au hachage calculé par le SDK. En cas de discordance, le code d'erreur InvalidDigest est renvoyé.
-
Finalisez la tâche de téléchargement multipartie.
Appelez
$ossClient->completeMultipartUploadpour assembler toutes les parties en un objet complet.
Exemple de code complet pour un téléchargement multipartie
L'exemple suivant illustre le processus complet de téléchargement multipartie :
<?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();
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint.
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// Specify the name of the bucket. Example: examplebucket.
$bucket= 'examplebucket';
// Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt.
$object = 'exampledir/exampleobject.txt';
// Specify the full path of the local file that you want to upload.
$uploadFile = 'D:\\localpath\\examplefile.txt';
$initOptions = array(
OssClient::OSS_HEADERS => array(
// Specify the caching behavior of the web page when the object is downloaded.
// 'Cache-Control' => 'no-cache',
//Specify the name of the object when the object is downloaded.
// 'Content-Disposition' => 'attachment;filename=oss_download.jpg',
// Specify the validity period of the request. Unit: milliseconds.
// 'Expires' => 150,
// If set to true, prevents this upload from overwriting an existing object with the same name.
//'x-oss-forbid-overwrite' => 'true',
// Specify the server-side encryption method that you want to use to encrypt each part of the object.
// 'x-oss-server-side-encryption'=> 'KMS',
// Specify the algorithm that you want to use to encrypt the object.
// 'x-oss-server-side-data-encryption'=>'SM4',
// Specify the ID of the customer master key (CMK) that is managed by Key Management Service (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 tags for the object. You can specify multiple tags for the object at a time.
// 'x-oss-tagging' => 'TagA=A&TagB=B',
),
);
/**
* Step 1: Initiate a multipart upload task and obtain the upload ID.
*/
try{
$config = array(
"provider" => $provider,
"endpoint" => $endpoint,
"signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
"region"=> "cn-hangzhou"
);
$ossClient = new OssClient($config);
// Obtain the upload ID. The upload ID is the unique identifier of a multipart upload task. You can perform related operations such as canceling or querying the multipart upload task based on the upload ID.
$uploadId = $ossClient->initiateMultipartUpload($bucket, $object, $initOptions);
print("initiateMultipartUpload OK" . "\n");
// Cancel the multipart upload task or list uploaded parts based on the upload ID.
// If you want to cancel a multipart upload task based on the upload ID, obtain the upload ID after you call the InitiateMultipartUpload operation to initiate the multipart upload task.
// If you want to list the uploaded parts in a multipart upload task based on the upload ID, obtain the upload ID after you call the InitiateMultipartUpload operation to initiate the multipart upload task but before you call the CompleteMultipartUpload operation to complete the multipart upload task.
//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 size of the last part can be less 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 object.
$ossClient::OSS_FILE_UPLOAD => $uploadFile,
// Specify part numbers.
$ossClient::OSS_PART_NUM => ($i + 1),
// Specify the position from which the multipart upload task starts.
$ossClient::OSS_SEEK_TO => $fromPos,
// Specify the object length.
$ossClient::OSS_LENGTH => $toPos - $fromPos + 1,
// Specify whether to enable MD5 verification. The value true specifies that MD5 verification is enabled.
$ossClient::OSS_CHECK_MD5 => $isCheckMd5,
);
// Enable MD5 verification.
if ($isCheckMd5) {
$contentMd5 = OssUtil::getMd5SumForFile($uploadFile, $fromPos, $toPos);
$upOptions[$ossClient::OSS_CONTENT_MD5] = $contentMd5;
}
try {
// Upload the parts.
$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 multipart upload task.
*/
$comOptions['headers'] = array(
// Specify whether the object that is uploaded by using multipart upload overwrites the existing object that has the same name when the multipart upload task is complete. In this example, this parameter is set to true, which specifies that the uploaded object that has the same name as the existing object does not overwrite the existing object.
// 'x-oss-forbid-overwrite' => 'true',
// If you set the x-oss-complete-all parameter to yes, OSS lists all parts that are uploaded by using the current upload ID, sorts the parts by part number, and then performs the CompleteMultipartUpload operation.
// 'x-oss-complete-all'=> 'yes'
);
try {
// Provide the list of all uploaded parts (PartNumber and ETag). OSS will verify each part before combining them into the final object.
$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;
}
Télécharger un fichier local via un téléchargement multipartie
L'exemple de code suivant montre comment télécharger un fichier local vers OSS en utilisant un téléchargement multipartie :
<?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();
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint.
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// Specify the name of the bucket. Example: examplebucket.
$bucket= 'examplebucket';
// Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt.
$object = 'exampledir/exampleobject.txt';
// Specify the full path of the local file that you want to upload.
$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");
Télécharger un répertoire local via un téléchargement multipartie (PHP SDK V1)
L'exemple de code suivant montre comment télécharger un répertoire local, y compris tous les fichiers qu'il contient, vers OSS en utilisant un téléchargement multipartie :
<?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();
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint.
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// Specify the name of the bucket. Example: examplebucket.
$bucket= 'examplebucket';
// Specify the full path of the local directory that you want to upload.
$localDirectory = "D:\\localpath";
// Specify the prefix of the directory.
$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");
Annuler une tâche de téléchargement multipartie (PHP SDK V1)
Utilisez la méthode $ossClient->abortMultipartUpload pour annuler une tâche de téléchargement multipartie. Si une tâche de téléchargement multipartie est annulée, l'ID de téléchargement ne peut plus être utilisé pour télécharger des parties. De plus, les parties déjà téléchargées sont supprimées.
<?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();
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint.
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// Specify the name of the bucket. Example: examplebucket.
$bucket= 'examplebucket';
// Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt.
$object = 'exampledir/exampleobject.txt';
// Specify the upload ID. Example: 0004B999EF518A1FE585B0C9360D****. You can obtain the upload ID from the response to the InitiateMultipartUpload operation.
$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");
Répertorier les parties téléchargées (PHP SDK V1)
Utilisez la méthode listParts pour répertorier toutes les parties téléchargées à l'aide de l'ID de téléchargement spécifié.
<?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();
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint.
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// Specify the name of the bucket. Example: examplebucket.
$bucket= 'examplebucket';
// Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt.
$object = 'exampledir/exampleobject.txt';
// Specify the upload ID. Example: 0004B999EF518A1FE585B0C9360D****. You can obtain the upload ID from the response to the InitiateMultipartUpload operation. You must obtain the upload ID before you call the CompleteMultipartUpload operation to complete the multipart upload task.
$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");
Répertorier les tâches de téléchargement multipartie (PHP SDK V1)
Utilisez la méthode listMultipartUploads pour répertorier toutes les tâches de téléchargement multipartie en cours. Les tâches en cours sont celles qui ont été initiées mais qui ne sont ni terminées ni annulées.
<?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();
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint.
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// Specify the name of the bucket. 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);
Le tableau suivant décrit les paramètres inclus dans $options dans l'exemple de code précédent.
|
Paramètre |
Description |
|
delimiter |
Caractère délimiteur utilisé pour regrouper les noms d'objets. Les objets dont les noms contiennent la même chaîne entre le préfixe et la prochaine occurrence du délimiteur sont regroupés en un seul élément de résultat dans le paramètre commonPrefixes. |
|
key-marker |
Utilisé conjointement avec upload-id-marker pour spécifier le point de départ de la liste. La liste inclura uniquement les tâches pour les clés d'objet qui sont alphabétiquement supérieures à cette valeur. |
|
max-uploads |
Nombre maximal de tâches de téléchargement multipartie que vous souhaitez renvoyer pour la liste actuelle. Valeur maximale : 1000. Valeur par défaut : 1000. |
|
prefix |
Préfixe qui doit être inclus dans les noms des objets renvoyés. Remarque
Si vous utilisez un préfixe pour une requête, les noms d'objets renvoyés contiennent le préfixe. |
|
upload-id-marker |
ID de téléchargement de la tâche de téléchargement multipartie à partir de laquelle la liste commence. Ce paramètre est utilisé conjointement avec le paramètre key-marker. Si le paramètre key-marker n'est pas spécifié, le paramètre upload-id-marker est invalide. Si le paramètre key-marker est spécifié, le résultat de la requête inclut :
|
Références
Pour consulter l'exemple de code complet utilisé pour effectuer un téléchargement multipartie, visitez GitHub.
-
Un téléchargement multipartie implique trois opérations API :
Initialiser un téléchargement multipartie : InitiateMultipartUpload.
Télécharger une partie : UploadPart.
Finaliser un téléchargement multipartie : CompleteMultipartUpload.
Annuler un téléchargement multipartie : AbortMultipartUpload.
Répertorier les parties téléchargées : ListParts.
Répertorier les téléchargements multipartie en cours : ListMultipartUploads.