融合接口

功能說明

分片上傳步驟較多，包括初始化、文件切片、各個分片上傳、完成上傳。分片復制包括了初始化、源對象信息獲取、各個分片復制、完成復制。為了簡化分片上傳和復制，PHP SDK 提供了對分片上傳和分片復制的封裝。Aws\S3\MultipartUploader 接口提供了簡潔的分片上傳方式，Aws\S3\MultiPartCopy 接口提供了簡潔的分片復制方式。在使用這些封裝接口的同時，您同樣可以配置一些參數，控制分片的大小、并發數。

代碼示例

• 使用 MultipartUploader 進行分片上傳：

public function MultiPartUpload()
{
    $file_Path = '<your-file-path>';
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
?
    $uploader = new Aws\S3\MultipartUploader($this->s3Client, $file_Path, [
        'bucket' => $bucket,
        'key'    => $objectName,
        'concurrency' => 5,         // 設置上傳分片 UploadPart 操作的最大并行數量，默認為5.
        'part_size' => 5242880,     // 設置分片大小，默認為5M.
        'acl' => 'public-read',     // 設置ACL，參考值private | public-read
        'before_initiate' => function(\Aws\Command $command)
        {
            $command['ContentType'] = 'text/json';      // 設置content-type
        },
    ]);
?
    try {
        $result = $uploader->upload();
        echo "Upload complete: {$result['ObjectURL']}" . "\n";
    } catch (Aws\Exception\MultipartUploadException $e) {
        echo $e->getMessage() . "\n";
    }
}

• 使用 MultiPartCopy 進行分片復制：

public function MultiPartCopy()
{
    $src_bucket = '<source-bucket-name>'; //從此桶復制
    $src_key = '<source-object-key>'; //復制的對象名
?
    $dst_bucket = '<your-bucket-name>';   //目標桶
    $dst_key = '<your-object-key>';   //目標對象名
?
    $source = '/'.$src_bucket.'/'.$src_key;
    $uploader = new Aws\S3\MultiPartCopy($this->s3Client, $source, [
        'bucket' => $dst_bucket,
        'key'    => $dst_key,
        'concurrency' => 5,         // 設置上傳分片 UploadPart 操作的最大并行數量，默認為5.
        'part_size' => 5242880,     // 設置分片大小，默認為5M.
        'acl' => 'public-read',     // 設置ACL，參考值private | public-read
        'before_initiate' => function(\Aws\Command $command)
        {
            $command['ContentType'] = 'text/json';      // 設置content-type
        },
    ]);
?
    try {
        $result = $uploader->upload();
        echo "Upload complete: {$result['ObjectURL']}" . "\n";
    } catch (Aws\Exception\MultipartUploadException $e) {
        echo $e->getMessage() . "\n";
    }
}

• 關于Content-Type的配置

Content-Type用于標識文件的資源類型，比如image/png， image/jpg 是圖片類型，video/mpeg， video/mp4是視頻類型，text/plain， text/html是文本類型， 瀏覽器針對不同的Content-Type會有不同的操作，比如圖片類型可以預覽，視頻類型可以播放，文本類型可以直接打開。application/octet-stream類型會直接打開下載窗口。

有些用戶反饋圖片和視頻無法預覽的問題，主要就是Content-Type沒有正確設置導致的；Content-Type參數需要用戶主動設置，默認是application/octet-stream。在php sdk中，可以根據對象key值后綴擴展名來決定文件的Content-Type，可參考 。

請求參數

初始化分片上傳任務

功能說明

分片上傳操作可以將超過5GB的大文件分割后上傳，分片上傳對象首先需要發起分片上傳請求獲取一個upload id。

代碼示例

// createMultipartUpload
$result = $this->s3Client->createMultipartUpload([
    'Bucket' => '<your-bucket-name>',
    'Key'    => '<your-object-key>',
    //'ACL'    => 'public-read',
]);
$uploadId = $result['UploadId'];

