租户端 存储 对象存储（COS） SDK文档

快速入门

最近更新时间: 2024-06-12 15:06:00

下载与安装

相关资源

环境依赖

  • PHP 5.3+ 您可以通过php -v命令查看当前的 PHP 版本。

  • cURL 扩展 您可以通过php -m命令查看 cURL 扩展是否已经安装好。

  • Ubuntu 系统中，您可以使用 apt-get 包管理器安装 PHP 的 cURL 扩展，安装命令如下：

     sudo apt-get install php-curl

  • CentOS 系统中，您可以使用 yum 包管理器安装 PHP 的 cURL 扩展。

     sudo yum install php-curl

安装 SDK

SDK 安装有三种方式：Composer 方式、Phar 方式 和 源码方式。

Composer 方式

推荐使用 Composer 安装 cos-php-sdk-v5，Composer 是 PHP 的依赖管理工具，允许您声明项目所需的依赖，然后自动将它们安装到您的项目中。

您可以在 Composer 官网 上找到更多关于如何安装 Composer，配置自动加载以及用于定义依赖项的其他最佳实践等相关信息。

安装步骤

  1. 打开终端。

  2. 下载 Composer，执行以下命令。

    curl -sS https://getcomposer.org/installer | php

  3. 创建一个名为composer.json的文件，内容如下。

    {
    "require": {
        "qcloud/cos-sdk-v5": ">=1.0"
    }
}

  4. 使用 Composer 安装，执行以下命令。

    php composer.phar install

    使用该命令后会在当前目录中创建一个 vendor 文件夹，里面包含 SDK 的依赖库和一个 autoload.php 脚本，方便在项目中调用。

  5. 通过 autoloader 脚本调用 cos-php-sdk-v5。

    require '/path/to/sdk/vendor/autoload.php';

    至此，您的项目已经可以使用 COS XML PHP SDK 了。

Phar 方式

Phar 方式安装 SDK 的步骤如下：

  1. 在 GitHub 发布页面 下载相应的 phar 文件。

  2. 在代码中引入 phar 文件：

    require  '/path/to/cos-sdk-v5.phar';

源码方式

源码方式安装 SDK 的步骤如下：

  1. 在 SDK 下载页面 下载 cos-sdk-v5.tar.gz 压缩文件。（注意：Source code压缩包为 Github 默认打包的代码包，里面不包含vendor目录）

  2. 解压后通过 autoload.php 脚本加载 SDK：

    require '/path/to/sdk/vendor/autoload.php';

开始使用

下面为您介绍如何使用 COS PHP SDK 完成一个基础操作，如初始化客户端、创建存储桶、查询存储桶列表、上传对象、查询对象列表、下载对象和删除对象。

术语解释

名称 描述
APPID 开发者访问 COS 服务时拥有的用户维度唯一资源标识，用以标识资源
SecretId 开发者拥有的项目身份识别 ID，用以身份认证
SecretKey 开发者拥有的项目身份密钥
Bucket COS 中用于存储数据的容器
Object COS 中存储的具体文件，是存储的基本实体
Region 域名中的地域信息
Endpoint Endpoint 由 Region 和域名组成，具体格式为： "."，其中 Domain 为自定义的域名。
在控制台创建 Bucket 时，可以看到对应的访问地址为："."，Bucket 后面的部分即为 Endpoint。
ACL 访问控制列表（Access Control List），是指特定 Bucket 或 Object 的访问控制信息列表
CORS 跨域资源共享（Cross-Origin Resource Sharing）， 指发起请求的资源所在域不同于该请求所指向资源所在的域的 HTTP 请求
Multipart Uploads 分块上传，COS 服务为上传文件提供的一种分块上传模式

初始化

$secretId = "COS_SECRETID";                  // 替换为用户的 SecretId
$secretKey = "COS_SECRETKEY";                // 替换为用户的 SecretKey

$region = "REGION";                          // 替换为用户的 Region
$domain = "DOMAIN.COM";                      // 替换为用户的 Domain

$formatRegion = sprintf("cos.%s", $region);  // 格式化为标准的 Region (前方加 cos.)
$endpoint = sprintf("%s.%s", $formatRegion, $domain);
                                             // 通过 FormatRegion 和 Domain 生成 Endpoint

$cosClient = new Qcloud\Cos\Client(
    array(
        'schema' => 'http',       // 协议头部，默认为http
        'region' => $region,      // Region
        'endpoint' => $endpoint,  // Endpoint
        'credentials'=> array(
            'secretId'  => $secretId ,
            'secretKey' => $secretKey)));

若您使用 临时密钥 初始化，请用下面方式创建实例。

