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

Catatan

• Kode contoh dalam topik ini menggunakan Wilayah China (Hangzhou) sebagai contoh, dengan ID wilayah cn-hangzhou. Secara default, titik akhir publik digunakan. Jika Anda ingin mengakses OSS dari layanan Alibaba Cloud lainnya di wilayah yang sama, gunakan titik akhir internal. Untuk informasi lebih lanjut tentang wilayah dan titik akhir yang didukung oleh OSS, lihat Wilayah dan Titik Akhir OSS.

• Untuk melakukan unggah multi-bagian, Anda harus memiliki izin oss:PutObject. Untuk informasi lebih lanjut, lihat Memberikan Kebijakan Akses Kustom kepada Pengguna RAM.

• Topik ini memberikan contoh cara membaca kredensial akses dari variabel lingkungan. Untuk lebih banyak contoh tentang cara mengonfigurasi kredensial akses, lihat Konfigurasikan Kredensial Akses untuk PHP.

Alur unggah multi-bagian

Proses unggah multi-bagian terdiri dari tiga langkah berikut:

1. Inisialisasi event unggah multi-bagian.

   Panggil metode InitiateMultipartUpload untuk mendapatkan ID unggah yang unik secara global dari OSS.

2. Unggah bagian-bagian.

   Panggil metode UploadPart untuk mengunggah data setiap bagian.

   Catatan

   • Jika Anda mengunggah data baru dengan nomor bagian yang sama, data bagian yang ada di OSS akan ditimpa.

   • OSS menyertakan hash MD5 dari data bagian yang diterima dalam header ETag dan mengembalikan header tersebut kepada Anda.

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

3. Selesaikan unggah multi-bagian.

   Setelah semua bagian diunggah, panggil metode CompleteMultipartUpload untuk menggabungkan bagian-bagian menjadi file yang lengkap.

Kode contoh

Berikut adalah contoh kode yang menunjukkan cara membagi file lokal besar menjadi beberapa bagian, mengunggah bagian-bagian tersebut ke bucket, dan kemudian menggabungkannya menjadi objek yang lengkap.

<?php

// Impor file autoloader untuk memastikan bahwa library dependensi dapat dimuat dengan benar.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Definisikan deskripsi argumen baris perintah.
$optsdesc = [
    "region" => ['help' => 'Wilayah tempat bucket berada.', 'required' => True], // Wilayah tempat bucket berada. (Diperlukan)
    "endpoint" => ['help' => 'Nama domain yang dapat digunakan layanan lain untuk mengakses OSS.', 'required' => False], // Titik akhir yang dapat digunakan untuk mengakses OSS. (Opsional)
    "bucket" => ['help' => 'Nama bucket', 'required' => True], // Nama bucket. (Diperlukan)
    "key" => ['help' => 'Nama objek', 'required' => True], // Nama objek. (Diperlukan)
];

// Konversikan deskripsi argumen ke format opsi panjang yang diperlukan oleh getopt.
// Tanda titik dua (:) setelah setiap argumen menunjukkan bahwa argumen tersebut memerlukan nilai.
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// Parsing argumen baris perintah.
$options = getopt("", $longopts);

// Periksa apakah argumen yang diperlukan ada.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // Dapatkan informasi bantuan dari argumen.
        echo "Error: argumen berikut diperlukan: --$key, $help" . PHP_EOL;
        exit(1); // Jika argumen yang diperlukan tidak ada, keluar dari program.
    }
}

// Ekstrak nilai dari argumen yang telah diparsing.
$region = $options["region"]; // Wilayah tempat bucket berada.
$bucket = $options["bucket"]; // Nama bucket.
$key = $options["key"];       // Nama objek.

// Muat informasi kredensial dari variabel lingkungan.
// Gunakan EnvironmentVariableCredentialsProvider untuk membaca Access Key ID dan Access Key Secret dari variabel lingkungan.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Gunakan konfigurasi default dari SDK.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // Atur penyedia kredensial.
$cfg->setRegion($region); // Atur wilayah tempat bucket berada.
$cfg->setEndpoint('http://oss-cn-hangzhou.aliyuncs.com'); // Atur titik akhir.

// Buat instance klien OSS.
$client = new Oss\Client($cfg);

// Inisialisasi tugas unggah multi-bagian.
$initResult = $client->initiateMultipartUpload(
    new Oss\Models\InitiateMultipartUploadRequest(
        bucket: $bucket,
        key: $key
    )
);

// Definisikan jalur file besar dan ukuran bagian.
$bigFileName = "/Users/yourLocalPath/yourFileName"; // Tentukan jalur file besar.
$partSize = 5 * 1024 * 1024; // Tetapkan ukuran bagian dalam byte. Dalam contoh ini, ukuran bagian diatur menjadi 5 MB.
$fileSize = filesize($bigFileName); // Dapatkan ukuran file.
$partsNum = intdiv($fileSize, $partSize) + intval(1); // Hitung jumlah bagian.
$parts = []; // Digunakan untuk menyimpan hasil unggah setiap bagian.

