搜狐云存储服务6533ae3156da9.cdn.sohucs.com/SCS_DOTNET_SDK.pdf · 2014. 6. 9. · 准的 Rest...

1

搜狐云存储服务

.NET SDK 文档

最后更新：2014.06.05

2

目录

1. 欢迎使用搜狐云存储服务 ................................................................................................ 1

2. 快速入门 ........................................................................................................................... 2

2.1. 初始化一个 SohuSCS ................................................................................................. 2

2.2. 创建空间 .................................................................................................................... 2

2.3. 上传文件 .................................................................................................................... 4

2.4. 下载文件 .................................................................................................................... 5

3. 新建 Client ......................................................................................................................... 7

3.1. 新建 SohuSCS ............................................................................................................. 7

3.2. 服务访问地址 ............................................................................................................. 7

4. 空间操作 ........................................................................................................................... 8

4.1. 空间命名规范 ............................................................................................................. 8

4.2. 获取用户创建的所有空间列表 ................................................................................. 8

4.3. 创建空间 ..................................................................................................................... 8

4.4. 删除空间 ..................................................................................................................... 8

4.5. 获取空间所在地域 ..................................................................................................... 9

4.6. 获取空间的版本状态 ............................................................................................... 10

4.7. 设置空间的版本状态 .............................................................................................. 11

4.8. 查询空间里的所有文件信息 .................................................................................. 12

4.9. 查询文件的版本信息 ............................................................................................... 13

5. 文件操作 .......................................................................................................................... 15

5.1. 文件命名规范 ........................................................................................................... 15

5.2. 获取文件元数据信息 ............................................................................................... 15

5.3. 拷贝文件 ................................................................................................................... 16

5.4. 上传文件 ................................................................................................................... 17

5.5. 下载文件 ................................................................................................................... 17

5.6. 删除文件 ................................................................................................................... 17

5.7. 批量删除文件 ........................................................................................................... 18

5.8. 初始化分块上传 ......................................................................................................... 20

5.9. 查看当前正在分块上传的文件 ............................................................................... 26

3

5.10. 分块上传 ................................................................................................................. 26

5.11. 完成分块上传 ......................................................................................................... 26

5.12. 取消分块上传 ......................................................................................................... 27

1

1. 欢迎使用搜狐云存储服务

本文档是搜狐云存储服务提供的 SDK 的参考文档。本文档详细描述了搜狐云存储服务

提供的.NET SDK。

搜狐云存储服务，是搜狐公司提供的安全、高效、低成本、高可靠性的云服务。通过标

准的 Rest API 接口，多种语言的 SDK 以及 Web 页面，用户可以方便地在任何时间、地点

访问和管理资源和权限。我们同时提供超低成本存储，云数据库，跨 IDC 同步， CDN 和

图片处理等服务，方便您搭建网盘，网站，备份个人或企业的大规模数据。

2

2. 快速入门

2.1. 初始化一个SohuSCS

描述：

SohuSCS 接口是与 SCS 服务交互的客户端，所有的操作都通过调用 SohuSCS 的接口函

数来完成。SohuCSClient 是 SohuSCS 的一个实现，也是目前唯一的实现。

在使用前，首先需要引用以下命名空间

using Sohu;

using Sohu.CS;

using Sohu.CS.Model;

using Sohu.Runtime;

代码：

static String accessKey = " Accesskey ";

static String secretKey = " Secretkey ";

SHSCSCredentials myCredentials = new BasicSHSCSCredentials(access

Key, secretKey);

SohuCSClient client = new SohuCSClient(myCredentials, RegionEndpo

int.BJCNC);

说明：

变量 Accesskey 和 Secretkey 是系统分给用户的，用于标识用户，为访问 SCS 做签名

验证。

2.2. 创建空间

方法描述：

3

Bucket 为用户在 SCS 上创建的空间，可以存储数据实体（Object）。用户需要权限验证

来访问 Bucket 中的数据，以保护您的数据的安全。

其中若指定了地域（region）信息，则按照地域（region）指定的节点服务器保存文件，

