1767 lines
57 KiB
Markdown
1767 lines
57 KiB
Markdown
|
||
|
||
# 开发者指南
|
||
## [English](DEVGUIDE.md)
|
||
|
||
阿里云对象存储（Object Storage Service，简称OSS），是阿里云对外提供的海量、安全、低成本、高可靠的云存储服务。用户可以通过调用API，在任何应用、任何时间、任何地点上传和下载数据，也可以通过用户Web控制台对数据进行简单的管理。OSS适合存放任意文件类型，适合各种网站、开发企业及开发者使用。
|
||
|
||
该开发套件隐藏了许多较低级别的实现，例如身份验证、请求重试和错误处理, 通过其提供的接口，让您不用复杂编程即可访问阿里云OSS服务。
|
||
|
||
该开发套件同时提供实用的模块，例如上传和下载管理器，自动将大对象分成多块并行传输。
|
||
|
||
您可以参阅该指南，来帮助您安装、配置和使用该开发套件。
|
||
|
||
跳转到:
|
||
|
||
* [安装](#安装)
|
||
* [配置](#配置)
|
||
* [接口说明](#接口说明)
|
||
* [场景示例](#场景示例)
|
||
* [迁移指南](#迁移指南)
|
||
|
||
# 安装
|
||
|
||
## 环境准备
|
||
|
||
使用PHP 7.4及以上版本。
|
||
请参考[php安装](https://www.php.net/manual/install.php)下载和安装php运行环境。
|
||
您可以执行以下命令查看php语言版本。
|
||
```
|
||
php -v
|
||
```
|
||
|
||
## 安装SDK
|
||
|
||
### composer 方式
|
||
在项目的根目录运行 composer require alibabacloud/oss-v2，
|
||
</br>或者在composer.json文件中添加如下依赖关系，并运行 composer install 安装依赖。
|
||
```
|
||
"require": {
|
||
"alibabacloud/oss-v2": "*"
|
||
}
|
||
```
|
||
安装完成后，目录结构如下，其中app.php是您的应用程序：
|
||
```
|
||
.
|
||
├── src
|
||
| └──app.php
|
||
├── composer.json
|
||
├── composer.lock
|
||
└── vendor
|
||
|
||
```
|
||
您可以通过将以下内容添加到您的代码中来自动加载所有依赖项
|
||
```
|
||
require_once __DIR__ . '/../vendor/autoload.php';
|
||
```
|
||
|
||
### phar方式
|
||
在[GitHub](https://github.com/aliyun/alibabacloud-oss-php-sdk-v2/releases)中选择相应的版本并下载打包好的phar文件。
|
||
|
||
在代码中引入phar文件：
|
||
```
|
||
require_once '/path/to/alibabacloud-oss-php-sdk-v2-{version}.phar';
|
||
```
|
||
|
||
### 源码方式
|
||
在[GitHub](https://github.com/aliyun/alibabacloud-oss-php-sdk-v2/releases)中选择相应的版本并并下载打包好的zip文件。
|
||
|
||
解压后的根目录中包含一个autoload.php文件，在代码中引入此文件：
|
||
```
|
||
require_once '/path/to/alibabacloud-oss-php-sdk-v2/autoload.php';
|
||
```
|
||
|
||
## 验证SDK
|
||
运行以下代码查看SDK版本：
|
||
```
|
||
<?php
|
||
require_once 'vendor/autoload.php';
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
|
||
print_r(Oss\Version::VERSION);
|
||
```
|
||
|
||
# 配置
|
||
您可以配置服务客户端的常用设置，例如超时、日志级别和重试配置，大多数设置都是可选的。
|
||
但是，对于每个客户端，您必须指定区域和凭证。 SDK使用这些信息签署请求并将其发送到正确的区域。
|
||
|
||
此部分的其它主题
|
||
* [区域](#区域)
|
||
* [凭证](#凭证)
|
||
* [访问域名](#访问域名)
|
||
* [HTTP客户端](#http客户端)
|
||
* [重试](#重试)
|
||
* [配置参数汇总](#配置参数汇总)
|
||
|
||
## 加载配置
|
||
配置客户端的设置有多种方法，以下是推荐的模式。
|
||
|
||
```
|
||
<?php
|
||
require_once 'vendor/autoload.php';
|
||
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
|
||
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider($credentialsProvider);
|
||
$region = 'cn-hangzhou';
|
||
$cfg->setRegion($region);
|
||
```
|
||
|
||
## 区域
|
||
指定区域时，您可以指定向何处发送请求，例如 cn-hangzhou 或 cn-shanghai。有关所支持的区域列表，请参阅 [OSS访问域名和数据中心](https://www.alibabacloud.com/help/zh/oss/user-guide/regions-and-endpoints)。
|
||
SDK 没有默认区域，您需要加载配置时使用`(new Config())->setRegion`作为参数显式设置区域。例如
|
||
```
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRegion("cn-hangzhou");
|
||
```
|
||
|
||
>**说明**：该SDK默认使用v4签名，所以必须指定该参数。
|
||
|
||
## 凭证
|
||
|
||
SDK需要凭证（访问密钥）来签署对 OSS 的请求, 所以您需要显式指定这些信息。当前支持凭证配置如下：
|
||
* [环境变量](#环境变量)
|
||
* [静态凭证](#静态凭证)
|
||
* [ECS实例角色](#ecs实例角色)
|
||
* [RAM角色](#ram角色)
|
||
* [OIDC角色SSO](#oidc角色sso)
|
||
* [自定义凭证提供者](#自定义凭证提供者)
|
||
|
||
### 环境变量
|
||
|
||
SDK 支持从环境变量获取凭证，支持的环境变量名如下：
|
||
* OSS_ACCESS_KEY_ID
|
||
* OSS_ACCESS_KEY_SECRET
|
||
* OSS_SESSION_TOKEN（可选）
|
||
|
||
以下展示了如何配置环境变量。
|
||
|
||
1. Linux、OS X 或 Unix
|
||
```
|
||
$ export OSS_ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID
|
||
$ export OSS_ACCESS_KEY_SECRET=YOUR_ACCESS_KEY_SECRET
|
||
$ export OSS_SESSION_TOKEN=TOKEN
|
||
```
|
||
|
||
2. Windows
|
||
```
|
||
$ set OSS_ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID
|
||
$ set OSS_ACCESS_KEY_SECRET=YOUR_ACCESS_KEY_SECRET
|
||
$ set OSS_SESSION_TOKEN=TOKEN
|
||
```
|
||
|
||
使用环境变量凭证
|
||
|
||
```
|
||
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider($credentialsProvider);
|
||
```
|
||
### 静态凭证
|
||
|
||
您可以在应用程序中对凭据进行硬编码，显式设置要使用的访问密钥。
|
||
|
||
> **注意:** 请勿将凭据嵌入应用程序中，此方法仅用于测试目的。
|
||
|
||
1. 长期凭证
|
||
```
|
||
$credentialsProvider = new Oss\Credentials\StaticCredentialsProvider("AKId", "AKSecrect");
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider($credentialsProvider);
|
||
```
|
||
|
||
2. 临时凭证
|
||
```
|
||
$credentialsProvider = new Oss\Credentials\StaticCredentialsProvider("AKId", "AKSecrect","Token");
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider($credentialsProvider);
|
||
```
|
||
|
||
### ECS实例角色
|
||
|
||
如果你需要在阿里云的云服务器ECS中访问您的OSS，您可以通过ECS实例RAM角色的方式访问OSS。实例RAM角色允许您将一个角色关联到云服务器实例，在实例内部基于STS临时凭证通过指定方法访问OSS。
|
||
|
||
SDK 不直接提供该访问凭证实现，需要结合阿里云凭证库[credentials-php](https://github.com/aliyun/credentials-php)，具体配置如下:
|
||
|
||
```
|
||
<?php
|
||
require_once 'vendor/autoload.php';
|
||
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
use AlibabaCloud\Credentials\Credential;
|
||
|
||
// ...
|
||
$config = new Credential\Config([
|
||
// 填写Credential类型，固定值为ecs_ram_role。
|
||
'type' => 'ecs_ram_role',
|
||
'roleName' => "<role_name>",
|
||
]);
|
||
|
||
$credential = new Credential($config);
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider(new Oss\Credentials\CredentialsProviderFunc(function () use ($credential) {
|
||
$cred = $credential->getCredential();
|
||
return new AlibabaCloud\Oss\V2\Credentials\Credentials($cred->getAccessKeyId(), $cred->getAccessKeySecret(), $cred->getSecurityToken());
|
||
}));
|
||
$region = 'cn-hangzhou';
|
||
$cfg->setRegion($region);
|
||
|
||
```
|
||
|
||
### RAM角色
|
||
|
||
如果您需要授权访问或跨账号访问OSS，您可以通过RAM用户扮演对应RAM角色的方式授权访问或跨账号访问OSS。
|
||
|
||
SDK 不直接提供该访问凭证实现，需要结合阿里云凭证库[credentials-php](https://github.com/aliyun/credentials-php)，具体配置如下:
|
||
|
||
```
|
||
<?php
|
||
require_once 'vendor/autoload.php';
|
||
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
use AlibabaCloud\Credentials\Credential;
|
||
|
||
// ...
|
||
$config = new Credential\Config([
|
||
// Which type of credential you want
|
||
'type' => 'ram_role_arn',
|
||
// AccessKeyId of your account
|
||
'accessKeyId' => 'AccessKeyId',
|
||
// AccessKeySecret of your account
|
||
'accessKeySecret' => 'AccessKeySecret',
|
||
// Format: acs:ram::USER_Id:role/ROLE_NAME
|
||
'roleArn' => 'RoleArn',
|
||
// Role Session Name
|
||
'roleSessionName' => 'yourRoleSessionName',
|
||
// Not required, limit the permissions of STS Token
|
||
'policy' => 'Policy',
|
||
]);
|
||
|
||
$credential = new Credential($config);
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider(new Oss\Credentials\CredentialsProviderFunc(function () use ($credential) {
|
||
$cred = $credential->getCredential();
|
||
return new AlibabaCloud\Oss\V2\Credentials\Credentials($cred->getAccessKeyId(), $cred->getAccessKeySecret(), $cred->getSecurityToken());
|
||
}));
|
||
$region = 'cn-hangzhou';
|
||
$cfg->setRegion($region);
|
||
|
||
```
|
||
|
||
### OIDC角色SSO
|
||
|
||
您也可以在应用或服务中使用OIDC认证访问OSS服务，关于OIDC角色SSO的更多信息，请参见[OIDC角色SSO概览](https://www.alibabacloud.com/help/zh/ram/user-guide/overview-of-oidc-based-sso)。
|
||
|
||
SDK 不直接提供该访问凭证实现，需要结合阿里云凭证库[credentials-php](https://github.com/aliyun/credentials-php)，具体配置如下:
|
||
|
||
```
|
||
<?php
|
||
require_once 'vendor/autoload.php';
|
||
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
use AlibabaCloud\Credentials\Credential;
|
||
|
||
// ...
|
||
$config = new Credential\Config([
|
||
'type' => 'oidc_role_arn',
|
||
// Specify the ARN of the OIDC IdP by specifying the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
|
||
'oidcProviderArn' => '<oidc_provider_arn>',
|
||
// Specify the path of the OIDC token file by specifying the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
|
||
'oidcTokenFilePath' => '<oidc_token_file_path>',
|
||
// Specify the ARN of the RAM role by specifying the ALIBABA_CLOUD_ROLE_ARN environment variable.
|
||
'roleArn' => '<role_arn>',
|
||
// Specify the role session name by specifying the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
|
||
'roleSessionName' => '<role_session_name>',
|
||
// Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
|
||
'policy' => '',
|
||
// Optional. Specify the validity period of the session.
|
||
'roleSessionExpiration' => 3600,
|
||
]);
|
||
|
||
$credential = new Credential($config);
|
||
$cfg = Oss\Config::loadDefault();
|
||
$providerWrapper = new AlibabaCloudCredentialsWrapper($credential);
|
||
$cfg->setCredentialsProvider(new Oss\Credentials\CredentialsProviderFunc(function () use ($credential) {
|
||
$cred = $credential->getCredential();
|
||
return new AlibabaCloud\Oss\V2\Credentials\Credentials($cred->getAccessKeyId(), $cred->getAccessKeySecret(), $cred->getSecurityToken());
|
||
}));
|
||
$region = 'cn-hangzhou';
|
||
$cfg->setRegion($region);
|
||
```
|
||
|
||
### 自定义凭证提供者
|
||
|
||
当以上凭证配置方式不满足要求时，您可以自定义获取凭证的方式。SDK 支持多种实现方式。
|
||
|
||
1. 实现 Oss\Credentials\CredentialsProvider 接口
|
||
```
|
||
<?php
|
||
require_once 'vendor/autoload.php';
|
||
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
use AlibabaCloud\Oss\V2\Credentials\Credentials;
|
||
|
||
class CustomerCredentialsProvider implements Oss\Credentials\CredentialsProvider
|
||
{
|
||
public function getCredentials(): Credentials
|
||
{
|
||
// 返回长期凭证
|
||
return new Credentials('id', 'secret');
|
||
// 返回临时凭证
|
||
// return new Credentials(
|
||
// 'id',
|
||
// 'secret',
|
||
// 'token',
|
||
// );
|
||
}
|
||
}
|
||
|
||
$provider = new CustomerCredentialsProvider();
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider($provider);
|
||
$region = 'cn-hangzhou';
|
||
$cfg->setRegion($region);
|
||
|
||
```
|
||
|
||
2. 通过 Oss\Credentials\CredentialsProviderFunc
|
||
|
||
Oss\Credentials\CredentialsProviderFunc 是 Oss\Credentials\CredentialsProvider 的 易用性封装。
|
||
|
||
```
|
||
<?php
|
||
require_once 'vendor/autoload.php';
|
||
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
use AlibabaCloud\Oss\V2\Credentials\Credentials;
|
||
|
||
$provider = new Oss\Credentials\CredentialsProviderFunc(
|
||
function () {
|
||
return new Credentials('id', 'secret');
|
||
// 返回临时凭证
|
||
// return new Credentials(
|
||
// 'id',
|
||
// 'secret',
|
||
// 'token',
|
||
// );
|
||
}
|
||
);
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider($provider);
|
||
$region = 'cn-hangzhou';
|
||
$cfg->setRegion($region);
|
||
```
|
||
## 访问域名
|
||
|
||
您可以通过Endpoint参数，自定义服务请求的访问域名。
|
||
|
||
当不指定时，SDK根据Region信息，构造公网访问域名。例如当Region为'cn-hangzhou'时，构造出来的访问域名为'oss-cn-hangzhou.aliyuncs.com'。
|
||
|
||
您可以通过修改配置参数，构造出其它访问域名，例如 内网访问域名，传输加速访问域名 和 双栈(IPV6,IPV4)访问域名。有关OSS访问域名规则，请参考[OSS访问域名使用规则](https://www.alibabacloud.com/help/zh/oss/user-guide/oss-domain-names)。
|
||
|
||
当通过自定义域名访问OSS服务时，您需要指定该配置参数。在使用自定义域名发送请求时，请先绑定自定域名至Bucket默认域名，具体操作详见 [绑定自定义域名](https://www.alibabacloud.com/help/zh/oss/user-guide/map-custom-domain-names-5)。
|
||
|
||
### 使用标准域名访问
|
||
|
||
以 访问 Region 'cn-hangzhou' 为例
|
||
|
||
1. 使用公网域名
|
||
|
||
```
|
||
$cfg = Oss\Config::loadDefault();
|
||
$region = 'cn-hangzhou';
|
||
$cfg->setRegion($region);
|
||
|
||
或者
|
||
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRegion('cn-hangzhou')->setEndpoint('oss-cn-hanghzou.aliyuncs.com');
|
||
```
|
||
|
||
2. 使用内网域名
|
||
|
||
```
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRegion('cn-hangzhou')->setUseInternalEndpoint(true);
|
||
|
||
或者
|
||
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRegion('cn-hangzhou')->setEndpoint('oss-cn-hanghzou-internal.aliyuncs.com');
|
||
```
|
||
|
||
3. 使用传输加速域名
|
||
```
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg = $cfg->setRegion('cn-hangzhou')->setUseAccelerateEndpoint(true);
|
||
|
||
或者
|
||
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRegion('cn-hangzhou')->setEndpoint('oss-accelerate.aliyuncs.com');
|
||
```
|
||
|
||
4. 使用双栈域名
|
||
```
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRegion('cn-hangzhou')->setUseDualStackEndpoint(true);
|
||
|
||
或者
|
||
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRegion('cn-hangzhou')->setEndpoint('cn-hangzhou.oss.aliyuncs.com');
|
||
```
|
||
|
||
### 使用自定义域名访问
|
||
|
||
以 'www.example-***.com' 域名 绑定到 'cn-hangzhou' 区域 的 bucket-example 存储空间为例
|
||
|
||
```
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRegion('cn-hangzhou')->setEndpoint('www.example-***.com')->setUseCname(true);
|
||
```
|
||
|
||
### 访问专有云或专有域
|
||
|
||
```
|
||
$region = 'YOUR Region';
|
||
$endpoint = 'YOUR Endpoint';
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRegion($region)->setEndpoint($endpoint);
|
||
```
|
||
|
||
## HTTP客户端
|
||
|
||
在大多数情况下，使用具有默认值的默认HTTP客户端 能够满足业务需求。您也可以更改HTTP 客户端，或者更改 HTTP 客户端的默认配置，以满足特定环境下的使用需求。
|
||
|
||
本部分将介绍如何设置 和 创建 HTTP 客户端。
|
||
|
||
### 设置HTTP客户端常用配置
|
||
|
||
通过config修改常用的配置，支持参数如下：
|
||
|
||
|参数名字 | 说明 | 示例
|
||
|:-------|:-------|:-------
|
||
|connectTimeout|建立连接的超时时间, 默认值为 10 秒|setConnectTimeout(10)
|
||
|readWriteTimeout|应用读写数据的超时时间, 默认值为 20 秒|setReadWriteTimeout(30)
|
||
|insecureSkipVerify|是否跳过SSL证书校验，默认检查SSL证书|setInsecureSkipVerify(true)
|
||
|enabledRedirect|是否开启HTTP重定向, 默认不开启|setEnabledRedirect(true)
|
||
|proxyHost|设置代理服务器|setProxyHost(’http://user:passswd@proxy.example-***.com’)
|
||
|
||
示例
|
||
|
||
```
|
||
$cfg->setConnectTimeout(10)->setInsecureSkipVerify(true);
|
||
```
|
||
|
||
### 使用 Swoole 配置
|
||
|
||
常用配置参数在 Swoole 项目中运行会出错，可以使用 $options 中的 handler 修改默认的 HTTP 客户端。
|
||
|
||
以 hyperf 框架为例，常用配置已经无法正常运行 sdk，需要添加 handler 。
|
||
|
||
```
|
||
<?php
|
||
require_once 'vendor/autoload.php';
|
||
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
use GuzzleHttp\HandlerStack;
|
||
use Hyperf\Guzzle\CoroutineHandler;
|
||
use function Hyperf\Coroutine\co;
|
||
|
||
$region = 'cn-hangzhou';
|
||
$bucket = 'bucket-name';
|
||
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider($credentialsProvider);
|
||
$cfg->setRegion($region);
|
||
$cfg->setEndpoint('http://oss-cn-hangzhou.aliyuncs.com');
|
||
$client = new Oss\Client($cfg, ['handler' => HandlerStack::create(new CoroutineHandler())]);
|
||
co(function () use ($client, $bucket) {
|
||
try {
|
||
$key = 'swoole.txt';
|
||
$data = 'Hello OSS';
|
||
$request = new Oss\Models\PutObjectRequest($bucket, $key);
|
||
$request->body = Oss\Utils::streamFor($data);
|
||
$result = $client->putObject($request);
|
||
echo var_export($result, true);
|
||
} catch (\Exception $e) {
|
||
print_r($e->getMessage());
|
||
}
|
||
});
|
||
|
||
co(function () use ($client, $bucket) {
|
||
try {
|
||
$key = 'hyperf.txt';
|
||
$data = 'Hello OSS';
|
||
$request = new Oss\Models\PutObjectRequest($bucket, $key);
|
||
$request->body = Oss\Utils::streamFor($data);
|
||
$result = $client->putObject($request);
|
||
echo var_export($result, true);
|
||
} catch (\Exception $e) {
|
||
print_r($e->getMessage());
|
||
}
|
||
});
|
||
```
|
||
|
||
## 重试
|
||
|
||
您可以配置对HTTP请求的重试行为。
|
||
|
||
### 默认重试策略
|
||
|
||
当没有配置重试策略时，SDK 使用 AlibabaCloud\Oss\V2\Retry\StandardRetryer 作为客户端的默认实现，其默认配置如下：
|
||
|
||
|参数名称 | 说明 | 默认值
|
||
|:-------|:-------|:-------
|
||
|maxAttempts|最大尝试次数| 3
|
||
|maxBackoff|最大退避时间| 20秒, 20
|
||
|baseDelay|基础延迟| 200毫秒, 0.2
|
||
|backoff|退避算法| FullJitter 退避, [0.0, 1.0) * min(2 ^ attempts * baseDealy, maxBackoff)
|
||
|errorRetryables|可重试的错误| 具体的错误信息，请参见[重试错误](src/Retry)
|
||
|
||
当发生可重试错误时，将使用其提供的配置来延迟并随后重试该请求。请求的总体延迟会随着重试次数而增加，如果默认配置不满足您的场景需求时，需要配置重试参数 或者修改重试实现。
|
||
|
||
### 调整最大尝试次数
|
||
|
||
您可以通过以下两种方式修改最大尝试次数。例如 最多尝试 5 次
|
||
|
||
```
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRetryMaxAttempts(5);
|
||
|
||
或者
|
||
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRetryer(new AlibabaCloud\Oss\V2\Retry\StandardRetryer(
|
||
maxAttempts: 5
|
||
));
|
||
```
|
||
|
||
### 调整退避延迟
|
||
|
||
例如 调整 BaseDelay 为 500毫秒，最大退避时间为 25秒
|
||
|
||
```
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRetryer(new AlibabaCloud\Oss\V2\Retry\StandardRetryer(
|
||
maxBackoff: 25,
|
||
baseDelay: 0.5
|
||
));
|
||
```
|
||
|
||
### 调整退避算法
|
||
|
||
例如 使用固定时间退避算法，每次延迟2秒
|
||
|
||
```
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRetryer(new AlibabaCloud\Oss\V2\Retry\StandardRetryer(
|
||
backoffDelayer: new Oss\Retry\FixedDelayBackoff(2)
|
||
));
|
||
```
|
||
|
||
### 调整重试错误
|
||
|
||
例如 在原有基础上，新增自定义可重试错误
|
||
|
||
```
|
||
class CustomErrorCodeRetryable implements AlibabaCloud\Oss\V2\Retry\ErrorRetryableInterface
|
||
{
|
||
public function isErrorRetryable(\Throwable $reason): bool
|
||
{
|
||
return false;
|
||
}
|
||
}
|
||
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setRetryer(new AlibabaCloud\Oss\V2\Retry\StandardRetryer(
|
||
errorRetryables: [
|
||
new AlibabaCloud\Oss\V2\Retry\ClientErrorRetryable(),
|
||
new AlibabaCloud\Oss\V2\Retry\ServiceErrorCodeRetryable(),
|
||
new AlibabaCloud\Oss\V2\Retry\HTTPStatusCodeRetryable(),
|
||
new CustomErrorCodeRetryable()
|
||
]
|
||
));
|
||
```
|
||
|
||
### 禁用重试
|
||
|
||
当您希望禁用所有重试尝试时，可以使用 AlibabaCloud\Oss\V2\Retry\NopRetryer 实现
|
||
```
|
||
$cfg->setRetryer(new AlibabaCloud\Oss\V2\Retry\NopRetryer());
|
||
```
|
||
## 配置参数汇总
|
||
|
||
支持的配置参数：
|
||
|
||
|参数名字 | 说明 | 示例
|
||
|:-------|:-------|:-------
|
||
|region|(必选)请求发送的区域, 必选|setRegion("cn-hangzhou")
|
||
|credentialsProvider|(必选)设置访问凭证|setCredentialsProvider(provider)
|
||
|endpoint|访问域名|setEndpoint("oss-cn-hanghzou.aliyuncs.com")
|
||
|retryMaxAttempts|HTTP请求时的最大尝试次数, 默认值为 3|setRetryMaxAttempts(5)
|
||
|retryer|HTTP请求时的重试实现|setRetryer(customRetryer)
|
||
|connectTimeout|建立连接的超时时间, 默认值为 10 秒|setConnectTimeout(5* time.Second)
|
||
|readWriteTimeout|应用读写数据的超时时间, 默认值为 20 秒|setReadWriteTimeout(30 * time.Second)
|
||
|insecureSkipVerify|是否跳过SSL证书校验，默认检查SSL证书|setInsecureSkipVerify(true)
|
||
|enabledRedirect|是否开启HTTP重定向, 默认不开启|setEnabledRedirect(true)
|
||
|proxyHost|设置代理服务器|setProxyHost(‘http://user:passswd@proxy.example-***.com’)
|
||
|signatureVersion|签名版本，默认值为v4|setSignatureVersion("v1")
|
||
|disableSSL|不使用https请求，默认使用https|setDisableSSL(true)
|
||
|usePathStyle|使用路径请求风格，即二级域名请求风格，默认为bucket托管域名|setUsePathStyle(true)
|
||
|useCName|是否使用自定义域名访问，默认不使用|setUseCName(true)
|
||
|useDualStackEndpoint|是否使用双栈域名访问，默认不使用|setUseDualStackEndpoint(true)
|
||
|useAccelerateEndpoint|是否使用传输加速域名访问，默认不使用|setUseAccelerateEndpoint(true)
|
||
|useInternalEndpoint|是否使用内网域名访问，默认不使用|setUseInternalEndpoint(true)
|
||
|additionalHeaders|指定额外的签名请求头，V4签名下有效|setAdditionalHeaders([‘content-length’])
|
||
|userAgent|指定额外的User-Agent信息|setUserAgent(‘user identifier’)
|
||
|
||
# 接口说明
|
||
|
||
本部分介绍SDK提供的接口, 以及如何使用这些接口。
|
||
|
||
此部分的其它主题
|
||
* [基础接口](#基础接口)
|
||
* [预签名接口](#预签名接口)
|
||
* [分页器](#分页器)
|
||
* [传输管理器](#传输管理器)
|
||
* [客户端加密](#客户端加密)
|
||
* [其它接口](#其它接口)
|
||
* [上传下载接口对比](#上传下载接口对比)
|
||
|
||
## 基础接口
|
||
|
||
SDK 提供了 与 REST API 对应的接口，把这类接口叫做 基础接口 或者 低级别API。您可以通过这些接口访问OSS的服务，例如创建存储空间，更新和删除存储空间的配置等。
|
||
|
||
这些接口采用了相同的命名规则，其接口定义如下：
|
||
|
||
```
|
||
public function <operationName>(Models\<OperationName>Request $request, array $args = []): Models\<OperationName>Result
|
||
public function <operationName>Async(Models\<OperationName>Request $request, array $args = []): \GuzzleHttp\Promise\Promise
|
||
```
|
||
|
||
**参数列表**：
|
||
|参数名|类型|说明
|
||
|:-------|:-------|:-------
|
||
|request|\<OperationName\>Request|设置具体接口的请求参数，例如bucket，key
|
||
|args|array|(可选)接口级的配置参数, 例如修改此次调用接口时读写超时
|
||
|
||
**返回值列表**：
|
||
|返回值名|类型|说明
|
||
|:-------|:-------|:-------
|
||
|result|\<OperationName\>Result|接口返回值
|
||
## 预签名接口
|
||
|
||
您可以使用预签名接口生成预签名URL，授予对存储空间中对象的限时访问权限，或者允许他人将特定对象的上传到存储空间。在过期时间之前，您可以多次使用预签名URL。
|
||
|
||
预签名接口定义如下：
|
||
```
|
||
public function presign(request: <OperationName>Request,args: $args): Models\PresignResult
|
||
```
|
||
|
||
**参数列表**：
|
||
|参数名|类型|说明
|
||
|:-------|:-------|:-------
|
||
|request|object|设置需要生成签名URL的接口名，和 '$OperationNameRequest' 一致
|
||
|args|array|(可选)，设置过期时间，如果不指定，默认有效期为15分钟
|
||
|
||
**返回值列表**：
|
||
|返回值名|类型|说明
|
||
|:-------|:-------|:-------
|
||
|result|PresignResult|返回结果，包含 预签名URL，HTTP 方法，过期时间 和 参与签名的请求头
|
||
|
||
**request参数支持的类型**：
|
||
|类型|对应的接口
|
||
|:-------|:-------
|
||
|GetObjectRequest|GetObject
|
||
|PutObjectRequest|PutObject
|
||
|HeadObjectRequest|HeadObject
|
||
|InitiateMultipartUploadRequest|InitiateMultipartUpload
|
||
|UploadPartRequest|UploadPart
|
||
|CompleteMultipartUploadRequest|CompleteMultipartUpload
|
||
|AbortMultipartUploadRequest|AbortMultipartUpload
|
||
|
||
**args选项**
|
||
|选项值|类型|说明
|
||
|:-------|:-------|:-------
|
||
|expires|DateTime|从当前时间开始，多长时间过期。例如 设置一个有效期为30分钟，new DateInterval('PT30M')
|
||
|expiration|DateInterval|绝对过期时间
|
||
|
||
> **注意:** 在签名版本4下，有效期最长为7天。同时设置 expiration和 expires时，优先取 expiration。
|
||
|
||
**PresignResult返回值**：
|
||
|参数名|类型|说明
|
||
|:-------|:-------|:-------
|
||
|method|string|HTTP 方法，和 接口对应，例如GetObject接口，返回 GET
|
||
|url|string|预签名 URL
|
||
|expiration|DateTime| 签名URL的过期时间
|
||
|signedHeaders|array|被签名的请求头，例如PutObject接口，设置了Content-Type 时，会返回 Content-Type 的信息。
|
||
|
||
|
||
示例
|
||
1. 为对象生成预签名 URL，然后下载对象（GET 请求）
|
||
```
|
||
$client = new Oss\Client($cfg);
|
||
$result = $client->presign(new Oss\Models\GetObjectRequest('bucket', 'key'));
|
||
$httpClient = new GuzzleHttp\Client();
|
||
$response = $httpClient->request($result->method, $result->url);
|
||
```
|
||
|
||
2. 为上传生成预签名 URL, 设置自定义元数据，有效期为10分钟，然后上传文件（PUT 请求）
|
||
```
|
||
$client = new Oss\Client($cfg);
|
||
$result = $client->presign(new Oss\Models\PutObjectRequest('bucket', 'key', metadata: ['user' => 'jack']), ['expires' => new DateInterval('PT10M')]);
|
||
$httpClient = new GuzzleHttp\Client();
|
||
$response = $httpClient->request($result->method, $result->url, ['headers' => $result->signedHeaders]);
|
||
```
|
||
|
||
更多的示例，请参考 sample 目录
|
||
|
||
## 分页器
|
||
|
||
对于列举类接口，当响应结果太大而无法在单个响应中返回时，都会返回分页结果，该结果同时包含一个用于检索下一页结果的标记。当需要获取下一页结果时，您需要在发送请求时设置该标记。
|
||
|
||
对常用的列举接口，V2 SDK 提供了分页器（Paginator），支持自动分页，当进行多次调用时，自动为您获取下一页结果。使用分页器时，您只需要编写处理结果的代码。
|
||
|
||
分页器 包含了 分页器对象 '\<OperationName\>Paginator'。分页器创建方法返回一个分页器对象，该对象通过'isTruncated' 参数判断是否还有更多页, 并调用操作来获取下一页。
|
||
|
||
分页器对象初始化 '\<OperationName\>Paginator' 里的 request 参数类型 与 '\<OperationName\>' 接口中的 reqeust 参数类型一致。
|
||
|
||
'\<OperationName\>Paginator' 返回的结果类型是一个Generator 对象， 该对象是 '\<OperationName\>' 接口 返回的结果类型 的集合。
|
||
|
||
```
|
||
public function iterPage(<OperationName>Request $request, array $args = []): \Generator
|
||
{
|
||
$limit = $args['limit'] ?? ($this->limit ?? null);
|
||
if (isset($args['limit'])) {
|
||
unset($args['limit']);
|
||
}
|
||
$req = clone $request;
|
||
if (isset($limit) && is_int($limit)) {
|
||
$req->maxKeys = $limit;
|
||
}
|
||
|
||
$firstPage = true;
|
||
$isTruncated = false;
|
||
|
||
while ($firstPage || $isTruncated) {
|
||
$result = $this->client-><OperationName>($req, $args);
|
||
yield $result;
|
||
|
||
$firstPage = false;
|
||
$isTruncated = $result->isTruncated ?? false;
|
||
$req->continuationToken = $result->nextContinuationToken;
|
||
}
|
||
}
|
||
|
||
```
|
||
|
||
支持的分页器对象如下：
|
||
|分页器对象|创建方法|对应的列举接口
|
||
|:-------|:-------|:-------
|
||
|ListObjectsPaginator|new Oss\Paginator\ListObjectsPaginator($client)|ListObjects, 列举存储空间中的对象信息
|
||
|ListObjectsV2Paginator|new Oss\Paginator\ListObjectsV2Paginator($client)|ListObjectsV2, 列举存储空间中的对象信息
|
||
|ListObjectVersionsPaginator|new Oss\Paginator\ListObjectVersionsPaginator($client)|ListObjectVersions, 列举存储空间中的对象版本信息
|
||
|ListBucketsPaginator|new Oss\Paginator\ListBucketsPaginator($client)|ListBuckets, 列举存储空间
|
||
|ListPartsPaginator|new Oss\Paginator\ListPartsPaginator($client)|ListParts, 列举指定Upload ID所属的所有已经上传成功分片
|
||
|ListMultipartUploadsPaginator|new Oss\Paginator\ListMultipartUploadsPaginator($client)|ListMultipartUploads, 列举存储空间中的执行中的分片上传事件
|
||
|
||
**args选项说明：**
|
||
|参数|说明
|
||
|:-------|:-------
|
||
|Limit|指定返回结果的最大数
|
||
|
||
|
||
以 ListObjects 为例，分页器遍历所有对象 和 手动分页遍历所有对象 对比
|
||
|
||
```
|
||
// 分页器遍历所有对象
|
||
...
|
||
$client = new Oss\Client($cfg);
|
||
$paginator = new Oss\Paginator\ListObjectsPaginator($client);
|
||
$iter = $paginator->iterPage(new Oss\Models\ListObjectsRequest($bucket));
|
||
foreach ($iter as $page) {
|
||
foreach ($page->contents ?? [] as $object) {
|
||
printf("object name:%s,type:%s,size:%s" . PHP_EOL, $object->key, $object->type, $object->size);
|
||
}
|
||
}
|
||
```
|
||
|
||
```
|
||
// 手动分页遍历所有对象
|
||
...
|
||
$client = new Oss\Client($cfg);
|
||
$firstPage = true;
|
||
$isTruncated = false;
|
||
$request = new Oss\Models\ListObjectsRequest($bucket);
|
||
while ($firstPage || $isTruncated) {
|
||
$result = $client->listObjects($request);
|
||
foreach ($result->contents as $object) {
|
||
printf("object name:%s,type:%s,size:%s" . PHP_EOL, $object->key, $object->type, $object->size);
|
||
}
|
||
$firstPage = false;
|
||
$isTruncated = $result->isTruncated ?? false;
|
||
$request->marker = $result->nextMarker;
|
||
}
|
||
```
|
||
|
||
## 传输管理器
|
||
|
||
针对大文件的传输场景，新增了 'Uploader'，'Downloader' 和 'Copier' 模块，分别管理对象的 上传，下载 和 拷贝。
|
||
|
||
### 上传管理器(Uploader)
|
||
|
||
上传管理器 利用分片上传接口，把大文件或者流分成多个较小的分片并发上传，提升上传的性能。
|
||
</br>针对文件的上传场景，还提供了断点续传的能力，即在上传过程中，记录已完成的分片状态，如果出现网络中断、程序异常退出等问题导致文件上传失败，甚至重试多次仍无法完成上传，再次上传时，可以通过断点记录文件恢复上传。
|
||
|
||
```
|
||
final class Uploader
|
||
{
|
||
...
|
||
public function __construct($client, array $args = [])
|
||
|
||
public function uploadFile(Models\PutObjectRequest $request, string $filepath, array $args = []): Models\UploadResult
|
||
|
||
public function uploadFrom(Models\PutObjectRequest $request, StreamInterface $stream, array $args = []): Models\UploadResult
|
||
...
|
||
}
|
||
```
|
||
|
||
**参数列表**：
|
||
|参数名|类型|说明
|
||
|:-------|:-------|:-------
|
||
|request|PutObjectRequest|上传对象的请求参数，和 PutObject 接口的 请求参数一致
|
||
|stream|StreamInterface|需要上传的流。
|
||
|filePath|string|本地文件路径
|
||
|args|array|(可选)，配置选项
|
||
|
||
|
||
**args选项说明：**
|
||
|参数|类型|说明
|
||
|:-------|:-------|:-------
|
||
|part_size|int|指定分片大小，默认值为 6MiB
|
||
|parallel_num|int|指定上传任务的并发数，默认值为 3。针对的是单次调用的并发限制，而不是全局的并发限制
|
||
|leave_parts_on_error|bool|当上传失败时，是否保留已上传的分片，默认不保留
|
||
|
||
当使用Uploader实例化实例时，您可以指定多个配置选项来自定义对象的上传行为。也可以在每次调用上传接口时，指定多个配置选项来自定义每次上传对象的行为。
|
||
|
||
设置Uploader的配置参数
|
||
```
|
||
$u = $client->newUploader(['part_size' => 10 * 1024 * 1024]);
|
||
```
|
||
|
||
设置每次上传请求的配置参数
|
||
```
|
||
$u->uploadFile(
|
||
new Oss\Models\PutObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key'
|
||
),
|
||
filepath: '/local/dir/example',
|
||
args: [
|
||
'part_size' => 10 * 1024 * 1024,
|
||
]
|
||
);
|
||
```
|
||
|
||
示例
|
||
|
||
1. 使用 Uploader上传流
|
||
|
||
```
|
||
...
|
||
$client = new Oss\Client($cfg);
|
||
$u = $client->newUploader();
|
||
$result = $u->uploadFrom(
|
||
new Oss\Models\PutObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key'
|
||
),
|
||
stream: new \GuzzleHttp\Psr7\LazyOpenStream('/local/dir/example', 'rb'),
|
||
);
|
||
printf(
|
||
'upload form status code:' . $result->statusCode . PHP_EOL .
|
||
'upload form request id:' . $result->requestId . PHP_EOL .
|
||
'upload form result:' . var_export($result, true) . PHP_EOL
|
||
);
|
||
```
|
||
|
||
2. 使用 Uploader上传文件
|
||
|
||
```
|
||
...
|
||
$client = new Oss\Client($cfg);
|
||
$u = $client->newUploader();
|
||
$result = $u->uploadFile(
|
||
new Oss\Models\PutObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key'
|
||
),
|
||
filepath: '/local/dir/example',
|
||
);
|
||
printf(
|
||
'upload file status code:' . $result->statusCode . PHP_EOL .
|
||
'upload file request id:' . $result->requestId . PHP_EOL .
|
||
'upload file result:' . var_export($result, true) . PHP_EOL
|
||
);
|
||
```
|
||
### 下载管理器(Downloader)
|
||
|
||
下载管理器 利用范围下载，把大文件分成多个较小的分片并发下载，提升下载的性能。
|
||
|
||
```
|
||
final class Downloader
|
||
{
|
||
...
|
||
public function __construct($client, array $args = [])
|
||
|
||
public function downloadFile(Models\GetObjectRequest $request, string $filepath, array $args = []): Models\DownloadResult
|
||
|
||
public function downloadTo(Models\GetObjectRequest $request, \Psr\Http\Message\StreamInterface $stream, array $args = []): Models\DownloadResult
|
||
}
|
||
```
|
||
|
||
**参数列表**：
|
||
|参数名|类型|说明
|
||
|:-------|:-------|:-------
|
||
|request|GetObjectRequest|下载对象的请求参数，和 GetObject 接口的 请求参数一致
|
||
|filePath|string|本地文件路径
|
||
|args|array|(可选)，配置选项
|
||
|
||
|
||
**args选项说明：**
|
||
|参数|类型|说明
|
||
|:-------|:-------|:-------
|
||
|part_size|int|指定分片大小，默认值为 6MiB
|
||
|parallel_num|int|指定上传任务的并发数，默认值为 3。针对的是单次调用的并发限制，而不是全局的并发限制
|
||
|use_temp_file|bool|下载文件时，是否使用临时文件，默认使用。先下载到临时文件上，当成功后，再重命名为目标文件
|
||
|
||
当使用Downloader实例化实例时，您可以指定多个配置选项来自定义对象的下载行为。也可以在每次调用下载接口时，指定多个配置选项来自定义每次下载对象的行为。
|
||
|
||
设置Downloader的配置参数
|
||
```
|
||
$d = $client->newDownloader(['part_size' => 10 * 1024 * 1024]);
|
||
```
|
||
|
||
设置每次下载请求的配置参数
|
||
```
|
||
$d->downloadFile(
|
||
new Oss\Models\GetObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key'
|
||
),
|
||
filepath: '/local/dir/example',
|
||
args: ['part_size' => 10 * 1024 * 1024]
|
||
);
|
||
```
|
||
|
||
示例
|
||
|
||
1. 使用 Downloader 下载到本地文件
|
||
|
||
```
|
||
...
|
||
$client = new Oss\Client($cfg);
|
||
$d = $client->newDownloader();
|
||
$d->downloadFile(
|
||
new Oss\Models\GetObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key'
|
||
),
|
||
filepath: '/local/dir/example',
|
||
);
|
||
```
|
||
2. 使用 Downloader 下载到流中
|
||
|
||
```
|
||
...
|
||
$client = new Oss\Client($cfg);
|
||
$d = $client->newDownloader();
|
||
$stream = new \GuzzleHttp\Psr7\BufferStream(1 * 1024 * 1024);
|
||
$d->downloadTo(
|
||
new Oss\Models\GetObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key'
|
||
),
|
||
stream: $stream,
|
||
);
|
||
```
|
||
|
||
### 拷贝管理器(Copier)
|
||
当需要将对象从存储空间复制到另外一个存储空间，或者修改对象的属性时，您可以通过拷贝接口 或者分片拷贝接口来完成这个操作。
|
||
</br>这两个接口有其适用的场景，例如：
|
||
* 拷贝接口(CopyObject) 只适合拷贝 5GiB 以下的对象；
|
||
* 分片拷贝接口(UploadPartCopy) 不支持 元数据指令(x-oss-metadata-directive) 和 标签指令(x-oss-tagging-directive) 参数,
|
||
拷贝时，您需要主动去设置需要复制的元数据和标签。
|
||
* 服务端优化了拷贝(CopyObject)接口，使其具备浅拷贝的能力，在特定的场景下也支持拷贝大文件。
|
||
|
||
拷贝管理器提供了通用的拷贝接口，隐藏了接口的差异和实现细节，根据拷贝的请求参数，自动选择合适的接口复制对象。
|
||
|
||
```
|
||
final class Copier
|
||
{
|
||
...
|
||
public function __construct($client, array $args = [])
|
||
|
||
public function copy(Models\CopyObjectRequest $request, array $args = []): Models\CopyResult
|
||
}
|
||
```
|
||
**参数列表**：
|
||
|参数名|类型|说明
|
||
|:-------|:-------|:-------
|
||
|request|CopyObjectRequest|拷贝对象的请求参数，和 CopyObject 接口的 请求参数一致
|
||
|args|array|(可选)，配置选项
|
||
|
||
|
||
**args选项说明：**
|
||
|参数|类型|说明
|
||
|:-------|:-------|:-------
|
||
|part_size|int|指定分片大小，默认值为 64MiB
|
||
|parallel_num|int|指定上传任务的并发数，默认值为 3。针对的是单次调用的并发限制，而不是全局的并发限制
|
||
|multipart_copy_threshold|int|使用分片拷贝的阈值，默认值为 200MiB
|
||
|leave_parts_on_error|bool|当拷贝失败时，是否保留已拷贝的分片，默认不保留
|
||
|disable_shallow_copy|bool|不使用浅拷贝行为，默认使用
|
||
|
||
|
||
当使用Copier实例化实例时，您可以指定多个配置选项来自定义对象的下载行为。也可以在每次调用下载接口时，指定多个配置选项来自定义每次下载对象的行为。
|
||
|
||
设置Copier的配置参数
|
||
```
|
||
$c = $client->newCopier(['part_size' => 100 * 1024 * 1024]);
|
||
```
|
||
|
||
设置每次拷贝请求的配置参数
|
||
```
|
||
$c->copy(
|
||
new Oss\Models\CopyObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key',
|
||
sourceBucket: 'src-bucket',
|
||
sourceKey: 'src-key',
|
||
),
|
||
args: ['part_size' => 100 * 1024 * 1024]
|
||
);
|
||
```
|
||
|
||
> **注意:**
|
||
> </br>拷贝对象时，CopyObjectRequest 中 metadataDirective 属性决定了对象元数据的拷贝行为，默认 复制 源对象标签
|
||
> </br>拷贝对象时，CopyObjectRequest 中 taggingDirective 属性决定了对象标签的拷贝行为，默认 复制 源对象标签
|
||
|
||
|
||
示例
|
||
|
||
1. 拷贝文件，默认会复制 元数据 和 标签
|
||
```
|
||
...
|
||
$client = new Oss\Client($cfg);
|
||
$c = $client->newCopier();
|
||
$result = $c->copy(
|
||
new Oss\Models\CopyObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key',
|
||
sourceBucket: 'src-bucket',
|
||
sourceKey: 'src-key',
|
||
)
|
||
);
|
||
printf(
|
||
'status code:' . $result->statusCode . PHP_EOL .
|
||
'request id:' . $result->requestId . PHP_EOL .
|
||
'result:' . var_export($result, true)
|
||
);
|
||
```
|
||
|
||
2. 拷贝文件，只拷贝数据，不拷贝元数据和标签
|
||
```
|
||
...
|
||
$client = new Oss\Client($cfg);
|
||
$c = $client->newCopier();
|
||
$result = $c->copy(
|
||
new Oss\Models\CopyObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key',
|
||
sourceBucket: 'src-bucket',
|
||
sourceKey: 'src-key',
|
||
metadataDirective: 'Replace',
|
||
taggingDirective: 'Replace'
|
||
)
|
||
);
|
||
printf(
|
||
'status code:' . $result->statusCode . PHP_EOL .
|
||
'request id:' . $result->requestId . PHP_EOL .
|
||
'result:' . var_export($result, true)
|
||
);
|
||
```
|
||
|
||
3. 修改 对象的存储类型 为标准类型
|
||
|
||
```
|
||
...
|
||
$client = new Oss\Client($cfg);
|
||
$c = $client->newCopier();
|
||
$result = $c->copy(
|
||
new Oss\Models\CopyObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key',
|
||
sourceBucket: 'src-bucket',
|
||
sourceKey: 'src-key',
|
||
storageClass: 'Standard',
|
||
)
|
||
);
|
||
printf(
|
||
'status code:' . $result->statusCode . PHP_EOL .
|
||
'request id:' . $result->requestId . PHP_EOL .
|
||
'result:' . var_export($result, true)
|
||
);
|
||
```
|
||
## 客户端加密
|
||
|
||
客户端加密是在数据上传至OSS之前，由用户在本地对数据进行加密处理，确保只有密钥持有者才能解密数据，增强数据在传输和存储过程中的安全性。
|
||
|
||
> **注意:**
|
||
> </br>使用客户端加密功能时，您需要对主密钥的完整性和正确性负责。
|
||
> </br>在对加密数据进行复制或者迁移时，您需要对加密元数据的完整性和正确性负责。
|
||
|
||
如果您需要了解OSS客户端加密实现的原理，请参考OSS用户指南中的[客户端加密](https://www.alibabacloud.com/help/zh/oss/user-guide/client-side-encryption)。
|
||
|
||
使用客户端加密，首先您需要实例化加密客户端，然后调用其提供的接口进行操作。您的对象将作为请求的一部分自动加密和解密。
|
||
|
||
```
|
||
final class EncryptionClient
|
||
{
|
||
...
|
||
|
||
public function __construct(Client $client, Crypto\MasterCipherInterface $masterCipher, ?array $decryptMasterCiphers = null)
|
||
}
|
||
```
|
||
|
||
**参数列表**：
|
||
|参数名|类型|说明
|
||
|:-------|:-------|:-------
|
||
|client|Client| 非加密客户端实例
|
||
|masterCipher|Crypto\MasterCipherInterface|主密钥实例，用于加密和解密数据密钥
|
||
|decryptMasterCiphers|array|(可选)，加密客户端配置选项
|
||
|
||
**返回值列表**：
|
||
|返回值名|类型|说明
|
||
|:-------|:-------|:-------
|
||
|eclient|EncryptionClient|加密客户端实例
|
||
|
||
**decryptMasterCiphers选项说明：**
|
||
|参数|类型|说明
|
||
|:-------|:-------|:-------
|
||
|decryptMasterCiphers|array<Crypto\MasterCipherInterface>|主密钥实例组, 用于解密数据密钥。
|
||
|
||
**EncryptionClient接口：**
|
||
|基础接口名|说明
|
||
|:-------|:-------
|
||
|GetObjectMeta|获取对象的部分元信息
|
||
|HeadObject|获取对象的部元信息
|
||
|GetObject|下载对象，并自动解密
|
||
|PutObject|上传对象，并自动加密
|
||
|InitiateMultipartUpload|初始化一个分片上传事件 和 分片加密上下文（EncryptionMultiPartContext）
|
||
|UploadPart|初始化一个分片上传事件, 调用该接口上传分片数据，并自动加密。调用该接口时，需要设置 分片加密上下文
|
||
|CompleteMultipartUpload|在将所有分片数据上传完成后，调用该接口合并成一个文件
|
||
|AbortMultipartUpload|取消分片上传事件,并删除对应的分片数据
|
||
|ListParts|列举指定上传事件所属的所有已经上传成功分片
|
||
|**高级接口名**|**说明**
|
||
|NewDownloader|创建下载管理器实例
|
||
|NewUploader|创建上传管理器实例
|
||
|**辅助接口名**|**说明**
|
||
|Unwrap|获取非加密客户端实例，可以通过该实例访问其它基础接口
|
||
|
||
> **说明:** EncryptionClient 采用了 和 Client 一样的接口命名规则 和 调用方式，有关接口的详细用法，请参考指南的其它章节说明。
|
||
|
||
### 使用RSA主密钥
|
||
|
||
**创建RAS加密客户端**
|
||
|
||
```
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider($credentialsProvider);
|
||
$cfg->setRegion('cn-hangzhou');
|
||
$client = new Oss\Client($cfg);
|
||
|
||
// 创建一个主密钥的描述信息，创建后不允许修改。主密钥描述信息和主密钥一一对应。
|
||
// 如果所有的对象都使用相同的主密钥，主密钥描述信息可以为空，但后续不支持更换主密钥。
|
||
// 如果主密钥描述信息为空，解密时无法判断使用的是哪个主密钥。
|
||
// 强烈建议为每个主密钥都配置主密钥描述信息，由客户端保存主密钥和描述信息之间的对应关系。
|
||
$materialDesc['desc'] = 'your master encrypt key material describe information';
|
||
|
||
// 创建只包含 主密钥 的 加密客户端
|
||
$masterCipher = new Oss\Crypto\MasterRsaCipher(
|
||
publicKey: "yourRsaPublicKey",
|
||
privateKey: "yourRsaPrivateKey",
|
||
matDesc: $materialDesc
|
||
);
|
||
$eclient = new Oss\EncryptionClient($client, $masterCipher);
|
||
|
||
// 创建包含主密钥 和 多个解密密钥的 加密客户端
|
||
// 当解密时，先匹配解密密钥的描述信息，如果不匹配，则使用主密钥解密
|
||
//$decryptMC = new Oss\Crypto\MasterRsaCipher(
|
||
// // TODO
|
||
//);
|
||
//$eclient = new Oss\EncryptionClient($client, $masterCipher,[$decryptMC]);
|
||
```
|
||
|
||
**使用加密客户端上传或者下载**
|
||
```
|
||
...
|
||
$eclient = new Oss\EncryptionClient($client, $masterCipher);
|
||
// Use PutObject
|
||
$eclient->putObject(
|
||
new Oss\Models\PutObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key',
|
||
body: Oss\Utils::streamFor('hi oss')
|
||
)
|
||
);
|
||
|
||
// Use GetObject
|
||
$eclient->getObject(
|
||
new Oss\Models\GetObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key',
|
||
)
|
||
);
|
||
|
||
// Use Downloader
|
||
$d = $eclient->newDownloader();
|
||
$d->downloadFile(
|
||
new Oss\Models\GetObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key',
|
||
),
|
||
filepath: '/local/dir/example',
|
||
);
|
||
|
||
// Use Uploader
|
||
$u = $eclient->newUploader();
|
||
$u->uploadFile(
|
||
new Oss\Models\PutObjectRequest(
|
||
bucket: 'bucket',
|
||
key: 'key',
|
||
body: Oss\Utils::streamFor('hi oss')
|
||
),
|
||
filepath: '/local/dir/example',
|
||
);
|
||
```
|
||
|
||
**使用加密客户端以分片方式上传数据**
|
||
</br>以上传500K内存数据为例
|
||
```
|
||
...
|
||
$eclient = new Oss\EncryptionClient($client, $masterCipher);
|
||
$partSize = 200 * 1024;
|
||
$length = 500 * 1024;
|
||
$bucket = 'bucket';
|
||
$key = 'key';
|
||
// 文件的大小是 500 * 1024
|
||
$fileName = '/local/dir/example';
|
||
|
||
// 加密客户端 需要 设置分片大小和总文件大小
|
||
$initResult = $client->initiateMultipartUpload(
|
||
new Oss\Models\InitiateMultipartUploadRequest(
|
||
bucket: $bucket,
|
||
key: $key,
|
||
cseDataSize: $length,
|
||
csePartSize: $partSize
|
||
)
|
||
);
|
||
|
||
$file = fopen($fileName, 'r');
|
||
$parts = array();
|
||
if ($file) {
|
||
$i = 1;
|
||
while (!feof($file)) {
|
||
$chunk = fread($file, $partSize);
|
||
$partResult = $eclient->uploadPart(new Oss\Models\UploadPartRequest(
|
||
bucket: $bucket,
|
||
key: $key,
|
||
partNumber: $i,
|
||
uploadId: $initResult->uploadId,
|
||
contentLength: strlen($chunk),
|
||
body: Oss\Utils::streamFor($chunk),
|
||
encryptionMultipartContext: $initResult->encryptionMultipartContext,
|
||
));
|
||
$part = new Oss\Models\UploadPart(
|
||
$i,
|
||
$partResult->etag,
|
||
);
|
||
array_push($parts, $part);
|
||
$i++;
|
||
}
|
||
fclose($file);
|
||
}
|
||
$comResult = $eclient->completeMultipartUpload(
|
||
new Oss\Models\CompleteMultipartUploadRequest(
|
||
bucket: $bucket,
|
||
key: $key,
|
||
uploadId: $initResult->uploadId,
|
||
completeMultipartUpload: new Oss\Models\CompleteMultipartUpload(
|
||
$parts
|
||
),
|
||
)
|
||
);
|
||
```
|
||
### 使用自定义主密钥
|
||
当RSA主密钥方式无法满足需求时，您可自定主密钥的加密实现。主密钥的接口定义如下：
|
||
```
|
||
interface MasterCipherInterface
|
||
{
|
||
public function encrypt(string $data): string;
|
||
|
||
public function decrypt(string $data): string;
|
||
|
||
public function getWrapAlgorithm(): string;
|
||
|
||
public function getMatDesc(): string;
|
||
}
|
||
```
|
||
**MasterCipher接口说明**
|
||
|接口名|说明
|
||
|:-------|:-------
|
||
|encrypt|加密 数据加密密钥 和 加密数据的初始值(IV)
|
||
|decrypt|解密 数据加密密钥 和 加密数据的初始值(IV)
|
||
|getWrapAlgorithm|返回 数据密钥的加密算法信息，建议采用 算法/模式/填充 格式，例如RSA/NONE/PKCS1Padding
|
||
|getMatDesc|返回 主密钥的描述信息，JSON格式
|
||
|
||
例如
|
||
|
||
```
|
||
...
|
||
final class MasterCustomCipher implements Oss\Crypto\MasterCipherInterface
|
||
{
|
||
private $matDesc;
|
||
|
||
private ?string $secrectKey;
|
||
|
||
public function __construct(
|
||
$matDesc = null,
|
||
?string $secrectKey = null
|
||
)
|
||
{
|
||
$this->secrectKey = $secrectKey;
|
||
$this->matDesc = null;
|
||
if (\is_array($matDesc)) {
|
||
$val = json_encode($matDesc);
|
||
if ($val !== false) {
|
||
$this->matDesc = $val;
|
||
}
|
||
} else if (is_string($matDesc)) {
|
||
$this->matDesc = $matDesc;
|
||
}
|
||
}
|
||
|
||
public function encrypt(string $data): string
|
||
{
|
||
// TODO
|
||
}
|
||
|
||
public function decrypt(string $data): string
|
||
{
|
||
// TODO
|
||
}
|
||
|
||
public function getWrapAlgorithm(): string
|
||
{
|
||
return "Custom/None/NoPadding";
|
||
}
|
||
|
||
public function getMatDesc(): string
|
||
{
|
||
return $this->matDesc;
|
||
}
|
||
}
|
||
|
||
$client = new Oss\Client($cfg);
|
||
$materialDesc['desc'] = 'your master encrypt key material describe information';
|
||
$masterCipher = new MasterCustomCipher(
|
||
matDesc: $materialDesc,
|
||
secrectKey: "yourSecrectKey"
|
||
);
|
||
$eclient = new Oss\EncryptionClient($client, $masterCipher);
|
||
```
|
||
|
||
## 其它接口
|
||
|
||
为了方便用户使用，封装了一些易用性接口。当前扩展的接口如下：
|
||
|
||
|接口名 | 说明
|
||
|:-------|:-------
|
||
|isObjectExist|判断对象(object)是否存在
|
||
|isBucketExist|判断存储空间(bucket)是否存在
|
||
|putObjectFromFile|上传本地文件到存储空间
|
||
|getObjectToFile|下载对象到本地文件
|
||
|
||
### isObjectExist/isBucketExist
|
||
|
||
这两个接口的返回值为 bool 如果bool 为 true，表示存在，如果 bool值为 false，表示不存在。当抛出异常 时，表示无法从该错误信息判断 是否存在。
|
||
|
||
```
|
||
public function isObjectExist(string $bucket, string $key, ?string $versionId = null, array $args = []): bool
|
||
public function isBucketExist(string $bucket, array $args = []): bool
|
||
```
|
||
|
||
例如 判断对象是否存在
|
||
|
||
```
|
||
client := oss.NewClient(cfg)
|
||
|
||
$existed = $client->isObjectExist( bucket: "examplebucket", key: "exampleobject");
|
||
//$existed = $client->isObjectExist( bucket: 'examplebucket', key: 'exampleobject',versionId: 'versionId');
|
||
|
||
printf('object existed :%s',var_export($existed,true));
|
||
```
|
||
|
||
### PutObjectFromFile
|
||
|
||
使用简单上传(PutObject)接口 把本地文件上传到存储空间，该接口不支持并发。
|
||
|
||
```
|
||
public function putObjectFromFile(Models\PutObjectRequest $request, string $filePath, array $args = []): Models\PutObjectResult
|
||
```
|
||
|
||
示例
|
||
|
||
```
|
||
...
|
||
$client = new Oss\Client($cfg);
|
||
|
||
$result = $client->putObjectFromFile(
|
||
new Oss\Models\PutObjectRequest(
|
||
bucket: 'examplebucket',
|
||
key: 'exampleobject',
|
||
),
|
||
filePath: '/local/dir/example'
|
||
);
|
||
```
|
||
|
||
### GetObjectToFile
|
||
|
||
使用GetObject接口，把存储空间的对象下载到本地文件，该接口不支持并发。
|
||
|
||
```
|
||
public function getObjectToFile(Models\GetObjectRequest $request, string $filePath, array $args = []): Models\GetObjectResult
|
||
```
|
||
|
||
示例
|
||
|
||
```
|
||
...
|
||
$client = new Oss\Client($cfg);
|
||
|
||
$client->getObjectToFile(
|
||
new Oss\Models\GetObjectRequest(
|
||
bucket: 'examplebucket',
|
||
key: 'exampleobject',
|
||
),
|
||
filePath: '/local/dir/example'
|
||
);
|
||
```
|
||
|
||
## 上传下载接口对比
|
||
|
||
提供了各种上传下载接口，您可以根据使用场景，选择适合的接口。
|
||
|
||
**上传接口**
|
||
|接口名 | 说明
|
||
|:-------|:-------
|
||
|putObject|简单上传, 最大支持5GiB
|
||
|putObjectFromFile|与putObject接口能力一致</br>请求body数据来源于文件路径
|
||
|分片上传接口</br>initiateMultipartUpload</br>uploadPart</br>completeMultipartUpload|分片上传，单个分片最大5GiB，文件最大48.8TiB
|
||
|uploadFrom|封装了简单上传 和 分片上传接口，最大支持48.8TiB
|
||
|uploadFile|与uploadFrom接口能力一致</br>请求body数据来源于文件路径
|
||
|appendObject|追加上传, 最终文件最大支持5GiB
|
||
|
||
**下载接口**
|
||
|接口名| 说明
|
||
|:-------|:-------
|
||
|getObject|流式下载, 响应体为StreamInterface类型
|
||
|getObjectToFile|下载到本地文件</br>单连接下载
|
||
|downloadFile|采用分片方式下载到本地文件</br>支持自定义分片大小和并发数
|
||
# 场景示例
|
||
|
||
本部分将从使用场景出发, 介绍如何使用SDK。
|
||
|
||
包含的主题
|
||
* [数据校验](#数据校验)
|
||
|
||
OSS提供基于MD5的数据校验，确保请求的过程中的数据完整性。
|
||
|
||
## MD5校验
|
||
|
||
当向OSS发送请求时，如果设置了Content-MD5，OSS会根据接收的内容计算MD5。当OSS计算的MD5值和上传提供的MD5值不一致时，则返回InvalidDigest异常，从而保证数据的完整性。
|
||
|
||
基础接口里， 除了PutObject, AppendObject, UploadPart 接口外，会自动计算MD5, 并设置Content-MD5, 保证请求的完整性。
|
||
|
||
如果您需要在 PutObject, AppendObject, UploadPart 接口里使用MD5校验，可以参考以下写法
|
||
|
||
```
|
||
...
|
||
$client = new Oss\Client($cfg);
|
||
|
||
$body = Oss\Utils::streamFor('hi oss');
|
||
$result = $client->putObject(
|
||
new Oss\Models\PutObjectRequest(
|
||
bucket: 'demo-1889',
|
||
key: 'demo',
|
||
contentMd5: base64_encode(md5($body, true)),
|
||
body: $body
|
||
));
|
||
printf(
|
||
'status code:' . $result->statusCode . PHP_EOL .
|
||
'request id:' . $result->requestId . PHP_EOL .
|
||
'result:' . var_export($result, true)
|
||
);
|
||
```
|
||
# 迁移指南
|
||
|
||
本部分介绍如何从V1 版本([aliyun-oss-php-sdk](https://github.com/aliyun/aliyun-oss-php-sdk)) 迁移到 V2 版本。
|
||
## 最低 PHP 版本
|
||
|
||
V2 版本 要求 PHP 版本最低为 7.4。
|
||
## 导入路径
|
||
|
||
V2 版本使用新的代码仓库，同时也对代码结构进行了调整，按照功能模块组织，以下是这些模块路径和说明：
|
||
|
||
|模块路径 | 说明
|
||
|:-------|:-------
|
||
|github.com/aliyun/alibabacloud-oss-php-sdk-v2/src|SDK核心，接口 和 高级接口实现
|
||
|github.com/aliyun/alibabacloud-oss-php-sdk-v2/src/Credentials|访问凭证相关
|
||
|github.com/aliyun/alibabacloud-oss-php-sdk-v2/src/Retry|重试相关
|
||
|github.com/aliyun/alibabacloud-oss-php-sdk-v2/src/Signer|签名相关
|
||
|github.com/aliyun/alibabacloud-oss-php-sdk-v2/src/Annotation|tag，xml 转换相关
|
||
|github.com/aliyun/alibabacloud-oss-php-sdk-v2/src/Crypto|客户端加密相关
|
||
|github.com/aliyun/alibabacloud-oss-php-sdk-v2/src/Models|请求对象，返回对象相关
|
||
|github.com/aliyun/alibabacloud-oss-php-sdk-v2/src/Paginator|列表分页器相关
|
||
|github.com/aliyun/alibabacloud-oss-php-sdk-v2/src/Exception|异常类型相关
|
||
|github.com/aliyun/alibabacloud-oss-php-sdk-v2/src/Types|类型相关
|
||
|
||
示例
|
||
|
||
```
|
||
// v1
|
||
require_once 'vendor/autoload.php';
|
||
use OSS\OssClient;
|
||
```
|
||
|
||
```
|
||
// v2
|
||
require_once 'vendor/autoload.php';
|
||
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
```
|
||
|
||
## 配置加载
|
||
|
||
V2 版本简化了配置设置方式，全部迁移到 [config](src/Config.php) 下，并提供了以set为前缀的辅助函数，方便以编程方式覆盖缺省配置。
|
||
|
||
V2 默认使用 V4签名，所以必须配置区域（Region）。
|
||
|
||
V2 支持从区域（Region）信息构造 访问域名(Endpoint), 当访问的是公有云时，可以不设置Endpoint。
|
||
|
||
示例
|
||
|
||
```
|
||
// v1
|
||
require_once 'vendor/autoload.php';
|
||
use OSS\OssClient;
|
||
...
|
||
|
||
// 环境变量中获取访问凭证
|
||
$provider = new \OSS\Credentials\EnvironmentVariableCredentialsProvider();
|
||
|
||
// Endpoint
|
||
$endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
|
||
|
||
$config = array(
|
||
"provider" => $provider,
|
||
"endpoint" => $endpoint,
|
||
"signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
|
||
"region" => "cn-hangzhou"
|
||
);
|
||
$ossClient = new OssClient($config);
|
||
// 不校验SSL证书校验
|
||
$ossClient->setUseSSL(false);
|
||
```
|
||
|
||
```
|
||
// v2
|
||
require_once 'vendor/autoload.php';
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
...
|
||
|
||
// 环境变量中获取访问凭证
|
||
$provider = new \OSS\Credentials\EnvironmentVariableCredentialsProvider();
|
||
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider($credentialsProvider);
|
||
// 设置HTTP连接超时时间为20秒
|
||
$cfg->setConnectTimeout(20);
|
||
// HTTP读取或写入超时时间为60秒
|
||
$cfg->setReadWriteTimeout(60);
|
||
// 不校验SSL证书校验
|
||
$cfg->setDisableSSL(true);
|
||
// 设置区域
|
||
$cfg->setRegion('cn-hangzhou');
|
||
$client = new Oss\Client($cfg);
|
||
```
|
||
|
||
## 创建Client
|
||
|
||
V2 版本 把 Client 的创建 函数 从 New 修改 为 NewClient， 同时 创建函数 不在支持传入Endpoint 以及 access key id 和 access key secrect 参数。
|
||
|
||
示例
|
||
|
||
```
|
||
// v1
|
||
$endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
|
||
|
||
$config = array(
|
||
"provider" => $provider,
|
||
"endpoint" => $endpoint,
|
||
"signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
|
||
"region" => "cn-hangzhou"
|
||
);
|
||
$ossClient = new OssClient($config);
|
||
|
||
or
|
||
|
||
$ossClient = new OssClient('accessKeyId','accessKeySecret','endpoint');
|
||
```
|
||
|
||
```
|
||
// v2
|
||
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
|
||
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider($credentialsProvider);
|
||
$cfg->setRegion('cn-hangzhou');
|
||
$ossClient = new Oss\Client($cfg);
|
||
```
|
||
|
||
## 调用API操作
|
||
|
||
基础 API 接口 都 合并为 单一操作方法 '\<OperationName\>'，操作的请求参数为 '\<OperationName\>Request'，操作的返回值为 '\<OperationName\>Result'。这些操作方法都 迁移到 Client下，如下格式：
|
||
|
||
```
|
||
public function <operationName>(Models\<OperationName>Request $request, array $args = []): Models\<OperationName>Result
|
||
public function <operationName>Async(Models\<OperationName>Request $request, array $args = []): \GuzzleHttp\Promise\Promise
|
||
```
|
||
|
||
关于API接口的详细使用说明，请参考[基础接口](#基础接口)。
|
||
|
||
示例
|
||
|
||
```
|
||
// v1
|
||
require_once 'vendor/autoload.php';
|
||
use OSS\OssClient;
|
||
$provider = new \OSS\Credentials\EnvironmentVariableCredentialsProvider();
|
||
$endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
|
||
$config = array(
|
||
"provider" => $provider,
|
||
"endpoint" => $endpoint,
|
||
"signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
|
||
"region" => "cn-hangzhou"
|
||
);
|
||
$ossClient = new OssClient($config);
|
||
$ossClient->putObject('examplebucket','exampleobject.txt','example data');
|
||
```
|
||
|
||
```
|
||
// v2
|
||
require_once 'vendor/autoload.php';
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
|
||
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
|
||
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider($credentialsProvider);
|
||
$cfg->setRegion('cn-hangzhou');
|
||
$ossClient = new Oss\Client($cfg);
|
||
|
||
$client->putObject(
|
||
new Oss\Models\PutObjectRequest(
|
||
bucket: 'examplebucket',
|
||
key: 'exampleobject.txt',
|
||
body: Oss\Utils::streamFor('example data'),
|
||
),
|
||
);
|
||
```
|
||
|
||
## 预签名
|
||
|
||
V2 版本 把 预签名接口 名字从 signUrl 修改为 presign，接口形式如下：
|
||
|
||
```
|
||
public function presign(request: $request,args: $options): Models\PresignResult
|
||
```
|
||
对于 request 参数，其类型 与 API 接口中的 '\<OperationName\>Request' 一致。
|
||
|
||
对于返回结果，除了返回 预签名 URL 外，还返回 HTTP 方法，过期时间 和 被签名的请求头，如下：
|
||
```
|
||
final class PresignResult
|
||
{
|
||
public ?string $method;
|
||
|
||
public ?string $url;
|
||
|
||
public ?\DateTime $expiration;
|
||
|
||
public ?array $signedHeaders;
|
||
}
|
||
```
|
||
|
||
关于预签名的详细使用说明，请参考[预签名接口](#预签名接口)。
|
||
|
||
以 生成下载对象的预签名URL 为例，如何从 V1 迁移到 V2
|
||
|
||
```
|
||
// v1
|
||
require_once 'vendor/autoload.php';
|
||
use OSS\OssClient;
|
||
$provider = new \OSS\Credentials\EnvironmentVariableCredentialsProvider();
|
||
$endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
|
||
$config = array(
|
||
"provider" => $provider,
|
||
"endpoint" => $endpoint,
|
||
"signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
|
||
"region" => "cn-hangzhou"
|
||
);
|
||
$ossClient = new OssClient($config);
|
||
$url = $ossClient->signUrl('examplebucket','exampleobject.txt',60,OssClient::OSS_HTTP_GET);
|
||
|
||
printf("Sign Url:%s\n", $url);
|
||
```
|
||
```
|
||
// v2
|
||
require_once 'vendor/autoload.php';
|
||
use AlibabaCloud\Oss\V2 as Oss;
|
||
|
||
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
|
||
|
||
$cfg = Oss\Config::loadDefault();
|
||
$cfg->setCredentialsProvider($credentialsProvider);
|
||
$cfg->setRegion('cn-hangzhou');
|
||
$ossClient = new Oss\Client($cfg);
|
||
|
||
$result = $ossClient->presign(
|
||
new Oss\Models\GetObjectRequest(
|
||
bucket: 'examplebucket',
|
||
key: 'exampleobject.txt',
|
||
),
|
||
args: ['expiration' => (new \DateTime('now', new \DateTimeZone('UTC')))->add(new DateInterval('PT60S'))],
|
||
);
|
||
print(
|
||
'sign url:' . $result->url . PHP_EOL .
|
||
'sign method :' . $result->method . PHP_EOL .
|
||
'sign expiration:' . var_export($result->expiration, true) . PHP_EOL .
|
||
'sign headers:' . var_export($result->signedHeaders, true) . PHP_EOL
|
||
);
|
||
``` |