Topik ini menjelaskan cara menggunakan modul Uploader di Object Storage Service (OSS) SDK untuk PHP V2 guna mengunggah file.
Catatan penggunaan
Topik ini menggunakan titik akhir publik Wilayah China (Hangzhou) (
cn-hangzhou) sebagai contoh. Jika Anda mengakses OSS dari layanan Alibaba Cloud lainnya di wilayah yang sama, gunakan titik akhir internal. Untuk informasi lebih lanjut tentang pemetaan wilayah dan titik akhir OSS, lihat Wilayah dan Titik Akhir.Untuk mengunggah file, Anda memerlukan izin
oss:PutObject. Untuk informasi lebih lanjut, lihat Melampirkan Kebijakan Kustom ke Pengguna RAM.Topik ini menggunakan variabel lingkungan untuk mendapatkan kredensial akses. Untuk informasi lebih lanjut tentang cara mengonfigurasi kredensial akses, lihat Konfigurasikan Kredensial Akses untuk OSS SDK untuk PHP.
Definisi metode
Ikhtisar Pengunggah
Modul Uploader dari OSS SDK untuk PHP V2 menyediakan operasi API umum untuk menyederhanakan pengunggahan file.
Modul Uploader menggunakan operasi unggah multi-bagian untuk membagi file besar atau aliran menjadi beberapa bagian untuk pengunggahan paralel, sehingga meningkatkan kinerja pengunggahan.
Modul Uploader juga mendukung kemampuan unggah yang dapat dilanjutkan. Selama pengunggahan, status bagian yang diunggah dicatat. Jika pengunggahan gagal karena masalah seperti gangguan jaringan atau keluar program yang tidak terduga, Anda dapat melanjutkan pengunggahan dari titik putus yang direkam.
Modul Uploader memiliki metode umum berikut:
final class Uploader
{
...
public function __construct($client, array $args = [])
public function uploadFile(Models\PutObjectRequest $request, string $filepath, array $args = []): Models\UploadResult
public function uploadFrom(Models\PutObjectRequest $request, StreamInterface $stream, array $args = []): Models\UploadResult
...
}Parameter permintaan
Parameter | Tipe | Deskripsi |
request | PutObjectRequest | Parameter permintaan untuk pengunggahan objek. Parameter tersebut sama dengan operasi PutObject. |
stream | StreamInterface | Aliran yang akan diunggah. |
filePath | string | Jalur file lokal. |
args | array | (Opsional) Opsi konfigurasi. |
Tabel berikut menjelaskan parameter umum dalam args.
Parameter | Tipe | Deskripsi |
part_size | int | Ukuran bagian. Nilai default adalah 6 MiB. |
parallel_num | int | Jumlah tugas unggah bersamaan. Nilai default adalah 3. Parameter ini menentukan batas konkurensi untuk satu panggilan, bukan batas konkurensi global. |
leave_parts_on_error | bool | Menentukan apakah akan mempertahankan bagian yang diunggah saat pengunggahan gagal. Secara default, bagian yang diunggah tidak dipertahankan. |
Saat menggunakan newUploader untuk membuat instance Uploader, Anda dapat menentukan opsi konfigurasi untuk menyesuaikan perilaku pengunggahan. Anda juga dapat menentukan opsi konfigurasi untuk setiap operasi pengunggahan guna menyesuaikan perilaku untuk objek tertentu.
Atur parameter konfigurasi untuk Uploader
$u = $client->newUploader(['part_size' => 10 * 1024 * 1024]);Atur parameter konfigurasi untuk setiap permintaan pengunggahan
$u->uploadFile( new Oss\Models\PutObjectRequest( bucket: 'bucket', key: 'key' ), filepath: '/local/dir/example', args: [ 'part_size' => 10 * 1024 * 1024, ] );
Kode contoh
Berikut adalah kode sampel yang menunjukkan cara menggunakan uploader untuk mengunggah file lokal ke bucket.
<?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 (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).
];
// 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 parameter yang diperlukan ada.
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 parameter yang telah diuraikan.
$region = $options["region"]; // Wilayah tempat bucket berada.
$bucket = $options["bucket"]; // Nama bucket.
$key = $options["key"]; // Nama objek.
// Muat kredensial akses 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);
// Tentukan path file lokal untuk diunggah.
$filename = "/Users/yourLocalPath/yourFileName"; // Contoh path file.
// Buat instance uploader.
$uploader = $client->newUploader();
// Jalankan operasi unggah multi-bagian.
$result = $uploader->uploadFile(
request: new Oss\Models\PutObjectRequest(bucket: $bucket, key: $key), // Buat objek PutObjectRequest dan tentukan nama bucket dan objek.
filepath: $filename, // Tentukan path file lokal untuk diunggah.
);
// Cetak hasil unggah multi-bagian.
printf(
'status code unggah multi-bagian:' . $result->statusCode . PHP_EOL . // Kode status HTTP. Misalnya, 200 menunjukkan sukses.
'ID permintaan unggah multi-bagian:' . $result->requestId . PHP_EOL . // ID permintaan, yang digunakan untuk debugging atau melacak permintaan.
'hasil unggah multi-bagian:' . var_export($result, true) . PHP_EOL // Hasil rinci dari unggah multi-bagian.
);
Skenario
Referensi
Untuk informasi lebih lanjut tentang uploader, lihat Panduan Pengembang.
Untuk kode sampel lengkap uploader, lihat Contoh GitHub.