若未指定，则默认将文件保存到 BJCNC（北京联通）的节点服务器。

方法名

PutBucket(PutBuck

etRequest)

PutBucketReque

st创建参数

类型说明是否必须

BucketName string 空间名必须

BucketRegion Sohu.CS.SCSReg

ion

空间所在节点选填(不填为BJCN

C)

代码：

PutBucketRequest request = new PutBucketRequest

{

BucketName = "bucketname",

BucketRegion = SCSRegion.SHCTC

};

PutBucketResponse response = client.PutBucket(request);

说明：

Bucket 的名字是全局唯一的。您可以尝试用您的公司或用户名作为前缀的命名方

式，防止 Bucket 名重复。

关于 Bucket 的命名规范，见 4.1 空间命名规范。

需要特别注意的是，在调用 SohuSCS 的函数时，使用 catch

Sohu.CS.SohuCSException 的方法来获取失败响应的错误码。为简化起见，在下面的

所有函数例子中，不再写出打印相关异常信息的代码。

4

2.3. 上传文件

描述：

Object 是 SCS 中基本的数据单元，可以理解为文件，可以添加自定义的文件元数据保

存到服务器中。

方法名

PutObject(PutObje

ctRequest)

PutObjectReque

st创建参数



Key string Object名必须

Metadata Sohu.CS.Model.

MetadataCollec

tion

Object的metadat

a

选填，通过add方

法添加

FilePath string 文件路径选填，FilePath和

InputStream二者

必须填一个。

代码：

//example 1

PutObjectRequest request1 = new PutObjectRequest

{


Key = "T1.jpg",

};

5

request1.Metadata.Add("x-scs-meta-height", "200");

request1.Metadata.Add("x-scs-meta-width", "200");

request1.Metadata.Add("x-scs-meta-test", "test");

request1.Metadata.Add("x-scs-meta-yes", "yes");

using (FileStream stream = new FileStream("E:/T1.jpg", FileMode.O

pen))

{

request1.InputStream = stream;

PutObjectResponse response1 = client.PutObject(request1);

}

//example 2

PutObjectRequest request5 = new PutObjectRequest

{


Key = "T2.png",

FilePath = "E:/T2.png",

};

request5.Metadata.Add("x-scs-meta-height", "200");

request5.Metadata.Add("x-scs-meta-width", "200");

request5.Metadata.Add("x-scs-meta-test", "test");

request5.Metadata.Add("x-scs-meta-yes", "yes");

PutObjectResponse response5 = client.PutObject(request5);

说明：

上述代码将 Object 上传到了 bucket。同时保存了用户自定义的元数据信息

Object 的命名规则见 5.1 文件命名规范。

2.4. 下载文件

6

描述：

GetObject 方法通过指定 bucket 以及文件名来下载文件。

方法名

GetObject(GetObje

ctRequest)

GetObjectRequ

est创建参数



Key string Object名必须

ByteRange Sohu.CS.Model.Byte

Range

所需获取文件字

节范围

选填，空缺时获

取完整文件

VersionId string 版本号选填，空缺时获

取最新版本文件

代码：

GetObjectRequest request1 = new GetObjectRequest

{

BucketName = "zcya-bjcnc",

Key = "T200.jpg",

//ByteRange = new ByteRange(0,140),

};

GetObjectResponse response1 = client.GetObject(request1);

Stream stream = response1.ResponseStream;

byte[] buffer = new byte[1024];

using (MemoryStream ms = new MemoryStream())

{

int read;

7

while ((read = stream.Read(buffer, 0, buffer.Length))

> 0)

{

ms.Write(buffer, 0, read);

}

byte[] data = ms.ToArray();

FileStream fs = new FileStream("E:/T200.jpg", FileMod

e.Create);

fs.Write(data, 0, data.Length);

}

说明：

然后调用 GetObject 方法，实现 Object 的下载。

3. 新建Client

SohuCSClient 是 SCS 服务的.Net 客户端，它为调用者提供了一系列的方法，用于和 SCS

交互。

3.1. 新建SohuSCS

描述：

以下代码新建了一个 SohuSCS。

