unduhan sederhana menggunakan PHP - Object Storage Service

Topik ini menjelaskan cara menggunakan metode unduhan sederhana untuk mengunduh objek dari bucket ke file lokal. Metode ini mudah digunakan dan cocok untuk mengunduh objek dari OSS ke komputer lokal Anda dengan cepat.

Perhatian

Kode contoh dalam topik ini menggunakan Wilayah China (Hangzhou) (ID Wilayah: cn-hangzhou) sebagai contoh. Secara default, titik akhir Internet 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 mengunduh objek ke file lokal, Anda harus memiliki izin oss:GetObject. Untuk informasi lebih lanjut, lihat Memberikan Kebijakan Akses Kustom kepada Pengguna RAM.
Topik ini memberikan contoh cara memperoleh kredensial akses dari variabel lingkungan. Untuk informasi lebih lanjut tentang cara mengonfigurasi kredensial akses, lihat Mengonfigurasi Kredensial Akses untuk PHP.

Kode Contoh

Gunakan kode berikut untuk mengunduh objek dari bucket ke file lokal.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

// Tentukan deskripsi parameter 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. (Diperlukan)
];

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

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

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

// Ekstrak nilai dari parameter 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); // Setel penyedia kredensial.
$cfg->setRegion($region); // Setel wilayah tempat bucket berada.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // Jika titik akhir disediakan, setel titik akhir.
}

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

// Buat objek GetObjectRequest untuk mendapatkan konten objek yang ditentukan.
$request = new Oss\Models\GetObjectRequest(bucket: $bucket, key: $key);

// Jalankan operasi get object.
$result = $client->getObject($request);

// Tentukan jalur file lokal yang akan disimpan.
$localFilePath = 'path/to/local/file.txt'; // Ganti dengan jalur file sebenarnya.

// Tulis konten ke file lokal.
file_put_contents( $localFilePath, $result->body->getContents());

// Cetak hasilnya.
// Keluarkan kode status HTTP, ID permintaan, dan konten objek.
printf(
    'kode status:' . $result->statusCode . PHP_EOL . // Kode status HTTP. Misalnya, 200 menunjukkan bahwa permintaan berhasil.
    'id permintaan:' . $result->requestId . PHP_EOL  // ID permintaan, yang digunakan untuk debugging atau melacak permintaan.
);

Skenario

Unduhan Bersyarat

Saat Anda mengunduh objek dari bucket, Anda dapat menentukan kondisi berdasarkan waktu modifikasi terakhir objek atau ETag. ETag adalah pengenal untuk konten file. Operasi unduhan dilakukan hanya jika kondisi-kondisi ini terpenuhi. Jika kondisi tidak terpenuhi, kesalahan dikembalikan dan unduhan tidak dipicu. Unduhan bersyarat dapat mengurangi lalu lintas jaringan dan konsumsi sumber daya yang tidak perlu, serta meningkatkan efisiensi unduhan.

Tabel berikut menjelaskan kondisi yang didukung oleh OSS.

Catatan

Anda dapat menentukan If-Modified-Since dan If-Unmodified-Since dalam permintaan yang sama. Anda juga dapat menentukan If-Match dan If-None-Match dalam permintaan yang sama.
Anda dapat memanggil metode ossClient.getObjectMeta untuk mendapatkan ETag.

Parameter	Deskripsi
IfModifiedSince	Jika waktu yang ditentukan lebih awal dari waktu modifikasi aktual objek, objek diunduh. Jika tidak, kesalahan 304 Not Modified dikembalikan.
IfUnmodifiedSince	Jika waktu yang ditentukan sama dengan atau lebih baru dari waktu modifikasi aktual objek, objek diunduh. Jika tidak, kesalahan 412 Precondition Failed dikembalikan.
IfMatch	Jika ETag yang ditentukan cocok dengan ETag objek OSS, objek diunduh. Jika tidak, kesalahan 412 Precondition Failed dikembalikan.
IfNoneMatch	Jika ETag yang ditentukan tidak cocok dengan ETag objek OSS, objek diunduh. Jika tidak, kesalahan 304 Not Modified dikembalikan.

Berikut adalah contoh kode untuk melakukan unduhan bersyarat.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

// Tentukan deskripsi parameter 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. (Diperlukan)
];

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

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

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

// Ekstrak nilai dari parameter 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); // Setel penyedia kredensial.
$cfg->setRegion($region); // Setel wilayah tempat bucket berada.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // Jika titik akhir disediakan, setel titik akhir.
}

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

