# OSS Example
## 项目说明
如果您的应用是 Spring Cloud 应用，且需要使用阿里云的 OSS 服务进行云端的文件存储，例如电商业务中常见的商品图片存储，那么您可以使用 OSS starter 完成 Spring Cloud 应用的对象存储。
阿里云对象存储服务（Object Storage Service，简称 OSS），是阿里云提供的海量、安全、低成本、高可靠的云存储服务。您可以在任何应用、任何时间、任何地点存储和访问任意类型的数据。更多 OSS 相关的信息，请参考 [OSS官网](https://www.aliyun.com/product/oss)。
## 示例
### 接入 OSS
在启动示例进行演示之前，我们先了解一下如何接入 OSS。
**注意：本节只是为了便于您理解接入方式，本示例代码中已经完成接入工作，您只需修改 accessKey、secretKey、endpoint 即可。**
1. 修改 pom.xml 文件，引入 alicloud-oss starter。
org.springframework.cloud
spring-cloud-starter-alicloud-oss
2. 在配置文件中配置 OSS 服务对应的 accessKey、secretKey 和 endpoint。
// application.properties
spring.cloud.alicloud.access-key=your-ak
spring.cloud.alicloud.secret-key=your-sk
spring.cloud.alicloud.oss.endpoint=***
以阿里云 accessKey、secretKey 为例，获取方式如下。
i. 在阿里云控制台界面，单击右上角头像，选择 accesskeys，或者直接登录[用户信息管理界面](https://usercenter.console.aliyun.com/)：
ii. 获取 accessKey、secretKey：
**注意：**如果您使用了阿里云 [STS服务](https://help.aliyun.com/document_detail/28756.html) 进行短期访问权限管理，则除了 accessKey、secretKey、endpoint 以外，还需配置 securityToken。
3. 注入 OSSClient 并进行文件上传下载等操作。
@Service
public class YourService {
@Autowired
private OSSClient ossClient;
public void saveFile() {
// download file to local
ossClient.getObject(new GetObjectRequest(bucketName, objectName), new File("pathOfYourLocalFile"));
}
}
**说明：**直接注入OSSClient 方式通常用于大量文件对象操作的场景。如果仅仅是需要读取文件对象内容，OSS Starter 也支持以 Resource 方式读取文件，详情请参考[下文](#1)。
### 启动应用
1. 在应用的 /src/main/resources/application.properties 中添加基本配置信息和 OSS 配置。
spring.application.name=oss-example
server.port=18084
spring.cloud.alicloud.access-key=your-ak
spring.cloud.alicloud.secret-key=your-sk
spring.cloud.alicloud.oss.endpoint=***
2. 通过 IDE 直接启动或者编译打包后启动应用。
- IDE直接启动：找到主类 `OSSApplication`，执行 main 方法启动应用。
- 打包编译后启动：
1. 执行 `mvn clean package` 将工程编译打包；
2. 执行 `java -jar oss-example.jar`启动应用。
应用启动后会自动在 OSS 上创建一个名为 `spring-cloud-alibaba-test` 的 Bucket。
### 上传或下载文件
#### 上传文件
使用 curl 调用上传接口 upload。该接口会上传 classpath 下的的 oss-test.json 文件。文件内容是一段 json:
curl http://localhost:18084/upload
显示结果：
// 如果配置正确，则输出
upload success
// 如果上传的过程中发生异常，则会输出 upload fail: fail reason。比如accessKeyId配置错误的时候，fail reason内容如下
upload fail: The OSS Access Key Id you provided does not exist in our records. [ErrorCode]: InvalidAccessKeyId [RequestId]: RequestId [HostId]: xxx.oss-cn-beijing.aliyuncs.com [ResponseError]: InvalidAccessKeyId The OSS Access Key Id you provided does not exist in our records. RequestId xxx.oss-cn-beijing.aliyuncs.com xxx-accessKeyId
#### 下载文件
使用 curl 调用下载接口 download。该接口会下载刚才用 upload 接口上传的 oss-test.json 文件，并打印文件内容到结果中:
curl http://localhost:18084/download
显示结果：
// 如果配置正确，则输出
download success, content: { "name": "oss-test" }
// 下载的过程中如果发生异常，则会输出download fail: fail reason。比如accessKeyId配置错误，则fail reason内容如下
download fail: The OSS Access Key Id you provided does not exist in our records. [ErrorCode]: InvalidAccessKeyId [RequestId]: RequestId [HostId]: xxx.oss-cn-beijing.aliyuncs.com [ResponseError]: InvalidAccessKeyId The OSS Access Key Id you provided does not exist in our records. RequestId sxxx.oss-cn-beijing.aliyuncs.com xxx-accessKeyId
### 在 OSS 上验证结果
完成文件上传或者下载操作后，可以登录 OSS 控制台进行验证。
1. 登陆[OSS控制台](https://oss.console.aliyun.com/)，可以看到左侧 Bucket 列表新增一个名字为`spring-cloud-alibaba-test`的 Bucket。
2. 单击`spring-cloud-alibaba-test` Bucket，选择 `文件管理` 页签，发现上传的 oss-test 文件。上传的 objectName 为`oss-test.json`。目录和文件以'/'符号分割。
## 查看 Endpoint 信息
Spring Boot 应用支持通过 Endpoint 来暴露相关信息，OSS Starter 也支持这一点。
**前提条件：**
在 maven 中添加 `spring-boot-starter-actuator`依赖，并在配置中允许 Endpoints 的访问。
- Spring Boot1.x 中添加配置 `management.security.enabled=false`
- Spring Boot2.x 中添加配置 `management.endpoints.web.exposure.include=*`
Spring Boot1.x 可以通过访问 http://127.0.0.1:18084/oss 来查看 OSS Endpoint 的信息。
Spring Boot2.x 可以通过访问 http://127.0.0.1:18084/actuator/oss 来访问。
Endpoint 内部会显示所有的 OSSClient 配置信息，以及该 OSSClient 对应的 Bucket 列表。
以 Resource 的形式读取文件
OSS Starter 支持以 Resource 的形式得到文件对象。如果只需读取少量文件，您可以使用这种方式。
**使用方法：**
只需配置 OSS 协议对应的 Resource 即可：
@Value("oss://spring-cloud-alibaba/oss-test")
private Resource file;
// 文件内容的读取
StreamUtils.copyToString(file.getInputStream(), Charset.forName(CharEncoding.UTF_8))
## 关闭 OSSClient 服务
如果您不再需要 OSS 服务，您也无需手动关闭 OSSClient。在 ApplicationContext close 的时候，OSS Starter 会在 `OSSApplicationListener` 中调用所有 OSSClient 的 shutdown 方法。
如果您对 Spring Cloud OSS Starter 有任何建议或想法，欢迎提交 issue 中或者通过其他社区渠道向我们反馈。