代码：

参考2.1

3.2. 服务访问地址

描述：

以下代码描述了如何设置服务访问地址。

代码：

参考2.1

8

4. 空间操作

4.1. 空间命名规范

空间命名的规范如下：

名字长度在 3 到 63 之内；

名字只支持由小写字母、数字、点和横杠组成；

名字中如包含点和横杠，则不能出现在第一位和最后一位，且不能临靠出现。

不支持大写字母

不支持包含 IPv4 格式（X.X.X.X）的字符串

4.2. 获取用户创建的所有空间列表

描述：

ListBuckets()是获取用户创建的所有的 Bucket 列表的接口。

代码：

ListBucketsResponse response = client.ListBuckets();

Console.WriteLine("Buckets owner - {0}", response.Owner.DisplayNa

me);

foreach (SCSBucket bucket in response.Buckets)

{

Console.WriteLine("Bucket {0}, Date {1}", bucket.BucketNam

e, bucket.CreationDate);

}

4.3. 创建空间

参照 2.2 创建空间

4.4. 删除空间

描述：

9

DeleteBucket(deleteBucketRequest)是删除 Bucket 的接口。

方法名

DeleteBucket(dele

teBucketRequest)

deleteBucketR

equest创建参数



BucketRegion Sohu.CS.SCSRegion 主机地址选填（建议不

填）

代码：

DeleteBucketRequest request1 = new DeleteBucketRequest

{


//BucketRegion = SCSRegion.BJCNC

};

client.DeleteBucket(request1);

4.5. 获取空间所在地域

描述：

GetBucketLocation(getBucketLocationRequest)是获取 Bucket 所在的区域的接口。

方法名

GetBucketLocation

(getBucketLocatio

nRequest)

GetBucketLoca 类型说明是否必须

10

tion创建参数


代码：

GetBucketLocationRequest request1 = new GetBucketLocationRequest

{

BucketName = "bucketname"

};

GetBucketLocationResponse response1 = client.GetBucketLocation(re

quest1);

Console.WriteLine("Bucket location - {0}", response1.Location);

4.6. 获取空间的版本状态

描述：

GetBucketVersioning (GetBucketVersioningRequest)是获取 Bucket 是否开

启了版本的接口。

方法名

GetBucketVersioni

ng(GetBucketVersi

oningRequest)

GetBucketVers

ioningRequest

创建参数



代码：

11

GetBucketVersioningRequest request1 = new GetBucketVersioningRequ

est

{

BucketName = "bucketname"

};

GetBucketVersioningResponse response1 = client.GetBucketVersionin

g(request1);

Console.WriteLine("Version - {0}", response1.VersioningConfig.Sta

tus.Value);

4.7. 设置空间的版本状态

描述：

版本信息说明如下：

PutBucketVersioning (PutBucketVersioningRequest)

是对 Bucket 开启版本功能的接口。

开启版本后（状态为 Enabled），不能再关闭版本。

开启版本后可以将版本状态转换为 Suspended，之后上传的文件将不存在版本区

别，但是之前的文件依旧保留版本号。

Suspended 与 enabled 状态可以互相转换。

方法名

PutBucketVersioni

ng(PutBucketVersi

oningRequest)

PutBucketVers

ioningRequest

创建参数



VersioningCon SCSBucketVersionCo 版本状态必须

12

fig nfig()

代码：

PutBucketVersioningRequest request1 = new PutBucketVersioningRequ

est

{

BucketName = "bucketname ",

VersioningConfig = new SCSBucketVersioningConfig {Status

= VersionStatus.Suspended}

};

PutBucketVersioningResponse response1 = client.PutBucketVersioni

ng(request1);

4.8. 查询空间里的所有文件信息

描述：

可以通过 ListObjects(ListObjectsRequest) 里的所有的文件的信息。

方法名

ListObjects(ListO

bjectsRequest )

ListObjectsRe

quest创建参数



Prefix string prefix 选填

Marker string marker 选填

MaxKeys int maxkeys 选填

Delimiter string delimiter 选填

13

代码：

