Object Storage Service：Unggah multi-bagian (PHP SDK V1)

Alur unggah multi-bagian

Unggah multi-bagian terdiri dari tiga langkah berikut:

1. Inisialisasi event unggah multi-bagian.

   Panggil metode $ossClient->initiateMultipartUpload. OSS akan mengembalikan uploadId yang bersifat unik secara global untuk event unggah multi-bagian tersebut.

2. Unggah bagian-bagian.

   Panggil metode $ossClient->uploadPart untuk mengunggah data setiap bagian.

   Catatan

   • Untuk uploadId tertentu, nomor bagian menentukan posisi suatu bagian dalam objek lengkap. Jika Anda mengunggah bagian baru dengan nomor bagian yang sama dengan bagian yang sudah ada, bagian tersebut akan ditimpa.

   • OSS menyertakan hash MD5 dari data bagian yang diterima dalam header ETag pada respons.

   • OSS menghitung hash MD5 dari data yang diunggah dan membandingkannya dengan hash MD5 yang dihitung oleh SDK. Jika kedua hash tidak cocok, OSS mengembalikan kode kesalahan InvalidDigest.

3. Selesaikan unggah multi-bagian.

   Panggil metode $ossClient->completeMultipartUpload untuk menggabungkan semua bagian menjadi satu objek utuh.

Contoh lengkap unggah multi-bagian

Contoh berikut menunjukkan proses lengkap unggah multi-bagian:

<?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;

// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel. 
$provider = new EnvironmentVariableCredentialsProvider();
// Wilayah China (Hangzhou) digunakan sebagai contoh untuk titik akhir. Tentukan titik akhir sesuai wilayah Anda.
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// Tentukan nama bucket, misalnya examplebucket.
$bucket= 'examplebucket';
// Tentukan path lengkap objek. Path tidak boleh mengandung nama bucket. Misalnya, exampledir/exampleobject.txt.
$object = 'exampledir/exampleobject.txt';
// Tentukan path lengkap file lokal.
$uploadFile = 'D:\\localpath\\examplefile.txt';
$initOptions = array(
    OssClient::OSS_HEADERS  => array(
        // Tentukan perilaku cache halaman web saat objek diunduh.
        // 'Cache-Control' => 'no-cache',
        // Tentukan nama objek saat diunduh.
        // 'Content-Disposition' => 'attachment;filename=oss_download.jpg',
        // Tentukan waktu kedaluwarsa dalam milidetik.
        // 'Expires' => 150,
        // Tentukan apakah objek dengan nama yang sama boleh ditimpa saat Anda menginisialisasi unggah multi-bagian. Pada contoh ini, parameter ini diatur ke true, yang berarti penimpaan dilarang.
        //'x-oss-forbid-overwrite' => 'true',
        // Tentukan metode enkripsi sisi server untuk setiap bagian objek.
        // 'x-oss-server-side-encryption'=> 'KMS',
        // Tentukan algoritma enkripsi objek.
        // 'x-oss-server-side-data-encryption'=>'SM4',
        // Tentukan customer master key (CMK) yang dikelola oleh KMS.
        //'x-oss-server-side-encryption-key-id' => '9468da86-3509-4f8d-a61e-6eab1eac****',
        // Tentukan kelas penyimpanan objek.
        // 'x-oss-storage-class' => 'Standard',
        // Tentukan tag objek. Anda dapat menentukan multiple tag.
        // 'x-oss-tagging' => 'TagA=A&TagB=B',
    ),
);

/**
 *  Langkah 1: Inisialisasi event unggah multi-bagian dan dapatkan uploadId.
 */
