本文介绍如何使用PHP SDK V2在开启版本控制的存储空间(Bucket)中上传文件(Object)。
注意事项
本文示例代码以华东1(杭州)的地域ID
cn-hangzhou
为例,默认使用外网Endpoint,如果您希望通过与OSS同地域的其他阿里云产品访问OSS,请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系,请参见OSS地域和访问域名。要上传文件,您必须有
oss:PutObject
权限。具体操作,请参见为RAM用户授权自定义的权限策略。
示例代码
简单上传
在已开启版本控制的Bucket中,OSS会为新添加的Object自动生成唯一的VersionId,并在响应header中通过x-oss-version-id形式返回。
在暂停了版本控制的Bucket中,新添加的Object的VersionId为“null”,上传同名Object,后一次会覆盖前一次上传的文件内容。OSS保证同一个Object只会有一个版本的ID为“null”。
您可以使用以下代码进行简单上传。
<?php
// 引入自动加载文件 加载依赖库
require_once __DIR__ . '/../vendor/autoload.php';
use AlibabaCloud\Oss\V2 as Oss;
// 定义命令行参数描述
$optsdesc = [
"region" => ['help' => 'The region in which the bucket is located', 'required' => True], // 区域是必填项 存储空间所在的区域
"endpoint" => ['help' => 'The domain names that other services can use to access OSS', 'required' => False], // 终端节点是可选项 其他服务可以用来访问OSS的域名
"bucket" => ['help' => 'The name of the bucket', 'required' => True], // 存储空间名称是必填项
"key" => ['help' => 'The name of the object', 'required' => True], // 对象名称是必填项
];
// 生成长选项列表 用于解析命令行参数
$longopts = \array_map(function ($key) {
return "$key:"; // 每个参数后面加冒号 表示需要值
}, array_keys($optsdesc));
// 解析命令行参数
$options = getopt("", $longopts);
// 检查必填参数是否缺失
foreach ($optsdesc as $key => $value) {
if ($value['required'] === True && empty($options[$key])) {
$help = $value['help'];
echo "Error: the following arguments are required: --$key, $help"; // 提示用户缺少必填参数
exit(1);
}
}
// 获取命令行参数值
$region = $options["region"]; // 存储空间所在区域
$bucket = $options["bucket"]; // 存储空间名称
$key = $options["key"]; // 对象名称
// 使用环境变量加载凭证信息 AccessKeyId 和 AccessKeySecret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
// 使用SDK的默认配置
$cfg = Oss\Config::loadDefault();
// 设置凭证提供者
$cfg->setCredentialsProvider($credentialsProvider);
// 设置区域
$cfg->setRegion($region);
// 如果提供了终端节点 则设置终端节点
if (isset($options["endpoint"])) {
$cfg->setEndpoint($options["endpoint"]);
}
// 创建OSS客户端实例
$client = new Oss\Client($cfg);
// 定义要上传的数据内容
$data = 'Hello OSS';
// 创建上传对象的请求对象
$request = new Oss\Models\PutObjectRequest(
bucket: $bucket,
key: $key,
);
// 设置请求体为数据流
$request->body = Oss\Utils::streamFor($data);
// 调用putObject方法上传对象
$result = $client->putObject($request);
// 打印返回结果
printf(
'status code:' . $result->statusCode . PHP_EOL . // HTTP响应状态码
'request id:' . $result->requestId . PHP_EOL . // 请求的唯一标识
'etag:' . $result->etag . PHP_EOL // 对象的ETag值
);
追加上传
在受版本控制的Bucket中,仅支持对于当前版本为Appendable类型的Object执行追加(AppendObject)操作,不支持对于历史版本为Appendable类型的Object执行AppendObject操作。
对当前版本为Appendable类型的Object执行AppendObject操作时,OSS不会为该Appendable类型的Object生成历史版本。
对当前版本为Appendable类型的Object执行PutObject或DeleteObject操作时,OSS会将该Appendable类型的Object保留为历史版本,且该Object不允许继续追加。
不支持对当前版本为非Appendable类型的Object(包括 Normal Object、Delete Marker等)执行AppendObject 操作。
您可以使用以下代码进行追加上传。
<?php
// 引入自动加载文件 加载依赖库
require_once __DIR__ . '/../vendor/autoload.php';
use AlibabaCloud\Oss\V2 as Oss;
// 定义命令行参数描述
$optsdesc = [
"region" => ['help' => 'The region in which the bucket is located', 'required' => True], // 区域是必填项 存储空间所在的区域
"endpoint" => ['help' => 'The domain names that other services can use to access OSS', 'required' => False], // 终端节点是可选项 其他服务可以用来访问OSS的域名
"bucket" => ['help' => 'The name of the bucket', 'required' => True], // 存储空间名称是必填项
"key" => ['help' => 'The name of the object', 'required' => True], // 对象名称是必填项
];
// 生成长选项列表 用于解析命令行参数
$longopts = \array_map(function ($key) {
return "$key:"; // 每个参数后面加冒号 表示需要值
}, array_keys($optsdesc));
// 解析命令行参数
$options = getopt("", $longopts);
// 检查必填参数是否缺失
foreach ($optsdesc as $key => $value) {
if ($value['required'] === True && empty($options[$key])) {
$help = $value['help'];
echo "Error: the following arguments are required: --$key, $help"; // 提示用户缺少必填参数
exit(1);
}
}
// 获取命令行参数值
$region = $options["region"]; // 存储空间所在区域
$bucket = $options["bucket"]; // 存储空间名称
$key = $options["key"]; // 对象名称
// 使用环境变量加载凭证信息 AccessKeyId 和 AccessKeySecret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
// 使用SDK的默认配置
$cfg = Oss\Config::loadDefault();
// 设置凭证提供者
$cfg->setCredentialsProvider($credentialsProvider);
// 设置区域
$cfg->setRegion($region);
// 如果提供了终端节点 则设置终端节点
if (isset($options["endpoint"])) {
$cfg->setEndpoint($options["endpoint"]);
}
// 创建OSS客户端实例
$client = new Oss\Client($cfg);
// 定义要追加的数据内容
$data = 'Hello Append Object';
// 创建追加对象的请求对象
$request = new Oss\Models\AppendObjectRequest(bucket: $bucket, key: $key);
// 设置请求体为数据流
$request->body = Oss\Utils::streamFor($data);
// 设置追加位置为0 表示从对象开头追加
$request->position = 0;
// 调用appendObject方法追加对象
$result = $client->appendObject($request);
// 打印返回结果
printf(
'status code:' . $result->statusCode . PHP_EOL . // HTTP响应状态码
'request id:' . $result->requestId // 请求的唯一标识
);
分片上传
在受版本控制的Bucket中,调用CompleteMultipartUpload接口来完成整个文件的分片上传,OSS会为整个文件生成唯一的版本ID,并在响应header中以x-oss-version-id的形式返回。
您可以使用以下代码进行分片上传。
<?php
// 引入自动加载文件,确保依赖库能够正确加载
require_once __DIR__ . '/../vendor/autoload.php';
use AlibabaCloud\Oss\V2 as Oss;
// 定义命令行参数的描述信息
$optsdesc = [
"region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // Bucket所在的地域(必填)
"endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // 访问域名(可选)
"bucket" => ['help' => 'The name of the bucket', 'required' => True], // Bucket名称(必填)
"key" => ['help' => 'The name of the object', 'required' => True], // 对象名称(必填)
];
// 将参数描述转换为getopt所需的长选项格式
// 每个参数后面加上":"表示该参数需要值
$longopts = \array_map(function ($key) {
return "$key:";
}, array_keys($optsdesc));
// 解析命令行参数
$options = getopt("", $longopts);
// 验证必填参数是否存在
foreach ($optsdesc as $key => $value) {
if ($value['required'] === True && empty($options[$key])) {
$help = $value['help']; // 获取参数的帮助信息
echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
exit(1); // 如果必填参数缺失,则退出程序
}
}
// 从解析的参数中提取值
$region = $options["region"]; // Bucket所在的地域
$bucket = $options["bucket"]; // Bucket名称
$key = $options["key"]; // 对象名称
// 加载环境变量中的凭证信息
// 使用EnvironmentVariableCredentialsProvider从环境变量中读取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
// 使用SDK的默认配置
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 设置凭证提供者
$cfg->setRegion($region); // 设置Bucket所在的地域
if (isset($options["endpoint"])) {
$cfg->setEndpoint($options["endpoint"]); // 如果提供了访问域名,则设置endpoint
}
// 创建OSS客户端实例
$client = new Oss\Client($cfg);
// 初始化分片上传请求
$request = new Oss\Models\InitiateMultipartUploadRequest(bucket: $bucket, key: $key);
$result = $client->initiateMultipartUpload($request);
// 获取分片上传的uploadId
$uploadId = $result->uploadId;
// 创建分片上传请求对象
$request = new Oss\Models\UploadPartRequest(bucket: $bucket, key: $key);
// 定义大文件路径和分片大小
$bigFileName = "/Users/localpath/yourfilename"; // 填写大文件路径
$partSize = 1 * 1024 * 1024; // 分片大小,单位为字节(此处设置为1MB)
// 打开大文件并准备分片上传
$file = fopen($bigFileName, 'r');
$parts = []; // 用于存储每个分片的信息
if ($file) {
$i = 1; // 分片编号从1开始
while (!feof($file)) {
$chunk = fread($file, $partSize); // 读取指定大小的数据块
// 执行分片上传操作
$partResult = $client->uploadPart(
new Oss\Models\UploadPartRequest(
bucket: $bucket,
key: $key,
partNumber: $i, // 分片编号
uploadId: $uploadId, // 分片上传的uploadId
contentLength: null,
contentMd5: null,
trafficLimit: null,
requestPayer: null,
body: Oss\Utils::streamFor(resource: $chunk) // 将数据块转换为流
)
);
// 创建UploadPart对象,记录分片编号和ETag
$part = new Oss\Models\UploadPart(
partNumber: $i,
etag: $partResult->etag,
);
array_push($parts, $part); // 将分片信息添加到数组中
$i++; // 分片编号递增
}
fclose($file); // 关闭文件句柄
}
// 完成分片上传操作
$comResult = $client->completeMultipartUpload(
new Oss\Models\CompleteMultipartUploadRequest(
bucket: $bucket,
key: $key,
uploadId: $uploadId, // 分片上传的uploadId
acl: null,
completeMultipartUpload: new Oss\Models\CompleteMultipartUpload(
parts: $parts // 传入所有分片的信息
),
)
);
// 打印完成分片上传的结果
printf(
'status code:' . $comResult->statusCode . PHP_EOL . // HTTP状态码,例如200表示成功
'request id:' . $comResult->requestId . PHP_EOL . // 请求ID,用于调试或追踪请求
'complete multipart upload result:' . var_export($comResult, true) // 完成分片上传的详细结果
);
相关文档
关于简单上传的更多信息,请参见PutObject。
关于追加上传的更多信息,请参见AppendObject。
关于分片上传的更多信息,请参见CompleteMultipartUpload。
- 本页导读 (1)
- 注意事项
- 示例代码
- 简单上传
- 追加上传
- 分片上传
- 相关文档