$i = 1; // Nomor bagian dimulai dari 1.
$file = new \GuzzleHttp\Psr7\LazyOpenStream($bigFileName, 'rb'); // Buka aliran file.
while ($i <= $partsNum) {
    // Unggah satu bagian.
    $partResult = $client->uploadPart(
        new Oss\Models\UploadPartRequest(
            bucket: $bucket,
            key: $key,
            partNumber: $i, // Nomor bagian saat ini.
            uploadId: $initResult->uploadId, // ID unggah yang dikembalikan oleh tugas unggah yang diinisiasi.
            contentLength: null, // Opsional: Panjang konten bagian.
            contentMd5: null, // Opsional: Hash MD5 dari konten bagian untuk validasi.
            trafficLimit: null, // Opsional: Batas lalu lintas.
            requestPayer: null, // Opsional: Peminta membayar permintaan.
            body: new \GuzzleHttp\Psr7\LimitStream($file, $partSize, ($i - 1) * $partSize) // Baca data bagian saat ini.
        )
    );

    // Simpan hasil unggah bagian.
    $part = new Oss\Models\UploadPart(
        partNumber: $i, // Nomor bagian.
        etag: $partResult->etag // Nilai ETag yang dikembalikan setelah bagian diunggah.
    );

    array_push($parts, $part); // Simpan hasil unggah bagian saat ini ke daftar bagian.
    $i++; // Tingkatkan nomor bagian untuk memproses bagian berikutnya.
}

// Selesaikan tugas unggah multi-bagian.
$comResult = $client->completeMultipartUpload(
    new Oss\Models\CompleteMultipartUploadRequest(
        bucket: $bucket,
        key: $key,
        uploadId: $initResult->uploadId, // ID unggah yang dikembalikan oleh tugas unggah yang diinisiasi.
        acl: null, // Opsional: Atur daftar kontrol akses (ACL) dari objek.
        completeMultipartUpload: new Oss\Models\CompleteMultipartUpload(
            parts: $parts // Kirim hasil unggah semua bagian.
        )
    )
);

// Cetak hasil unggah multi-bagian yang selesai.
printf(
    'status code:' . $comResult->statusCode . PHP_EOL . // Kode status HTTP. Misalnya, 200 menunjukkan bahwa permintaan berhasil.
    'request id:' . $comResult->requestId . PHP_EOL .   // ID permintaan, yang digunakan untuk debugging atau melacak permintaan.
    'hasil unggah multi-bagian lengkap:' . var_export($comResult, true) . PHP_EOL // Hasil rinci setelah unggah multi-bagian selesai.
);

Skenario

<?php

// Impor file autoloader untuk memastikan bahwa library dependensi dapat dimuat dengan benar.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Definisikan deskripsi argumen baris perintah.
$optsdesc = [
    "region" => ['help' => 'Wilayah tempat bucket berada.', 'required' => True], // Wilayah tempat bucket berada. (Diperlukan)
    "endpoint" => ['help' => 'Nama domain yang dapat digunakan layanan lain untuk mengakses OSS.', 'required' => False], // Titik akhir yang dapat digunakan untuk mengakses OSS. (Opsional)
    "bucket" => ['help' => 'Nama bucket', 'required' => True], // Nama bucket. (Diperlukan)
    "key" => ['help' => 'Nama objek', 'required' => True], // Nama objek. (Diperlukan)
];

// Konversikan deskripsi argumen ke format opsi panjang yang diperlukan oleh getopt.
// Tanda titik dua (:) setelah setiap argumen menunjukkan bahwa argumen tersebut memerlukan nilai.
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// Parsing argumen baris perintah.
$options = getopt("", $longopts);

// Periksa apakah argumen yang diperlukan ada.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // Dapatkan informasi bantuan dari argumen.
        echo "Error: argumen berikut diperlukan: --$key, $help" . PHP_EOL;
        exit(1); // Jika argumen yang diperlukan tidak ada, keluar dari program.
    }
}

// Ekstrak nilai dari argumen yang telah diparsing.
$region = $options["region"]; // Wilayah tempat bucket berada.
$bucket = $options["bucket"]; // Nama bucket.
$key = $options["key"];       // Nama objek.

// Muat informasi kredensial dari variabel lingkungan.
// Gunakan EnvironmentVariableCredentialsProvider untuk membaca Access Key ID dan Access Key Secret dari variabel lingkungan.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Gunakan konfigurasi default dari SDK.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // Atur penyedia kredensial.
$cfg->setRegion($region); // Atur wilayah tempat bucket berada.
$cfg->setEndpoint('http://oss-cn-hangzhou.aliyuncs.com'); // Atur titik akhir.

