Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Menggunakan unggahan multipart Amazon S3 dengan Versi 3 AWS SDK untuk PHP
<a name="s3-multipart-upload"></a>

Dengan satu `PutObject` operasi, Anda dapat mengunggah objek hingga 5 GB. Namun, dengan menggunakan metode upload multipart (misalnya,,, `CreateMultipartUpload``UploadPart`,`AbortMultipartUpload`)`CompleteMultipartUpload`, Anda dapat mengunggah objek dari ukuran 5 MB hingga 5 TB.

Contoh berikut menunjukkan cara:
+ Unggah objek ke Amazon S3, menggunakan. [ObjectUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectUploader.html)
+ Buat unggahan multibagian untuk objek Amazon S3 menggunakan. [MultipartUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.MultipartUploader.html)
+ Salin objek dari satu lokasi Amazon S3 ke lokasi lain menggunakan. [ObjectCopier](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectCopier.html)

Semua kode contoh untuk AWS SDK untuk PHP tersedia [di sini GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).

## Kredensial
<a name="examplecredentials"></a>

Sebelum menjalankan kode contoh, konfigurasikan AWS kredensil Anda, seperti yang dijelaskan dalam. [Mengautentikasi dengan AWS menggunakan AWS SDK untuk PHP Versi 3](credentials.md) Kemudian impor AWS SDK untuk PHP, seperti yang dijelaskan dalam[Menginstal AWS SDK untuk PHP Versi 3](getting-started_installation.md).

## Pengunggah objek
<a name="object-uploader"></a>

Jika Anda tidak yakin apakah `PutObject` atau `MultipartUploader` yang terbaik untuk tugas itu, gunakan`ObjectUploader`. `ObjectUploader`mengunggah file besar ke Amazon S3 menggunakan `PutObject` salah satu `MultipartUploader` atau, berdasarkan ukuran payload.

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\ObjectUploader;
use Aws\S3\S3Client;
```

 **Kode Sampel** 

```
// Create an S3Client.
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-east-2',
    'version' => '2006-03-01'
]);

$bucket = 'your-bucket';
$key = 'my-file.zip';

// Use a stream instead of a file path.
$source = fopen('/path/to/large/file.zip', 'rb');

$uploader = new ObjectUploader(
    $s3Client,
    $bucket,
    $key,
    $source
);

do {
    try {
        $result = $uploader->upload();
        if ($result["@metadata"]["statusCode"] == '200') {
            print('<p>File successfully uploaded to ' . $result["ObjectURL"] . '.</p>');
        }
        print($result);
        // If the SDK chooses a multipart upload, try again if there is an exception.
        // Unlike PutObject calls, multipart upload calls are not automatically retried.
    } catch (MultipartUploadException $e) {
        rewind($source);
        $uploader = new MultipartUploader($s3Client, $source, [
            'state' => $e->getState(),
        ]);
    }
} while (!isset($result));

