快速入门（Java）

请先阅读常用概念术语文档。

新建一个存储空间

存储空间（Bucket）是存储对象（Object）的容器。对象都隶属于存储空间。本文介绍如何创建存储空间。

以下代码用于创建examplebucket存储空间。

您可以在创建存储空间时指定存储类型和存储空间读写权限。更多信息，请分别参见存储类型介绍和设置存储空间读写权限（ACL）。

控制台创建

进入控制台，点击右上角新建空间，新建的空间名称即为之后提到的bucket。

SDK 创建

// yourEndpoint填写Bucket所在地域对应的Endpoint。以中国（北京）为例，Endpoint填写为ks3-cn-beijing.ksyuncs.com。如果使用自定义域名，设置endpoint为自定义域名，同时设置domainMode为true
String endpoint = "yourEndpoint";
// 金山云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用子账号账号进行 API 访问或日常运维，请登录 https://uc.console.ksyun.com/pro/iam/#/user/list 创建子账号。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 创建Ks3ClientConfig 实例。
Ks3ClientConfig config = new Ks3ClientConfig();
// 设置域名
config.setEndpoint(endpoint); 
/**
 * false: （推荐）使用三级域名：{bucketName}.{endpoint}/{objectKey}的形式访问
 * true:  使用二级域名：{endpoint}/{bucketName}/{objectKey}的形式访问
 * 如果domainMode设置为true，则pathStyleAccess可忽略设置
 */
config.setPathStyleAccess(false);

// 创建Ks3Client实例
Ks3 client = new Ks3Client(accessKeyId,accessKeySecret,config);   
// 创建CreateBucketRequest对象。
CreateBucketRequest createBucketRequest = new CreateBucketRequest("examplebucket");
// 如果创建存储空间的同时需要指定存储类型和数据容灾类型, 请参考如下代码。
// 此处以设置存储空间的存储类型为标准存储(默认是标准存储)为例介绍。
//createBucketRequest.setBucketType(BucketType.Normal);
// 设置存储空间的权限为公共读写，默认为私有。
//createBucketRequest.setCannedAcl(CannedAccessControlList.PublicReadWrite);
client.createBucket(createBucketRequest);

上传文件

简单上传是指通过PutObject方法上传单个文件（Object）。简单上传包括流式上传和文件上传，流式上传使用InputStream作为KS3文件的数据源，文件上传使用本地文件作为KS3文件的数据源。本文介绍如何使用流式上传和文件上传方式上传文件。

流式上传

• 上传字符串

  以下代码用于将字符串上传到目标存储空间examplebucket中exampledir目录下的exampleobject.txt文件。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以中国（北京）为例，Endpoint填写为ks3-cn-beijing.ksyuncs.com。如果使用自定义域名，设置endpoint为自定义域名，同时设置domainMode为true
String endpoint = "yourEndpoint";
// 金山云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用子账号账号进行 API 访问或日常运维，请登录 https://uc.console.ksyun.com/pro/iam/#/user/list 创建子账号。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 创建Ks3ClientConfig 实例。
Ks3ClientConfig config = new Ks3ClientConfig();
// 设置域名
config.setEndpoint(endpoint); 
/**
 * false: （推荐）使用三级域名：{bucketName}.{endpoint}/{objectKey}的形式访问
 * true:  使用二级域名：{endpoint}/{bucketName}/{objectKey}的形式访问
 * 如果domainMode设置为true，则pathStyleAccess可忽略设置
 */
config.setPathStyleAccess(false);

// 创建Ks3Client实例
Ks3 client = new Ks3Client(accessKeyId,accessKeySecret,config);
  
// 填写字符串。
String content = "Hello KS3";
// 设置上传文件的meta信息
ObjectMetadata metadata = new ObjectMetadata();
// 创建PutObjectRequest对象。
// 依次填写Bucket名称（例如examplebucket）和Object完整路径（例如exampledir/exampleobject.txt）。Object完整路径中不能包含Bucket名称。
PutObjectRequest putObjectRequest = new PutObjectRequest("examplebucket", "exampledir/exampleobject.txt", new ByteArrayInputStream(content.getBytes()), metadata);
  
// 如果需要上传时设置存储类型和访问权限，请参考以下示例代码。
// putObjectRequest.setStorageClass(StorageClass.Standard);
// putObjectRequest.setCannedAcl(CannedAccessControlList.Private);
  
// 上传字符串。
client.putObject(putObjectRequest);            

• 上传Byte数组

  以下代码用于将Byte数组上传到目标存储空间examplebucket中exampledir目录下的exampleobject.txt文件。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以中国（北京）为例，Endpoint填写为ks3-cn-beijing.ksyuncs.com。如果使用自定义域名，设置endpoint为自定义域名，同时设置domainMode为true
  String endpoint = "yourEndpoint";
