Unggah file dengan PHP SDK V1 menggunakan unggahan sederhana, tambahan, dan multipart - Object Storage Service

Topik ini menjelaskan cara mengunggah objek ke bucket yang telah diaktifkan fitur versioning.

Perhatian

Pada topik ini digunakan titik akhir publik wilayah China (Hangzhou). Untuk mengakses OSS dari layanan Alibaba Cloud lainnya dalam wilayah yang sama, gunakan titik akhir internal. Untuk detail wilayah dan titik akhir yang didukung, lihat Regions and endpoints.
Pada topik ini, instans OSSClient dibuat menggunakan titik akhir OSS. Jika Anda ingin membuat instans OSSClient dengan nama domain kustom atau Security Token Service (STS), lihat Create an OssClient.
Untuk mengunggah objek, Anda harus memiliki izin oss:PutObject. Untuk informasi selengkapnya, lihat Grant custom permissions to a RAM user.

Simple upload

Untuk bucket yang telah diaktifkan fitur versioning, OSS menghasilkan string acak yang unik secara global sebagai ID versi untuk setiap objek yang baru diunggah. ID ini dikembalikan dalam bidang x-oss-version-id pada header respons.

Untuk bucket yang telah disuspend versioning-nya, OSS menghasilkan ID versi "null" untuk setiap objek yang baru diunggah. Jika Anda mengunggah objek dengan nama yang sama, objek baru tersebut akan menimpa objek sebelumnya, sehingga objek tersebut hanya memiliki satu versi dengan ID "null".

Kode berikut menunjukkan cara melakukan simple 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;

// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah diatur.
$provider = new EnvironmentVariableCredentialsProvider();
// Titik akhir wilayah China (Hangzhou) digunakan sebagai contoh. Gantilah dengan Titik akhir yang sebenarnya.
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$bucket= "<yourBucketName>";
// Tentukan path lengkap objek. Jangan sertakan nama bucket. Contoh: example/test.txt.
$object = "<yourObjectName>";
$content = "hello world";

$config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);

try {
    // Unggah objek ke bucket yang telah diaktifkan versioning.
    $ret = $ossClient->putObject($bucket, $object, $content);

    // Lihat informasi versi objek.
    print("versionId:" .$ret[OssClient::OSS_HEADER_VERSION_ID]);
} catch (OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

print(__FUNCTION__ . ": OK" . "\n");

Untuk informasi selengkapnya tentang simple upload, lihat PutObject.

Append upload

Saat menambahkan data ke objek (AppendObject) di bucket yang telah diaktifkan versioning, perhatikan hal-hal berikut:

Anda hanya dapat melakukan operasi AppendObject pada objek yang versi terkininya bertipe Appendable.
Anda tidak dapat melakukan operasi AppendObject pada objek yang versi terkininya bukan bertipe Appendable, seperti Normal Object atau Delete Marker. Operasi ini juga tidak dapat dilakukan jika hanya versi historis objek yang bertipe Appendable.
Saat Anda melakukan operasi AppendObject pada objek yang versi terkininya bertipe Appendable, OSS tidak membuat versi historis untuk objek tersebut.
Saat Anda melakukan operasi PutObject atau DeleteObject pada objek yang versi terkininya bertipe Appendable, OSS menyimpan objek Appendable tersebut sebagai versi historis. Anda tidak dapat lagi menambahkan data ke objek ini.

Kode berikut menunjukkan cara melakukan append 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;

// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah diatur.
$provider = new EnvironmentVariableCredentialsProvider();
// Titik akhir wilayah China (Hangzhou) digunakan sebagai contoh. Gantilah dengan Titik akhir yang sebenarnya.
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$bucket= "<yourBucketName>";
$object = "<yourObjectName>";
// Setelah unggah append pertama, kedua, dan ketiga, konten file masing-masing menjadi "Hello OSS", "Hi OSS", dan "OSS OK".
$content_array = array('Hello OSS', 'Hi OSS', 'OSS OK');
try{
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);

    // Unggah append pertama. Posisi untuk append pertama adalah 0. Nilai kembali adalah posisi untuk append berikutnya. Posisi untuk append selanjutnya adalah panjang file sebelum append.
    $position = $ossClient->appendObject($bucket, $object, $content_array[0], 0);    
    $position = $ossClient->appendObject($bucket, $object, $content_array[1], $position);   
    $position = $ossClient->appendObject($bucket, $object, $content_array[2], $position);
} catch(OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
print(__FUNCTION__ . ": OK" . "\n");

Untuk informasi selengkapnya tentang append upload, lihat AppendObject.

Multipart upload

Di bucket yang telah diaktifkan versioning, Anda dapat memanggil operasi CompleteMultipartUpload untuk menyelesaikan unggah multi-bagian. OSS menghasilkan ID versi unik untuk seluruh objek dan mengembalikannya dalam bidang x-oss-version-id pada header respons.

Kode berikut menunjukkan cara melakukan 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 diatur.
$provider = new EnvironmentVariableCredentialsProvider();
// Titik akhir wilayah China (Hangzhou) digunakan sebagai contoh. Gantilah dengan Titik akhir yang sebenarnya.
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$bucket= "<yourBucketName>";
$object = "<yourObjectName>";
// Tentukan path lengkap file lokal.
$uploadFile = "<yourLocalFile>";

/**
 *  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);

    // uploadId dikembalikan. uploadId adalah pengenal unik untuk event unggah multi-bagian. Anda dapat menggunakan uploadId untuk melakukan operasi terkait, seperti membatalkan atau menanyakan status unggah multi-bagian.
    $uploadId = $ossClient->initiateMultipartUpload($bucket, $object);
} catch(OssException $e) {
    printf(__FUNCTION__ . ": initiateMultipartUpload FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
print(__FUNCTION__ . ": initiateMultipartUpload OK" . "\n");
/*
 * Langkah 2: Unggah bagian-bagian.
 */
$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 bagian yang akan diunggah.
        $ossClient::OSS_SEEK_TO => $fromPos,
        // Tentukan panjang file.
        $ossClient::OSS_LENGTH => $toPos - $fromPos + 1,
        // Menentukan apakah Validasi MD5 diaktifkan. true: aktifkan. false: nonaktifkan.
        $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);
    } catch(OssException $e) {
        printf(__FUNCTION__ . ": initiateMultipartUpload, uploadPart - part#{$i} FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    printf(__FUNCTION__ . ": initiateMultipartUpload, uploadPart - part#{$i} OK\n");
}
// $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 unggahan.
 */
try {
    // Saat Anda memanggil operasi completeMultipartUpload, Anda harus menyediakan semua $uploadParts yang valid. Setelah OSS menerima $uploadParts yang dikirimkan, OSS akan memverifikasi validitas setiap bagian. Setelah semua bagian diverifikasi, OSS akan menggabungkannya menjadi satu file lengkap.
    $ret = $ossClient->completeMultipartUpload($bucket, $object, $uploadId, $uploadParts);
    // Lihat informasi versi objek.
    print("versionId:" .$ret[OssClient::OSS_HEADER_VERSION_ID]);
}  catch(OssException $e) {
    printf(__FUNCTION__ . ": completeMultipartUpload FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
printf(__FUNCTION__ . ": completeMultipartUpload OK\n");

Untuk informasi selengkapnya tentang unggah multi-bagian, lihat operasi seperti InitiateMultipartUpload, UploadPart, dan CompleteMultipartUpload.