<commit_before>---
title: Java SDK | 七牛云存储
---

# Java SDK 使用指南


此SDK适用于Java 6及以上版本。

SDK下载地址：[https://github.com/qiniu/java-sdk/tags](https://github.com/qiniu/java-sdk/tags)


**环境准备**

**应用接入**

- [获取Access Key 和 Secret Key](#acc-appkey)
- [签名认证](#acc-auth)

**云存储接口**

- [新建资源表](#rs-NewService)
- [获得上传授权](#rs-PutAuth)
- [上传文件](#rs-PutFile)
- [获取已上传文件信息](#rs-Stat)
- [下载文件](#rs-Get)
- [发布公开资源](#rs-Publish)
- [取消资源发布](#rs-Unpublish)
- [删除已上传的文件](#rs-Delete)
- [删除整张资源表](#rs-Drop)

## 环境准备

需要在Eclipse工程中，导入七牛云存储的 SDK。目前，七牛云存储的 SDK 依赖于一下第三方包：

- commons-codec-1.6.jar
- commons-logging-1.1.1.jar
- fluent-hc-4.2.jar
- httpclient-4.2.jar
- httpclient-cache-4.2.jar
- httpcore-4.2.1.jar
- httpcore-4.2.jar
- httpcore-ab-4.2.1.jar
- httpcore-nio-4.2.1.jar
- httpmime-4.2.jar

七牛云存储 SDK 中的 qbox/lib 目录默认已经包含这些第三方包，您直接使用就行。但是，也有可能因为你本地编译环境问题，需要重新载入这些包。

## 应用接入

<a name="acc-appkey"></a>

### 1. 获取Access Key 和 Secret Key

要接入七牛云存储，您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得：

1. [开通七牛开发者帐号](https://dev.qiniutek.com/signup)
2. [登录七牛开发者自助平台，查看 Access Key 和 Secret Key](https://dev.qiniutek.com/account/keys) 。

<a name="acc-auth"></a>

### 2. 签名认证

首先，到 [https://github.com/qiniu/java-sdk/tags](https://github.com/qiniu/java-sdk/tags) 下载SDK源码。

然后，将SDK导入到您的 Eclipse 项目中，并编辑当前工程目录下QBox.config文件，确保其包含您从七牛开发者平台所获取的 [Access Key 和 Secret Key](#acc-appkey)：

    ACCESS_KEY	: "<Please apply your access key>";
	SECRET_KEY	: "<Dont send your secret key to anyone>";



在完成 Access Key 和 Secret Key 配置后，为了正常使用该 SDK 提供的功能需要根据配置文件进行初始化，您还需要使用你获得的 Access Key 和 Secret Key 向七牛云存储服务器发出认证请求：

	Config.init("QBox.config"); // 此处通过传入配置文件完成初始化，您可以将配置文件存放任何位置，初始化时候要注意传入路径的正确性。
	DigestAuthClient conn = new DigestAuthClient();

请求成功后得到的 conn 即可用于您正常使用七牛云存储的一系列功能，接下来将一一介绍。

## 云存储接口

<a name="rs-NewService"></a>

### 1. 新建资源表

新建资源表的意义在于，您可以将所有上传的资源分布式加密存储在七牛云存储服务端后还能保持相应的完整映射索引。

    // 通过传入配置文件，完成初始化工作
    Config.init("QBox.config") ;

    // 首先定义资源表名
    String bucketName = "bucketName";
    
    // 然后获得签名认证
    DigestAuthClient conn = new DigestAuthClient();
    
    // 签名认证完成后，即可使用该认证来新建资源表
    RSService rs = new RSService(conn, bucketName);


<a name="rs-PutAuth"></a>

### 2. 获得上传授权

建完资源表，在上传文件并和该资源表建立关联之前，还需要取得上传授权。所谓上传授权，就是获得一个可匿名直传的且离客户端应用程序最近的一个云存储节点的临时有效URL。

要取得上传授权，只需调用已经实例化好的资源表对象的 putAuth() 方法。实例代码如下：

    // 获得上传授权之前需要通过签名认证的方式来实例化一个资源表对象
    Config.init("QBox.config") ;
    String bucketName = "bucketName";
    DigestAuthClient conn = new DigestAuthClient();
    RSService rs = new RSService(conn, bucketName);
    
    // 然后，调用该资源表对象的 putAuth() 方法来获得上传授权
    PutAuthRet putAuthRet = rs.putAuth();


如果请求成功，putAuthRet 会包含 url 和 expires_in 两个字段。url 字段对应的值为匿名上传的临时URL，expires_in 对应的值则是该临时URL的有效期。

<a name="rs-PutFile"></a>

### 3. 上传文件

七牛云存储上传文件的方式分为直传和断点续传两种。

##### 1.文件上传
Java SDK 目前支持从本地上传某个文件，用户可以根据需要选择是直传还是断点续传。  
要以直传的方式上传文件，用户只需获得相关认证就可以上传文件了。  
如果上传成功，得到的 putFileRet 会包含对应的 hash 值，否则返回对应的错误。

示例代码如下：
   
    // 获得认证
    Config.init("QBox.config") ;
    String bucketName = "bucketName";
    AuthPolicy policy = new AuthPolicy(bucketName, 3600);
    String token = policy.makeAuthTokenString();
    UpTokenClient upTokenClient = new UpTokenClient(token);
    UpService upClient = new UpService(upTokenClient);

    // 上传文件
    String key = "README.md";
    String path = RSDemo.class.getClassLoader().getResource("").getPath();		
    RandomAccessFile f = new RandomAccessFile(path + key, "r");
    long fsize = f.length();
    long blockCount = UpService.blockCount(fsize);
    String[] checksums = new String[(int)blockCount];
    BlockProgress[] progresses = new BlockProgress[(int)blockCount];
    // 由于此处的 Notifer 未提供任何的"持久化"功能，所以此处相当于文件直传
    Notifier notif = new Notifier();

    PutFileRet putFileRet = RSClient.resumablePutFile(upClient, 
		checksums, progresses, 
		(ProgressNotifier)notif, (BlockProgressNotifier)notif, 
		bucketName, key, "", f, fsize, "CustomMeta", "");

	


##### 2. 断点续上传

客户端在上传文件的时候也可以根据需求选择断点续上传的方式，此处所说的断点上传是指用户在某次上传过程中出现错误，再重新上传的时候只需要从上次上传失败处上传即可。用户可以根据通过修改配置文件改变上传块（Config文件中的PUT_CHUNK_SIZE对应的值）的大小来适应用户所处的网络环境。为了提供一个简单的接口，我们将上传进度持久化的相关工作内置在了 SDK 中，当然用户也可以根据需要自己实现文件上传进度的持久化工作。

如果上传成功，得到的 putFileRet 会包含对应的 hash 值，否则返回对应的错误。

示例代码如下：  

    Config.init("/home/wangjinlei/QBox.config") ;
	String bucketName = "bucketName";
	String key = "RSDemo.class";
				
	AuthPolicy policy = new AuthPolicy("bucketName", 3600);
	String token = policy.makeAuthTokenString();
	UpTokenClient upTokenClient = new UpTokenClient(token);
	UpService upClient = new UpService(upTokenClient);
	PutFileRet  putFileRet = null ;
	
	putFileRet = RSClient.resumablePutFile(upClient,
				bucketName, key, "", inputFile, "CustomMeta", "", "");



<a name="rs-Stat"></a>

### 4. 获取已上传文件信息

您可以调用资源表对象的 Stat() 方法并传入一个 Key（类似ID）来获取指定文件的相关信息。

	// 实例化一个资源表对象，并获得一个相应的授权认证<commit_msg>new doc<commit_after>---
title: Java SDK | 七牛云存储
---

# Java SDK 使用指南


此SDK适用于Java 6及以上版本。

SDK下载地址：[https://github.com/qiniu/java-sdk/tags](https://github.com/qiniu/java-sdk/tags)


**环境准备**

**应用接入**

- [获取Access Key 和 Secret Key](#acc-appkey)
- [签名认证](#acc-auth)

**云存储接口**

- [新建资源表](#rs-NewService)
- [获得上传授权](#rs-PutAuth)
- [上传文件](#rs-PutFile)
- [获取已上传文件信息](#rs-Stat)
- [下载文件](#rs-Get)
- [发布公开资源](#rs-Publish)
- [取消资源发布](#rs-Unpublish)
- [删除已上传的文件](#rs-Delete)
- [删除整张资源表](#rs-Drop)

## 环境准备

需要在Eclipse工程中，导入七牛云存储的 SDK。目前，七牛云存储的 SDK 依赖于一下第三方包：

- commons-codec-1.6.jar
- commons-logging-1.1.1.jar
- fluent-hc-4.2.jar
- httpclient-4.2.jar
- httpclient-cache-4.2.jar
- httpcore-4.2.1.jar
- httpcore-4.2.jar
- httpcore-ab-4.2.1.jar
- httpcore-nio-4.2.1.jar
- httpmime-4.2.jar

七牛云存储 SDK 中的 qbox/lib 目录默认已经包含这些第三方包，您直接使用就行。但是，也有可能因为你本地编译环境问题，需要重新载入这些包。

## 应用接入

<a name="acc-appkey"></a>

### 1. 获取Access Key 和 Secret Key

要接入七牛云存储，您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得：

1. [开通七牛开发者帐号](https://dev.qiniutek.com/signup)
2. [登录七牛开发者自助平台，查看 Access Key 和 Secret Key](https://dev.qiniutek.com/account/keys) 。

<a name="acc-auth"></a>

### 2. 签名认证

首先，到 [https://github.com/qiniu/java-sdk/tags](https://github.com/qiniu/java-sdk/tags) 下载SDK源码。

然后，将SDK导入到您的 Eclipse 项目中，并编辑当前工程目录下QBox.config文件，确保其包含您从七牛开发者平台所获取的 [Access Key 和 Secret Key](#acc-appkey)：

    ACCESS_KEY	: "<Please apply your access key>";
	SECRET_KEY	: "<Dont send your secret key to anyone>";



在完成 Access Key 和 Secret Key 配置后，为了正常使用该 SDK 提供的功能需要根据配置文件进行初始化，您还需要使用你获得的 Access Key 和 Secret Key 向七牛云存储服务器发出认证请求：

	Config.init("QBox.config"); // 此处通过传入配置文件完成初始化，您可以将配置文件存放任何位置，初始化时候要注意传入路径的正确性。
	DigestAuthClient conn = new DigestAuthClient();

请求成功后得到的 conn 即可用于您正常使用七牛云存储的一系列功能，接下来将一一介绍。

## 云存储接口

<a name="rs-NewService"></a>

### 1. 新建资源表

新建资源表的意义在于，您可以将所有上传的资源分布式加密存储在七牛云存储服务端后还能保持相应的完整映射索引。

    // 通过传入配置文件，完成初始化工作
    Config.init("QBox.config") ;

    // 首先定义资源表名
    String bucketName = "bucketName";
    
    // 然后获得签名认证
    DigestAuthClient conn = new DigestAuthClient();
    
    // 签名认证完成后，即可使用该认证来新建资源表
    RSService rs = new RSService(conn, bucketName);


<a name="rs-PutAuth"></a>

### 2. 获得上传授权

建完资源表，在上传文件并和该资源表建立关联之前，还需要取得上传授权。所谓上传授权，就是获得一个可匿名直传的且离客户端应用程序最近的一个云存储节点的临时有效URL。

要取得上传授权，只需调用已经实例化好的资源表对象的 putAuth() 方法。实例代码如下：

    // 获得上传授权之前需要通过签名认证的方式来实例化一个资源表对象
    Config.init("QBox.config") ;
    String bucketName = "bucketName";
    DigestAuthClient conn = new DigestAuthClient();
    RSService rs = new RSService(conn, bucketName);
    
    // 然后，调用该资源表对象的 putAuth() 方法来获得上传授权
    PutAuthRet putAuthRet = rs.putAuth();


如果请求成功，putAuthRet 会包含 url 和 expires_in 两个字段。url 字段对应的值为匿名上传的临时URL，expires_in 对应的值则是该临时URL的有效期。

<a name="rs-PutFile"></a>

### 3. 上传文件

七牛云存储上传文件的方式分为直传和断点续传两种。

##### 1.文件上传
Java SDK 目前支持从本地上传某个文件，用户可以根据需要选择是直传还是断点续传。  
要以直传的方式上传文件，用户只需获得相关认证就可以上传文件了。  
如果上传成功，得到的 putFileRet 会包含对应的 hash 值，否则返回对应的错误。

示例代码如下：
   
    // 获得认证
    Config.init("QBox.config") ;
    String bucketName = "bucketName";
    AuthPolicy policy = new AuthPolicy(bucketName, 3600);
    String token = policy.makeAuthTokenString();
    UpTokenClient upTokenClient = new UpTokenClient(token);
    UpService upClient = new UpService(upTokenClient);

    // 上传文件
    String key = "README.md";
    String path = RSDemo.class.getClassLoader().getResource("").getPath();		
    RandomAccessFile f = new RandomAccessFile(path + key, "r");
    long fsize = f.length();
    long blockCount = UpService.blockCount(fsize);
    String[] checksums = new String[(int)blockCount];
    BlockProgress[] progresses = new BlockProgress[(int)blockCount];
    // 由于此处的 Notifer 未提供任何的"持久化"功能，所以此处相当于文件直传
    Notifier notif = new Notifier();

    PutFileRet putFileRet = RSClient.resumablePutFile(upClient, 
		checksums, progresses, 
		(ProgressNotifier)notif, (BlockProgressNotifier)notif, 
		bucketName, key, "", f, fsize, "CustomMeta", "");

	
##### 2. 断点续上传

客户端在上传文件的时候也可以根据需求选择断点续上传的方式，此处所说的断点上传是指用户在某次上传过程中出现错误，再重新上传的时候只需要从上次上传失败处上传即可。用户可以根据通过修改配置文件改变上传块（Config文件中的PUT_CHUNK_SIZE对应的值）的大小来适应用户所处的网络环境。为了提供一个简单的接口，我们将上传进度持久化的相关工作内置在了 SDK 中，当然用户也可以根据需要自己实现文件上传进度的持久化工作。

如果上传成功，得到的 putFileRet 会包含对应的 hash 值，否则返回对应的错误。

示例代码如下：  

    Config.init("/home/wangjinlei/QBox.config") ;
	String bucketName = "bucketName";
	String key = "RSDemo.class";
				
	AuthPolicy policy = new AuthPolicy("bucketName", 3600);
	String token = policy.makeAuthTokenString();
	UpTokenClient upTokenClient = new UpTokenClient(token);
	UpService upClient = new UpService(upTokenClient);
	PutFileRet  putFileRet = null ;
	
	putFileRet = RSClient.resumablePutFile(upClient,
				bucketName, key, "", inputFile, "CustomMeta", "", "");



<a name="rs-Stat"></a>

### 4. 获取已上传文件信息

您可以调用资源表对象的 Stat() 方法并传入一个 Key（类似ID）来获取指定文件的相关信息。

	// 实例化一个资源表对象，并获得一个相应的授权认证
{'fraction_non_alphanumeric': 0.13766611295681064, 'fraction_numerical': 0.008928571428571428, 'mean_word_length': 4.568208092485549, 'pattern_counts': {'":': 0, '<': 31, '<?xml version=': 0, '>': 31, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3546802', 'n_tokens_mistral': 5338, 'n_tokens_neox': 5792, 'n_words': 644}