fclose($source);
```

### Konfigurasi
<a name="object-uploader-configuration"></a>

Konstruktor `ObjectUploader` objek menerima argumen berikut:

**`$client`**  
`Aws\ClientInterface`Objek yang digunakan untuk melakukan transfer. Ini harus menjadi contoh dari`Aws\S3\S3Client`.

**`$bucket`**  
(`string`, *wajib*) Nama ember tempat objek diunggah.

**`$key`**  
(`string`, *wajib*) Kunci yang akan digunakan untuk objek yang sedang diunggah.

**`$body`**  
(`mixed`, *wajib*) Data objek untuk diunggah. Bisa berupa`StreamInterface`, sumber daya aliran PHP, atau string data untuk diunggah.

**`$acl`**  
(`string`) Daftar kontrol akses (ACL) untuk mengatur objek yang sedang diunggah. Objek bersifat pribadi secara default.

**`$options`**  
Array asosiatif opsi konfigurasi untuk unggahan multipart. Opsi konfigurasi berikut valid:    
**`add_content_md5`**  
(`bool`) Setel ke true untuk secara otomatis menghitung MD5 checksum untuk unggahan.  
**`mup_threshold`**  
(`int`, *default*:`int(16777216)`) Jumlah byte untuk ukuran file. Jika ukuran file melebihi batas ini, unggahan multibagian digunakan.  
**`before_complete`**  
(`callable`) Callback untuk memanggil sebelum operasi. `CompleteMultipartUpload` Callback harus memiliki tanda tangan fungsi yang mirip dengan:`function (Aws\Command $command) {...}`. Lihat [referensi CompleteMultipartUpload API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#completemultipartupload) untuk parameter yang dapat Anda tambahkan ke `CommandInterface` objek.  
**`before_initiate`**  
(`callable`) Callback untuk memanggil sebelum operasi. `CreateMultipartUpload` Callback harus memiliki tanda tangan fungsi yang mirip dengan:`function (Aws\Command $command) {...}`. SDK memanggil callback ini jika ukuran file melebihi nilai. `mup_threshold` Lihat [referensi CreateMultipartUpload API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#createmultipartupload) untuk parameter yang dapat Anda tambahkan ke `CommandInterface` objek.  
**`before_upload`**  
(`callable`) Panggilan balik untuk memanggil sebelum operasi apa pun `PutObject` atau`UploadPart`. Callback harus memiliki tanda tangan fungsi yang mirip dengan:`function (Aws\Command $command) {...}`. SDK memanggil callback ini jika ukuran file kurang dari atau sama dengan nilai. `mup_threshold` Lihat [referensi PutObject API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) untuk parameter yang dapat Anda terapkan pada `PutObject` permintaan. Untuk parameter yang berlaku untuk `UploadPart` permintaan, lihat [referensi UploadPart API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#uploadpart). SDK mengabaikan parameter apa pun yang tidak berlaku untuk operasi yang diwakili oleh objek. `CommandInterface`  
**`concurrency`**  
(`int`, *default*:`int(3)`) Jumlah maksimum `UploadPart` operasi bersamaan yang diizinkan selama pengunggahan multibagian.  
**`part_size`**  
(`int`, *default*:`int(5242880)`) Ukuran bagian, dalam byte, untuk digunakan saat melakukan pengunggahan multibagian. Nilai harus antara 5 MB dan 5 GB, inklusif.  
**`state`**  
(`Aws\Multipart\UploadState`) Objek yang mewakili status unggahan multibagian dan yang digunakan untuk melanjutkan unggahan sebelumnya. Ketika opsi ini disediakan, `$key` argumen `$bucket` and dan `part_size` opsi diabaikan.  
**`params`**  
Array asosiatif yang menyediakan opsi konfigurasi untuk setiap subperintah. Contoh:  

```
new ObjectUploader($bucket, $key, $body, $acl, ['params' => ['CacheControl' => <some_value>])
```

## MultipartUploader
<a name="multipartuploader"></a>

Unggahan multipart dirancang untuk meningkatkan pengalaman mengunggah objek yang lebih besar. Mereka memungkinkan Anda untuk mengunggah objek dalam beberapa bagian secara independen, dalam urutan apa pun, dan secara paralel.

Pelanggan Amazon S3 didorong untuk menggunakan unggahan multipart untuk objek yang lebih besar dari 100 MB.

## MultipartUploader objek
<a name="multipartuploader-object"></a>

SDK memiliki `MultipartUploader` objek khusus yang menyederhanakan proses upload multipart.

 **Impor** 

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **Kode Sampel** 

```
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

// Use multipart upload
$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

try {
    $result = $uploader->upload();
    echo "Upload complete: {$result['ObjectURL']}\n";
} catch (MultipartUploadException $e) {
    echo $e->getMessage() . "\n";
}
```

Pengunggah membuat generator data bagian, berdasarkan sumber dan konfigurasi yang disediakan, dan mencoba mengunggah semua bagian. Jika beberapa bagian unggahan gagal, pengunggah terus mengunggah bagian selanjutnya hingga seluruh data sumber dibaca. Setelah itu, pengunggah mencoba lagi untuk mengunggah bagian yang gagal atau melempar pengecualian yang berisi informasi tentang bagian yang gagal diunggah.

## Menyesuaikan unggahan multipart
<a name="customizing-a-multipart-upload"></a>

Anda dapat mengatur opsi kustom pada`CreateMultipartUpload`,`UploadPart`, dan `CompleteMultipartUpload` operasi yang dijalankan oleh pengunggah multibagian melalui panggilan balik yang diteruskan ke konstruktornya.

 **Impor** 

```
require 'vendor/autoload.php';

use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **Kode Sampel** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

// Customizing a multipart upload
$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
    'before_initiate' => function (Command $command) {
        // $command is a CreateMultipartUpload operation
        $command['CacheControl'] = 'max-age=3600';
    },
    'before_upload' => function (Command $command) {
        // $command is an UploadPart operation
        $command['RequestPayer'] = 'requester';
    },
    'before_complete' => function (Command $command) {
        // $command is a CompleteMultipartUpload operation
        $command['RequestPayer'] = 'requester';
    },
]);
```

### Pengumpulan sampah manual antara unggahan bagian
<a name="manual-garbage-collection-between-part-uploads"></a>

Jika Anda mencapai batas memori dengan unggahan besar, ini mungkin karena referensi siklik yang dihasilkan oleh SDK belum dikumpulkan oleh [pengumpul sampah PHP](https://www.php.net/manual/en/features.gc.php) ketika batas memori Anda tercapai. Memanggil algoritme pengumpulan secara manual di antara operasi memungkinkan siklus dikumpulkan sebelum mencapai batas itu. Contoh berikut memanggil algoritma koleksi menggunakan callback sebelum setiap bagian diunggah. Perhatikan bahwa memanggil pengumpul sampah memang datang dengan biaya kinerja, dan penggunaan optimal akan tergantung pada kasus penggunaan dan lingkungan Anda.

```
$uploader = new MultipartUploader($client, $source, [
   'bucket' => 'your-bucket',
   'key' => 'your-key',
   'before_upload' => function(\Aws\Command $command) {
      gc_collect_cycles();
   }
]);
```

## Memulihkan dari kesalahan
<a name="recovering-from-errors"></a>

Ketika terjadi kesalahan selama proses pengunggahan multipart, a `MultipartUploadException` dilemparkan. Pengecualian ini menyediakan akses ke `UploadState` objek, yang berisi informasi tentang kemajuan unggahan multibagian. `UploadState`Dapat digunakan untuk melanjutkan unggahan yang gagal diselesaikan.

 **Impor** 

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **Kode Sampel** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

//Recover from errors
do {
    try {
        $result = $uploader->upload();
    } catch (MultipartUploadException $e) {
        $uploader = new MultipartUploader($s3Client, $source, [
            'state' => $e->getState(),
        ]);
    }
} while (!isset($result));

//Abort a multipart upload if failed
try {
    $result = $uploader->upload();
} catch (MultipartUploadException $e) {
    // State contains the "Bucket", "Key", and "UploadId"
    $params = $e->getState()->getId();
    $result = $s3Client->abortMultipartUpload($params);
}
```