$secretId = "COS_SECRETID";                  // 临时密钥 SecretId
$secretKey = "COS_SECRETKEY";                // 临时密钥 SecretKey
$tmpToken = "COS_TMPTOKEN"                   // 临时密钥 Token

$region = "REGION";                          // 替换为用户的 Region
$domain = "DOMAIN.COM";                      // 替换为用户的 Domain

$formatRegion = sprintf("cos.%s", $region);  // 格式化为标准的 Region (前方加 cos.)
$endpoint = sprintf("%s.%s", $formatRegion, $domain);
                                             // 通过 FormatRegion 和 Domain 生成 Endpoint

$cosClient = new Qcloud\Cos\Client(
    array(
        'schema' => 'http',       // 协议头部，默认为http
        'region' => $region,      // Region
        'endpoint' => $endpoint,  // Endpoint
        'credentials'=> array(
            'secretId'  => $secretId ,
            'secretKey' => $secretKey,
            'token' => $tmpToken)));

创建存储桶

try {
    $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
    $result = $cosClient->createBucket(array('Bucket' => $bucket));
    //请求成功
    print_r($result);
} catch (\Exception $e) {
    //请求失败
    echo($e);
}

上传对象

  • 使用 putObject 接口上传文件（最大5G）。

  • 使用 Upload 接口分块上传文件。

     # 上传文件
 ## putObject(上传接口，最大支持上传5G文件)
 ### 上传内存中的字符串
 try {
     $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
     $key = "exampleobject";
     $result = $cosClient->putObject(array(
         'Bucket' => $bucket,
         'Key' => $key,
         'Body' => 'Hello World!'));
     print_r($result);
 } catch (\Exception $e) {
     echo "$e\n";
 }

 ### 上传文件流
 try {
     $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
     $key = "exampleobject";
     $srcPath = "F:/exampleobject";//本地文件绝对路径
     $result = $cosClient->putObject(array(
         'Bucket' => $bucket,
         'Key' => $key,
         'Body' => fopen($srcPath, 'rb')));
     print_r($result);
 } catch (\Exception $e) {
     echo "$e\n";
 }

 ### 设置header和meta
 try {
     $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
     $key = "exampleobject";
     $srcPath = "F:/exampleobject";//本地文件绝对路径
     $result = $cosClient->putObject(array(
         'Bucket' => $bucket,
         'Key' => $key,
         'Body' => fopen($srcPath, 'rb'),
         'ACL' => 'string',
         'CacheControl' => 'string',
         'ContentDisposition' => 'string',
         'ContentEncoding' => 'string',
         'ContentLanguage' => 'string',
         'ContentLength' => integer,
         'ContentType' => 'string',
         'Expires' => 'mixed type: string (date format)|int (unix timestamp)|\DateTime',
         'GrantFullControl' => 'string',
         'GrantRead' => 'string',
         'GrantWrite' => 'string',
         'Metadata' => array(
             'string' => 'string',
         ),
         'StorageClass' => 'string'));
     print_r($result);
 } catch (\Exception $e) {
     echo "$e\n";
 }

 ## Upload(高级上传接口，默认使用分块上传最大支持50T)
 ### 上传内存中的字符串
 try {    
     $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
     $key = "exampleobject";
     $result = $cosClient->Upload(
         $bucket = $bucket,
         $key = $key,
         $body = 'Hello World!');
     print_r($result);
 } catch (\Exception $e) {
     echo "$e\n";
 }

 ### 上传文件流
 try {    
     $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
     $key = "exampleobject";
     $srcPath = "F:/exampleobject";//本地文件绝对路径
     $result = $cosClient->Upload(
         $bucket = $bucket,
         $key = $key,
         $body = fopen($srcPath, 'rb'));
     print_r($result);
 } catch (\Exception $e) {
     echo "$e\n";
 }

 ### 设置header和meta
 try {
     $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
     $key = "exampleobject";
     $srcPath = "F:/exampleobject";//本地文件绝对路径
     $result = $cosClient->Upload(
         $bucket= $bucket,
         $key = $key,
         $body = fopen($srcPath, 'rb'),
         $options = array(
             'ACL' => 'string',
             'CacheControl' => 'string',
             'ContentDisposition' => 'string',
             'ContentEncoding' => 'string',
             'ContentLanguage' => 'string',
             'ContentLength' => integer,
             'ContentType' => 'string',
             'Expires' => 'mixed type: string (date format)|int (unix timestamp)|\DateTime',
             'GrantFullControl' => 'string',
             'GrantRead' => 'string',
             'GrantWrite' => 'string',
             'Metadata' => array(
                 'string' => 'string',
             ),
             'StorageClass' => 'string'));
     print_r($result);
 } catch (\Exception $e) {
     echo "$e\n";
 }