// Buat instance klien OSS.
$client = new Oss\Client($cfg);

// Inisialisasi tugas unggah multi-bagian.
$initResult = $client->initiateMultipartUpload(
    new Oss\Models\InitiateMultipartUploadRequest(
        bucket: $bucket,
        key: $key
    )
);

// Definisikan jalur file besar dan ukuran bagian.
$bigFileName = "/Users/yourLocalPath/yourFileName"; // Tentukan jalur file besar.
$partSize = 5 * 1024 * 1024; // Tetapkan ukuran bagian dalam byte. Dalam contoh ini, ukuran bagian diatur menjadi 5 MB.
$fileSize = filesize($bigFileName); // Dapatkan ukuran file.
$partsNum = intdiv($fileSize, $partSize) + intval(1); // Hitung jumlah bagian.
$parts = []; // Digunakan untuk menyimpan hasil unggah setiap bagian.

$i = 1; // Nomor bagian dimulai dari 1.
$file = new \GuzzleHttp\Psr7\LazyOpenStream($bigFileName, 'rb'); // Buka aliran file.
while ($i <= $partsNum) {
    // Unggah satu bagian.
    $partResult = $client->uploadPart(
        new Oss\Models\UploadPartRequest(
            bucket: $bucket,
            key: $key,
            partNumber: $i, // Nomor bagian saat ini.
            uploadId: $initResult->uploadId, // ID unggah yang dikembalikan oleh tugas unggah yang diinisiasi.
            contentLength: null, // Opsional: Panjang konten bagian.
            contentMd5: null, // Opsional: Hash MD5 dari konten bagian untuk validasi.
            trafficLimit: null, // Opsional: Batas lalu lintas.
            requestPayer: null, // Opsional: Peminta membayar permintaan.
            body: new \GuzzleHttp\Psr7\LimitStream($file, $partSize, ($i - 1) * $partSize) // Baca data bagian saat ini.
        )
    );

    // Simpan hasil unggah bagian.
    $part = new Oss\Models\UploadPart(
        partNumber: $i, // Nomor bagian.
        etag: $partResult->etag // Nilai ETag yang dikembalikan setelah bagian diunggah.
    );

    array_push($parts, $part); // Simpan hasil unggah bagian saat ini ke daftar bagian.
    $i++; // Tingkatkan nomor bagian untuk memproses bagian berikutnya.
}


// Tambahkan header x-oss-callback dan x-oss-callback-var.
// Definisikan alamat webhook.
$call_back_url = "http://www.example.com/callback";

// Bangun parameter callback: Tentukan alamat webhook dan badan permintaan untuk callback. Gunakan pengkodean Base64.
// Gunakan placeholder {var1} dan {var2} untuk mengganti ${x:var1} dan ${x:var2}.
$callback_body_template = "bucket={bucket}&object={object}&my_var_1={var1}&my_var_2={var2}";
$callback_body_replaced = str_replace(
    ['{bucket}', '{object}', '{var1}', '{var2}'],
    [$bucket, $key, 'value1', 'value2'],
    $callback_body_template
);
$callback = base64_encode(json_encode([
    "callbackUrl" => $call_back_url,
    "callbackBody" => $callback_body_replaced
]));

// Bangun variabel kustom (callback-var). Gunakan pengkodean Base64.
$callback_var = base64_encode(json_encode([
    "x:var1" => "value1",
    "x:var2" => "value2"
]));

// Selesaikan tugas unggah multi-bagian.
$comResult = $client->completeMultipartUpload(
    new Oss\Models\CompleteMultipartUploadRequest(
        bucket: $bucket,
        key: $key,
        uploadId: $initResult->uploadId, // ID unggah yang dikembalikan oleh tugas unggah yang diinisiasi.
        acl: null, // Opsional: Atur daftar kontrol akses (ACL) dari objek.
        completeMultipartUpload: new Oss\Models\CompleteMultipartUpload(
            parts: $parts // Kirim hasil unggah semua bagian.
        ),
        callback: $callback,
        callbackVar: $callback_var,
    )
);

// Cetak hasil unggah multi-bagian yang selesai.
printf(
    'status code:' . $comResult->statusCode . PHP_EOL . // Kode status HTTP. Misalnya, 200 menunjukkan bahwa permintaan berhasil.
    'request id:' . $comResult->requestId . PHP_EOL .   // ID permintaan, yang digunakan untuk debugging atau melacak permintaan.
    'hasil unggah multi-bagian lengkap:' . var_export($comResult, true) . PHP_EOL // Hasil rinci setelah unggah multi-bagian selesai.
);

Referensi

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