// 金山云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用子账号账号进行 API 访问或日常运维，请登录 https://uc.console.ksyun.com/pro/iam/#/user/list 创建子账号。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 创建Ks3ClientConfig 实例。
Ks3ClientConfig config = new Ks3ClientConfig();
// 设置域名
config.setEndpoint(endpoint); 
/**
* false: （推荐）使用三级域名：{bucketName}.{endpoint}/{objectKey}的形式访问
* true:  使用二级域名：{endpoint}/{bucketName}/{objectKey}的形式访问
* 如果domainMode设置为true，则pathStyleAccess可忽略设置
*/
config.setPathStyleAccess(false);

// 创建Ks3Client实例
Ks3 client = new Ks3Client(accessKeyId,accessKeySecret,config);
  
// 填写Byte数组。
byte[] content = "Hello KS3".getBytes();
// 设置上传文件的meta信息
ObjectMetadata metadata = new ObjectMetadata();
// 依次填写Bucket名称（例如examplebucket）和Object完整路径（例如exampledir/exampleobject.txt）。Object完整路径中不能包含Bucket名称。
client.putObject("examplebucket", "exampledir/exampleobject.txt", new ByteArrayInputStream(content), metadata);

• 上传网络流

  以下代码用于将网络流上传到目标存储空间examplebucket中exampledir目录下的exampleobject.txt文件。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以中国（北京）为例，Endpoint填写为ks3-cn-beijing.ksyuncs.com。如果使用自定义域名，设置endpoint为自定义域名，同时设置domainMode为true
String endpoint = "yourEndpoint";
// 金山云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用子账号账号进行 API 访问或日常运维，请登录 https://uc.console.ksyun.com/pro/iam/#/user/list 创建子账号。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 创建Ks3ClientConfig 实例。
Ks3ClientConfig config = new Ks3ClientConfig();
// 设置域名
config.setEndpoint(endpoint); 
/**
 * false: （推荐）使用三级域名：{bucketName}.{endpoint}/{objectKey}的形式访问
 * true:  使用二级域名：{endpoint}/{bucketName}/{objectKey}的形式访问
 * 如果domainMode设置为true，则pathStyleAccess可忽略设置
 */
config.setPathStyleAccess(false);

// 创建Ks3Client实例
Ks3 client = new Ks3Client(accessKeyId,accessKeySecret,config);
  
// 填写网络流地址。
InputStream inputStream = new URL("https://www.ksyun.com").openStream();
// 设置上传文件的meta信息
  ObjectMetadata metadata = new ObjectMetadata();
// 依次填写Bucket名称（例如examplebucket）和Object完整路径（例如exampledir/exampleobject.txt）。Object完整路径中不能包含Bucket名称。
client.putObject("examplebucket", "exampledir/exampleobject.txt", inputStream, metadata);

文件上传

以下代码用于将文件流上传到目标存储空间examplebucket中exampledir目录下的exampleobject.txt文件。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以中国（北京）为例，Endpoint填写为ks3-cn-beijing.ksyuncs.com。如果使用自定义域名，设置endpoint为自定义域名，同时设置domainMode为true
String endpoint = "yourEndpoint";
// 金山云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用子账号账号进行 API 访问或日常运维，请登录 https://uc.console.ksyun.com/pro/iam/#/user/list 创建子账号。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 创建Ks3ClientConfig 实例。
Ks3ClientConfig config = new Ks3ClientConfig();
// 设置域名
config.setEndpoint(endpoint); 
/**
 * false: （推荐）使用三级域名：{bucketName}.{endpoint}/{objectKey}的形式访问
 * true:  使用二级域名：{endpoint}/{bucketName}/{objectKey}的形式访问
 * 如果domainMode设置为true，则pathStyleAccess可忽略设置
 */
config.setPathStyleAccess(false);

// 创建Ks3Client实例
Ks3 client = new Ks3Client(accessKeyId,accessKeySecret,config);
// 填写本地文件的完整路径。如果未指定本地路径，则默认从示例程序所属项目对应本地路径中上传文件流。
File file = new File("D:\\localpath\\examplefile.txt");
// 依次填写Bucket名称（例如examplebucket）和Object完整路径（例如exampledir/exampleobject.txt）。Object完整路径中不能包含Bucket名称。
client.putObject("examplebucket", "exampledir/exampleobject.txt", file);

通过表单的方式上传文件

1. 了解KS3表单上传协议，以及表单上传签名认证方式。

2. 在KS3控制台->空间设置->CORS配置里配置CORS跨域规则。CORS为跨域资源共享，当使用js跨域时，需要配置该规则。W3C文档。

3. 使用js sdk上传文件: 。

4. js sdk 中的policy和signature可以通过Java SDK的该方法计算出来。