查询对象列表

try {
    $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
    $result = $cosClient->listObjects(array(
        'Bucket' => $bucket
    ));
    // 请求成功
    foreach ($result['Contents'] as $rt) {
        print_r($rt);
    }
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

单次调用listObjects接口一次只能查询1000个对象，如需要查询所有的对象，则需要循环调用

try {
    $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
    $prefix = ''; //列出对象的前缀
    $marker = ''; //上次列出对象的断点
    while (true) {
        $result = $cosClient->listObjects(array(
            'Bucket' => $bucket,
            'Marker' => $marker,
            'MaxKeys' => 1000 //设置单次查询打印的最大数量，最大为1000
        ));
        foreach ($result['Contents'] as $rt) {
            // 打印key
            echo($rt['Key'] . "\n");
        }
        $marker = $result['NextMarker']; //设置新的断点
        if (!$result['IsTruncated']) {
            break; //判断是否已经查询完
        }
    }
} catch (\Exception $e) {
    echo($e);
}

下载对象

  • 使用 getObject 接口下载文件。

  • 使用 getObjectUrl 接口获取文件下载 URL。

     # 下载文件
 ## getObject(下载文件)
 ### 下载到内存
 try {
     $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
     $key = "exampleobject"; //对象在存储桶中的位置，即称对象键
     $result = $cosClient->getObject(array(
         'Bucket' => $bucket,
         'Key' => $key));
     // 请求成功
     echo($result['Body']);
 } catch (\Exception $e) {
     // 请求失败
     echo "$e\n";
 }

 ### 下载到本地
 try {
     $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
     $key = "exampleobject"; //对象在存储桶中的位置，即称对象键
     $localPath = @"F:/exampleobject";//下载到本地指定路径
     $result = $cosClient->getObject(array(
         'Bucket' => $bucket,
         'Key' => $key,
         'SaveAs' => $localPath));
 } catch (\Exception $e) {
     // 请求失败
     echo "$e\n";
 }

 ### 指定下载范围
 /*
  * Range 字段格式为 'bytes=a-b'
  */
 try {
     $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
     $key = "exampleobject"; //对象在存储桶中的位置，即称对象键
     $localPath = @"F:/exampleobject";//下载到本地指定路径
     $result = $cosClient->getObject(array(
         'Bucket' => $bucket,
         'Key' => $key,
         'Range' => 'bytes=0-10',
         'SaveAs' => $localPath));
 } catch (\Exception $e) {
     // 请求失败
     echo "$e\n";
 }

 ### 设置返回header
 try {
     $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
     $key = "exampleobject"; //对象在存储桶中的位置，即称对象键
     $localPath = @"F:/exampleobject";//下载到本地指定路径
     $result = $cosClient->getObject(array(
         'Bucket' => $bucket,
         'Key' => $key,
         'ResponseCacheControl' => 'string',
         'ResponseContentDisposition' => 'string',
         'ResponseContentEncoding' => 'string',
         'ResponseContentLanguage' => 'string',
         'ResponseContentType' => 'string',
         'ResponseExpires' => 'mixed type: string (date format)|int (unix timestamp)|\DateTime',
         'SaveAs' => $localPath));
 } catch (\Exception $e) {
     // 请求失败
     echo "$e\n";
 }

 ## getObjectUrl(获取文件UrL)
 try {    
     $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
     $key = "exampleobject"; //对象在存储桶中的位置，即称对象键
     $signedUrl = $cosClient->getObjectUrl($bucket, $key, '+10 minutes');
     // 请求成功
     echo $signedUrl;
 } catch (\Exception $e) {
     // 请求失败
     print_r($e);
 }

删除对象

# 删除object
## deleteObject
try {
    $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
    $key = "exampleobject"; //对象在存储桶中的位置，即称对象键
    $result = $cosClient->deleteObject(array(
        'Bucket' => $bucket,
        'Key' => $key,
        'VersionId' => 'string'
    ));
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}
# 删除多个object
## deleteObjects
try {
    $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
    $key1 = "exampleobject1"; //对象在存储桶中的位置，即称对象键
    $key2 = "exampleobject2"; //对象在存储桶中的位置，即称对象键
    $result = $cosClient->deleteObjects(array(
        'Bucket' => $bucket,
        'Objects' => array(
            array(
                'Key' => $key1,
            ),
            array(
                'Key' => $key2,
            ),
            //...
        ),
    ));
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}