获取对象列表

功能说明

您可以使用 listObjects 接口列举对象，每次最多返回1000个对象。

代码示例

以下代码展示如何简单列举对象：

public function ListObjects()
{
    try {
        $res = $this->s3Client->listObjects([
            'Bucket' => '<your-bucket-name>',
        ]);
        foreach ($res['Contents']  as $object) {
            echo $object['Key'] . "\n";
        }
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo "Exception: $e";
    }
}

如果 list 大于1000，则可以使用 getPaginator 接口列举所有对象。列举所有对象示例代码如下：

public function ListObjects2()
{
    try {
        $results = $this->s3Client->getPaginator('ListObjectsV2', [
            'Bucket' => '<your-bucket-name>',
        ]);
        foreach ($results as $result) {
            foreach ($result['Contents'] as $object) {
                echo $object['Key'] . "\n";
            }
        }
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo $e->getMessage() . "\n";
    }
}

请求参数

返回结果

上传对象

功能说明

您可以使用 putObject 接口上传对象。

代码示例

public function PutObject()
{
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    try {
        $res = $this->s3Client->putObject([
            'Bucket' => $bucket,
            'Key' => $objectName,
            'Body' => "1234",
            'ACL' => 'public-read',         //设置 ACL 为公共读
            'ContentType' => "text/json",   // 设置content-type
        ]);
        echo $res;
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo "Exception: $e";
    }
}

上传本地文件到对象存储：

public function PutObjectLocalFile()
{
    $file_Path = '<your-file-path>';
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    try {
        $res = $this->s3Client->putObject([
            'Bucket' => $bucket,
            'Key' => $objectName,
            'SourceFile' => $file_Path,
        ]);
        echo $res;
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo "Exception: $e";
    }
}

请求参数

返回结果

下载对象

功能说明

您可以使用 getObject 接口下载对象。

代码示例

public function GetObject()
{
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    try {
        //            $dateTime = new DateTime('<your-datetime>');
        $res = $this->s3Client->getObject([
            'Bucket' => $bucket,
            'Key' => $objectName,
            //'IfModifiedSince' => $dateTime,      //指定晚于修改时间
            //'IfMatch' => '<your-ETag>',          //指定匹配的ETag
        ]);
        echo $res->get('Body')->getContents();
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo "Exception: $e";
    }
}

请求参数

下载文件时，可以指定一个或者多个限定条件，满足条件时才下载对象，不满足时则返回错误代码，不下载对象。

返回结果

复制对象

功能说明

您可以使用 copyObject 接口复制对象，您需要设置复制的对象名，所在的桶以及目标桶和对象名。

代码示例

复制一个对象

public function CopyObject()
{
    $desBucket = '<your-bucket-name>';   //目标桶
    $desKeyName = '<your-object-key>';   //目标对象名
    $srcBucket = '<source-bucket-name>'; //从此桶复制
    $srcKeyName = '<source-object-key>'; //复制的对象名
    try {
        $result = $this->s3Client->copyObject(array(
            'Bucket' => $desBucket,
            'Key' => $desKeyName,
            'CopySource' => '/' . $srcBucket . '/' . $srcKeyName,
        ));
        echo $result;
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo $e->getMessage() . "\n";
    }
}

文件比较大（超过1GB）的情况下，直接使用copyObject 可能会出现超时，需要使用分片复制的方式进行文件复制。Aws\S3\MultiPartCopy封装了分片复制的接口，可以用于分片复制文件，具体示例请参考 分片上传融合接口 中的使用 MultiPartCopy 进行分片复制部分。

请求参数

返回结果

删除对象

功能说明

您可以使用 deleteObject 接口删除单个对象。

代码示例

public function DeleteObject()
{
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    try {
        $res = $this->s3Client->deleteObject([
            'Bucket' => $bucket,
            'Key' => $objectName,
        ]);
        echo $res;
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo "Exception: $e";
    }
}

请求参数

批量删除对象

功能说明

您可以使用 deleteObjects 接口批量删除多个对象。

代码示例

