Object Storage Service：Menyalin objek menggunakan OSS SDK untuk PHP 2.0

Catatan penggunaan

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

• Untuk menyalin objek, Anda harus memiliki izin baca pada objek sumber dan izin baca serta tulis pada bucket tujuan.

• Bucket sumber dan bucket tujuan harus berada di wilayah yang sama. Sebagai contoh, objek dalam bucket yang berlokasi di Wilayah (Hangzhou) Tiongkok tidak dapat disalin ke bucket yang berlokasi di Wilayah (Qingdao) Tiongkok.

• Pastikan tidak ada kebijakan retensi yang dikonfigurasi untuk bucket sumber dan bucket tujuan. Jika tidak, pesan kesalahan berikut akan dikembalikan: Objek yang Anda tentukan tidak dapat diubah.

• Dalam topik ini, kredensial akses diperoleh dari variabel lingkungan. Untuk informasi tentang cara mengonfigurasi kredensial akses untuk OSS SDK untuk PHP 2.0, lihat Konfigurasikan Kredensial Akses untuk PHP.

Metode

Copier

Jika Anda ingin menyalin objek dari satu bucket ke bucket lain atau memodifikasi atribut objek, Anda dapat memanggil operasi CopyObject atau operasi UploadPartCopy. Kedua operasi tersebut cocok untuk skenario yang berbeda:

• API salinan (CopyObject) hanya cocok untuk menyalin objek yang lebih kecil dari 5 GiB.

• Operasi (UploadPartCopy) cocok untuk menyalin objek yang berukuran sama dengan atau lebih besar dari 5 GiB. Perhatikan bahwa operasi ini tidak mendukung direktif (x-oss-metadata-directive) dan (x-oss-tagging-directive). Untuk mengonfigurasi metadata dan penandaan selama operasi salinan multipart, Anda memerlukan implementasi tambahan.

Manajer Salinan Baru, Copier, yang diperkenalkan di OSS SDK untuk PHP 2.0, menyediakan antarmuka tingkat tinggi yang seragam untuk menyalin objek. Ini secara otomatis memilih API salinan optimal berdasarkan parameter permintaan, mengabstraksi detail implementasi dasar dan perbedaan antarmuka. Metode umum untuk Copier didefinisikan sebagai berikut:

final class Copier
{
    ...
    public function __construct($client, array $args = [])

    public function copy(Models\CopyObjectRequest $request, array $args = []): Models\CopyResult
}

Parameter permintaan

Parameter Umum CopyObjectRequest

Parameter Umum args

Saat membuat instance klien Copier, Anda dapat menentukan opsi konfigurasi untuk menyesuaikan perilaku unduhan default untuk semua objek. Anda juga dapat menimpa pengaturan ini untuk unduhan individu dengan memberikan opsi spesifik dengan setiap permintaan unduhan.

• Tentukan parameter konfigurasi untuk Copier:

  $c = $client->newCopier(['part_size' => 100 * 1024 * 1024]);

• Tentukan parameter konfigurasi untuk setiap permintaan salinan:

  $c->copy(
      new Oss\Models\CopyObjectRequest(
          bucket: 'bucket',
          key: 'key',
          sourceBucket: 'src-bucket',
          sourceKey: 'src-key',
      ),
      args: ['part_size' => 100 * 1024 * 1024]
  );

Kode contoh

Kode berikut menyalin objek dari bucket sumber ke bucket tujuan. Secara default, metadata dan tag objek sumber juga disalin.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

// Tentukan 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. (Opsional)
    "bucket" => ['help' => 'Nama bucket', 'required' => True], // Nama bucket. (Diperlukan)
    "key" => ['help' => 'Nama objek', 'required' => True], // Nama objek tujuan. (Diperlukan)
    "src-key" => ['help' => 'Nama objek sumber', 'required' => True], // Nama objek sumber. (Diperlukan)
];

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

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

// Verifikasi bahwa semua argumen yang diperlukan telah diberikan.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // Dapatkan informasi bantuan untuk parameter.
        echo "Error: argumen berikut diperlukan: --$key, $help" . PHP_EOL;
        exit(1); // Jika parameter yang diperlukan hilang, keluar dari program.
    }
}

