pengunduh file php - Object Storage Service

Tema ini menjelaskan cara menggunakan modul Downloader di OSS SDK untuk PHP V2 untuk mengunduh file.

Catatan

Kode contoh dalam tema ini menggunakan Titik akhir publik wilayah China (Hangzhou) (cn-hangzhou). Jika Anda ingin mengakses OSS dari layanan Alibaba Cloud lainnya di wilayah yang sama, Anda dapat menggunakan Titik akhir internal. Untuk informasi lebih lanjut tentang pemetaan wilayah dan titik akhir OSS, lihat Wilayah dan titik akhir.
Tema ini memberikan contoh mendapatkan kredensial akses dari variabel lingkungan. Untuk informasi lebih lanjut, lihat Konfigurasi kredensial akses untuk PHP.
Untuk mengunduh file, Anda harus memiliki izin oss:GetObject. Untuk informasi lebih lanjut, lihat Memberikan izin khusus kepada Pengguna RAM.

Definisi metode

Pengenalan fitur Downloader

Modul Downloader dari OSS SDK untuk PHP V2 menyediakan antarmuka tingkat tinggi yang menyederhanakan proses pengunduhan file dengan mengabstraksi detail implementasi dasar.

Modul Downloader menggunakan Unduhan rentang untuk secara otomatis membagi file menjadi beberapa shard kecil untuk pengunduhan bersamaan, meningkatkan performa pengunduhan.
Modul Downloader juga mendukung unduhan yang dapat dilanjutkan. Selama pengunduhan, status shard yang selesai dicatat. Jika pengunduhan gagal karena gangguan jaringan atau keluar program yang tidak terduga, Anda dapat menggunakan file rekaman breakpoint untuk melanjutkan pengunduhan dari shard terakhir yang berhasil.

Tabel berikut menjelaskan metode umum dari modul Downloader.

final class Downloader
{
	...
    public function __construct($client, array $args = [])
    
    public function downloadFile(Models\GetObjectRequest $request, string $filepath, array $args = []): Models\DownloadResult   
    
    public function downloadTo(Models\GetObjectRequest $request, \Psr\Http\Message\StreamInterface $stream, array $args = []): Models\DownloadResult
}

Parameter permintaan

Parameter	Tipe	Deskripsi
request	GetObjectRequest	Parameter permintaan untuk unduhan objek. Parameter tersebut sama dengan yang digunakan dalam operasi GetObject.
filePath	string	Path file lokal.
args	array	(Opsional) Opsi konfigurasi.

Tabel berikut menjelaskan parameter umum dalam args.

Parameter	Tipe	Deskripsi
part_size	int	Ukuran shard. Nilai default adalah 6 MiB.
parallel_num	int	Jumlah tugas unduhan bersamaan. Nilai default adalah 3. Parameter ini menentukan batas konkurensi untuk satu panggilan saja, bukan batas konkurensi global.
use_temp_file	bool	Menentukan apakah akan menggunakan file sementara saat Anda mengunduh file. Secara default, file sementara digunakan. File pertama kali diunduh ke file sementara. Setelah unduhan berhasil, file sementara diubah namanya menjadi file objek.

Saat membuat instance Downloader, Anda dapat menentukan opsi konfigurasi untuk menyesuaikan perilaku unduhan. Opsi ini dapat diterapkan saat membuat instance Downloader atau untuk setiap panggilan unduhan individual.

Atur parameter konfigurasi untuk instance Downloader:

$d = $client->newDownloader(['part_size' => 10 * 1024 * 1024]);

Atur parameter konfigurasi untuk setiap permintaan unduhan:

$d->downloadFile(
    new Oss\Models\GetObjectRequest(
        bucket: 'bucket',
        key: 'key'
    ),
    filepath: '/local/dir/example',
    args: ['part_size' => 10 * 1024 * 1024]
);

Kode contoh

Gunakan kode berikut untuk mengunduh file dari bucket ke mesin lokal Anda.

<?php

// Impor file autoload untuk memastikan bahwa pustaka dependensi 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. (Wajib)
    "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. (Wajib)
    "key" => ['help' => 'Nama objek', 'required' => True], // Nama objek. (Wajib)
];

// Ubah deskripsi argumen ke format opsi panjang yang diperlukan oleh getopt.
// Tambahkan titik dua (:) di akhir setiap argumen untuk menentukan bahwa nilai diperlukan.
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

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

