edit-icon download-icon

Installation

Last Updated: May 04, 2018

SDK Installation

Requirements

  • You must have activated Alibaba Cloud OSS. If you do not know about Alibaba Cloud OSS, log on to the OSS Product Homepage. For more information, see Product Overview.

  • You must have created an AccessKeyID and an AccessKeySecret. Since the Alibaba Cloud account AccessKey gives you permission to access all APIs, we recommend that you follow the Alibaba Cloud Security Best Practices. If you deploy the service on the server, you can use an RAM sub-account or STS for API access or daily O&M management and control. If you deploy the service on the client, we recommend you use STS for API access. For more information, see Access control.

Environment requirements

The OSS BrowserJS-SDK is built on the Node.js environment. It generates codes that apply to browsers through Browserify and Babel.

However, because of the special natures of the browser environment, some features cannot be used:

  • Stream upload: The chunked encoding cannot be set in browsers. The multipart upload can be used instead.
  • Operations on local files: You cannot directly operate on local file systems in the browser. You can download the file using a signed URL.
  • Bucket-related operations (listBuckets/BucketACL/BucketLogging). Since OSS does not support bucket-related cross-origin requests currently, you can perform bucket-related operations in the console.

Usage

The OSS BrowserJS-SDK supports both synchronous and asynchronous usages.

  • Synchronous mode: Similar to coroutine. It is based on Generator Function and uses Co and yield.
  • Asynchronous mode: Similar to callback. The API returns Promise. The .then() method is used to process the returned result and the .catch() method is used to process errors.

In the synchronous mode, the new OSS() method is used to create a client. In the asynchronous mode, the new OSS.Wrapper() method is used to create a client.

Here are the examples of uploading a file and then downloading the file immediately in the two modes:

Synchronous mode

  1. // var client = new OSS(...);
  2. var co = require('co');
  3. co(function* () {
  4. var r1 = yield client.put('object', '/tmp/file');
  5. console.log('put success: %j', r1);
  6. var r2 = yield client.get('object');
  7. console.log('get success: %j', r2);
  8. }).catch(function (err) {
  9. console.error('error: %j', err);
  10. });

Asynchronous mode

  1. // var client = new OSS.Wrapper(...);
  2. client.put('object', '/tmp/file').then(function (r1) {
  3. console.log('put success: %j', r1);
  4. return client.get('object');
  5. }).then(function (r2) {
  6. console.log('get success: %j', r2);
  7. }).catch(function (err) {
  8. console.error('error: %j', err);
  9. });

Installation

Usage in browsers

Supported browsers:

  • IE (>=10) and Edge
  • Mainstream Chrome/Firefox/Safari versions
  • Mainstream Android/iOS/WindowsPhone versions
Browser introduction:

Note: Some browsers do not support promise, so a promise compatibility library must be introduced.
For example, promise-polyfill must be introduced for IE10 and IE11.

  1. <!-- Introduce online resources -->
  2. <script src="http://gosspublic.alicdn.com/aliyun-oss-sdk-x.x.x.min.js"></script>
  1. <!-- Introduce local resources -->
  2. <script src="./aliyun-oss-sdk-x.x.x.min.js"></script>

Note:

  • x.x.x represents the version number. For more information about the specific version, see https://github.com/ali-sdk/ali-oss.
  • The introduction of online resources depends on the stability of the CDN server. Users are recommended to introduce resources offline, that is, through local resources or self-built.

You can use the OSS.Wrapper object in the code:

  1. <script type="text/javascript">
  2. var client = new OSS.Wrapper({
  3. region: '<oss region>',
  4. //Since the Alibaba Cloud account AccessKey gives you permission to access all APIs, we recommend that you access an API using STS by following the Alibaba Cloud Security Best Practices.
  5. accessKeyId: '<Your accessKeyId(STS)>',
  6. accessKeySecret: '<Your accessKeySecret(STS)>',
  7. stsToken: '<Your securityToken(STS)>',
  8. bucket: '<Your bucket name>'
  9. });
  10. </script>
Use npm to install the SDK:
  1. npm install ali-oss

After the installation is completed, you can reference it using “import” or “require”.

  1. var OSS = require('ali-oss');
  2. var client = new
  3. region: '<oss region>',
  4. //Since the Alibaba Cloud account AccessKey gives you permission to access all APIs, we recommend that you follow the Alibaba Cloud Security Best Practices. If you deploy the service on the server, use an RAM sub-account or STS, and if you deploy the service on the client, use STS.
  5. accessKeyId: '<Your accessKeyId>',
  6. accessKeySecret: '<Your accessKeySecret>',
  7. bucket: '<Your bucket name>'
  8. });
Use Bower:

For web projects, you can install the SDK through the Bower:

  1. bower install ali-oss

Then you can add the <script> tag in the webpage:

  1. <script src="bower_components/ali-oss/dist/aliyun-oss-sdk.min.js"></script>
Thank you! We've received your feedback.