public function DeleteObjects()
{
    try {
        $res = $this->s3Client->deleteObjects([
            'Bucket' => '<your-bucket-name>',
            'Delete' => [
                'Objects' => [
                    [
                        'Key' => '<your-object-key1>',
                    ],
                    [
                        'Key' => '<your-object-key2>',
                    ],
                ]
            ],
        ]);
        echo $res;
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo "Exception: $e";
    }
}

请求参数

获取对象元数据

功能说明

您可以使用 headObject 接口获取对象元数据。headObject 操作的请求参数与 getObject 类似，但是 headObject 返回的http响应中没有对象数据。

代码示例

public function HeadObject()
{
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    try {
        $res = $this->s3Client->headObject([
            'Bucket' => $bucket,
            'Key' => $objectName,
        ]);
        echo 'ETag: ' . $res->get('ETag') . "\n";                         //打印对象ETag
        echo 'ContentLength: ' . $res->get('ContentLength') . "\n";       //打印对象大小
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo "Exception: $e";
    }
}

请求参数

返回结果

返回的属性如下：

设置对象访问权限

功能说明

与桶访问权限类似，对象访问权限同样具有 AccessControlList 与 CannedAccessControlList 两种。需要注意的是，对象的访问优先级要高于桶访问权限。比如桶访问权限是 private，但是对象访问权限是 public read，则所有用户都可以访问该对象。默认情况下，只有对象的拥有者才能访问该对象，即对象的访问权限默认是 private。设置对象ACL操作需要具有对象的WRITE_ACP权限。

代码示例

• CannedAccesssControlList

使用 CannedAccesssControlList 设置桶的访问权限示例代码如下:

public function PutObjectAcl(){
    //设置对象为公共读写
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    try {
        $this->s3Client->putObjectAcl([
            'ACL' => 'public-read',
            'Bucket' => $bucket,
            'Key' => $objectName,
        ]);
        echo "Succeed in setting object ACL.\n";
    } catch (AwsException $e) {
        echo $e->getMessage();
        echo "\n";
    }
}

• AccessControlList

使用 AccessControlList 设置对象访问权限时，可以设置特定用户对象的访问权限。使用AccesssControlList设置对象的权限示例代码如下:

public function PutObjectAcl2(){
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    try {
        $this->s3Client->putObjectAcl([
            'AccessControlPolicy' => [
                'Grants' => [
                    [
                        //开启用户 exampleuser 的完全控制权限
                        'Grantee' => [
                            'ID' => 'exampleuser',
                            'Type' => 'CanonicalUser',
                        ],
                        'Permission' => 'FULL_CONTROL',
                    ],
                    [
                        //开启所有用户的读权限
                        'Grantee' => [
                            'Type' => 'Group',
                            'URI' => 'http://acs.amazonaws.com/groups/global/AllUsers',
                        ],
                        'Permission' => 'READ',
                    ],
                    // ...
                ],
                // 可以从 getObjectAcl 接口获取 Owner 信息
                'Owner' => [
                    'DisplayName' => 'exampleuser',
                    'ID' => 'Example DisplayName',
                ],
            ],
            'Bucket' => $bucket,
            'Key' => $objectName,
        ]);
        echo "Succeed in setting object ACL.\n";
    } catch (AwsException $e) {
        // Display error message
        echo $e->getMessage();
        echo "\n";
    }
}

请求参数

• CannedAccesssControlList

使用 CannedAccesssControlList 方式设置桶权限参数如下：

CannedAccesssControlList 是一系列的预定义访问权限。

• AccessControlList

使用 AccessControlList 方式设置桶权限参数如下：

在 AccessControlList 中可通过 Grants 设置权限，Grants 中关于Permission说明如下：

获取对象访问权限

功能说明

您可以使用 getObjectAcl 接口获取对象访问的权限。

代码示例

public function GetObjectAcl(){
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    try {
        $resp = $this->s3Client->getObjectAcl([
            'Bucket' => $bucket,
            'Key' => $objectName,
        ]);
        echo "Succeed in retrieving object ACL as follows: \n";
        //打印获取的对象 owner displayname，ID 以及访问权限信息
        echo 'Owner DisplayName: ' . $resp['Owner']['DisplayName'] . "\n";
        echo 'Owner ID: '          . $resp['Owner']['ID']          . "\n";
        foreach ($resp['Grants'] as $grant) {
            echo "Grant: \n";
            foreach($grant['Grantee'] as $k=>$val)
            {
                echo $k . "： " . $val . "\n";
            }
            echo 'Permission: ' . $grant['Permission'] . "\n";
        }
    } catch (AwsException $e) {
        echo $e->getMessage();
        echo "\n";
    }
}

