阿里云 OSS API 学习总结

1. 资源术语

• 存储空间（Bucket): 存储空间是用户用于存储对象（Object）的容器，所有的对象都必须隶属于某个存储空间。
• 对象/文件（Object）: 对象是 OSS 存储数据的基本单元，也被称为 OSS 的文件。对象由元信息（Object Meta），用户数据（Data）和文件名（Key）组成。对象由存储空间内部唯一的 Key 来标识。对象元信息是一组键值对，表示了对象的一些属性，比如最后修改时间、大小等信息，同时用户也可以在元信息中存储一些自定义的信息。
• Region（地域）: Region 表示 OSS 的数据中心所在物理位置。用户可以根据费用、请求来源等选择合适的地域创建 Bucket。一般来说，距离用户更近的 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。
• AccessKey（访问密钥）: AccessKey（简称 AK）指的是访问身份验证中用到的 AccessKeyId 和 AccessKeySecret。OSS 通过使用 AccessKeyId 和 AccessKeySecret 对称加密的方法来验证某个请求的发送者身份。AccessKeyId用于标识用户；AccessKeySecret 是用户用于加密签名字符串和 OSS 用来验证签名字符串的密钥，必须保密。

2. 访问域名使用规则

<Schema>://<Bucket>.<外网Endpoint>/<Object> 

<Schema>://<Bucket>.<内网Endpoint>/<Object> 

3. 文件操作

3.1 下载文件

// Endpoint以杭州为例，其它Region请按实际情况填写。
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录 https://ram.console.aliyun.com 创建RAM账号。
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";
String bucketName = "<yourBucketName>";
String objectName = "<yourObjectName>";

// 创建OSSClient实例。
OSSClient ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// 下载OSS文件到本地文件。如果指定的本地文件存在会覆盖，不存在则新建。
ossClient.getObject(new GetObjectRequest(bucketName, objectName), new File("<yourLocalFile>"));

// 关闭OSSClient。
ossClient.shutdown();   

3.2 上传文件

// Endpoint以杭州为例，其它Region请按实际情况填写。
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录 https://ram.console.aliyun.com 创建RAM账号。
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";

// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId,accessKeySecret);

// 上传Byte数组。
byte[] content = "Hello OSS".getBytes();
ossClient.putObject("<yourBucketName>", "<yourObjectName>", new ByteArrayInputStream(content));

// 关闭OSSClient。
ossClient.shutdown();

3.3 列举文件

ObjectListing listObjects(String bucketName)：列举存储空间下的文件。最多列举100个文件。
ObjectListing listObjects(String bucketName, String prefix)： 列举存储空间下指定前缀的文件。最多列举100个文件。
ObjectListing listObjects(ListObjectsRequest listObjectsRequest)：提供多种过滤功能，实现灵活的查询功能。

// Endpoint以杭州为例，其它Region请按实际情况填写。
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录 https://ram.console.aliyun.com 创建RAM账号。
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";
String bucketName = "<yourBucketName>";

// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

final int maxKeys = 200;
String nextMarker = null;
ObjectListing objectListing;

do {
    objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).withMarker(nextMarker).withMaxKeys(maxKeys));

    List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
    for (OSSObjectSummary s : sums) {
        System.out.println("\t" + s.getKey());
    }

    nextMarker = objectListing.getNextMarker();

} while (objectListing.isTruncated());

// 关闭OSSClient。
ossClient.shutdown();

4. 公司使用OSS 小结

endPoint 使用内网

endpoint: oss-cn-beijing-internal.aliyuncs.com

列举文件

@Service
@ActuatorAnalysis("storage.oss-storage")
public class OssResourceStorage implements ResourceStorage {

    private static final int MAX_KEYS = 100;

    @Autowired
    protected OssConfiguration ossConfig;

    @Autowired
    protected FenbiOssClient ossClient;

    @Override
    public List<String> listResources(String prefix) throws IOException, TimeoutException {
        ObjectListing listing = ossClient.listObjects(ossConfig.getEndpoint(), ossConfig.getBucketName(), prefix, ossConfig.getTimeout());

        //list中会包括目录，目录在oss会被当做一个"文件"来，其size为0
        return listing.getObjectSummaries().stream().filter(summary -> summary.getSize() > 0).map(summary -> summary.getKey()).collect(Collectors.toList());
    }

    @Override
    public List<String> listPagingResources(String prefix) throws IOException, TimeoutException {
        List<String> resourceList = new ArrayList<>();
        String nextMarker = null;
        ObjectListing objectListing;
        do {
            objectListing = ossClient.listPagingObjects(ossConfig.getEndpoint(), ossConfig.getBucketName(), prefix, nextMarker, MAX_KEYS, ossConfig.getTimeout());
            resourceList.addAll(objectListing.getObjectSummaries().stream().filter(summary -> summary.getSize() > 0).map(summary -> summary.getKey()).collect(Collectors.toList()));
            //下一页的开始标记位置
            nextMarker = objectListing.getNextMarker();
        } while (objectListing.isTruncated());

        return resourceList;
    }
}

下载文件

@Slf4j
@Service
public class OssService {

    @Value("${oss.endpoint}")
    private String endPoint;

    @Value("${oss.bucketName}")
    private String bucketName;

    @Value("${oss.accessKeyId}")
    private String accessKeyId;

    @Value("${oss.accessKeySecret}")
    private String accessKeySecret;

    public static final long DEFAULT_OSS_TIMEOUT = 10000;

    @AllArgsConstructor
    @Data
    public static class ResourceData {
        private String resourceId;
        private byte[] data;
    }

    public void uploadKeynoteResources(List<String> resourceUrls, List<byte[]> resources) {
        OSSClient ossClient = new OSSClient(endPoint, accessKeyId, accessKeySecret);
        try {
            for (int i = 0; i < resourceUrls.size(); i++) {
                ossClient.putObject(bucketName, resourceUrls.get(i), new ByteArrayInputStream(resources.get(i)));
            }
        } catch (OSSException | ClientException e) {
            throw new RuntimeException("upload resource to oss failed.");
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }

    public ResourceData getOssResource(FenbiOssClient ossClient, FenbiOssResourceId fenbiOssResourceId) {
        try {
            OSSObject ossObject = ossClient.get(fenbiOssResourceId, DEFAULT_OSS_TIMEOUT);
            byte[] bytes = IOUtils.toByteArray(ossObject.getObjectContent());
            if (bytes.length != 0) {
                ossObject.close();
                return new ResourceData(fenbiOssResourceId.getResourceId(), bytes);
            } else {
                log.error("Empty resource: resourceId={}", fenbiOssResourceId);
            }
        } catch (Exception e) {
            log.error("GET resource error, resourceId=" + fenbiOssResourceId, e);
        }
        return null;
    }
}