How to configure OSSClient (Harmony SDK) - Object Storage Service

Before you use the Harmony SDK to send an Object Storage Service (OSS) request, you must initialize an OSS client instance.

Notes

Before you initialize an OSS client, you must configure access credentials. This topic uses temporary access credentials from Security Token Service (STS) as an example. For more information, see Configure access credentials (Harmony SDK).
For more information about the regions and Endpoints supported by OSS, see Regions and endpoints.
For more information about creating an AccessKey for a Resource Access Management (RAM) user, see Create an AccessKey.
For more information about how to create temporary access credentials from STS, see Use temporary credentials provided by STS to access OSS.

Default configuration example

Important

The Harmony SDK uses V4 signatures by default. When you initialize the Client, you must specify an Alibaba Cloud OSS-specific region ID to identify the request region. This example uses oss-cn-hangzhou, which is the region ID for China (Hangzhou). For more information about other region IDs, see Regions and endpoints.

import Client from '@aliyun/oss';

// Create an OSS client instance.
const client = new Client({
  // Replace with the AccessKey ID from the STS temporary credential.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the AccessKey Secret from the STS temporary credential.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token from the STS temporary credential.
  securityToken: 'yourSecurityToken',
  // Specify the region where the bucket is located. For example, for China (Hangzhou), set Region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

Configuration examples for common scenarios

Custom domain name configuration example

If you have multiple OSS buckets for different purposes, you can set a different subdomain for each bucket to better manage and organize your resources.

The following code shows an example of how to configure an OSSClient instance with a custom domain name.

Warning

You must first map the custom domain name to the bucket's default domain name. Otherwise, an error occurs. For more information about how to bind a custom domain name, see Access OSS using a custom domain name.

import Client from '@aliyun/oss';

// Create an OSS client instance.
const client = new Client({
  // Replace with the AccessKey ID from the STS temporary credential.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the AccessKey Secret from the STS temporary credential.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token from the STS temporary credential.
  securityToken: 'yourSecurityToken',
  // Specify the region where the bucket is located. For example, for China (Hangzhou), set Region to 'oss-cn-hangzhou'.
  region: 'oss-cn-hangzhou',

  // Use a custom domain name to access OSS data.
  // Example: 'https://your-bucket.com' or 'http://your-bucket.com'.
  // Replace with your actual custom domain name.
  endpoint: 'https://your-bucket.com',

  // Set to true to access OSS using a CNAME.
  cname: true,
});

Proxy server configuration example

To configure a client proxy server, see the following code example.

import Client from '@aliyun/oss';

// Create an OSS client instance.
const client = new Client({
  // Replace with the AccessKey ID from the STS temporary credential.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the AccessKey Secret from the STS temporary credential.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token from the STS temporary credential.
  securityToken: 'yourSecurityToken',
  // Specify the region where the bucket is located. For example, for China (Hangzhou), set Region to 'oss-cn-hangzhou'.
  region: 'oss-cn-hangzhou',

  // Configure a proxy to access OSS through a custom proxy server.
  // For more information, see the ProxyConfiguration section in the official document at https://developer.huawei.com/consumer/en/doc/harmonyos-references-V13/remote-communication-rcp-V13#section731665213712.
  proxy: {
    // The URL of the proxy server. Replace with your actual proxy server address.
    url: 'http://custom-proxy.example.com',

    // Specifies whether to always create a tunnel connection. Valid values: 'always' and 'never'.
    createTunnel: 'always',

    // A list of URLs to exclude from proxy access.
    exclusions: ['http://exclude.example.com'],

    // Security configuration for the proxy server's certificate and identity verification.
    security: {
      // Certificate configuration
      certificate: {
        // The certificate content, usually a string in PEM format.
        content: '-----BEGIN CERTIFICATE-----\n...',
        // The certificate type, such as PEM.
        type: 'PEM',
        // The private key content. Set as needed.
        key: '-----BEGIN PRIVATE KEY-----\n...',
        // The password for the private key, if the key is encrypted.
        keyPassword: 'your-password',
      },

      // Server identity verification configuration
      serverAuthentication: {
        // Identity credentials
        credential: {
          username: 'proxy-username', // The username for the proxy server.
          password: 'proxy-password', // The password for the proxy server.
        },
        // The identity verification type, such as basic.
        authenticationType: 'basic',
      },
    },
  },
});

Custom user agent configuration example

To configure a custom User-Agent, see the following code example.

import Client from '@aliyun/oss';

// Create an OSS client instance.
const client = new Client({
  // Replace with the AccessKey ID from the STS temporary credential.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the AccessKey Secret from the STS temporary credential.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token from the STS temporary credential.
  securityToken: 'yourSecurityToken',
  // Specify the region where the bucket is located. For example, for China (Hangzhou), set Region to 'oss-cn-hangzhou'.
  region: 'oss-cn-hangzhou',

  /**
   * The custom userAgent passed here is part of the final generated user-agent request header.
   * The final user-agent request header is in the format: `<SDK version information> <system version information>/${userAgent}`
   *
   * Example:
   * If the SDK version is "MySDK/1.0.0", the system version is "(Windows 10; x64)",
   * and you pass the custom UserAgent string "CustomApp/2.3.1",
   * the final generated user-agent will be "MySDK/1.0.0 (Windows 10; x64)/CustomApp/2.3.1".
   *
   */
  userAgent: 'CustomApp/2.3.1', // Enter your custom userAgent string, for example, CustomApp/2.3.1.
});

Error retry configuration example

The following code example shows how to configure the client to retry failed requests.

import Client from '@aliyun/oss';

// Create an OSS client instance.
const client = new Client({
  // Replace with the AccessKey ID from the STS temporary credential.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the AccessKey Secret from the STS temporary credential.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token from the STS temporary credential.
  securityToken: 'yourSecurityToken',
  // Specify the region where the bucket is located. For example, for China (Hangzhou), set Region to 'oss-cn-hangzhou'.
  region: 'oss-cn-hangzhou',

  // Set the maximum number of retries for a failed request to 3. The default is 0, which means no retries.
  retryMax: 3,

  // Implement the custom `requestErrorShouldRetry` method to decide whether to retry a failed request.
  // The default implementation is `() => true`, which means all errors trigger a retry.
  requestErrorShouldRetry: (err, params) => {
    // err: The error object from the failed request.
    // params: The parameters of the current request.
    // Return true to retry, or false to not retry.
    return true;
  },
});

Finance Cloud configuration example

The following code shows an example of configuring an OSSClient instance with an Alibaba Finance Cloud domain name.

import Client from '@aliyun/oss';

// Create an OSS client instance.
const client = new Client({
  // Replace with the AccessKey ID from the STS temporary credential.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the AccessKey Secret from the STS temporary credential.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token from the STS temporary credential.
  securityToken: 'yourSecurityToken',
  // Specify the Region and Endpoint.
  // Specify the region where the bucket is located. For China (Hangzhou) Finance, set Region to cn-hangzhou-finance.
  region: 'cn-hangzhou-finance',
   // Specify the internal Endpoint for the bucket's region. For China (Hangzhou) Finance, set Endpoint to 'https://oss-cn-hzjbp-a-internal.aliyuncs.com'.
   // To use the HTTP protocol, set the domain name to 'http://oss-cn-hzjbp-a-internal.aliyuncs.com'.
  endpoint: 'https://oss-cn-hzjbp-a-internal.aliyuncs.com',
});

Alibaba Gov Cloud configuration example

The following code shows how to configure an OSSClient instance using an Alibaba Gov Cloud domain name.

import Client from '@aliyun/oss';

// Create an OSS client instance.
const client = new Client({
  // Replace with the AccessKey ID from the STS temporary credential.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the AccessKey Secret from the STS temporary credential.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token from the STS temporary credential.
  securityToken: 'yourSecurityToken',
  // Specify the Region and Endpoint.
  // Specify the region where the bucket is located. For China North 2 Ali Gov 1, set Region to cn-north-2-gov-1.
  region: 'cn-north-2-gov-1',
  // Specify the internal Endpoint for the bucket's region. For China North 2 Ali Gov 1, set Endpoint to 'https://oss-cn-north-2-gov-1-internal.aliyuncs.com'.
  // To use the HTTP protocol, set the domain name to 'http://oss-cn-north-2-gov-1-internal.aliyuncs.com'.
  endpoint: 'https://oss-cn-north-2-gov-1-internal.aliyuncs.com',
});