請求參數

createMultipartUpload 可設置的參數如下：

返回結果

返回的屬性如下：

上傳分片

功能說明

初始化分片上傳任務后，指定分片上傳任務的id可以上傳分片數據，可以將大文件分割成分片后上傳，除了最后一個分片，每個分片的數據大小為5MB~5GB，每個分片上傳任務最多上傳10000個分片。

代碼示例

$file_Path = '<your-file-path>';
$bucket = '<your-bucket-name>';
$objectName = '<your-object-key>';
// uploadPart
$file = fopen($file_Path, 'r');
$partNumber = 1;
while (!feof($file)) {
    // 創建分片復制請求
    $result = $this->s3Client->uploadPart([
        'Bucket'     => $bucket,
        'Key'        => $objectName,
        'UploadId'   => $uploadId,                     //uploadId從createMultipartUpload返回值獲取
        'PartNumber' => $partNumber,                   //設置分片號
        'Body'       => fread($file, 5 * 1024 * 1024), //讀取文件分片，分片大小為5M
    ]);
    $parts['Parts'][$partNumber] = [
        // 記錄ETag
        'PartNumber' => $partNumber,
        'ETag' => $result['ETag'],
    ];
    echo "Uploading part {$partNumber}" . "\n";
    $partNumber++;
}
fclose($file);

請求參數

uploadPart 可設置的參數如下：

返回結果

合并分片

功能說明

合并指定分片上傳任務id對應任務中已上傳的對象分片，使之成為一個完整的文件。

代碼示例

// completeMultipartUpload
$result = $this->s3Client->completeMultipartUpload([
    'Bucket'   => '<your-bucket-name>',
    'Key'      => '<your-object-key>',
    'UploadId' => '<your-upload-id>',
    'MultipartUpload' => $parts,
]);
echo $result;
echo "Upload success";

請求參數

completeMultipartUpload可設置的參數如下：

返回結果

列舉分片上傳任務

功能說明

列舉分片上傳操作可以列出一個桶中正在進行的分片上傳，這些分片上傳的請求已經發起，但是還沒完成或者被中止。listMultipartUploads 操作可以通過指定maxUploads參數來設置返回分片上傳信息的數量，maxUploads參數的最大值和默認值均為1000。如果返回結果中的isTruncated字段為true，表示還有符合條件的分片上傳信息沒有列出，可以通過設置請求中的keyMarker和uploadIdMarker參數，來列出符合篩選條件的正在上傳的分片信息。

代碼示例

public function ListMultipartUploads()
{
    $result = $this->s3Client->listMultipartUploads([
        'Bucket' => '<your-bucket-name>',
    ]);
    echo $result;
}

如果list大于1000，則可以使用 getPaginator 接口列舉所有分片上傳任務。列舉所有分片上傳任務示例代碼如下：

public function ListMultipartUploads2()
{
    try {
        $results = $this->s3Client->getPaginator('ListMultipartUploads', [
            'Bucket' => '<your-bucket-name>',
        ]);
        foreach ($results as $result) {
            foreach ($result['Uploads'] as $upload) {
                echo 'object key: ' . $upload['Key'] . "\n";
                echo 'uploadId: ' . $upload['UploadId'] . "\n";
            }
        }
    } catch (S3Exception $e) {
        echo $e->getMessage() . "\n";
    }
}

請求參數

listMultipartUploads 可設置的參數如下：

返回結果

列舉已上傳的分片

功能說明

列舉已上傳分片操作可以列出一個分片上傳操作中已經上傳完畢但是還未合并的分片信息。請求中需要提供object key和 upload id，返回的結果最多包含1000個已上傳的分片信息，默認返回1000個，可以通過設置maxParts參數的值指定返回結果中分片信息的數量。如果已上傳的分片信息的數量多于1000個，則返回結果中的isTruncated字段為true，可用通過設置partNumberMarker參數獲取partNumber大于該參數的分片信息。