ListObjectsRequest Request1 = new ListObjectsRequest

{


Prefix = "prefix",

Marker = "marker",

MaxKeys = 2,

Delimiter = "delimiter"

};

ListObjectsResponse Response1 ;

Response1 = client.ListObjects(Request1);

foreach (string pre in Response1.CommonPrefixes)

{

Console.WriteLine("CommonPrefixes - " + pre);

}

foreach (scsObject obj in Response1.scsObjects)

{

Console.WriteLine("Object - " + obj.Key);

Console.WriteLine(" Size - " + obj.Size);

Console.WriteLine(" LastModified - " + obj.LastModifie

d);

Console.WriteLine(" Storage class - " + obj.StorageCla

ss);

}

4.9. 查询文件的版本信息

描述：

14

ListVersions()，指定查询参数，返回符合版本要求的文件列表。提供两种参数列表，指

定 6 种参数去查询，或者将参数封装成 request 查询。

方法名

ListVersions (ListVer

sionsRequest )

ListVersionsRe

quest创建参数



prefix string prefix 选填

VersionIdMarke

r

string versionIdmarke

r

选填

KeyMarker string keymarker 选填

Delimiter string delimiter 选填

MaxKeys int maxkeys 选填

返回值为 ListVersionsResponse 类的对象，相比 ListObjectsResponse 对象多了版本信息。

代码：

ListVersionsRequest request = new ListVersionsRequest

{

BucketName = "zcya-bjcnc",

Prefix = "prefix",

MaxKeys = 2,

delimiter = " delimiter ",

KeyMarker = " KeyMarker ",

VersionIdMarker = " versionIdmarker ",

};

ListVersionsResponse response = client.ListVersions(request);

15

Console.WriteLine(response.Prefix);

Console.WriteLine(response.ContentLength);

foreach(scsObjectVersion objversion in response.Versions)

{

Console.WriteLine("{0}-{1}-{2}-{3}", objversion.Key, objv

ersion.VersionId, objversion.ETag, objversion.IsDeleteMarker);

}

5. 文件操作

5.1. 文件命名规范

文件的命名规范为：

使用 unicode 编码，支持中文，a-z0-9A-Z，-_.!~'%/

不支持 : ; \r \n

最长为 799 位

5.2. 获取文件元数据信息

描述：

GetObjectMetadata (GetObjectMetadataRequest)为获取文件元数据信息（包括用户自定

义元数据）的接口。

GetObjectMetadata (GetObjectMetadataRequest)可以获取指定版本号的文件的元数据。

方法名

GetObjectMetadata

(GetObjectMetadat

aRequest)

PutBucketVers 类型说明是否必须

16

ioningRequest

创建参数


key string object名必须

VersionId string 版本号选填

代码：

GetObjectMetadataRequest request1 = new GetObjectMetadataRequest

{


Key = "T1.jpg",

VersionId = "versionid"

};

GetObjectMetadataResponse response1 = client.GetObjectMetadata(re

quest1);

Console.WriteLine("{0}", response1.LastModified);

foreach (string sk in response1.Metadata.Keys)

{

Console.WriteLine("{0}-{1}", sk, response1.Metadata[sk]);

}

5.3. 拷贝文件

描述：

CopyObject(CopyObjectRequest)用于拷贝文件，拷贝文件时只能在同 Region 的空间之间

进行拷贝。

代码：

CopyObjectRequest request1 = new CopyObjectRequest

{

SourceBucket = "sourcebucket",

17

SourceKey = "sourcekey",

DestinationBucket = "destinationbucket",

DestinationKey = "destinationkey ",

};

request1.Metadata.Add("x-scs-meta-test","test");

CopyObjectResponse response1 = client.CopyObject(request1);

5.4. 上传文件

详细见 2.3

5.5. 下载文件

详细见 2.4

5.6. 删除文件

描述：

可以通过 DeleteObject(DeleteObjectRequest)删除文件。当删除特定版本，即配置了

VersionId，但是空间没有开启版本功能时，并不会删除文件，文件并不会真正删除，而是插

入一个 delete marker;

