SDK を使用してマルチパートアップロードを実行する方法 (PHP SDK V1) - Object Storage Service

Object Storage Service (OSS) は、マルチパートアップロード機能を提供します。この機能を使用すると、ラージオブジェクトを複数のパートに分割し、それらを個別にアップロードできます。すべてのパートがアップロードされた後、CompleteMultipartUpload 操作を呼び出してパートを結合し、完全なオブジェクトにすることができます。このプロセスにより、再開可能なアップロードが可能になります。

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

マルチパートアップロードは、次の 3 つのステップで構成されます：

マルチパートアップロードイベントの初期化
$ossClient->initiateMultipartUpload メソッドを呼び出します。OSS は、マルチパートアップロードイベントに対してグローバルに一意の uploadId を返します。
パートのアップロード
$ossClient->uploadPart メソッドを呼び出して、各パートのデータをアップロードします。
説明
- 特定の uploadId では、パート番号は完全なオブジェクト内でのパートの位置を識別します。既存のパートと同じパート番号で新しいパートをアップロードすると、既存のパートは上書きされます。
- OSS は、受信したパートデータの MD5 ハッシュをレスポンスの ETag ヘッダーに含めます。
- OSS は、アップロードされたデータの MD5 ハッシュを計算し、SDK によって計算された MD5 ハッシュと比較します。2 つのハッシュが一致しない場合、OSS は InvalidDigest エラーコードを返します。
マルチパートアップロードの完了
$ossClient->completeMultipartUpload メソッドを呼び出して、すべてのパートを結合し、完全なオブジェクトにします。

マルチパートアップロードの完全な例

次の例は、マルチパートアップロードの完全なプロセスを示しています：

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\CoreOssException;
use OSS\Core\OssUtil;

// 環境変数からアクセス認証情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
$provider = new EnvironmentVariableCredentialsProvider();
// エンドポイントの例として、中国 (杭州) リージョンを使用します。ご利用のリージョンに基づいてエンドポイントを指定してください。
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// バケット名を指定します (例: examplebucket)。
$bucket= 'examplebucket';
// オブジェクトの完全なパスを指定します。パスにバケット名を含めることはできません。例: exampledir/exampleobject.txt。
$object = 'exampledir/exampleobject.txt';
// ローカルファイルの完全なパスを指定します。
$uploadFile = 'D:\\localpath\\examplefile.txt';
$initOptions = array(
    OssClient::OSS_HEADERS  => array(
        // オブジェクトがダウンロードされる際のウェブページのキャッシュ動作を指定します。
        // 'Cache-Control' => 'no-cache',
        // オブジェクトがダウンロードされる際のオブジェクト名を指定します。
        // 'Content-Disposition' => 'attachment;filename=oss_download.jpg',
        // 有効期限をミリ秒単位で指定します。
        // 'Expires' => 150,
        // マルチパートアップロードを初期化する際に、同名のオブジェクトを上書きするかどうかを指定します。この例では、このパラメーターは true に設定されており、上書きが禁止されていることを示します。
        //'x-oss-forbid-overwrite' => 'true',
        // オブジェクトの各パートのサーバー側暗号化方式を指定します。
        // 'x-oss-server-side-encryption'=> 'KMS',
        // オブジェクトの暗号化アルゴリズムを指定します。
        // 'x-oss-server-side-data-encryption'=>'SM4',
        // KMS で管理されるカスタマーマスターキー (CMK) を指定します。
        //'x-oss-server-side-encryption-key-id' => '9468da86-3509-4f8d-a61e-6eab1eac****',
        // オブジェクトのストレージクラスを指定します。
        // 'x-oss-storage-class' => 'Standard',
        // オブジェクトのタグを指定します。複数のタグを指定できます。
        // 'x-oss-tagging' => 'TagA=A&TagB=B',
    ),
);

/**
 *  ステップ 1: マルチパートアップロードイベントを初期化し、uploadId を取得します。
 */
