分段上传-九游平台

初始化分段上传任务

使用分段上传方式传输数据前，必须先通知obs初始化一个分段上传任务。该操作会返回一个obs服务端创建的全局唯一标识（upload id），用于标识本次分段上传任务。您可以根据这个唯一标识来发起相关的操作，如取消分段上传任务、列举分段上传任务、列举已上传的段等。

您可以通过obsclient->initiatemultipartupload初始化一个分段上传任务：

// 引入依赖库
require 'vendor/autoload.php';
// 使用源码安装时引入sdk代码库
// require 'obs-autoloader.php';
// 声明命名空间
use obs\obsclient;
// 创建obsclient实例
$obsclient = new obsclient ( [ 
      //推荐通过环境变量获取aksk，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险。
      //您可以登录访问管理控制台获取访问密钥ak/sk，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
      'key' => getenv('access_key_id'),
      'secret' => getenv('secret_access_key'),
      'endpoint' => 'https://your-endpoint'
] );
$resp = $obsclient->initiatemultipartupload([
       'bucket' => 'bucketname',
       'key' => 'objectname',
       'contenttype' => 'text/plain',
       'metadata' => ['property' => 'property-value']
]);
printf("requestid:%s\n",$resp['requestid']);
printf("uploadid:%s\n",$resp['uploadid']);

• 初始化分段上传任务时，除了指定上传对象的名称和所属桶外，您还可以使用contenttype参数和metadata参数分别指定对象mime类型和对象自定义元数据。
• 调用初始化分段上传任务接口成功后，会返回分段上传任务的全局唯一标识（upload id），在后面的操作中将用到它。

上传段

初始化一个分段上传任务之后，可以根据指定的对象名和upload id来分段上传数据。每一个上传的段都有一个标识它的号码——分段号（part number，范围是1~10000）。对于同一个upload id，该分段号不但唯一标识这一段数据，也标识了这段数据在整个对象内的相对位置。如果您用同一个分段号上传了新的数据，那么obs上已有的这个段号的数据将被覆盖。除了最后一段以外，其他段的大小范围是100kb~5gb；最后段大小范围是0~5gb。每个段不需要按顺序上传，甚至可以在不同进程、不同机器上上传，obs会按照分段号排序组成最终对象。

您可以通过obsclient->uploadpart上传段：

// 引入依赖库
require 'vendor/autoload.php';
// 使用源码安装时引入sdk代码库
// require 'obs-autoloader.php';
// 声明命名空间
use obs\obsclient;
// 创建obsclient实例
$obsclient = new obsclient ( [ 
      //推荐通过环境变量获取aksk，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险。
      //您可以登录访问管理控制台获取访问密钥ak/sk，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
      'key' => getenv('access_key_id'),
      'secret' => getenv('secret_access_key'),
      'endpoint' => 'https://your-endpoint'
] );
$resp = $obsclient->uploadpart([
       'bucket' => 'bucketname',
       'key' => 'objectname',
       // 设置分段号，范围是1~10000
       'partnumber' => 1,
       // 设置upload id
       'uploadid' => 'upload id from initiatemultipartupload',
       // 设置将要上传的大文件,localfile为上传的本地文件路径，需要指定到具体的文件名
       'sourcefile' => 'localfile',
       // 设置分段大小
       'partsize' => 5 * 1024 * 1024,
       // 设置分段的起始偏移大小
       'offset' => 0
]);
printf("requestid:%s\n",$resp['requestid']);
printf("etag:%s\n",$resp['etag']);

• 使用partnumber参数指定分段号；使用uploadid参数指定分段上传任务的全局唯一标识；使用sourcefile参数指定待上传的文件；使用partsize参数指定分段大小；使用offset参数指定分段的起始偏移大小。
• 上传段接口要求除最后一段以外，其他的段大小都要大于100kb。但是上传段接口并不会立即校验上传段的大小（因为不知道是否为最后一段）；只有调用合并段接口时才会校验。
• obs会将服务端收到段数据的etag值（段数据的md5值）返回给用户。
• 可以通过contentmd5参数设置上传数据的md5值，提供给obs服务端用于校验数据完整性。
• 分段号的范围是1~10000。如果超出这个范围，obs将返回400 bad request错误。
• obs 3.0的桶支持最小段的大小为100kb，obs 2.0的桶支持最小段的大小为5mb。请在obs 3.0的桶上执行分段上传操作。

合并段

所有分段上传完成后，需要调用合并段接口来在obs服务端生成最终对象。在执行该操作时，需要提供所有有效的分段列表（包括分段号和分段etag值）；obs收到提交的分段列表后，会逐一验证每个段的有效性。当所有段验证通过后，obs将把这些分段组合成最终的对象。

