全部文档
当前文档
最近更新时间：2023-01-11 10:41:09
请先阅读常用概念术语文档。
存储空间（Bucket）是存储对象（Object）的容器。对象都隶属于存储空间。本文介绍如何创建存储空间。
以下代码用于创建examplebucket存储空间。
您可以在创建存储空间时指定存储类型和存储空间读写权限。更多信息，请分别参见存储类型介绍和设置存储空间读写权限（ACL）。
进入控制台，点击右上角新建空间，新建的空间名称即为之后提到的bucket。
// 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);
2. 在KS3控制台->空间设置->CORS配置里配置CORS跨域规则。CORS为跨域资源共享，当使用js跨域时，需要配置该规则。W3C文档。
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;
}
常见问题：
如果是公开文件
通过：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秒后过期是参照客户端本地时间的。
纯净模式