public PostObjectFormFields postObjectSimple() {
       // yourEndpoint填写Bucket所在地域对应的Endpoint。以中国（北京）为例，Endpoint填写为ks3-cn-beijing.ksyuncs.com。如果使用自定义域名，设置endpoint为自定义域名，同时设置domainMode为true
       String endpoint = "yourEndpoint";
       // 金山云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用子账号账号进行 API 访问或日常运维，请登录 https://uc.console.ksyun.com/pro/iam/#/user/list 创建子账号。
       String accessKeyId = "yourAccessKeyId";
       String accessKeySecret = "yourAccessKeySecret";
       // 创建Ks3ClientConfig 实例。
       Ks3ClientConfig config = new Ks3ClientConfig();
       // 设置域名
       config.setEndpoint(endpoint);
       /**
        * false: （推荐）使用三级域名：{bucketName}.{endpoint}/{objectKey}的形式访问
        * true:  使用二级域名：{endpoint}/{bucketName}/{objectKey}的形式访问
        * 如果domainMode设置为true，则pathStyleAccess可忽略设置
        */
       config.setPathStyleAccess(false);

       // 创建Ks3Client实例
       Ks3 client = new Ks3Client(accessKeyId, accessKeySecret, config);
       /**
       * 需要用户在postData和unknowValueField中提供所有的除KSSAccessKeyId, signature, file, policy外的所有表单项。否则用生成的签名上传会返回403</br>
       * 对于用户可以确定表单值的放在 postData中，对于用户无法确定表单值的放在unknownValueField中(比如有的上传控件会添加一些表单项,但表单项的值可能是随机的)</br>
       */
       Map<String, String> postData = new HashMap<String, String>();
       // 如果使用js sdk上传的时候设置了ACL，请提供以下一行，且值要与SDK中一致，否则删除下面一行代码
       postData.put("acl","public-read");
       // 提供js sdk中的key值
       postData.put("key","20150115/中文/${filename}");
       // 设置无法确定的表单值
       List<String> unknowValueField = new ArrayList<String>();
       // js sdk上传的时候会自动加上一个name的表单项，所以下面需要加上这样的代码。
       unknowValueField.add("name");      
       // 如果计算签名时提供的key里不包含${filename}占位符，第二个参数传一个空字符串。
       PostObjectFormFields fields = client.postObject("<您的bucket名称>", "<要上传的文件名称,不包含路径信息>", postData, unknowValueField);
       // 获取KssAccessKeyId
       fields.getKssAccessKeyId();
       // 获取 post 的 policy 
       fields.getPolicy();
       // 获取 signature
       fields.getSignature();
       // 返回 policy 相关信息
       return fields;
}

• 上传时，浏览器一共会发送两个请求，首先是OPTIONS请求，如果该请求返回403，请检测CORS配置是否正确。第二个为POST请求，如果该请求返回403，请检查生成policy时，是否按照表单内容生成，或者把policy进行base64解码，对比表单内容是否正确。对比规则：Policy、Signature构建方法。

获取文件访问地址

• 如果是公开文件
  通过：http://{bucket}.{endpoint}/{key}的方式拼接一个URL即可。比如：http://test-bucket.ks3-cn-beijing.ksyuncs.com/2015/10/19/image.jpg, 该URL中的{bucket}是test-bucket,{endpoint}是kssws.ks-cdn.com,{key}是2015/10/19/image.jpg。

• 如果是私有文件
  通过以下代码可以生成一个访问地址

// yourEndpoint填写Bucket所在地域对应的Endpoint。以中国（北京）为例， 
Endpoint填写为ks3-cn-beijing.ksyuncs.com。如果使用自定义域名，设置endpoint为自定义域名，同时设置domainMode为true
String endpoint = "yourEndpoint";
// 金山云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用子账号账号进行 API 访问或日常运维，请登录 
https://uc.console.ksyun.com/pro/iam/#/user/list 创建子账号。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 创建Ks3ClientConfig 实例。
Ks3ClientConfig config = new Ks3ClientConfig();
// 设置域名
config.setEndpoint(endpoint);
/**
 * false: （推荐）使用三级域名：{bucketName}.{endpoint}/{objectKey}的形式访问
 * true:  使用二级域名：{endpoint}/{bucketName}/{objectKey}的形式访问
 * 如果domainMode设置为true，则pathStyleAccess可忽略设置
 */
config.setPathStyleAccess(false);

// 创建Ks3Client实例
Ks3 client = new Ks3Client(accessKeyId, accessKeySecret, config);
// 生成一个在1000秒后过期的外链
client.generatePresignedUrl(<bucket>,<key>,1000);
// 生成一个1000秒后过期并重写返回的heade的外链
ResponseHeaderOverrides overrides = new ResponseHeaderOverrides();
// overrides.setContentType("text/html");
// .......
// 生成指定 bucket 和 key 的外链，有效期1000秒
String url = client.generatePresignedUrl(<bucket>,<key>,1000,overrides);

常见问题：

• 如果文件不存在，会返回NoSuchKey错误。
• 如果以公开的方式访问私有文件，会返回AccessDined错误。
• 如果私有文件访问地址过期，会返回URLExpired错误。
• 1000秒后过期是参照客户端本地时间的。