try{
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
    // Mengembalikan uploadId. UploadId adalah pengenal unik untuk event unggah multi-bagian. Anda dapat menggunakan uploadId untuk melakukan operasi seperti membatalkan atau mengkueri unggah multi-bagian.
    $uploadId = $ossClient->initiateMultipartUpload($bucket, $object, $initOptions);
    print("initiateMultipartUpload OK" . "\n");
    // Gunakan uploadId untuk membatalkan event unggah multi-bagian atau mencantumkan bagian yang telah diunggah.
    // Untuk menggunakan uploadId guna membatalkan event unggah multi-bagian, Anda harus mendapatkan uploadId setelah memanggil InitiateMultipartUpload untuk menginisialisasi unggah multi-bagian. 
    // Untuk menggunakan uploadId guna mencantumkan bagian yang telah diunggah, Anda harus mendapatkan uploadId setelah memanggil InitiateMultipartUpload untuk menginisialisasi unggah multi-bagian dan sebelum memanggil CompleteMultipartUpload untuk menyelesaikan unggah multi-bagian.
    //print("UploadId: " . $uploadId . "\n");
} catch(OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

/*
 * Langkah 2: Unggah bagian-bagian.
 */
// Ukuran bagian minimum adalah 100 KB dan ukuran maksimum adalah 5 GB. Ukuran bagian terakhir boleh kurang dari 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(
        // File yang akan diunggah.
        $ossClient::OSS_FILE_UPLOAD => $uploadFile,
        // Atur nomor bagian.
        $ossClient::OSS_PART_NUM => ($i + 1),
        // Tentukan posisi awal unggah multi-bagian.
        $ossClient::OSS_SEEK_TO => $fromPos,
        // Tentukan panjang file.
        $ossClient::OSS_LENGTH => $toPos - $fromPos + 1,
        // Tentukan apakah Validasi MD5 diaktifkan. true berarti Validasi MD5 diaktifkan.
        $ossClient::OSS_CHECK_MD5 => $isCheckMd5,
    );
    // Aktifkan Validasi MD5.
    if ($isCheckMd5) {
        $contentMd5 = OssUtil::getMd5SumForFile($uploadFile, $fromPos, $toPos);
        $upOptions[$ossClient::OSS_CONTENT_MD5] = $contentMd5;
    }
    try {
        // Unggah bagian.
        $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 adalah array yang terdiri dari ETag dan nomor bagian setiap bagian.
$uploadParts = array();
foreach ($responseUploadPart as $i => $eTag) {
    $uploadParts[] = array(
        'PartNumber' => ($i + 1),
        'ETag' => $eTag,
    );
}
/**
 * Langkah 3: Selesaikan unggah.
 */
$comOptions['headers'] = array(
    // Tentukan apakah objek dengan nama yang sama boleh ditimpa saat Anda menyelesaikan unggah multi-bagian. Pada contoh ini, parameter ini diatur ke true, yang berarti penimpaan dilarang.
    // 'x-oss-forbid-overwrite' => 'true',
    // Jika Anda menentukan x-oss-complete-all:yes, OSS akan mencantumkan semua bagian yang diunggah untuk uploadId saat ini, mengurutkannya berdasarkan nomor bagian, lalu menjalankan operasi CompleteMultipartUpload.
    // 'x-oss-complete-all'=> 'yes'
);

try {
    // Saat menjalankan operasi completeMultipartUpload, Anda harus menyediakan semua $uploadParts yang valid. Setelah OSS menerima $uploadParts yang dikirimkan, OSS akan memverifikasi validitas setiap bagian. Setelah semua bagian data diverifikasi, OSS akan menggabungkannya menjadi satu file utuh.
    $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;
}
           

Lakukan unggah multi-bagian file lokal

Kode berikut menunjukkan cara melakukan unggah multi-bagian file lokal ke OSS.

<?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;

// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel. 
$provider = new EnvironmentVariableCredentialsProvider();
// Wilayah China (Hangzhou) digunakan sebagai contoh untuk titik akhir. Tentukan titik akhir sesuai wilayah Anda.
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// Tentukan nama bucket, misalnya examplebucket.
$bucket= 'examplebucket';
// Tentukan path lengkap objek. Path tidak boleh mengandung nama bucket. Misalnya, exampledir/exampleobject.txt.
$object = 'exampledir/exampleobject.txt';
// Tentukan path lengkap file lokal.
$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");            

Lakukan unggah multi-bagian folder (PHP SDK V1)

Kode berikut menunjukkan cara melakukan unggah multi-bagian folder lokal beserta seluruh isinya ke OSS.

<?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;

// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel. 
$provider = new EnvironmentVariableCredentialsProvider();
// Wilayah China (Hangzhou) digunakan sebagai contoh untuk titik akhir. Tentukan titik akhir sesuai wilayah Anda.
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// Tentukan nama bucket, misalnya examplebucket.
$bucket= 'examplebucket';
// Tentukan path lengkap folder lokal yang akan diunggah.
$localDirectory = "D:\\localpath";
// Tentukan awalan folder di 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");            

Batalkan event unggah multi-bagian (PHP SDK V1)

Anda dapat memanggil metode $ossClient->abortMultipartUpload untuk membatalkan event unggah multi-bagian. Setelah event dibatalkan, uploadId-nya tidak dapat digunakan lagi untuk operasi apa pun, dan data bagian yang telah diunggah akan dihapus.

<?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;

// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel. 
$provider = new EnvironmentVariableCredentialsProvider();
// Wilayah China (Hangzhou) digunakan sebagai contoh untuk titik akhir. Tentukan titik akhir sesuai wilayah Anda.
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// Tentukan nama bucket, misalnya examplebucket.
$bucket= 'examplebucket';
// Tentukan path lengkap objek. Path tidak boleh mengandung nama bucket. Misalnya, exampledir/exampleobject.txt.
$object = 'exampledir/exampleobject.txt';
// Tentukan uploadId, misalnya 0004B999EF518A1FE585B0C9360D****. UploadId dikembalikan setelah Anda memanggil InitiateMultipartUpload untuk menginisialisasi unggah multi-bagian.
$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");            

Cantumkan bagian yang telah diunggah (PHP SDK V1)

Anda dapat memanggil metode listParts untuk mencantumkan semua bagian yang berhasil diunggah untuk uploadId tertentu.

<?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;

// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel. 
$provider = new EnvironmentVariableCredentialsProvider();
// Wilayah China (Hangzhou) digunakan sebagai contoh untuk titik akhir. Tentukan titik akhir sesuai wilayah Anda.
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// Tentukan nama bucket, misalnya examplebucket.
$bucket= 'examplebucket';
// Tentukan path lengkap objek. Path tidak boleh mengandung nama bucket. Misalnya, exampledir/exampleobject.txt.
$object = 'exampledir/exampleobject.txt';
// Tentukan uploadId, misalnya 0004B999EF518A1FE585B0C9360D****. UploadId dikembalikan setelah Anda memanggil InitiateMultipartUpload untuk menginisialisasi unggah multi-bagian dan sebelum Anda memanggil CompleteMultipartUpload untuk menyelesaikan unggah multi-bagian.
$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");            

Cantumkan event unggah multi-bagian (PHP SDK V1)

Anda dapat memanggil metode listMultipartUploads untuk mencantumkan semua event unggah multi-bagian yang sedang berjalan—yaitu event yang telah diinisialisasi tetapi belum diselesaikan atau dibatalkan.

<?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;

// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel. 
$provider = new EnvironmentVariableCredentialsProvider();
// Wilayah China (Hangzhou) digunakan sebagai contoh untuk titik akhir. Tentukan titik akhir sesuai wilayah Anda.
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// Tentukan nama bucket, misalnya 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);            

Tabel berikut menjelaskan parameter dalam $options.

Referensi

• Untuk kode contoh lengkap unggah multi-bagian, lihat contoh GitHub.

• Unggah multi-bagian melibatkan tiga operasi API. Untuk informasi selengkapnya tentang operasi tersebut, lihat topik berikut:

  • InitiateMultipartUpload

  • UploadPart

  • CompleteMultipartUpload

• Untuk informasi selengkapnya tentang operasi API untuk membatalkan event unggah multi-bagian, lihat AbortMultipartUpload.

• Untuk informasi selengkapnya tentang operasi API untuk mencantumkan bagian yang telah diunggah, lihat ListParts.

• Untuk informasi selengkapnya tentang operasi API untuk mencantumkan semua event unggah multi-bagian yang sedang berjalan, lihat ListMultipartUploads.