方法名

DeleteObject(Dele

teObjectRequest)

DeleteObjectR

equest创建参数



key string object名必须

VersionId string 版本号选填

18

代码：

DeleteObjectRequest request1 = new DeleteObjectRequest

{


Key = "T1.jpg",

VersionId = "versionid"

};

client.DeleteObject(request1);

5.7. 批量删除文件

描述：

DeleteObjects(DeleteObjectsRequest ) 是批量删除文件的接口，在参数

DeleteObjectsRequest 中可以指定需要删除的所有文件的文件名和版本号，其中版本号可选。

方法名

DeleteObjects(Del

eteObjectsReques

t)

DeleteObjectReque

st创建参数



Objects list<Sohu.CS.M

odel.KeyVersio

n.KeyVresion

()>

object对象集合必须

代码：

19

DeleteObjectsRequest request = new DeleteObjectsRequest

{


Objects = new List<KeyVersion>

{

new KeyVersion() {Key = "T1.png", VersionId = "versio

nid"},

new KeyVersion() {Key = "T2.jpg", VersionId = "versio

nid"},

}

};

try

{

DeleteObjectsResponse response = client.DeleteObjects(req

uest);

}

catch (DeleteObjectsException doe)

{

DeleteObjectsResponse errorResponse = doe.Response;

foreach (DeletedObject deletedObject in errorResponse.Del

etedObjects)

{

Console.WriteLine("Deleted item " + deletedObject.Ke

y);

}

foreach (DeleteError deleteError in errorResponse.DeleteE

rrors)

{

Console.WriteLine("Error deleting item " + deleteErr

20

or.Key);

Console.WriteLine(" Code - " + deleteError.Code);

Console.WriteLine(" Message - " + deleteError.Messag

e);

}

}

5.8. 初始化分块上传

描述：

分块上传的流程为：

调用初始化分块上传接口 InitiateMultipartUpload ，即

InitiateMultipartUpload(InitiateMultipartUploadRequest request)接口，获取 UploadId，

即唯一标识本次分块上传的 ID；

调用分块上传接口，即 UploadPartResponse UploadPart (UploadPartRequest

uploadPartRequest)接口分块上传；

调用完成分块上传接口，即 CompleteMultipartUploadResponse

CompleteMultipartUpload(CompleteMultipartUploadRequest reqest)接口完成分块上

传。

InitiateMultipartUpload 函数是初始化分块上传的接口，该接口的参数可以指定空间名字，

key，用户自定义的元数据等等。

代码部分提供了两个例子，第一个例子需要指定分配分块上传的分块数量。第二个例子

无需指定分块数量。

代码：

//-----------------------------------------------example2--------

-----------------------------------------

//-------------------------------------指定UploadPart的数量-------

-------------------------

21

int MB = (int)Math.Pow(2, 20);

Stream inputStream = new FileStream("E:/T100.jpg", FileMode.Ope

n);

// Initiate multipart upload

InitiateMultipartUploadRequest initRequest = new InitiateMultipar

tUploadRequest

{


Key = "T100.jpg"

};

initRequest.Metadata.Add("x-scs-meta-test", "test");

InitiateMultipartUploadResponse initResponse = client.InitiateMul

tipartUpload(initRequest);

// Upload part 1

UploadPartRequest uploadRequest = new UploadPartRequest

{

BucketName = " bucketname ",

Key = "T100.jpg",

UploadId = initResponse.UploadId,

PartNumber = 1,

PartSize = 5 * MB,

InputStream = inputStream

};

UploadPartResponse up1Response = client.UploadPart(uploadReques

t);

// Upload part 2

uploadRequest = new UploadPartRequest

{


22

Key = "T100.jpg",


PartNumber = 2,

PartSize = 5 * MB,


};


t);

// Upload part 3


{


Key = "T100.jpg",


PartNumber = 3,

PartSize = 5 * MB,


};


t);

// Upload part 4


{


Key = "T100.jpg",


PartNumber = 4,


};

23


t);

// List parts for current upload

ListPartsRequest listPartRequest = new ListPartsRequest