您可以通过obsclient->completemultipartupload合并段：

// 引入依赖库
require 'vendor/autoload.php';
// 使用源码安装时引入sdk代码库
// require 'obs-autoloader.php';
// 声明命名空间
use obs\obsclient;
// 创建obsclient实例
$obsclient = new obsclient ( [ 
      //推荐通过环境变量获取aksk，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险。
      //您可以登录访问管理控制台获取访问密钥ak/sk，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
      'key' => getenv('access_key_id'),
      'secret' => getenv('secret_access_key'),
      'endpoint' => 'https://your-endpoint'
] );
$resp = $obsclient->completemultipartupload([
       'bucket' => 'bucketname',
       'key' => 'objectname',
       // 设置upload id
       'uploadid' => 'upload id from initiatemultipartupload',
       'parts' => [
                     ['partnumber' => 1, 'etag' => 'etag value from uploadpart']
       ]
]);
printf("requestid:%s\n",$resp['requestid']);

• 如果最后一个段之外的其它段尺寸过小（小于100kb），obs返回400 bad request。

• 使用uploadid参数指定分段上传任务的全局唯一标识；使用parts参数指定分段号与分段etag值的列表，该列表必须按分段号升序排列。
• 分段可以是不连续的。

取消分段上传任务

分段上传任务可以被取消，当一个分段上传任务被取消后，就不能再使用其upload id做任何操作，已经上传段也会被obs删除。

采用分段上传方式上传对象过程中或上传对象失败后会在桶内产生段，这些段会占用您的存储空间，您可以通过取消该分段上传任务来清理掉不需要的段，节约存储空间。

您可以通过obsclient->abortmultipartupload取消分段上传任务：

// 引入依赖库
require 'vendor/autoload.php';
// 使用源码安装时引入sdk代码库
// require 'obs-autoloader.php';
// 声明命名空间
use obs\obsclient;
// 创建obsclient实例
$obsclient = new obsclient ( [ 
      //推荐通过环境变量获取aksk，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险。
      //您可以登录访问管理控制台获取访问密钥ak/sk，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
      'key' => getenv('access_key_id'),
      'secret' => getenv('secret_access_key'),
      'endpoint' => 'https://your-endpoint'
] );
$resp = $obsclient->abortmultipartupload([
       'bucket' => 'bucketname',
       'key' => 'objectname',
       // 设置upload id
       'uploadid' => 'upload id from initiatemultipartupload'
]);
printf("requestid:%s\n",$resp['requestid']);

列举已上传的段

您可使用obsclient->listparts列举出某一分段上传任务所有已经上传成功的段。

该接口可设置的参数如下：

• 简单列举

// 引入依赖库
require 'vendor/autoload.php';
// 使用源码安装时引入sdk代码库
// require 'obs-autoloader.php';
// 声明命名空间
use obs\obsclient;
// 创建obsclient实例
$obsclient = new obsclient ( [ 
      //推荐通过环境变量获取aksk，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险。
      //您可以登录访问管理控制台获取访问密钥ak/sk，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
      'key' => getenv('access_key_id'),
      'secret' => getenv('secret_access_key'),
      'endpoint' => 'https://your-endpoint'
] );
$resp = $obsclient->listparts ( [ 
      'bucket' => 'bucketname',
      'key' => 'objectname',
      'uploadid' => 'upload id from initiatemultipartupload' 
] );
printf ( "requestid:%s\n", $resp ['requestid'] );
foreach ( $resp ['parts'] as $index => $part ) {
       printf ( "parts[%d]\n", $index   1 );
       // 分段号，上传时候指定
       printf ( "partnumber:%s\n", $part ['partnumber'] );
       // 段的最后上传时间
       printf ( "lastmodified:%s\n", $part ['lastmodified'] );
       // 分段的etag值
       printf ( "etag:%s\n", $part ['etag'] );
       // 段数据大小
       printf ( "size:%s\n", $part ['size'] );
}

• 列举段至多返回1000个段信息，如果指定的upload id包含的段数量大于1000，则返回结果中istruncated为true表明本次没有返回全部段，并可通过nextpartnumbermarker获取下次列举的起始位置。
• 如果想获取指定upload id包含的所有分段，可以采用分页列举的方式。

• 列举所有段

由于obsclient->listparts只能列举至多1000个段，如果段数量大于1000，列举所有分段请参考如下示例：