Melanjutkan unggahan dari `UploadState` upaya untuk mengunggah bagian yang belum diunggah. Objek negara melacak bagian yang hilang, bahkan jika mereka tidak berurutan. Pengunggah membaca atau mencari melalui file sumber yang disediakan ke rentang byte milik bagian yang masih perlu diunggah.

 `UploadState`objek dapat diserialkan, sehingga Anda juga dapat melanjutkan unggahan dalam proses yang berbeda. Anda juga bisa mendapatkan `UploadState` objek, bahkan ketika Anda tidak menangani pengecualian, dengan menelepon`$uploader->getState()`.

**penting**  
Aliran yang diteruskan sebagai sumber ke a tidak `MultipartUploader` diputar ulang secara otomatis sebelum mengunggah. Jika Anda menggunakan aliran alih-alih jalur file dalam loop yang mirip dengan contoh sebelumnya, setel ulang `$source` variabel di dalam `catch` blok.

 **Impor** 

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **Kode Sampel** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

//Using stream instead of file path
$source = fopen('/path/to/large/file.zip', 'rb');
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

do {
    try {
        $result = $uploader->upload();
    } catch (MultipartUploadException $e) {
        rewind($source);
        $uploader = new MultipartUploader($s3Client, $source, [
            'state' => $e->getState(),
        ]);
    }
} while (!isset($result));
fclose($source);
```

### Membatalkan unggahan multibagian
<a name="aborting-a-multipart-upload"></a>

Unggahan multipart dapat dibatalkan dengan mengambil yang `UploadId` terkandung dalam `UploadState` objek dan meneruskannya ke. `abortMultipartUpload`

```
try {
    $result = $uploader->upload();
} catch (MultipartUploadException $e) {
    // State contains the "Bucket", "Key", and "UploadId"
    $params = $e->getState()->getId();
    $result = $s3Client->abortMultipartUpload($params);
}
```

## Unggahan multipart asinkron
<a name="asynchronous-multipart-uploads"></a>

Memanggil `upload()` `MultipartUploader` adalah permintaan pemblokiran. Jika Anda bekerja dalam konteks asinkron, Anda bisa mendapatkan [janji](guide_promises.md) untuk unggahan multibagian.

```
require 'vendor/autoload.php';

