快速入门

最近更新时间:2022-11-09 17:09:26

查看PDF

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

新建一个存储空间

存储空间(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秒后过期是参照客户端本地时间的。

文档内容是否对您有帮助?

根本没帮助
文档较差
文档一般
文档不错
文档很好

在文档使用中是否遇到以下问题

内容不全,不深入
内容更新不及时
描述不清晰,比较混乱
系统或功能太复杂,缺乏足够的引导
内容冗长

更多建议

0/200

评价建议不能为空

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!

问题反馈