请求参数

返回结果

获取对象标签

功能说明

您可以使用GetObjectTagging接口获取对象标签。

代码示例

public function GetObjectTagging()
{
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    $res = $this->s3Client->getObjectTagging([
        'Bucket' => $bucket,
        'Key' => $objectName,
    ]);
    echo "getObjectTagging success " . $res . "\n";
}

请求参数

返回参数

删除对象标签

功能说明

您可以使用deleteObjectTagging接口删除对象标签。

代码示例

public function DeleteObjectTagging()
{
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    $this->s3Client->deleteObjectTagging([
        'Bucket' => $bucket,
        'Key' => $objectName,
    ]);
    echo "deleteObjectTagging success\n";
}

请求参数

设置对象标签

功能说明

您可以使用putObjectTagging接口为对象设置标签。标签是一个键值对，每个对象最多可以有10个标签。bucket的拥有者默认拥有给bucket中的对象设置标签的权限，并且可以将权限授予其他用户。每次执行PutObjectTagging操作会覆盖对象已有的标签信息。每个对象最多可以设置10个标签，标签Key和Value区分大小写，并且Key不可重复。每个标签的Key长度不超过128字节，Value长度不超过255字节。SDK通过HTTP header的方式设置标签且标签中包含任意字符时，需要对标签的Key和Value做URL编码。设置对象标签信息不会更新对象的最新更改时间。

代码示例

public function PutObjectTagging()
{
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    $this->s3Client->putObjectTagging([
        'Bucket' => $bucket,
        'Key' => $objectName,
        'Tagging' => [ // required
            'TagSet' => [
                [
                    'Key' => 'key1',
                    'Value' => 'value1',
                ],
            ]
        ],
    ]);
    echo "putObjectTagging success\n";
}

请求参数

生成下载预签名URL

功能说明

您可以通过 createPresignedRequest 接口为一个指定对象生成一个预签名的下载链接。

代码示例

生成下载预签名URL：

public function generateGetobjectPresignedUrl()
{
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    $expires = "+5 minutes"; // 表示5分钟后过期
    $cmd = $this->s3Client->getCommand('GetObject', [
        'Bucket' => $bucket,
        'Key' => $objectName,
    ]);
    $request = $this->s3Client->createPresignedRequest($cmd, $expires);
    $presignedUrl = (string)$request->getUri();
    echo "generateGetobjectPresignedUrl success " . $presignedUrl . "\n";
}

生成下载对象的预签名URL后，可以通过该URL下载文件：

public function getObjUsingPresignedUrl($presignedUrl, $localFilePath)
{
    try {
        $objectContent = file_get_contents($presignedUrl);
​
        if ($objectContent === false) {
            $error = error_get_last();
            echo "Download failed: " . $error['message'] . "\n";
            return;
        }
​
        file_put_contents($localFilePath, $objectContent);
​
        echo "Download successful. File saved to: " . $localFilePath . "\n";
    } catch (Exception $e) {
        echo "Download failed: " . $e->getMessage() . "\n";
    }
}

请求参数

返回结果

生成对应的预签名下载 URL，该链接允许用户在指定的时间内直接从媒体存储下载对象。

生成上传预签名URL

功能说明

您可以通过 createPresignedRequest 接口为一个指定对象生成一个预签名的上传链接。

代码示例

生成上传预签名URL：

public function generatePutobjectPresignedUrl()
{
    $bucket = '<your-bucket-name>';
    $objectName = '<your-object-key>';
    $expires = time() + 300; // 当前时间戳加上300秒，表示5分钟后过期
    $cmd = $this->s3Client->getCommand('PutObject', [
        'Bucket' => $bucket,
        'Key' => $objectName,
    ]);
    $request = $this->s3Client->createPresignedRequest($cmd, $expires);
    $presignedUrl = (string)$request->getUri();
    echo "generatePutobjectPresignedUrl success " . $presignedUrl . "\n";
}