use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **Kode Sampel** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

$promise = $uploader->promise();
```

### Konfigurasi
<a name="asynchronous-multipart-uploads-configuration"></a>

Konstruktor `MultipartUploader` objek menerima argumen berikut:

** `$client` **  
`Aws\ClientInterface`Objek yang digunakan untuk melakukan transfer. Ini harus menjadi contoh dari`Aws\S3\S3Client`.

** `$source` **  
Sumber data yang sedang diunggah. Ini bisa berupa jalur atau URL (misalnya,`/path/to/file.jpg`), pegangan sumber daya (misalnya,`fopen('/path/to/file.jpg', 'r)`), atau instance aliran [PSR-7](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Psr.Http.Message.StreamInterface.html).

** `$config` **  
Array asosiatif opsi konfigurasi untuk unggahan multipart.  
Opsi konfigurasi berikut valid:    
** `acl` **  
(`string`) Daftar kontrol akses (ACL) untuk mengatur objek yang sedang diunggah. Objek bersifat pribadi secara default.  
** `before_complete` **  
(`callable`) Callback untuk memanggil sebelum operasi. `CompleteMultipartUpload` Callback harus memiliki tanda tangan fungsi seperti`function (Aws\Command $command) {...}`.  
** `before_initiate` **  
(`callable`) Callback untuk memanggil sebelum operasi. `CreateMultipartUpload` Callback harus memiliki tanda tangan fungsi seperti`function (Aws\Command $command) {...}`.  
** `before_upload` **  
(`callable`) Callback untuk memanggil sebelum operasi apa pun`UploadPart`. Callback harus memiliki tanda tangan fungsi seperti`function (Aws\Command $command) {...}`.  
** `bucket` **  
(`string`, *wajib*) Nama ember tempat objek diunggah.  
** `concurrency` **  
(`int`, *default*:`int(5)`) Jumlah maksimum `UploadPart` operasi bersamaan yang diizinkan selama pengunggahan multibagian.  
** `key` **  
(`string`, *wajib*) Kunci yang akan digunakan untuk objek yang sedang diunggah.  
** `part_size` **  
(`int`, *default*:`int(5242880)`) Ukuran bagian, dalam byte, untuk digunakan saat melakukan pengunggahan multibagian. Ini harus antara 5 MB dan 5 GB, inklusif.  
** `state` **  
(`Aws\Multipart\UploadState`) Objek yang mewakili status unggahan multibagian dan yang digunakan untuk melanjutkan unggahan sebelumnya. Ketika opsi ini disediakan, `part_size` opsi `bucket``key`,, dan diabaikan.  
**`add_content_md5`**  
(`boolean`) Setel ke true untuk secara otomatis menghitung MD5 checksum untuk unggahan.  
**`params`**  
Array asosiatif yang menyediakan opsi konfigurasi untuk setiap subperintah. Contoh:  

```
new MultipartUploader($client, $source, ['params' => ['CacheControl' => <some_value>]])
```

## Salinan multipart
<a name="multipart-copies"></a>

Ini AWS SDK untuk PHP juga mencakup `MultipartCopy` objek yang digunakan dengan cara yang mirip dengan`MultipartUploader`, tetapi dirancang untuk menyalin objek antara 5 GB dan 5 TB dalam ukuran dalam Amazon S3.

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartCopy;
use Aws\S3\S3Client;
```

 **Kode Sampel** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

//Copy objects within S3
$copier = new MultipartCopy($s3Client, '/bucket/key?versionId=foo', [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

try {
    $result = $copier->copy();
    echo "Copy complete: {$result['ObjectURL']}\n";
} catch (MultipartUploadException $e) {
    echo $e->getMessage() . "\n";
}
```