代碼示例

public function ListParts()
{
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    $uploadId = '<your-upload-id>';
    $result = $this->s3Client->listParts([
        'Bucket' => $bucket,
        'Key' => $objectName,
        'UploadId' => $uploadId,
    ]);
    echo $result;
}

如果 list 大于1000，則可以使用 getPaginator 接口列舉所有分片。列舉所有分片示例代碼如下：

public function ListParts2()
{
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    $uploadId = '<your-upload-id>';
    try {
        $results = $this->s3Client->getPaginator('ListParts', [
            'Bucket' => $bucket,
            'Key' => $objectName,
            'UploadId' => $uploadId,
        ]);
        foreach ($results as $result) {
            foreach ($result['Parts'] as $part) {
                echo 'part number:' . $part['PartNumber'] . "\n";
                echo 'ETag:' . $part['ETag'] . "\n";
                echo 'size' . $part['Size'] . "\n";
            }
        }
    } catch (S3Exception $e) {
        echo $e->getMessage() . "\n";
    }
}

請求參數

ListPartsRequest 可設置的參數如下：

返回結果

復制分片

功能說明

復制分片操作可以從一個已存在的對象中復制指定分片的數據。您可以使用 uploadPartCopy 復制分片。在復制分片前，需要使用 createMultipartUpload 接口獲取一個upload id，在完成復制和上傳分片操作之后，需要使用 completeMultipartUpload 操作組裝分片成為一個對象。當復制的對象大小超過5GB，必須使用復制分片操作完成對象的復制。除了最后一個分片外，每個復制分片的大小范圍是[5MB，5GB]。

代碼示例

// copyPart
$desBucket = '<your-bucket-name>';   //目標桶
$desKeyName = '<your-object-key>';   //目標對象名
$srcBucket = '<source-bucket-name>'; //從此桶復制
$srcKeyName = '<source-object-key>'; //復制的對象名
$result = $this->s3Client->uploadPartCopy([
    'Bucket'     => $desBucket,
    'Key'        => $desKeyName,
    'CopySource' => '/' . $srcBucket . '/' . $srcKeyName,
    'UploadId'   => $uploadId,                     //uploadId從createMultipartUpload返回值獲取
    'PartNumber' => $partNumber,                   //設置分片號
    'CopySourceRange' => 'bytes=' . $firstByte . '-' . $lastByte,         //復制文件分片的數據范圍
]);
echo $result;
$parts['Parts'][$partNumber] = [
    // 記錄ETag
    'PartNumber' => $partNumber,
    'ETag' => $result['CopyPartResult']['ETag'],
];
echo "Uploading part {$partNumber}" . "\n";

請求參數

uploadPartCopy 可設置的參數如下：

返回結果

取消分片上傳任務

功能說明

取消分片上傳任務操作用于終止一個分片上傳。當一個分片上傳被中止后，不會再有數據通過與之相應的upload id上傳，同時已經被上傳的分片所占用的空間會被釋放。執行取消分片上傳任務操作后，正在上傳的分片可能會上傳成功也可能會被中止，所以必要的情況下需要執行多次取消分片上傳任務操作去釋放全部上傳成功的分片所占用的空間。可以通過執行列舉已上傳分片操作來確認所有中止分片上傳后所有已上傳分片的空間是否被被釋放。

代碼示例

public function abortMultipartUpload() {
    //UploadId從createMultipartUpload中獲取
    $bucket = '<your-bucket-name>';
    $keyname = '<your-object-key>';
    $uploadId = '<your-upload-id';
?
    $result = $this->s3Client->abortMultipartUpload([
        'Bucket'   => $bucket,
        'Key'      => $keyname,
        'UploadId' => $uploadId,
    ]);
    echo $result;
}

請求參數

abortMultipartUpload 可設置的參數如下：