Amazon S3 マルチパートアップロードの使用AWS SDK for PHPバージョン 3 - AWS SDK for PHP
認証情報オブジェクトアップローダーMultipartUploaderMultipartUploader オブジェクトマルチパートアップロードのカスタマイズエラーからの復旧非同期マルチパートアップロード設定マルチパートコピー

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Amazon S3 マルチパートアップロードの使用AWS SDK for PHPバージョン 3

1 回の PutObject 操作では、合計サイズが 5 GB 以内のオブジェクトをアップロードできます。ただし、マルチパートアップロード手法 (たとえば、CreateMultipartUpload、UploadPart、CompleteMultipartUpload、AbortMultipartUpload) を使用すると、合計サイズが 5 MB～5 TB のオブジェクトをアップロードできます。

以下の例では、次の方法を示しています。

  • を使用して、オブジェクトを Amazon S3 にアップロードするObjectUploader。

  • を使用して Amazon S3 オブジェクトのマルチパートアップロードを作成するMultipartUploader。

  • を使用して、Amazon S3 の場所間でオブジェクトをコピーします。ObjectCopier。

AWS SDK for PHP 用のすべてのサンプルコードは GitHub で入手できます。

認証情報

サンプルコードを実行する前に、AWSクレデンシャル (を参照) 認証情報の設定。次にをインポートしますAWS SDK for PHPが挙げられる。基本的な使用法。

オブジェクトアップローダー

かどうかわからない場合PutObjectまたはMultipartUploaderタスクに最も適しているのは、ObjectUploader。ObjectUploader次のいずれかを使用して、大きなファイルを Amazon S3 にアップロードします。PutObjectまたはMultipartUploaderペイロードサイズに基づいて最適なものによって異なります。


require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;
use Aws\S3\ObjectUploader;

サンプルコード 

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

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

// Using stream instead of 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);
    } catch (MultipartUploadException $e) {
        rewind($source);
        $uploader = new MultipartUploader($s3Client, $source, [
            'state' => $e->getState(),
        ]);
    }
} while (!isset($result));

fclose($source);

MultipartUploader

マルチパートアップロードは、大容量オブジェクトのアップロードを効率よく行えるように設計されています。マルチパートアップロードでは、オブジェクトを分割して、別々に任意の順序で並行してアップロードできます。

Amazon S3 のお客様は、100 MB を超えるオブジェクトに対してマルチパートアップロードを使用することをお勧めします。

MultipartUploader オブジェクト

SDK には、マルチパートアップロードのプロセスを簡素化する特別な MultipartUploader オブジェクトがあります。

インポート 

require 'vendor/autoload.php';

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

サンプルコード 

$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";
}

このアップローダーでは、指定されたソースと設定に基づいてパートデータのジェネレーターが作成され、すべてのパートのアップロードが試行されます。一部のパートアップロードが失敗すると、アップローダーによってソースデータ全体が読み取られるまで、失敗したパートのアップロードが続行されます。その後、アップローダーは失敗したパートのアップロードを再試行するか、アップロードに失敗したパートに関する情報を含む例外をスローします。

マルチパートアップロードのカスタマイズ

マルチパートアップローダーによって実行される CreateMultipartUpload、UploadPart、CompleteMultipartUpload オペレーションに対して、コンストラクタに渡すコールバックを介してカスタムオプションを設定できます。

インポート 

require 'vendor/autoload.php';

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

サンプルコード 

// 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 (\Aws\Command $command) {
        // $command is a CreateMultipartUpload operation
        $command['CacheControl'] = 'max-age=3600';
    },
    'before_upload' => function (\Aws\Command $command) {
        // $command is an UploadPart operation
        $command['RequestPayer'] = 'requester';
    },
    'before_complete' => function (\Aws\Command $command) {
        // $command is a CompleteMultipartUpload operation
        $command['RequestPayer'] = 'requester';
    },
]);

パートのアップロード間の手動のガベージコレクション

大きなアップロードでメモリ制限に達している場合、メモリ制限に達したときに PHP ガベージコレクターで収集されていない SDK によって生成された巡回参照が原因である可能性があります。オペレーション間で収集アルゴリズムを手動で呼び出すと、制限に達する前にサイクルを収集できます。次の例では、各パートをアップロードする前にコールバックを使用して、収集アルゴリズムを呼び出します。ガベージコレクターを呼び出してもパフォーマンスに影響することはなく、最適な使用はお客様のユースケースと環境によって異なることに注意してください。

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