// Anggaplah waktu modifikasi terakhir objek adalah 18:43:02 pada 21 Oktober 2024. Jika waktu UTC yang ditentukan lebih awal dari waktu ini, kondisi IfModifiedSince terpenuhi dan unduhan dipicu.
$ifModifiedSince = "Sun, 21 Oct 2024 18:43:02 GMT";

// Anggaplah ETag adalah e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. Jika ETag yang ditentukan sama dengan ETag objek, kondisi IfMatch terpenuhi dan unduhan dipicu.
$etag = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";

// Buat objek GetObjectRequest untuk mendapatkan konten objek yang ditentukan.
$request = new Oss\Models\GetObjectRequest(
            bucket: $bucket,
            key: $key,
            ifModifiedSince: $ifModifiedSince,
            ifMatch: $etag);

// Jalankan operasi get object.
$result = $client->getObject($request);

// Cetak hasilnya.
// Keluarkan kode status HTTP, ID permintaan, dan konten objek.
printf(
    'kode status:' . $result->statusCode . PHP_EOL . // Kode status HTTP. Misalnya, 200 menunjukkan bahwa permintaan berhasil.
    'id permintaan:' . $result->requestId . PHP_EOL . // ID permintaan, yang digunakan untuk debugging atau melacak permintaan.
    'konten objek:' . $result->body->getContents() . PHP_EOL // Konten objek.
);

Unduhan Streaming

Gunakan kode berikut untuk mengaktifkan unduhan streaming dengan menyetel parameter stream saat memanggil operasi GetObject.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

// Tentukan deskripsi parameter 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. (Diperlukan)
];

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

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

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

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

// Gunakan EnvironmentVariableCredentialsProvider untuk memuat kredensial akses dari variabel lingkungan.
// Pastikan bahwa variabel lingkungan ALIBABA_CLOUD_ACCESS_KEY_ID dan ALIBABA_CLOUD_ACCESS_KEY_SECRET disetel dengan benar.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Muat konfigurasi default dari SDK.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // Setel penyedia kredensial.
$cfg->setRegion($region); // Setel wilayah tempat bucket berada.

// Jika parameter titik akhir disediakan di baris perintah, gunakan titik akhir yang ditentukan.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

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

// Buat objek GetObjectRequest dan tentukan bucket dan kunci objek.
$request = new Oss\Models\GetObjectRequest(bucket: $bucket, key: $key);

// Panggil metode getObject untuk mengunduh objek. Setel opsi stream ke true untuk memproses file besar dalam aliran.
$result = $client->getObject(request: $request, args: ['request_options' => ['stream' => true]]);

// Dapatkan objek aliran.
$stream = $result->body;

// Baca konten aliran (dalam chunk).
while (!$stream->eof()) { // Periksa apakah aliran telah berakhir.
    echo $stream->read(1024); // Baca 1 KB data sekaligus dan keluarkan data.
}

Tampilkan Kemajuan Unduhan

Gunakan kode berikut untuk menampilkan kemajuan unduhan saat memanggil operasi GetObject.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

// Tentukan deskripsi parameter 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. (Diperlukan)
];

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

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

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

// Ekstrak nilai dari parameter yang telah diparsed.
$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); // Setel penyedia kredensial.
$cfg->setRegion($region); // Setel wilayah tempat bucket berada.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // Jika titik akhir disediakan, setel titik akhir.
}

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

// Buat objek GetObjectRequest untuk mendapatkan konten objek yang ditentukan.
$request = new Oss\Models\GetObjectRequest(
            bucket: $bucket,
            key: $key,
);

# Setel fungsi callback kemajuan untuk menampilkan informasi kemajuan unduhan.
$request->progressFn = static function (int $increment, int $transferred, int $total) {
    echo sprintf("Diunduh: %d" . PHP_EOL, $transferred);
    echo sprintf("Unduhan saat ini: %d" . PHP_EOL, $increment);
    echo sprintf("Total data: %d" . PHP_EOL, $total);
    echo '-------------------------------------------' . PHP_EOL;
};

// Jalankan operasi get object.
$result = $client->getObject($request);

// Cetak hasilnya.
// Keluarkan kode status HTTP, ID permintaan, dan konten objek.
printf(
    'kode status:' . $result->statusCode . PHP_EOL . // Kode status HTTP. Misalnya, 200 menunjukkan bahwa permintaan berhasil.
    'id permintaan:' . $result->requestId . PHP_EOL . // ID permintaan, yang digunakan untuk debugging atau melacak permintaan.
    'konten objek:' . $result->body->getContents() . PHP_EOL // Konten objek.
);

Referensi

Untuk kode contoh lengkap yang digunakan untuk mengunduh objek ke file lokal, lihat contoh GitHub.