获取对象列表

功能说明

ListObjects操作用于列出桶中的全部对象，该操作返回最多1000个对象信息，可以通过设置过滤条件来列出桶中符合特定条件的对象信息。

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class ListObjectsExample
    {
        public static async Task ListObjects()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var credentials = new BasicAWSCredentials(accessKey, secretKey);
            try
            {
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var listObjectsRequest = new ListObjectsRequest()
                {
                    BucketName = bucketName
                };

                var result = await s3Client.ListObjectsAsync(listObjectsRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.OK)
                {
                    Console.WriteLine("fail to list objects in bucket {0}, HttpStatusCode:{1}, ErrorCode:{2}.", bucketName, (int) result.HttpStatusCode, result.HttpStatusCode);
                    return;
                }

                Console.WriteLine("the objects in bucket {0} are: ", bucketName);
                foreach (var obj in result.S3Objects)
                {
                    Console.WriteLine(obj.Key);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

如果 list 大于1000，则返回的结果中 isTruncated 为true，通过返回的 nextMarker 标记可以作为下次读取的起点。列举所有对象示例代码如下：

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class ListObjectsExample
    {
        public static async Task ListObjects2()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var credentials = new BasicAWSCredentials(accessKey, secretKey);
            try
            {
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);

                string marker = string.Empty; 
                bool isTruncated;

                do
                {
                    var listObjectsRequest = new ListObjectsRequest()
                    {
                        BucketName = bucketName,
                        Marker = marker
                    };

                    var result = await s3Client.ListObjectsAsync(listObjectsRequest);

                    if (result.HttpStatusCode != System.Net.HttpStatusCode.OK)
                    {
                        Console.WriteLine("fail to list objects in bucket {0}, HttpStatusCode:{1}, ErrorCode:{2}.", 
                            bucketName, (int)result.HttpStatusCode, result.HttpStatusCode);
                        return;
                    }

                    foreach (var obj in result.S3Objects)
                    {
                        Console.WriteLine(obj.Key);
                    }

                    isTruncated = result.IsTruncated; 
                    marker = result.NextMarker ?? string.Empty;

                } while (isTruncated && !string.IsNullOrEmpty(marker));

            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

ListObjects可以设置的参数如下：

参数	类型	说明	是否必要
BucketName	string	桶的名称	是
Delimiter	string	与Prefix参数一起用于对对象key进行分组的字符。所有key包含指定的Prefix且第一次出现Delimiter字符的对象作为一组。如果没有指定Prefix参数，按Delimiter对所有对象key进行分割，多个对象分割后从对象key开始到第一个Delimiter之间相同的部分形成一组	否
Marker	string	指定一个标识符，返回的对象的key将是按照字典顺序排序后位于该标识符之后的所有对象	否
MaxKeys	int	设置response中返回对象的数量，默认值和最大值均为1000	否
Prefix	string	限定返回对象的key必须以Prefix作为前缀	否

返回结果

ListObjects返回的结果如下：

属性名	类型	说明
CommonPrefixes	List<string>	当请求中设置了Delimiter和Prefix属性时，所有包含指定的Prefix且第一次出现Delimiter字符的key作为一组
Contents	List<S3Object>	对象数据，每个对象包含了Etag、Key、LastModifiedTime、Owner和Size等信息
Delimiter	string	与请求中设置的Delimiter一致
IsTruncated	bool	当为false时表示返回结果中包含了全部符合本次请求查询条件的对象信息，否则只返回了数量为MaxKeys个的对象信息
MaxKeys	int	本次返回结果包含的对象数量上限
Name	string	桶的名字
NextMarker	string	当返回结果中的IsTruncated为true时，可以使用NextMarker作为下次查询的Marker，继续查询出下一部分的对象信息
Prefix	string	与请求中设置的Prefix一致

上传对象

功能说明

PutObject操作用于上传对象。如果对同一个对象同时发起多个上传请求，最后一次完成的请求将覆盖之前所有请求的上传的对象。可以通过设置请求头部中的Content-MD5字段来保证数据被完整上传，如果上传的数据不能通过MD5校验，该操作将返回一个错误提示。用户可以通过比较上传对象后获得的ETag与原文件的MD5值是否相等来确认上传操作是否成功。

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class PutObjectExample
    {
        public static async Task PutObject()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var key = "<your-object-key>";
            var filePath = "<file-path>";
            try
            {
                var credentials = new BasicAWSCredentials(accessKey, secretKey);
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var putObjectRequest = new PutObjectRequest()
                {
                    BucketName = bucketName,
                    Key = key,
                    FilePath = filePath
                };

                var result = await s3Client.PutObjectAsync(putObjectRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.OK)
                {
                    Console.WriteLine("fail to put object {0}, HttpStatusCode:{1}, ErrorCode:{2}.", key, (int) result.HttpStatusCode, result.HttpStatusCode);
                    return;
                }

                Console.WriteLine("put obejct {0}, ETag: {1}, versionId:{2}", key, result.ETag, result.VersionId);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

PutObject可设置的参数如下：

参数	类型	说明	是否必要
CannedACL	S3CannedACL	配置上传对象的预定义的标准ACL信息	否
ContentBody	string	上传对象的数据内容，与FilePath、InputStream任选其一作为上传对象数据的来源	否
ContentType	string	描述上传文件格式的标准MIME类型	否
FilePath	string	上传文件的本地路径，与ContentBody、InputStream任选其一作为上传对象数据的来源	否
InputStream	Stream	对象的数据，与ContentBody、FilePath任选其一作为上传对象数据的来源	否
Bucket	string	桶的名称	是
MD5Digest	string	上传对象数据的base64编码的128位MD5值，不包含请求头部的信息	否
Key	string	上传文件到媒体存储服务后对应的key	是
Tagset	List<Tag>	对象的标签信息	否
WebsiteRedirectLocation	string	如果桶被配置用于提供网站的静态数据，该参数可以用于设置访问对象时候重定向到当前桶下的其他对象或者外部的URL	否

返回结果

PutObject返回的结果如下：

参数	类型	说明
ETag	string	上传对象后的对应的Entity Tag
VersionId	string	上传对象后相应的版本id

下载对象

功能说明

GetObject操作可以获取对象数据，并且保存为本地文件。执行GetObject操作必须对目标对象具有READ权限。

代码示例

using System;
using System.IO;
using System.Threading;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class GetObjectExample
    {
        public static async Task GetObject()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var key = "<your-object-key>";
            var filePath = "<file-path>";
            try
            {
                var credentials = new BasicAWSCredentials(accessKey, secretKey);
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var getObjectRequest = new GetObjectRequest()
                {
                    BucketName = bucketName,
                    Key = key
                };

                using (var result = await s3Client.GetObjectAsync(getObjectRequest))
                using (Stream stream = result.ResponseStream)
                {
                    var fileStream = File.Create(filePath);
                    await stream.CopyToAsync(fileStream);
                    fileStream.Close();
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

GetObject可设置的参数如下：

参数	类型	说明	是否必要
BucketName	string	桶的名称	是
EtagToMatch	string	用于指定只有在对象的ETag和该参数值匹配的情况下才返回对象数据，否则返回412错误码	否
ModifiedSinceDateUtc	DateTime	用于只有当对象在指定时间后被修改的情况下才返回该对象，否则返回304错误码	否
EtagToNotMatch	string	用于指定只有在对象的ETag和该参数值不匹配的情况下才返回对象数据，否则返回304错误码	否
UnmodifiedSinceDateUtc	DateTime	用于仅当对象自指定时间以来未被修改的情况下才返回对象数据，否则返回412错误码	否
Key	string	对象的key	是
PartNumber	int	读取对象指定的分片，该参数大于等于1，小于等于10000	否
ByteRange	ByteRange	下载对象指定范围内的数据（单位：字节）	否
VersionId	string	当桶开启版本控制的时候，用于指定获取指定版本的对象数据，当不指定该参数的时候，默认获取最新版本的对象数据	否

返回结果

GetObject返回的结果如下：

参数	类型	说明
BucketName	string	对象所在桶的名称
ContentLength	long	对象数据的长度，单位为字节
ETag	string	对象的Entity Tag
LastModified	DateTime	最后修改对象的时间
TagCount	int	对象标签的数量
VersionId	string	对象的version id

复制对象

功能说明

CopyObject操作用于根据一个已存在的对象创建新的对象。使用CopyOoject可以复制单个最大为5GB的对象，如果需要复制更大的对象，可以使用UploadPartCopy操作。执行CopyObject操作，必须具有对被拷贝对象的READ权限和对目标桶的WRITE权限。

拷贝生成的对象默认保留原对象的元数据信息，也可以才CopyObject操作中指定新的元数据。拷贝生成的对象不会保留原来的ACL信息，该对象默认是发起CopyObject操作的用户私有的。

CopyObject操作默认拷贝原对象的当前版本数据，如果需要拷贝原对象的指定版本，可以在CopySource中加入version id来拷贝指定的Object版本，如果原对象的version id为删除标记，则不会被拷贝。

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class CopyObjectExample
    {
        public static async Task CopyObject()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var sourceBucket = "<source-bucket>";
            var sourceKey = "<source-key>";
            var destinationBucket = "<destination-bucket>";
            var destinationKey = "<destination-key>";
            try
            {
                var credentials = new BasicAWSCredentials(accessKey, secretKey);
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var copyObjectRequest = new CopyObjectRequest()
                {
                    SourceBucket = sourceBucket,
                    SourceKey = sourceKey,
                    DestinationBucket = destinationBucket,
                    DestinationKey = destinationKey
                };
                var result = await s3Client.CopyObjectAsync(copyObjectRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.OK)
                {
                    Console.WriteLine("fail to copy object, HttpStatusCode:{0}, ErrorCode:{1}.", (int) result.HttpStatusCode, result.HttpStatusCode);
                    return;
                }

                Console.WriteLine("copy object from {0}/{1} to {2}/{3}.", sourceBucket, sourceKey, destinationBucket, destinationKey);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

CopyObject可设置的参数如下：

参数	类型	说明	是否必要
CannedACL	S3CannedACL	拷贝后对象的预定义的标准ACL信息	否
DestinationBucket	string	放置拷贝生成对象的桶名称	是
DestinationKey	string	拷贝生成对象的key	是
SourceBucket	string	放置被拷贝对象的桶的名称	是
SourceKey	string	被拷贝对象的key	是
Metadata	MetadataCollection	拷贝生成对象的元数据信息	否
MetadataDirective	S3MetadataDirective	指定拷贝生成的对象的元数据信息来自被拷贝对象，还是来自请求中附带的信息	否
TagSet	List<Tag>	拷贝生成对象的标签信息	否
SourceVersionId	string	指定被拷贝对象的版本信息，如果不指定，默认拷贝对象的当前版本	否
WebsiteRedirectLocation	string	如果桶被配置用于提供网站的静态数据，该参数可以用于设置访问对象时候重定向到当前桶下的其他对象或者外部的URL	否

返回结果

CopyObject返回的结果如下：

参数	类型	说明
ETag	string	拷贝生成对象的ETag
LastModified	string	拷贝生成对象的最新修改时间

删除对象

功能说明

DeleteObject操作用于删除一个对象。当桶未开启多版本时会直接删除对象。对开启版本控制的桶执行删除对象操作时，如果未指定version id ，则保留对象的当前版本，并插入删除标记（Delete Marker）。如果指定version id，则永久删除该指定版本的对象。如果在未指定version id的情况下执行DeleteObject操作时，默认仅作用于对象的当前版本，但不会直接删除该对象的当前版本，而是插入一个删除标记（Delete Marker），并保留原来的当前版本。当执行GetObject操作时，会检测到当前版本为删除标记，并返回404 NotFound。

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class DeleteObjectExample
    {
        public static async Task DeleteObject()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var key = "<your-object-key>";
            var credentials = new BasicAWSCredentials(accessKey, secretKey);
            try
            {
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);

                var deleteObjectRequest = new DeleteObjectRequest()
                {
                    BucketName = bucketName,
                    Key = key
                };
                var result = await s3Client.DeleteObjectAsync(deleteObjectRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.NoContent)
                {
                    Console.WriteLine("fail to delete object {0}, HttpStatusCode:{1}, ErrorCode:{2}.", key, (int) result.HttpStatusCode, result.HttpStatusCode);
                }

                Console.WriteLine("deleted object {0}.", key);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

DeleteObject可设置的参数如下：

参数	类型	说明	是否必要
BucketName	string	桶的名称	是
Key	string	对象的key	是
VersionId	string	用于指定要删除对象的版本，即version id	否

返回结果

DeleteObject返回的结果如下：

参数	类型	说明
DeleteMarker	string	有效值为true。在桶开启版本控制的情况下，执行DeleteObject 操作时如果未指定对象的版本，会创建删除标记，此时DeleteMarker为true。如果指定对象的版本来永久删除指定对象版本时，若该版本是删除标记，则DeleteMarker也为true。其他情况下DeleteMarker的值为空
VersionId	string	执行DeleteObject操作时如果未指定对象的版本Id，会创建删除标记，VersionId为删除标记的版本。如果指定版本来永久删除对象指定版本时，返回的VersionId为对象的版本

批量删除对象

功能说明

（本接口目前仅支持部分资源池使用，如需使用，请联系天翼云客服确认。）

DeleteObjects操作可以实现通过一个请求批量删除多个对象的功能，可以减少发起多起请求去删除大量对象的花销。DeleteObjects操作发起一个包含了最多1000个对象的删除请求，对象存储服务会对相应的对象逐个进行删除，并且将删除成功或者失败的结果通过response返回。如果请求删除的对象不存在，会当作已删除处理。

DeleteObjects操作返回verbose和quiet两种response模式。 verbose response是默认的返回模式，该模式的返回结果包含了每个key的删除结果。quiet response返回模式返回的结果仅包含了删除失败的key，对于一个完全成功的删除操作，该返回模式不在相应消息体中返回任何信息。

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class DeleteObjectsExample
    {
        public static async Task DeleteObjects()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            try
            {
                var credentials = new BasicAWSCredentials(accessKey, secretKey);
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                DeleteObjectsRequest deleteObjectsRequest = new DeleteObjectsRequest()
                {
                    BucketName = bucketName,
                    Quiet = false
                };
                deleteObjectsRequest.AddKey("<object-key1>");
                deleteObjectsRequest.AddKey("<object-key2>");

                var result = await s3Client.DeleteObjectsAsync(deleteObjectsRequest);
                Console.WriteLine("HttpStatusCode:{0}, {1}", (int) result.HttpStatusCode, result.HttpStatusCode);
                //打印删除成功的对象信息
                foreach (var deletedObject in result.DeletedObjects)
                {
                    Console.WriteLine("Key:{0}, DeleteMarker:{1}, VersionId:{2}, DeleteMarkerVersionId:{3}.", deletedObject.Key, deletedObject.DeleteMarker, deletedObject.VersionId,
                        deletedObject.DeleteMarkerVersionId);
                }

                //打印删除失败的对象信息
                foreach (var deleteError in result.DeleteErrors)
                {
                    Console.WriteLine("Code:{0}, Key:{1}, Message:{2}, VersionId:{3}", deleteError.Code, deleteError.Key, deleteError.Message, deleteError.VersionId);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

DeleteObjects可设置的参数如下：

参数	类型	说明	是否必要
BucketName	string	桶的名称	是
Quiet	bool	设置为ture表示采用返回结果为quiet response模式，设置为false表示返回结果为verbose response模式	否

返回结果

DeleteObjects返回的结果如下：

参数	类型	说明
Deleted	List<DeletedObject>	被删除对象信息的数组，数组中每一项包含了一个被成功删除的对象的信息，包括删除标记、对象名称和版本等信息
Errors	List<DeleteError>	删除失败的对象信息的数组，数组中每一项包含了一个删除失败的对象的信息，包括错误码、对象名称和版本等信息

获取对象元数据

功能说明

GetObjectMetadata操作用于获取对象的元数据信息。执行HeadObject操作需要具有对该对象的READ权限。GetObjectMetadata操作可以用于判断对象是否存在。

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class GetObjectMetadataExample
    {
        public static async Task GetObjectMetadata()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var key = "<your-object-key>";
            try
            {
                var credentials = new BasicAWSCredentials(accessKey, secretKey);
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var getObjectMetadataRequest = new GetObjectMetadataRequest()
                {
                    BucketName = bucketName,
                    Key = key
                };

                var result = await s3Client.GetObjectMetadataAsync(getObjectMetadataRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.OK)
                {
                    Console.WriteLine("fail to get metadata of object {0}, HttpStatusCode:{1}, ErrorCode:{2}.", key, (int) result.HttpStatusCode, result.HttpStatusCode);
                    return;
                }

                Console.WriteLine("get object metadata response: {0}", (int) result.HttpStatusCode);
                Console.WriteLine("object ETag:{0}, object versionId:{1}", result.ETag, result.VersionId);
                Console.WriteLine("object storage class:{0}", result.StorageClass);
                Console.WriteLine("object content length:{0}", result.ContentLength);
                Console.WriteLine("object last modified time:{0}", result.LastModified);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

GetObjectMetadata可设置的参数如下：

参数	类型	说明	是否必要
BucketName	string	桶的名称	是
EtagToMatch	string	用于指定只有在对象的ETag和该参数值匹配的情况下才返回对象数据，否则返回412错误码	否
ModifiedSinceDateUtc	DateTime	用于只有当对象在指定时间后被修改的情况下才返回该对象，否则返回304错误码	否
EtagToNotMatch	string	用于指定只有在对象的ETag和该参数值不匹配的情况下才返回对象数据，否则返回304错误码	否
UnmodifiedSinceDateUtc	DateTime	用于仅当对象自指定时间以来未被修改的情况下才返回对象数据，否则返回412错误码	否
Key	string	对象的key	是
PartNumber	int	读取对象指定的分片，该参数大于等于1，小于等于10000	否
VersionId	string	当桶开启版本控制的时候，用于指定获取指定版本的对象数据，当不指定该参数的时候，默认获取最新版本的对象数据	否

返回结果

GetObjectMetadata返回的结果如下：

参数	类型	说明
ContentLength	long	本次请求返回数据的大小（单位：字节）
ETag	string	对象的Entity Ttag
LastModified	DateTime	最近一次修改对象的时间
VersionId	string	对象最新的版本ID
StorageClass	string	对象的存储类型

设置对象访问权限

功能说明

PutACL操作可以通过access control list（ACL）设置一个对象的访问权限。用户在设置对象的ACL之前需要具备WRITE_ACP 权限。

对象的访问权限说明：

权限类型	说明
READ	可以对桶进行list操作
READ_ACP	可以读取桶的ACL信息。桶的所有者默认具有桶的READ_ACP权限
WRITE	可以在桶中创建对象，修改原有对象数据和删除对象
WRITE_ACP	可以修改桶的ACL信息，授予该权限相当于授予FULL_CONTROL权限，因为具有WRITE_ACP权限的用户可以配置桶的任意权限。桶的所有者默认具有桶的WRITE_ACP权限
FULL_CONTROL	同时授予READ、READ_ACP、WRITE和WRITE_ACP权限

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class PutObjectACLExample
    {
        public static async Task PubObjectACL()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var key = "<your-object-key>";
            try
            {
                var credentials = new BasicAWSCredentials(accessKey, secretKey);
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var putACLRequest = new PutACLRequest()
                {
                    BucketName = bucketName,
                    Key = key,
                    // 添加一个公共读权限
                    CannedACL = S3CannedACL.PublicRead
                };

                var result = await s3Client.PutACLAsync(putACLRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.OK)
                {
                    Console.WriteLine("fail to put ACL to object {0}, HttpStatusCode:{1}, ErrorCode:{2}.", key, (int) result.HttpStatusCode, result.HttpStatusCode);
                    return;
                }

                Console.WriteLine("set {0} to object {1}", putACLRequest.CannedACL.Value, key);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

PutACL可设置的参数如下：

参数	类型	说明	是否必要
CannedACL	S3CannedACL	配置对象的预定义的标准ACL信息	否
AccessControlList	S3AccessControlList	配置自定义的ACL信息	否
BucketName	string	桶的名称	是
Key	string	对象的key	是
VersionId	string	设置对象的version id	否

S3CannedACL包含了一组预定义的访问控制权限，可以应用于对象的访问权限如下：

权限	说明
NoACL	默认访问权限，对象的所有者拥有FULL_CONTROL权限，其他用户没有访问权限
Private	对象的所有者拥有FULL_CONTROL权限，其他用户没有访问权限
PublicRead	对象的所有者拥有FULL_CONTROL权限，其他用户拥有READ权限
PublicReadWrite	对象的所有者拥有FULL_CONTROL权限，其他用户拥有READ和WRITE权限
BucketOwnerRead	对象的所有者拥有FULL_CONTROL权限，桶的所有者拥有READ权限
BucketOwnerFullControl	对象的所有者和桶的所有者拥有FULL_CONTROL权限

获取对象访问权限

功能说明

GetACL操作可以获取对象的access control list（ACL）信息。对象的ACL可以在上传对象的时候设置并且通过API查看，用户需要具有READ_ACP（读取桶ACL信息）权限才可以查询对象的ACL信息。

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class GetObjectACLExample
    {
        public static async Task GetObjectACL()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var key = "<your-object-key>";
            try
            {
                var credentials = new BasicAWSCredentials(accessKey, secretKey);
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var getAclRequest = new GetACLRequest()
                {
                    BucketName = bucketName,
                    Key = key
                };
                var result = await s3Client.GetACLAsync(getAclRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.OK)
                {
                    Console.WriteLine("fail to get ACL of bucket {0}, HttpStatusCode:{1}, ErrorCode:{2}.", bucketName, (int) result.HttpStatusCode, result.HttpStatusCode);
                    return;
                }

                foreach (var grant in result.AccessControlList.Grants)
                {
                    Console.WriteLine("Type:{0}, CanonicalUser:{1}, DisplayName:{2}, EmailAddress:{3}, URI:{4}, Permission:{5}",
                        grant.Grantee.Type, grant.Grantee.CanonicalUser, grant.Grantee.DisplayName, grant.Grantee.EmailAddress, grant.Grantee.URI, grant.Permission.Value);
                }

                Console.WriteLine("OwnerId:{0}, OwnerDisplayName:{1}.", result.AccessControlList.Owner.Id, result.AccessControlList.Owner.DisplayName);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

GetACL可设置的参数如下：

参数	类型	说明	是否必要
BucketName	string	桶的名称	是
Key	string	对象的key	是
VersionId	string	设置对象的版本	否

返回结果

GetACL返回的结果如下：

属性名	类型	说明
Grants	List<S3Grant>	Grant信息的数组，包含了每项授权和被授予人的信息
Owner	Owner	对象的所有者信息

获取对象标签

功能说明

GetObjectTagging操作可以查询对象的标签信息，对象标签以key-value的形式设置。桶的所有者默认拥有查询桶中对象的标签的权限，并且可以将权限授予其他用户。

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class GetObjectTaggingExample
    {
        public static async Task GetObjectTagging()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var key = "<your-object-key>";
            var credentials = new BasicAWSCredentials(accessKey, secretKey);
            try
            {
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var getObjectTaggingRequest = new GetObjectTaggingRequest()
                {
                    BucketName = bucketName,
                    Key = key
                };
                var result = await s3Client.GetObjectTaggingAsync(getObjectTaggingRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.OK)
                {
                    Console.WriteLine("fail to get tags of object {0}, HttpStatusCode:{1}, ErrorCode:{2}.", key, (int) result.HttpStatusCode, result.HttpStatusCode);
                    return;
                }

                Console.WriteLine("the tags of {0} are: ", key);
                foreach (var tag in result.Tagging)
                {
                    Console.WriteLine("key={0}, value={1}", tag.Key, tag.Value);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

GetObjectTagging可设置的参数如下：

参数	类型	说明	是否必要
BucketName	string	执行本操作的桶名称	是
Key	string	想获取标签信息的对象的key	是
VersionId	string	想获取标签信息的对象的版本Id	否

返回结果

GetObjectTagging返回的结果如下：

参数	类型	说明
Tagging	List<Tag>	对象标签信息数组，数组中的每一项包含了标签Key和Value的值

删除对象标签

功能说明

DeleteObjectTagging操作可以删除一个对象的全部标签信息，删除时可以指定version id参数删除指定版本对象的标签信息，如果不设置version id，则默认删除当前版本的对象标签信息。

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class DeleteObjectTaggingExample
    {
        public static async Task DeleteObjectTagging()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var key = "<your-object-key>";
            try
            {
                var credentials = new BasicAWSCredentials(accessKey, secretKey);
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var deleteObjectTaggingRequest = new DeleteObjectTaggingRequest()
                {
                    BucketName = bucketName,
                    Key = key
                };
                var result = await s3Client.DeleteObjectTaggingAsync(deleteObjectTaggingRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.NoContent)
                {
                    Console.WriteLine("fail to delete tags of object {0}, HttpStatusCode:{1}, ErrorCode:{2}.", key, (int) result.HttpStatusCode, result.HttpStatusCode);
                    return;
                }

                Console.WriteLine("deleted the tags of object {0} ", key);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

DeleteObjectTagging可设置的参数如下：

参数	类型	说明	是否必要
BucketName	string	执行本操作的桶名称	是
Key	string	被删除标签信息的对象的key	是
VersionId	string	被删除标签信息的对象的version id	否

设置对象标签

功能说明

PutObjectTagging操作可以为对象设置标签，对象标签以key-value的形式设置，每个对象最多可以有10个标签。桶的所有者默认拥有给桶中的对象设置标签的权限，并且可以将权限授予其他用户。

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class PutObjectTaggingExample
    {
        public static async Task PutObjectTagging()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var key = "<your-object-key>";
            try
            {
                var credentials = new BasicAWSCredentials(accessKey, secretKey);
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var putObjectTaggingRequest = new PutObjectTaggingRequest()
                {
                    BucketName = bucketName,
                    Key = key,
                };
                putObjectTaggingRequest.Tagging.TagSet.Add(new Tag()
                {
                    Key = "<key1>",
                    Value = "<value1>"
                });
                putObjectTaggingRequest.Tagging.TagSet.Add(new Tag()
                {
                    Key = "<key2>",
                    Value = "<value2>"
                });
                var result = await s3Client.PutObjectTaggingAsync(putObjectTaggingRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.OK)
                {
                    Console.WriteLine("fail to put tags of object {0}, HttpStatusCode:{1}, ErrorCode:{2}.", key, (int) result.HttpStatusCode, result.HttpStatusCode);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

PutObjectTagging可设置的参数如下：

参数	类型	说明	是否必要
BucketName	string	设置标签信息的对象所在桶的名称	是
Key	string	设置标签信息的对象的key	是
VersionId	string	设置标签信息的对象的version id	否

生成下载预签名URL

功能说明

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class PutObjectTaggingExample
    {
        public static async Task PutObjectTagging()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var key = "<your-object-key>";
            try
            {
                var credentials = new BasicAWSCredentials(accessKey, secretKey);
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var putObjectTaggingRequest = new PutObjectTaggingRequest()
                {
                    BucketName = bucketName,
                    Key = key,
                };
                putObjectTaggingRequest.Tagging.TagSet.Add(new Tag()
                {
                    Key = "<key1>",
                    Value = "<value1>"
                });
                putObjectTaggingRequest.Tagging.TagSet.Add(new Tag()
                {
                    Key = "<key2>",
                    Value = "<value2>"
                });
                var result = await s3Client.PutObjectTaggingAsync(putObjectTaggingRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.OK)
                {
                    Console.WriteLine("fail to put tags of object {0}, HttpStatusCode:{1}, ErrorCode:{2}.", key, (int) result.HttpStatusCode, result.HttpStatusCode);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

PutObjectTagging可设置的参数如下：

参数	类型	说明	是否必要
BucketName	string	设置标签信息的对象所在桶的名称	是
Key	string	设置标签信息的对象的key	是
VersionId	string	设置标签信息的对象的version id	否

生成上传预签名URL

功能说明

GetPreSignedURL接口为一个指定对象生成一个预签名的上传链接，访问该链接可以直接上传对象。

代码示例

生成上传预签名URL：

public string GeneratePutUrl()
{
    Console.Out.WriteLine("generateUploadUrl");

    GetPreSignedUrlRequest request = new GetPreSignedUrlRequest
    {
        BucketName = "<your-bucket-name>",
        Key = "<your-object-key>",
        Expires = DateTime.Now.AddMinutes(5),
        Protocol = Protocol.HTTP,  //Protocol.HTTP or Protocol.HTTPS
        Verb = HttpVerb.PUT, // 设置 HTTP 方法为 PUT，用于上传
        ContentType = "application/octet-stream"  // 指定 Content-Type
    };

    string url = this.s3Client.GetPreSignedURL(request);
    Console.Out.WriteLine("generateUploadUrl: {0}", url);
    return url;
}

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

public void PutObjUsingPresignedUrl(string url, string filePath)
{
    try
    {
        using (WebClient client = new WebClient())
        {
            client.Headers.Add("Content-Type", "application/octet-stream");
            client.UploadFile(url, "PUT", filePath);
        }
        Console.WriteLine("Upload successful. File uploaded from: " + filePath);
    }
    catch (Exception ex)
    {
        Console.WriteLine("Upload failed: " + ex.ToString());
    }
}

请求参数

参数	类型	说明	是否必要
BucketName	string	桶的名称	是
Key	string	对象的key	是
Expires	DateTime	超时的时间戳	否
Protocol	Protocol	指定生成的URL使用http协议还是https协议	否
Verb	HttpVerb	HTTP 方法，设置为 PUT 以生成上传 URL，默认为GET	否
ContentType	String	对象的ContentType	否。若生成预签名URL时指定了，则通过预签名链接上传时也需要指定为相同的ContentType

返回结果

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

服务端加密

功能说明

上传对象时可以指定对象的加密算法，即使设置桶的加密配置也可以加密请求上传的对象数据，服务端根据指定的加密算法对对象数据进行加密。目前支持AES256和国密SM4加密算法。

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class PutObjectWithEncryptionExample
    {
        public static async Task PutObjectWithEncryption()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var key = "<your-object-key>";
            var filePath = "<file-path>";
            try
            {
                var credentials = new BasicAWSCredentials(accessKey, secretKey);
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint,
                    UseHttp = false
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var putObjectRequest = new PutObjectRequest()
                {
                    BucketName = bucketName,
                    Key = key,
                    FilePath = filePath,
                    ServerSideEncryptionMethod = new ServerSideEncryptionMethod("AES256")
                };

                var result = await s3Client.PutObjectAsync(putObjectRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.OK)
                {
                    Console.WriteLine("fail to put object {0}, HttpStatusCode:{1}, ErrorCode:{2}.", key, (int) result.HttpStatusCode, result.HttpStatusCode);
                    return;
                }
                Console.WriteLine("object ETag:{0}, object versionId:{1}", result.ETag, result.VersionId);
                Console.WriteLine("encryption method:{0}", result.ServerSideEncryptionMethod.Value);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

加密参数说明如下：

参数	类型	说明	是否必要
ServerSideEncryptionMethod	ServerSideEncryptionMethod	指定服务端采用的加密算法，如AES256、SM4	否

返回结果

PutObject返回的结果如下：

参数	类型	说明
ETag	string	上传对象后的对应的Entity Tag
VersionId	string	上传对象后相应的版本id
ServerSideEncryptionMethod	ServerSideEncryptionMethod	返回对象数据加密的算法名称

获取多版本对象列表

功能说明

ListVersions操作可以获取关于对象版本信息的元数据，执行该操作需要对桶有READ权限。

代码示例

using System;
using System.Threading.Tasks;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

namespace DotNetSDK.ObjectOperation
{
    public class ListVersionsExample
    {
        public static async Task ListVersions()
        {
            var accessKey = "<your-access-key>";
            var secretKey = "<your-secret-access-key>";
            var endpoint = "<your-endpoint>";
            var bucketName = "<your-bucket-name>";
            var key = "<your-object-key>";
            try
            {
                var credentials = new BasicAWSCredentials(accessKey, secretKey);
                var conf = new AmazonS3Config
                {
                    ServiceURL = endpoint
                };
                var s3Client = new AmazonS3Client(credentials, conf);
                var listVersionsRequest = new ListVersionsRequest()
                {
                    BucketName = bucketName,
                    Prefix = key
                };
                var result = await s3Client.ListVersionsAsync(listVersionsRequest);
                if (result.HttpStatusCode != System.Net.HttpStatusCode.OK)
                {
                    Console.WriteLine("fail to list versions, HttpStatusCode:{0}, ErrorCode:{1}.", (int) result.HttpStatusCode, result.HttpStatusCode);
                    return;
                }

                foreach (var s3ObjectVersion in result.Versions)
                {
                    Console.WriteLine("key: {0}, versionId: {1}.", s3ObjectVersion.Key, s3ObjectVersion.VersionId);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

请求参数

ListVersions可以设置的参数如下：

参数	类型	说明	是否必要
BucketName	string	查询版本信息的对象所在的桶的名称	是
Delimiter	string	与Prefix参数一起用于对对象key进行分组的字符。所有key包含指定的Prefix且第一次出现Delimiter字符之间的对象作为一组。如果没有指定Prefix参数，按Delimiter对所有对象key进行分割，多个对象分割后从对象key开始到第一个Delimiter之间相同的部分形成一组	否
KeyMarker	string	指定一个标识符，返回的对象的key将是按照字典顺序排序后位于该标识符之后的所有对象	否
MaxKeys	int	设置response中返回对象key的数量，默认值和最大值均为1000	否
Prefix	string	限定返回对象的key必须以Prefix作为前缀	否

返回结果

ListVersions返回的结果如下：

属性名	类型	说明
CommonPrefixes	List<string>	当请求中设置了Delimiter和Prefix属性时，所有包含指定的Prefix且第一次出现Delimiter字符的对象key作为一组
Delimiter	string	与请求中设置的Delimiter一致
IsTruncated	bool	当为false时表示返回结果中包含了全部符合本次请求查询条件的对象版本信息，否则只返回了MaxKeys个对象版本信息
KeyMarker	string	与请求中设置的KeyMarker一致
MaxKeys	int	本次返回结果中包含的对象版本信息数量的最大值
Name	string	执行本操作的桶名称
NextKeyMarker	string	当返回结果中的IsTruncated为true时，可以使用NextKeyMarker作为下次查询请求中的KeyMarker，继续查询出下一部分的对象版本信息
NextVersionIdMarker	string	本次查询返回的最后一个的对象version id
Prefix	string	与请求中设置的Prefix一致
Versions	List<S3ObjectVersion>	对象版本信息的数组，数组中每一项包含了对象的Entity Tag、是否为最新版本以及DeleteMarker、对象key、最新修改时间、拥有者、大小、存储类型和对象版本的信息

活动

智算服务

应用商城

定价

合作伙伴

开发者

支持与服务

了解天翼云

媒体存储

媒体存储

获取对象列表

功能说明

代码示例

请求参数

返回结果

上传对象

功能说明

代码示例

请求参数

返回结果

下载对象

功能说明

代码示例

请求参数

返回结果

复制对象

功能说明

代码示例

请求参数

返回结果

删除对象

功能说明

代码示例

请求参数

返回结果

批量删除对象

功能说明

代码示例

请求参数

返回结果

获取对象元数据

功能说明

代码示例

请求参数

返回结果

设置对象访问权限

功能说明

代码示例

请求参数

获取对象访问权限

功能说明

代码示例

请求参数

返回结果

获取对象标签

功能说明

代码示例

请求参数

返回结果

删除对象标签

功能说明

代码示例

请求参数

设置对象标签

功能说明

代码示例

请求参数

生成下载预签名URL

功能说明

代码示例

请求参数

生成上传预签名URL

功能说明

代码示例

请求参数

返回结果

服务端加密

功能说明

代码示例

请求参数