try{
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
    // uploadId を返します。uploadId は、マルチパートアップロードイベントの一意の識別子です。uploadId を使用して、マルチパートアップロードの中止やクエリなどの操作を実行できます。
    $uploadId = $ossClient->initiateMultipartUpload($bucket, $object, $initOptions);
    print("initiateMultipartUpload OK" . "\n");
    // uploadId を使用して、マルチパートアップロードイベントを中止したり、アップロード済みのパートをリスト表示したりします。
    // uploadId を使用してマルチパートアップロードイベントを中止するには、InitiateMultipartUpload を呼び出してマルチパートアップロードを初期化した後に uploadId を取得する必要があります。
    // uploadId を使用してアップロード済みのパートをリスト表示するには、InitiateMultipartUpload を呼び出してマルチパートアップロードを初期化し、CompleteMultipartUpload を呼び出してマルチパートアップロードを完了する前に uploadId を取得する必要があります。
    //print("UploadId: " . $uploadId . "\n");
} catch(OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

/*
 * ステップ 2: パートをアップロードします。
 */
// 最小パートサイズは 100 KB、最大パートサイズは 5 GB です。最後のパートのサイズは 100 KB 未満でもかまいません。
$partSize = 10 * 1024 * 1024;
$uploadFileSize = sprintf('%u',filesize($uploadFile));
$pieces = $ossClient->generateMultiuploadParts($uploadFileSize, $partSize);
$responseUploadPart = array();
$uploadPosition = 0;
$isCheckMd5 = true;
foreach ($pieces as $i => $piece) {
    $fromPos = $uploadPosition + (integer)$piece[$ossClient::OSS_SEEK_TO];
    $toPos = (integer)$piece[$ossClient::OSS_LENGTH] + $fromPos - 1;
    $upOptions = array(
        // アップロードするファイル。
        $ossClient::OSS_FILE_UPLOAD => $uploadFile,
        // パート番号を設定します。
        $ossClient::OSS_PART_NUM => ($i + 1),
        // マルチパートアップロードの開始位置を指定します。
        $ossClient::OSS_SEEK_TO => $fromPos,
        // ファイルの長さを指定します。
        $ossClient::OSS_LENGTH => $toPos - $fromPos + 1,
        // MD5 検証を有効にするかどうかを指定します。true は MD5 検証が有効であることを示します。
        $ossClient::OSS_CHECK_MD5 => $isCheckMd5,
    );
    // MD5 検証を有効にします。
    if ($isCheckMd5) {
        $contentMd5 = OssUtil::getMd5SumForFile($uploadFile, $fromPos, $toPos);
        $upOptions[$ossClient::OSS_CONTENT_MD5] = $contentMd5;
    }
    try {
        // パートをアップロードします。
        $responseUploadPart[] = $ossClient->uploadPart($bucket, $object, $uploadId, $upOptions);
        printf("initiateMultipartUpload, uploadPart - part#{$i} OK\n");
    } catch(OssException $e) {
        printf("initiateMultipartUpload, uploadPart - part#{$i} FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }

}
// $uploadParts は、各パートの ETag とパート番号で構成される配列です。
$uploadParts = array();
foreach ($responseUploadPart as $i => $eTag) {
    $uploadParts[] = array(
        'PartNumber' => ($i + 1),
        'ETag' => $eTag,
    );
}
/**
 * ステップ 3: アップロードを完了します。
 */
$comOptions['headers'] = array(
    // マルチパートアップロードを完了する際に、同名のオブジェクトを上書きするかどうかを指定します。この例では、このパラメーターは true に設定されており、上書きが禁止されていることを示します。
    // 'x-oss-forbid-overwrite' => 'true',
    // x-oss-complete-all:yes を指定すると、OSS は現在の uploadId のすべてのアップロード済みパートをリスト表示し、パート番号でソートしてから、CompleteMultipartUpload 操作を実行します。
    // 'x-oss-complete-all'=> 'yes'
);

try {
    // completeMultipartUpload 操作を実行する際は、すべての有効な $uploadParts を提供する必要があります。OSS は、送信された $uploadParts を受信した後、各パートの有効性を検証します。すべてのデータパートが検証されると、OSS はそれらを結合して完全なファイルを作成します。
    $ossClient->completeMultipartUpload($bucket, $object, $uploadId, $uploadParts,$comOptions);
    printf( "Complete Multipart Upload OK\n");
}  catch(OssException $e) {
    printf("Complete Multipart Upload FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

ローカルファイルのマルチパートアップロード

次のコードは、ローカルファイルを OSS にマルチパートアップロードする方法を示しています。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\CoreOssException;

// 環境変数からアクセス認証情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
$provider = new EnvironmentVariableCredentialsProvider();
// エンドポイントの例として、中国 (杭州) リージョンを使用します。ご利用のリージョンに基づいてエンドポイントを指定してください。
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// バケット名を指定します (例: examplebucket)。
$bucket= 'examplebucket';
// オブジェクトの完全なパスを指定します。パスにバケット名を含めることはできません。例: exampledir/exampleobject.txt。
$object = 'exampledir/exampleobject.txt';
// ローカルファイルの完全なパスを指定します。
$file = 'D:\\localpath\\examplefile.txt';

$options = array(
    OssClient::OSS_CHECK_MD5 => true,
    OssClient::OSS_PART_SIZE => 1,
);
try{
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);

    $ossClient->multiuploadFile($bucket, $object, $file, $options);
} catch(OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
print(__FUNCTION__ . ":  OK" . "\n");

フォルダのマルチパートアップロード (PHP SDK V1)

次のコードは、ローカルフォルダ (フォルダ内のすべてのファイルを含む) を OSS にマルチパートアップロードする方法を示しています。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\CoreOssException;

// 環境変数からアクセス認証情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
$provider = new EnvironmentVariableCredentialsProvider();
// エンドポイントの例として、中国 (杭州) リージョンを使用します。ご利用のリージョンに基づいてエンドポイントを指定してください。
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// バケット名を指定します (例: examplebucket)。
$bucket= 'examplebucket';
// アップロードするローカルフォルダの完全なパスを指定します。
$localDirectory = "D:\\localpath";
// OSS 内のフォルダのプレフィックスを指定します。
$prefix = "samples/codes/";
try {
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);

    $ossClient->uploadDir($bucket, $prefix, $localDirectory);
}  catch(OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
print(__FUNCTION__ . ":  OK" . "\n");

マルチパートアップロードイベントの中止 (PHP SDK V1)

$ossClient->abortMultipartUpload メソッドを呼び出して、マルチパートアップロードイベントを中止できます。イベントが中止されると、その uploadId はどの操作にも使用できなくなり、アップロードされたパートデータは削除されます。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\CoreOssException;

// 環境変数からアクセス認証情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
$provider = new EnvironmentVariableCredentialsProvider();
// エンドポイントの例として、中国 (杭州) リージョンを使用します。ご利用のリージョンに基づいてエンドポイントを指定してください。
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// バケット名を指定します (例: examplebucket)。
$bucket= 'examplebucket';
// オブジェクトの完全なパスを指定します。パスにバケット名を含めることはできません。例: exampledir/exampleobject.txt。
$object = 'exampledir/exampleobject.txt';
// uploadId を指定します (例: 0004B999EF518A1FE585B0C9360D****)。uploadId は、InitiateMultipartUpload を呼び出してマルチパートアップロードを初期化した後に返されます。
$upload_id = '0004B999EF518A1FE585B0C9360D****';

try{
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);

    $ossClient->abortMultipartUpload($bucket, $object, $upload_id);
} catch(OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
print(__FUNCTION__ . ": OK" . "\n");

アップロード済みパートのリスト表示 (PHP SDK V1)

listParts メソッドを呼び出して、指定された uploadId に対して正常にアップロードされたすべてのパートをリスト表示できます。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\CoreOssException;

// 環境変数からアクセス認証情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
$provider = new EnvironmentVariableCredentialsProvider();
// エンドポイントの例として、中国 (杭州) リージョンを使用します。ご利用のリージョンに基づいてエンドポイントを指定してください。
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// バケット名を指定します (例: examplebucket)。
$bucket= 'examplebucket';
// オブジェクトの完全なパスを指定します。パスにバケット名を含めることはできません。例: exampledir/exampleobject.txt。
$object = 'exampledir/exampleobject.txt';
// uploadId を指定します (例: 0004B999EF518A1FE585B0C9360D****)。uploadId は、InitiateMultipartUpload を呼び出してマルチパートアップロードを初期化し、CompleteMultipartUpload を呼び出してマルチパートアップロードを完了する前に返されます。
$upload_id = '0004B999EF518A1FE585B0C9360D****';

try{
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);

    $listPartsInfo = $ossClient->listParts($bucket, $object, $uploadId);
    foreach ($listPartsInfo->getListPart() as $partInfo) {
        print($partInfo->getPartNumber() . "\t" . $partInfo->getSize() . "\t" . $partInfo->getETag() . "\t" . $partInfo->getLastModified() . "\n");
    }
} catch(OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
print(__FUNCTION__ . ": OK" . "\n");

マルチパートアップロードイベントのリスト表示 (PHP SDK V1)

listMultipartUploads メソッドを呼び出して、進行中のすべてのマルチパートアップロードイベントをリスト表示できます。進行中のイベントとは、初期化されたがまだ完了または中止されていないイベントのことです。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\CoreOssException;

// 環境変数からアクセス認証情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
$provider = new EnvironmentVariableCredentialsProvider();
// エンドポイントの例として、中国 (杭州) リージョンを使用します。ご利用のリージョンに基づいてエンドポイントを指定してください。
$endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
// バケット名を指定します (例: examplebucket)。
$bucket= 'examplebucket';

$options = array(
    'delimiter' => '/',
    'max-uploads' => 100,
    'key-marker' => '',
    'prefix' => '',
    'upload-id-marker' => ''
);
try {
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);

    $listMultipartUploadInfo = $ossClient->listMultipartUploads($bucket, $options);
} catch(OssException $e) {
    printf(__FUNCTION__ . ": listMultipartUploads FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
printf(__FUNCTION__ . ": listMultipartUploads OK\n");
$listUploadInfo = $listMultipartUploadInfo->getUploads();
var_dump($listUploadInfo);

$options のパラメーターを次の表に示します。

パラメーター	説明
delimiter	オブジェクト名をグループ化するために使用される文字。指定されたプレフィックスを含み、デリミタが最初に出現するまでのすべてのオブジェクト名がグループとして扱われます。
key-marker	オブジェクト名が `key-marker` の値よりも辞書順で大きいマルチパートアップロードイベント。このパラメーターを `upload-id-marker` と、結果の開始位置を指定します。
max-uploads	返すマルチパートアップロードイベントの最大数。デフォルト値と最大値はどちらも 1000 です。
prefix	返されるオブジェクト名に含める必要があるプレフィックス。説明クエリでプレフィックスを使用した場合、返されるオブジェクト名には引き続きプレフィックスが含まれます。
upload-id-marker	このパラメーターを `key-marker` と、結果の開始位置を指定します。このパラメーターは `key-marker` が設定されていない場合は無視されます。`key-marker` が設定されている場合、クエリ結果には以下が含まれます：名前が `key-marker` の値よりも辞書順で大きいすべてのオブジェクト。名前が `key-marker` の値と等しく、アップロード ID が `upload-id-marker` の値よりも辞書順で大きいオブジェクトのすべてのマルチパートアップロードイベント。

Object Storage Service:マルチパートアップロード (PHP SDK V1)