// Ekstrak nilai dari argumen yang telah diuraikan.
$region = $options["region"]; // Wilayah tempat bucket berada.
$bucket = $options["bucket"]; // Nama bucket.
$key = $options["key"];       // Nama objek tujuan.
$srcKey = $options["src-key"]; // Nama objek sumber.

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

// Gunakan konfigurasi default SDK.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // Tetapkan penyedia kredensial.
$cfg->setRegion($region); // Tetapkan wilayah tempat bucket berada.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // Jika titik akhir diberikan, tetapkan titik akhir.
}

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

// Buat instance Copier untuk melakukan operasi salinan.
$copier = $client->newCopier();

$dstKey = "multipart-copy-replace-empty-metadata-and-tagging-$key"; // Nama objek tujuan.
$copyRequest = new Oss\Models\CopyObjectRequest(
    bucket: $bucket,
    key: $dstKey,
    sourceBucket: $bucket,
    sourceKey: $srcKey
);
$copyRequest->metadataDirective = 'REPLACE'; // Ganti metadata.
$copyRequest->taggingDirective = 'REPLACE';  // Ganti tag.
$result = $copier->copy(request: $copyRequest);

printf(
    'status code:' . $result->statusCode . PHP_EOL . // Kode status HTTP. Contohnya, 200 menunjukkan bahwa permintaan berhasil.
    'request id:' . $result->requestId . PHP_EOL     // ID permintaan, yang digunakan untuk debugging atau melacak permintaan.
);

Skenario umum

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

// Tentukan 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. (Opsional)
    "bucket" => ['help' => 'Nama bucket', 'required' => True], // Nama bucket. (Diperlukan)
    "key" => ['help' => 'Nama objek', 'required' => True], // Nama objek tujuan. (Diperlukan)
    "src-key" => ['help' => 'Nama objek sumber', 'required' => True], // Nama objek sumber. (Diperlukan)
];

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

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

// Verifikasi bahwa semua argumen yang diperlukan telah diberikan.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // Dapatkan informasi bantuan untuk parameter.
        echo "Error: argumen berikut diperlukan: --$key, $help" . PHP_EOL;
        exit(1); // Jika parameter yang diperlukan hilang, keluar dari program.
    }
}

// Ekstrak nilai dari argumen yang telah diuraikan.
$region = $options["region"]; // Wilayah tempat bucket berada.
$bucket = $options["bucket"]; // Nama bucket.
$key = $options["key"];       // Nama objek tujuan.
$srcKey = $options["src-key"]; // Nama objek sumber.

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

// Gunakan konfigurasi default SDK.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // Tetapkan penyedia kredensial.
$cfg->setRegion($region); // Tetapkan wilayah tempat bucket berada.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // Jika titik akhir diberikan, tetapkan titik akhir.
}

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

// Buat instance Copier untuk melakukan operasi salinan.
$copier = $client->newCopier();

// Kasus 1: Salinan multipart dengan metadata dan tag kosong.
$dstKey = "multipart-copy-replace-empty-metadata-and-tagging-$key"; // Nama objek tujuan.
$copyRequest = new Oss\Models\CopyObjectRequest(
    bucket: $bucket,
    key: $dstKey,
    sourceBucket: $bucket,
    sourceKey: $srcKey
);
$copyRequest->metadataDirective = 'REPLACE'; // Ganti metadata.
$copyRequest->taggingDirective = 'REPLACE';  // Ganti tag.
$result = $copier->copy(
    request: $copyRequest,
    args: [
        'part_size' => 1 * 1024 * 1024, // Tentukan ukuran bagian sebagai 1 MB.
        'parallel_num' => 5    // Tentukan konkurensi untuk tugas salinan sebagai 5.
    ]
);
printf(
    'status code:' . $result->statusCode . PHP_EOL . // Kode status HTTP. Contohnya, 200 menunjukkan bahwa permintaan berhasil.
    'request id:' . $result->requestId . PHP_EOL     // ID permintaan, yang digunakan untuk debugging atau melacak permintaan.
);

Referensi

• Untuk kode contoh lengkap untuk manajer salinan, lihat GitHub.