// Verifikasi bahwa argumen yang diperlukan ada.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // Dapatkan informasi bantuan tentang argumen.
        echo "Error: argumen berikut diperlukan: --$key, $help" . PHP_EOL;
        exit(1); // Jika argumen yang diperlukan hilang, 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.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // Jika titik akhir disediakan, atur titik akhir.
}

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

// Buat instance downloader.
$downloader = $client->newDownloader();

// Tentukan path file lokal untuk menyimpan konten yang diunduh.
$filename = "/Users/yourLocalPath/yourFileName"; // Contoh path file.
touch($filename); // Buat file kosong untuk memastikan bahwa file tersebut ada.

// Lakukan operasi unduhan terpecah.
$result = $downloader->downloadFile(
    new Oss\Models\GetObjectRequest(
        bucket: $bucket,
        key: $key
    ),
    $filename
);

// Cetak hasil unduhan.
printf(
    'kode status unduhan:' . $result->statusCode . PHP_EOL .
    'ID permintaan unduhan:' . $result->requestId . PHP_EOL .
    'hasil unduhan:' . var_export($result, true) . PHP_EOL
);

Skenario

Gunakan Downloader untuk menetapkan ukuran shard dan konkurensi

Gunakan kode berikut untuk menetapkan ukuran shard dan konkurensi untuk downloader.

<?php

// Impor file autoload untuk memastikan bahwa pustaka dependensi 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. (Wajib)
    "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. (Wajib)
    "key" => ['help' => 'Nama objek', 'required' => True], // Nama objek. (Wajib)
];

// Ubah deskripsi argumen ke format opsi panjang yang diperlukan oleh getopt.
// Tambahkan titik dua (:) di akhir setiap argumen untuk menentukan bahwa nilai diperlukan.
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

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

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

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

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

// Buat instance downloader.
$downloader = $client->newDownloader();

// Tentukan parameter yang terkait dengan unduhan terpecah.
$partSize = 100 * 1024; // Ukuran shard dalam byte. Dalam contoh ini, ukuran shard diatur menjadi 100 KB.

// Tentukan path file lokal untuk menyimpan konten yang diunduh.
$filename = "/Users/yourLocalPath/yourFileName"; // Contoh path file.
touch($filename); // Buat file kosong untuk memastikan bahwa file tersebut ada.

// Lakukan operasi unduhan terpecah.
$result = $downloader->downloadFile(
    new Oss\Models\GetObjectRequest(
        bucket: $bucket,
        key: $key
    ),
    $filename,
    args: [ // Parameter opsional yang digunakan untuk menyesuaikan perilaku unduhan terpecah.
        'part_size' => $partSize, // Ukuran shard kustom.
        'parallel_num' => 1,      // Jumlah shard yang dapat diunduh secara paralel.
    ]
);

// Cetak hasil unduhan.
printf(
    'kode status unduhan:' . $result->statusCode . PHP_EOL .
    'ID permintaan unduhan:' . $result->requestId . PHP_EOL .
    'hasil unduhan:' . var_export($result, true) . PHP_EOL
);

Gunakan Downloader untuk mengunduh ke aliran

<?php

// Impor file autoload untuk memastikan bahwa pustaka dependensi 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. (Wajib)
    "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. (Wajib)
    "key" => ['help' => 'Nama objek', 'required' => True], // Nama objek. (Wajib)
];

// Ubah deskripsi argumen ke format opsi panjang yang diperlukan oleh getopt.
// Tambahkan titik dua (:) di akhir setiap argumen untuk menentukan bahwa nilai diperlukan.
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

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

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

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

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

// Buat instance downloader.
$downloader = $client->newDownloader();

// Tentukan aliran buffer untuk menyimpan konten yang diunduh.
$stream = new \GuzzleHttp\Psr7\BufferStream(1 * 1024 * 1024); // Ukuran buffer adalah 1 MB.

// Lakukan operasi unduhan untuk mengunduh konten objek ke aliran buffer.
$result = $downloader->downloadTo(
    request: new Oss\Models\GetObjectRequest(
        bucket: $bucket,
        key: $key // Tentukan nama objek yang ingin Anda unduh.
    ),
    stream: $stream, // Tentukan aliran tujuan untuk menyimpan konten yang diunduh.
);

// Cetak konten yang diunduh.
printf(
    'unduh ke body:' . $stream->getContents() . PHP_EOL // Keluarkan konten dalam aliran buffer.
);

Referensi

Untuk contoh downloader lengkap, lihat contoh GitHub.