spring-cloud-alibaba/spring-cloud-alibaba-examples/oss-example

OSS Example

Introduction

If your applications are Spring Cloud applications and you need to use Alibaba Cloud's OSS service for file storage (for example, storing commodity image for your e-commerce business), you can use OSS starter. This topic provides an example to illustrate how to use OSS starter to implement object storage for Spring Cloud applications.

Alibaba Cloud Object Storage Service (OSS) is an encrypted, secure, cost-effective, and easy-to-use object storage service that enables you to store, back up, and archive large amounts of data in the cloud.

Demo

Connect to OSS

Before we start the demo, let's learn how to connect OSS to a Spring Cloud application. Note: This section is to show you how to connect to oss. The actual configurations have been completed in the following example, and you only need to specify your accessKey, secretKey and endpoint.

1. Add dependency spring-cloud-starter-alicloud-oss in the pom.xml file in your Spring Cloud project.

    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-alicloud-oss</artifactId>
    </dependency>
   

2. Configure accessKeyId, secretAccessKey and region in application.properties.

    // application.properties
    spring.cloud.alicloud.access-key=your-ak
    spring.cloud.alicloud.secret-key=your-sk
    spring.cloud.alicloud.oss.endpoint=***
   

   To get accessKey, secretKey, follow these steps:

   1. On the Alibaba Cloud console, click your avatar on the upper-right corner and click accesskeys. Or visit User Management page directly：

      

   2. Get your accessKey、secretKey：

      

   Note: If you are using STS, you should configure securityToken in addition to accessKey, secretKey, and endpoint.

3. Inject OSSClient and use it to upload files to the OSS server and download a file from OSS server.

    @Service
    public class YourService {
    	@Autowired
    	private OSSClient ossClient;
   
    	public void saveFile() {
    		// download file to local
    		ossClient.getObject(new GetObjectRequest(bucketName, objectName), new File("pathOfYourLocalFile"));
    	}
    }
   

Note: Direct injection into the OSSClient mode is typically used for scenarios where you need to handle a large number of file objects. If you only need to read the contents of the file object, OSS Starter also supports reading the file in Resource mode.

Start Application

1. Add necessary configurations to file /src/main/resources/application.properties.

    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. Start the application in IDE or by building a fatjar.

   • Start in IDE: Find main class OSSApplication, and execute the main method.
   • Build a fatjar：
     1. Execute command mvn clean package to build a fatjar.
     2. Run command java -jar oss-example.jar to start the application.

After startup, a bucket called 'spring-cloud-alibaba-test' is automatically created in OSS.

Upload or download files

Upload files

Run curl command to upload files. It will upload file 'oss-test.json' in the classpath directory. The content of this file is JSON string:

curl http://localhost:18084/upload

Results：

// If configurations are correct, the output will be as follows
upload success
// If an error occurs during uploading, the output will be 'upload fail: fail reason'. For example, if accessKeyId is wrong，the output will be
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

Download files

Use curl command to download files. It will download the oss-test.json file that you uploaded just now and print in result:

curl http://localhost:18084/download

Results：

// If configurations are correct, the output will be as follows
download success, content: { "name": "oss-tes" }
// If an error occurs during downloading, the output will be 'download fail: fail reason'. For example, if accessKeyId is wrong，fail reason will be as follows
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

Verify results on OSS

You can verify results on the OSS console when you finish uploading or downloading files.

1. Log on to the OSS console，and you will find a bucket named spring-cloud-alibaba-test.

   

2. Click the spring-cloud-alibaba-test bucket, select the Files tab, and you will find the oss-test.json file. The objectName of the file is 'oss-test.json'. File directory and file is separated by '/'.

   

Endpoint

OSS starter also supports the implmentation of Spring Boot acutator endpoints.

Prerequisite:

Add denpendency spring-boot-starter-actuator to your pom.xml file, and configure your endpoint security stategy.

• Spring Boot1.x: Add configuration management.security.enabled=false
• Spring Boot2.x: Add configuration management.endpoints.web.exposure.include=*

To view the endpoint information, visit the following URLs:

Spring Boot1.x: OSS Endpoint URL is http://127.0.0.1:18084/oss.

Spring Boot2.x: OSS Endpoint URL is http://127.0.0.1:18084/acutator/oss.

Endpoint will show the configurations and the list of buckets of all OSSClients.

Read file using resource mode

OSS Starter supports getting file objects by Spring Resource. Simply configure OSS protocol of the resource：

  @Value("oss://spring-cloud-alibaba/oss-test")
  private Resource file;

  // read file content
  StreamUtils.copyToString(file.getInputStream(), Charset.forName(CharEncoding.UTF_8))

Stop OSSClient service

You do not need to manually shut down OSSClient. OSS Starter calls all OSSClient shutdown methods in the OSSApplicationListener during ApplicationContext close.

If you have any feedback or suggestions for Spring Cloud OSS Starter, please don't hesitate to tell us by submitting github issues or via other community channels.