阿里云 OSS开发使用文档

阿里云 OSS（Object Storage Service）提供基于网络的数据存取服务。使用 OSS，可以通过网络随时存储和调用包括文本、图片、音频和视频等在内的各种结构化或非结构化数据文件。

阿里云 OSS 将数据文件以对象（object）的形式上传到存储空间（bucket）中。通过OSS可以创建一个或者多个存储空间，然后向每个存储空间中添加一个或多个文件。也可以通过获取已上传文件的地址进行文件的分享和下载。还可以通过修改存储空间或文件的属性或元信息来设置相应的访问权限。本文档主要内容如下：

基本概念
开通阿里云 OSS服务
使用Java SDK操作OSS
其他

基本概念

存储空间（Bucket）
对象/文件（Object）
Region（地域）
Endpoint（访问域名）
AccessKey（访问密钥）

存储空间（Bucket）

存储空间是用于存储对象（Object）的容器，所有的对象都必须隶属于某个存储空间。可以设置和修改存储空间属性用来控制地域、访问权限、生命周期等，这些属性设置直接作用于该存储空间内所有对象，因此可以通过灵活创建不同的存储空间来完成不同的管理功能。

同一个存储空间的内部是扁平的，没有文件系统的目录等概念，所有的对象都直接隶属于其对应的存储空间。
每个用户可以拥有多个存储空间。
存储空间的名称在 OSS 范围内必须是全局唯一的，一旦创建之后无法修改名称。
存储空间内部的对象数目没有限制。

存储空间的命名规范如下：

只能包括小写字母、数字和短横线（-）。
必须以小写字母或者数字开头和结尾。
长度必须在3-63字节之间。

对象/文件（Object）

对象是 OSS 存储数据的基本单元，也被称为 OSS 的文件。对象由元信息（Object Meta），用户数据（Data）和文件名（Key）组成。对象由存储空间内部唯一的 Key 来标识。对象元信息是一个键值对，表示了对象的一些属性，比如最后修改时间、大小等信息，同时用户也可以在元信息中存储一些自定义的信息。

根据不同的上传方式，对象的大小限制是不一样的。分片上传最大支持 48.8TB 的对象大小，其他的上传方式最大支持 5GB。

对象的生命周期是从上传成功到被删除为止。在整个生命周期内，对象信息不可变更。重复上传同名的对象会覆盖之前的对象，因此，OSS 不支持修改文件的部分内容等操作。

OSS 提供了追加上传功能，用户可以使用该功能不断地在Object尾部追加写入数据。

对象的命名规范如下：

使用UTF-8编码。
长度必须在1-1023字节之间。
不能以“/”或者“\”字符开头。

注意：对象名称需要区分大小写。如无特殊说明，本文档中的对象、文件称谓等同于 Object。

Region（地域）