通过该预签名URL，可以直接将文件上传到指定的桶：

public function putObjUsingPresignedUrl($presignedUrl, $localFilePath)
{
    if (!file_exists($localFilePath)) {
        echo "File does not exist: " . $localFilePath . "\n";
        return;
    }
​
    $file = fopen($localFilePath, 'r');
​
    $ch = curl_init($presignedUrl);
    curl_setopt($ch, CURLOPT_PUT, true);
    curl_setopt($ch, CURLOPT_INFILE, $file);
    curl_setopt($ch, CURLOPT_INFILESIZE, filesize($localFilePath));
​
    $result = curl_exec($ch);
    
    if ($result === false) {
        echo "Upload failed: " . curl_error($ch) . "\n";
    } else {
        echo "Upload successful. File uploaded from: " . $localFilePath . "\n";
    }
​
    // 关闭资源
    curl_close($ch);
    fclose($file);
}

请求参数

返回结果

生成对应的预签名上传 URL，该链接允许用户在指定的时间内直接将对象上传到媒体存储存储桶。

Post上传

功能说明

PostObjectV4接口为一个指定对象生成一个支持post方式上传文件的参数集合，可以在前端使用post form-data的方式上传文件。

代码示例

public function postPresign() {
    $objectName = '<your-object-key>';
    $formInputs = [
        'key' => $objectName
    ];
    $options = [
        ['starts-with', '$bucket', ''],
        ['starts-with', '$key', ''],
        ['starts-with', '$acl', ''],
        ['starts-with', '$Content-Type', ''],
    ];
​
    $expires = '+2 hours';
    $postObject = new Aws\S3\PostObjectV4(
        $this->s3Client,
        '<your-bucket-name>',
        $formInputs,
        $options,
        $expires
    );
​
    $formAttributes = $postObject->getFormAttributes();
    $formInputs = $postObject->getFormInputs();
    var_dump($formAttributes);
    var_dump($formInputs);
}

请求参数

返回结果

关于FormAttributes的说明：

关于FormInputs的说明：

前端使用方式如下：

<form action="<action>" method="POST" enctype="multipart/form-data">
    <input type="hidden" name="Policy" value="<data.fields['Policy']>" />
    <input type="hidden" name="X-Amz-Algorithm" value="<data.fields['X-Amz-Algorithm']>" />
    <input type="hidden" name="X-Amz-Credential" value="<data.fields['X-Amz-Credential']>" />
    <input type="hidden" name="X-Amz-Date" value="<data.fields['X-Amz-Date']>" />
    <input type="hidden" name="X-Amz-Signature" value="<data.fields['X-Amz-Signature']>" />
    <input type="hidden" name="bucket" value="<data.fields['bucket']>" />
    <input type="hidden" name="key" value="<data.fields['key']>" />
​
    <input type="file" name="file" value="" />
    <input type="submit" value="Submit" />
</form>

获取多版本对象列表

功能说明

如果桶开启了版本控制，您可以使用 listObjectVersions 接口列举对象的版本，每次list操作最多返回1000个对象版本。

代码示例

以下代码展示如何简单列举对象版本：

public function ListObjectVersions(){
    $versions = $this->s3Client->listObjectVersions([
        'Bucket' => '<your-bucket-name>'
    ])->search('Versions');
    foreach ($versions as $version){
        echo "Key: " . $version['Key'] . "\n";
        echo "VersionId: " . $version['VersionId'] . "\n";
    }
}

如果 list 大于1000，则可以使用 Paginator 接口列举所有对象版本。列举所有对象版本示例代码如下：

public function ListObjectVersions2(){
    $versions = $this->s3Client->getPaginator('ListObjectVersions', [
        'Bucket' => '<your-bucket-name>'
    ])->search('Versions');
    foreach ($versions as $version){
        echo "Key: " . $version['Key'] . "\n";
        echo "VersionId: " . $version['VersionId'] . "\n";
    }
}

请求参数

返回结果