// 引入依赖库
require 'vendor/autoload.php';
// 使用源码安装时引入sdk代码库
// require 'obs-autoloader.php';
// 声明命名空间
use obs\obsclient;
// 创建obsclient实例
$obsclient = new obsclient ( [ 
      //推荐通过环境变量获取aksk，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险。
      //您可以登录访问管理控制台获取访问密钥ak/sk，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
      'key' => getenv('access_key_id'),
      'secret' => getenv('secret_access_key'),
      'endpoint' => 'https://your-endpoint'
] );
$partnumbermarker = null;
$index = 1;
do{
       $resp = $obsclient->listparts ( [ 
             'bucket' => 'bucketname',
             'key' => 'objectname',
             'uploadid' => 'upload id from initiatemultipartupload',
             'partnumbermarker' => $partnumbermarker
       ] );
       
       printf ( "requestid:%s\n", $resp ['requestid'] );
       foreach ( $resp ['parts'] as $part ) {
              printf ( "parts[%d]\n", $index );
              // 分段号，上传时候指定
              printf ( "partnumber:%s\n", $part ['partnumber'] );
              // 段的最后上传时间
              printf ( "lastmodified:%s\n", $part ['lastmodified'] );
              // 分段的etag值
              printf ( "etag:%s\n", $part ['etag'] );
              // 段数据大小
              printf ( "size:%s\n", $part ['size'] );
              $index   ;
       }
       
       $partnumbermarker = $resp['nextpartnumbermarker'];
       
}while($resp['istruncated']);

列举分段上传任务

您可以通过obsclient->listmultipartuploads列举分段上传任务。列举分段上传任务可设置的参数如下：

• 简单列举分段上传任务

// 引入依赖库
require 'vendor/autoload.php';
// 使用源码安装时引入sdk代码库
// require 'obs-autoloader.php';
// 声明命名空间
use obs\obsclient;
// 创建obsclient实例
$obsclient = new obsclient ( [ 
      //推荐通过环境变量获取aksk，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险。
      //您可以登录访问管理控制台获取访问密钥ak/sk，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
      'key' => getenv('access_key_id'),
      'secret' => getenv('secret_access_key'),
      'endpoint' => 'https://your-endpoint'
] );
$resp = $obsclient->listmultipartuploads ( [ 
      'bucket' => 'bucketname' 
] );
printf ( "requestid:%s\n", $resp ['requestid'] );
foreach ( $resp ['uploads'] as $index => $upload ) {
       printf ( "uploads[%d]\n", $index   1 );
       printf ( "key:%s\n", $upload ['key'] );
       printf ( "uploadid:%s\n", $upload ['uploadid'] );
       printf ( "initiated:%s\n", $upload ['initiated'] );
       printf ( "owner[id]:%s\n", $upload ['owner'] ['id'] );
       printf ( "storageclass:%s\n", $upload ['storageclass'] );
}

• 列举分段上传任务至多返回1000个任务信息，如果指定的桶包含的分段上传任务数量大于1000，则返回结果中istruncated为true表明本次没有返回全部结果，并可通过nextkeymarker和nextuploadidmarker获取下次列举的起点。
• 如果想获取指定桶包含的所有分段上传任务，可以采用分页列举的方式。

• 列举全部分段上传任务

// 引入依赖库
require 'vendor/autoload.php';
// 使用源码安装时引入sdk代码库
// require 'obs-autoloader.php';
// 声明命名空间
use obs\obsclient;
// 创建obsclient实例
$obsclient = new obsclient ( [ 
      //推荐通过环境变量获取aksk，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险。
      //您可以登录访问管理控制台获取访问密钥ak/sk，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
      'key' => getenv('access_key_id'),
      'secret' => getenv('secret_access_key'),
      'endpoint' => 'https://your-endpoint'
] );
$keymarker = null;
$uploadidmarker = null;
$index = 1;
do{
       $resp = $obsclient->listmultipartuploads ( [ 
             'bucket' => 'bucketname',
             'keymarker' => $keymarker,
             'uploadidmarker' => $uploadidmarker
       ] );
       
       printf ( "requestid:%s\n", $resp ['requestid'] );
       foreach ( $resp ['uploads'] as $index => $upload ) {
              printf ( "uploads[%d]\n", $index );
              printf ( "key:%s\n", $upload ['key'] );
              printf ( "uploadid:%s\n", $upload ['uploadid'] );
              printf ( "initiated:%s\n", $upload ['initiated'] );
              printf ( "owner[id]:%s\n", $upload ['owner'] ['id'] );
              printf ( "storageclass:%s\n", $upload ['storageclass'] );
              $index   ;
       }
       $keymarker = $resp['nextkeymarker'];
       $uploadidmarker = $resp['nextuploadidmarker'];
}while ($resp['istruncated']);