Region 表示 OSS 的数据中心所在的地域，物理位置。用户可以根据费用、请求来源等综合选择数据存储的 Region。一般来说，距离用户更近的 Region 访问速度更快。详细请查看[ OSS 已经开通的 Region](https://help.aliyun.com/document_detail/31837.html?spm=5176.doc31827.2.4.LSbk6U)。 Region是在创建 Bucket 的时候指定的，一旦指定之后就不允许更改，该 Bucket 下所有的 Object 都存储在对应的数据中心，目前不支持 Object 级别的 Region 设置。

Endpoint（访问域名）

Endpoint 表示 OSS 对外服务的访问域名。OSS 以 HTTP RESTful API 的形式对外提供服务，当访问不同的 Region 的时候，需要不同的域名。通过内网和外网访问同一个 Region 所需要的 Endpoint 也是不同的。例如杭州 Region 的外网 Endpoint 是 oss-cn-hangzhou.aliyuncs.com，内网 Endpoint 是 oss-cn-hangzhou-internal.aliyuncs.com。具体的内容请参见[ 各个 Region 对应的 Endpoint](https://help.aliyun.com/document_detail/31834.html?spm=5176.doc31827.2.5.UtF5cG)。

AccessKey（访问密钥）

AccessKey，简称 AK，指的是访问身份验证中用到的 AccessKeyId 和AccessKeySecret。OSS 通过使用 AccessKeyId 和 AccessKeySecret 对称加密的方法来验证某个请求的发送者身份。AccessKeyId 用于标识用户，AccessKeySecret 是用户用于加密签名字符串和 OSS 用来验证签名字符串的密钥，其中 AccessKeySecret 必须保密。对于 OSS 来说，AccessKey 的来源有：

Bucket 的拥有者申请的 AccessKey。
被 Bucket 的拥有者通过 RAM 授权给第三方请求者的 AccessKey。
被 Bucket 的拥有者通过 STS 授权给第三方请求者的 AccessKey。

开通阿里云 OSS

开通 OSS 服务后才能使用 OSS 提供的各种功能。具体请参考阿里云OSS在线文档的以下部分：
1. 开通OSS服务
3. 创建存储空间
3. 上传文件
4. 分享文件
5. 删除文件

使用Java SDK操作OSS

要开始使用Java SDK操作OSS，请按照如下步骤进行：

步骤 1：创建阿里云账号

为了访问阿里云OSS服务，您需要有一个阿里云账号。如果没有，请访问阿里云官方网站，进行注册。

步骤 2：获取阿里云访问密钥

为了使用阿里云OSS服务 Java SDK，还必须申请阿里云的访问密钥。如果没有，请登陆登录阿里云密钥管理页面，创建一对新访问密钥，且保证它处于“启用”状态。该密钥对需要保管好，不能对外泄露。

步骤3：安装 OSS服务 Java SDK

在Java 开发环境中，需要安装 OSS Java SDK。目前，有两种方式安装OSS的 Java SDK：

方式一：在Maven项目中加入依赖项（推荐方式）

在Maven工程中使用OSS Java SDK只需在pom.xml中加入相应依赖即可。以2.5.0版本为例，在dependencies标签内加入如下内容：

<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>2.5.0</version>
</dependency>

方式二：在Eclipse项目中导入JAR包

以2.5.0版本为例，步骤如下：

下载Java SDK开发包版本号 aliyun_java_sdk_20170222.zip；
解压该开发包；
将解压后文件夹中的文件： aliyun-sdk-oss-<versionId>.jar 以及lib文件夹下的所有文件拷贝到您的项目中；
在Eclipse中选择您的工程，右击 -> Properties -> Java Build Path -> Add JARs；
选中在第三步拷贝的所有JAR文件，将其加入；

经过以上几步，您就可以在Eclipse项目中使用OSS Java SDK。

步骤4：使用 OSS服务 Java SDK

参考代码功能如下：

构建OSS服务客户端
判断bucket是否存在及查看bucket信息
把字符串存入OSS及下载
查看bucket中的object
下载object到本地文件
删除object

import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.File;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.util.List;

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSSClient;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.BucketInfo;
import com.aliyun.oss.model.GetObjectRequest;
import com.aliyun.oss.model.ListObjectsRequest;
import com.aliyun.oss.model.OSSObject;
import com.aliyun.oss.model.OSSObjectSummary;
import com.aliyun.oss.model.ObjectListing;


public class TestAliOSS {

    // endpoint 访问OSS的域名
    private static String endPoint = "https://oss-cn-beijing.aliyuncs.com";

    // accessKeyId和accessKeySecret OSS的访问密钥
    private static String accessKeyId = "*************";
    private static String accessKeySecret = "*************";

    // Bucket 用来管理所存储Object的存储空间
    private static String bucketName = "*************";

    // Object OSS存储数据的基本单元，称为OSS的对象或OSS的文件
    private static String testKey = "my-test-key";


    public static void main(String[] args) {
        // 生成OSSClient
        OSSClient ossClient = new OSSClient(endPoint, accessKeyId, accessKeySecret);

        try {
            // 判断Bucket是否存在
            if (ossClient.doesBucketExist(bucketName)) {
                System.out.println("您已经创建Bucket：" + bucketName + "。");
            } else {
                System.out.println("您的Bucket不存在，创建Bucket：" + bucketName + "。");
                // 创建Bucket
                ossClient.createBucket(bucketName);
            }

            // 查看Bucket信息
            BucketInfo info = ossClient.getBucketInfo(bucketName);
            System.out.println("Bucket " + bucketName + "的信息如下：");
            System.out.println("\t数据中心：" + info.getBucket().getLocation());
            System.out.println("\t创建时间：" + info.getBucket().getCreationDate());
            System.out.println("\t用户标志：" + info.getBucket().getOwner());


            // 把字符串存入OSS，Object的名称为testKey
            InputStream is = new ByteArrayInputStream("Test OSS putObject".getBytes());
            ossClient.putObject(bucketName, testKey, is);
            System.out.println("Object：" + testKey + "存入OSS成功。");

            // 下载Object
            OSSObject ossObject = ossClient.getObject(bucketName, testKey);
            InputStream inputStream = ossObject.getObjectContent();
            StringBuilder objectContent = new StringBuilder();
            BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
            while (true) {
                String line = reader.readLine();
                if (line == null)
                    break;
                objectContent.append(line);
            }
            inputStream.close();
            System.out.println("Object：" + testKey + "的内容是：" + objectContent);


            // 上传文件到OSS，Object的名称为fileKey
            String fileKey = "my-file-key";
            //运行时注意修改File路径及文件名
            ossClient.putObject(bucketName, fileKey, new File("F:\\mvn\\Readme.txt"));
            System.out.println("Object：" + fileKey + "存入OSS成功。");


            // 查看Bucket中的Object
            ObjectListing objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).
                    withMaxKeys(300));
            List<OSSObjectSummary> objectSummary = objectListing.getObjectSummaries();
            System.out.println("您有以下Object：");
            for (OSSObjectSummary object : objectSummary) {
                System.out.println("\t" + object.getKey());
            }

            // 下载object到本地文件
            ossClient.getObject(new GetObjectRequest(bucketName, "全球经济与市场展望.pdf"), new File("F:\\mvn\\test.pdf"));

            // 删除Object
            ossClient.deleteObject(bucketName, testKey);
            System.out.println("删除Object：" + testKey + "成功。");
            ossClient.deleteObject(bucketName, fileKey);
            System.out.println("删除Object：" + fileKey + "成功。");

        } catch (OSSException oe) {
            oe.printStackTrace();
        } catch (ClientException ce) {
            ce.printStackTrace();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            ossClient.shutdown();
        }
    }

}