帮助与文档

我们为你提供丰富、详尽的使用指南以及产品文档

Java SDK

QingStor Java SDK 已在 GitHub 开源,下文为简要使用文档。更多详细信息请参见 GitHub 项目页面, 和Java SDK API 文档。Java SDK 使用 Snips 工具生成, 各个调用的均与具体的 Qingstor Restful API 对应, 返回码、请求头、错误码等规定请参照具体 API 文档的描述。

安装

可以下载源码:

> git clone git@github.com:yunify/qingstor-sdk-java.git

也可以访问 GitHub 的 release 页面 下载压缩包

快速开始

使用 SDK 之前请先在 青云控制台 申请 access key 。

初始化服务

发起请求前首先建立需要初始化服务:

import com.qingstor.sdk.config.EvnContext;
import com.qingstor.sdk.service.*;

EvnContext evn = new EvnContext("ACCESS_KEY_ID", "SECRET_ACCESS_KEY");
QingStor storService = new QingStor(evn);

上面代码初始化了一个 QingStor Service

获取账户下的 Bucket 列表

ListBucketsOutput listOutput = storService.listBuckets(null);

创建 Bucket

初始化并创建 Bucket, 需要指定 Bucket 名称和所在 Zone:

Bucket bucket = storService.getBucket("test-bucket", "pek3a");
Bucket.PutBucketOutput putBucketOutput = bucket.put();

获取 Bucket 中存储的 Object 列表

Bucket.ListjavaObjectsOutput listObjectsOutput = Bucket.listObjects(null);

创建一个 Object

例如一个文件:

Bucket.PutObjectInput input = new Bucket.PutObjectInput();
File f = new File("test_file");
input.setBodyInputFile(f);
input.setContentType("text/plain");
input.setContentLength((int) f.length());
Bucket.PutObjectOutput putObjectOutput = bucket.putObject(test_object, input);

删除一个 Object

Bucket.DeleteObjectOutput deleteObjectOutput = bucket.deleteObject("test_file");

本地时间和网络时间不同步

如果用户本地时间与网络时间不同步会因签名原因造成请求失败。您还需要从服务端获取网络时间。

下面是一个关于服务端如何返回正确时间到客户端的示例。

Calendar instance = Calendar.getInstance(TimeZone.getTimeZone("Asia/Beijing"));
String gmtTime = QSSignatureUtil.formatGmtDate(instance.getTime());
return gmtTime;

在您从服务端获取到正确时间后,您需要在调用 reqHandler.sendAsync(); 方法前将时间设置到 SDK 中。

reqHandler.getBuilder().setHeader(QSConstant.HEADER_PARAM_KEY_DATE, gmtTime);
reqHandler.sendAsync();

使用服务端签名

以上传文件为例:

try {
    // 第一步: 创建 EvnContext 并设置 zone 和 bucket
    EvnContext evn = new EvnContext("", "");
    Bucket bucket = new Bucket(evn, "zone 名称", "bucket 名称");

    Bucket.PutObjectInput putObjectInput = new Bucket.PutObjectInput();
    File file = new File("/文件路径/文件名");
    putObjectInput.setBodyInputFile(file);
    putObjectInput.setContentLength(file.length());

    // bucket.putObject("对象名称", putObjectInput);

    // 第二步:获取 RequestHandler,正常 bucket.putObject("对象名称", putObjectInput); 就完成操作
    RequestHandler reqHandler = bucket.putObjectAsyncRequest(objectName, putObjectInput,
        new ResponseCallBack<PutObjectOutput>() {
            @Override
            public void onAPIResponse(PutObjectOutput output) {
                System.out.println("Message = " + output.getMessage());
                System.out.println("RequestId = " + output.getRequestId());
                System.out.println("Code = " + output.getCode());
                System.out.println("StatueCode = " + output.getStatueCode());
                System.out.println("Url = " + output.getUrl());
                }
            });
            	
    // 第三步:获取 strToSignature。将这个字符串发送到用户的 server 端。
    String strToSignature = reqHandler.getStringToSignature();

    // 第四步:serverAuthorization。server 端处理返回信息,服务端参考如下代码:
    // String serverAuthorization = QSSignatureUtil.generateSignature("您的 secretKey", strToSignature);
    String serverAuthorization = "您从服务端获取到的签名字符串";

    // 第五步:将计算的签名设置到 request 中
    
    // 因客户端跟服务端通讯可能有时间差,而签名计算结果跟时间密切相关,因此需要将服务端计算签名时所用的时间设置到 request 中
    // 服务端代码示例:return QSSignatureUtil.formatGmtDate(new Date());
    String gmtTime = "您从服务端获取的 GMT 时间";
    reqHandler.getBuilder().setHeader(QSConstant.HEADER_PARAM_KEY_DATE, gmtTime);
    		
    reqHandler.setSignature("您的 accessKey", serverAuthorization);

    // 第六步:发送请求。异步请求使用 sendAsync() 方法。同步请求使用 send() 方法。
    reqHandler.sendAsync();

} catch (QSException e) {
    e.printStackTrace();
}