エラーからの復旧

マルチパートアップロードのプロセスでエラーが発生すると MultipartUploadException がスローされます。この例外では、マルチパートアップロードの進行状況に関する情報が含まれている UploadState オブジェクトへのアクセスが提供されます。UploadState を使用して、完了できなかったアップロードを再開できます。

インポート 

require 'vendor/autoload.php';

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

サンプルコード 

// 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);
}

UploadState によるアップロードの再開では、まだアップロードされていないパートのアップロードが試行されます。この状態オブジェクトでは、パートが連続していない場合であっても、欠落しているパートが追跡されます。アップローダーは、指定されたソースファイルで、アップロードする必要があるパートに属するバイト範囲まで読み取りまたはシークします。

UploadState オブジェクトはシリアル化可能であるため、別のプロセスでアップロードを再開することもできます。また、例外を処理していない場合でも、UploadState を呼び出すことによって $uploader->getState() オブジェクトを取得できます。

重要

MultipartUploader にソースとして渡されるストリームは、アップロード前に自動的には巻き戻しされません。そのため、前述の例のようなループでファイルパスではなくストリームを使用している場合は、catch ブロック内で $source 変数をリセットします。

インポート 

require 'vendor/autoload.php';

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

サンプルコード 

// 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));

マルチパートアップロードの中止

マルチパートアップロードは、UploadState オブジェクトに含まれた UploadId を取得し、abortMultipartUpload に渡すことで中止できます。

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

非同期マルチパートアップロード

upload() で MultipartUploader を呼び出すとリクエストがブロックされます。非同期コンテキストを使用している場合は、マルチパートアップロードの promise を取得できます。

require 'vendor/autoload.php';

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

サンプルコード 

// 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();

設定

MultipartUploader オブジェクトのコンストラクタでは次の引数を指定できます。

$client

転送の実行に使用する Aws\ClientInterface オブジェクト。これは Aws\S3\S3Client のインスタンスである必要があります。

$source

アップロードするソースデータ。これは、パスや URL (例: /path/to/file.jpg)、リソースハンドル (例: fopen('/path/to/file.jpg', 'r))、PSR-7 ストリームのインスタンスのいずれかです。

$config

マルチパートアップロードの設定オプションの連想配列。

有効な設定オプションは次のとおりです。

acl

(string) をアップロードするオブジェクトに設定するアクセスコントロールリスト (ACL)。デフォルトでは、オブジェクトはプライベートです。

before_complete

(callable) CompleteMultipartUpload オペレーションの前に呼び出すコールバック。このコールバックは、function (Aws\Command $command) {...} のような関数の署名を持っている必要があります。

before_initiate

(callable) CreateMultipartUpload オペレーションの前に呼び出すコールバック。このコールバックは、function (Aws\Command $command) {...} のような関数の署名を持っている必要があります。

before_upload

(callable) すべての UploadPart オペレーションの前に呼び出すコールバック。このコールバックは、function (Aws\Command $command) {...} のような関数の署名を持っている必要があります。

bucket

(string、必須) オブジェクトのアップロード先のバケットの名前。

concurrency

(int,デフォルト:int(5)) 同時の最大数UploadPartマルチパートアップロード中に許容される操作。

key

(string、必須) アップロードするオブジェクトで使用するキー。

part_size

(int,デフォルト:int(5242880)) マルチパートアップロードの実行時に使用するパートサイズ (バイト単位)。5 MB 以上かつ 5 GB 以内である必要があります。

state

(Aws\Multipart\UploadState) マルチパートアップロードの状態を表すオブジェクトであり、前回のアップロードを再開するために使用されます。このオプションを指定している場合、bucket、key、part_size オプションは無視されます。

マルチパートコピー

-AWS SDK for PHPまた、MultipartCopy同様の方法で使用されるオブジェクトMultipartUploader、5 GB 以上かつ 5 TB 以内のサイズのオブジェクトを Amazon S3 内でコピーするように設計されているオブジェクトです。

require 'vendor/autoload.php';

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

サンプルコード 

// 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";
}