{


Key = "T100.jpg",

UploadId = initResponse.UploadId

};

ListPartsResponse listPartResponse = client.ListParts(listPartReq

uest);

Console.WriteLine("MaxParts:"+listPartRequest.MaxParts);

Console.WriteLine("BucketName:" + listPartRequest.BucketName);

Console.WriteLine("Encoding:" + listPartRequest.Encoding);

Console.WriteLine("Key:" + listPartRequest.Key);

Console.WriteLine("PartNumberMarker:" + listPartRequest.PartNumbe

rMarker);

Console.WriteLine("UploadId:" + listPartRequest.UploadId);

foreach (PartDetail pt in listPartResponse.Parts)

{

Console.WriteLine(" {0} - {1} - {2} ", pt.PartNumber, p

t.ETag, pt.Size);

}

// Complete the multipart upload

CompleteMultipartUploadRequest compRequest = new CompleteMultipar

tUploadRequest

24

{


Key = "T100.jpg",


PartETags = new List<PartETag>

{

new PartETag { ETag = up1Response.ETag, PartNum

ber = 1 },


ber = 2 },


ber = 3 },


ber = 4 }

}

};

CompleteMultipartUploadResponse compResponse = client.CompleteMul

tipartUpload(compRequest);

//-----------------------------------------------example2--------

-----------------------------------------

//-------------------------------------无需指定UploadPart的数量---

-----------------------------

int MB = (int)Math.Pow(2, 20);

Stream inputStream = new FileStream("E:/T100.jpg", FileMode.Ope

n);

long fileLength = inputStream.Length;

// Initiate multipart upload

InitiateMultipartUploadRequest initRequest = new InitiateMultipar

25

tUploadRequest

{


Key = "T200.jpg"

};

initRequest.Metadata.Add("x-scs-meta-test", "test");

InitiateMultipartUploadResponse initResponse = client.InitiateMul

tipartUpload(initRequest);

long leftsize = fileLength;

int partnumber = 1;

CompleteMultipartUploadRequest compRequest = new CompleteMultipar

tUploadRequest

{

BucketName = "bucketname ",

Key = "T200.jpg",


};

while (leftsize > 0)

{

long partsize = 0;

if (leftsize > 5 * MB)

partsize = 5 * MB;

else

partsize = leftsize;

UploadPartRequest uploadRequest = new UploadPartRequest

{


26

Key = "T200.jpg",

PartNumber = partnumber,

PartSize = 5 * MB,



};

UploadPartResponse uploadResponse = client.UploadPart(uploadReque

st);

compRequest.PartETags.Add(new PartETag { ETag = uploadResponse.ET

ag, PartNumber = partnumber });

partnumber++;

leftsize = leftsize - 5 * MB;

}

CompleteMultipartUploadResponse compResponse = client.CompleteMul

tipartUpload(compRequest);

5.9. 查看当前正在分块上传的文件

描述：

ListParts(ListPartsRequest)可以查看当前正在分块上传的文件。

代码：

详细见 5.9 代码部分

5.10. 分块上传

描述：

UploadPart(UploadPartRequest)是分块上传的接口。在调用分块上传接口前，必须先调用

初始化分块上传接口。调用分块上传接口后，必须调用完成分块上传接口或取消分块上传。

代码：


5.11. 完成分块上传

27

描述：

CompleteMultipartUpload(CompleteMultipartUploadRequest) 是完成分块上传的接口。

代码：


5.12. 取消分块上传

描述：

AbortMultipartUpload(AbortMultipartUploadRequest)为取消分块上

传的接口。

代码：

AbortMultipartUploadRequest request = new AbortMultipartUploadReq

uest

{


Key = "T100.jpg",

UploadId = "uploadid"

};

client.AbortMultipartUpload(request);

Date post:	22-Aug-2020
Category:	Documents
Upload:	others
View:	24 times
Download:	0 times

搜狐云存储服务6533ae3156da9.cdn.sohucs.com/SCS_DOTNET_SDK.pdf · 2014. 6. 9. · 准的 Rest...

Documents