Configure a client (Harmony SDK)

Custom domain name

Use a custom domain name when you want to access OSS buckets through your own branded domain (for example, https://assets.example.com instead of the default OSS endpoint).

import Client from '@aliyun/oss';

const client = new Client({
  accessKeyId: '<your-access-key-id>',
  accessKeySecret: '<your-access-key-secret>',
  securityToken: '<your-security-token>',
  region: 'oss-cn-hangzhou',
  // Your custom domain (HTTP or HTTPS)
  endpoint: 'https://your-bucket.com',
  // Required when using a custom domain — tells the SDK to route via CNAME instead of the default OSS endpoint
  cname: true,
});

Proxy server

Route OSS traffic through a proxy server when your HarmonyOS app operates in a network environment that requires it (for example, a corporate intranet with restricted outbound access).

import Client from '@aliyun/oss';

const client = new Client({
  accessKeyId: '<your-access-key-id>',
  accessKeySecret: '<your-access-key-secret>',
  securityToken: '<your-security-token>',
  region: 'oss-cn-hangzhou',

  // Proxy configuration — see HarmonyOS ProxyConfiguration reference:
  // https://developer.huawei.com/consumer/en/doc/harmonyos-references-V13/remote-communication-rcp-V13#section731665213712
  proxy: {
    // URL of the proxy server
    url: 'http://custom-proxy.example.com',

    // 'always': force tunnel even for HTTP; 'never': direct connection
    createTunnel: 'always',

    // URLs to bypass the proxy (omit if no exclusions needed)
    exclusions: ['http://exclude.example.com'],

    // Security settings — omit this block if the proxy does not require certificate or credential verification
    security: {
      // Client certificate for mutual TLS (omit if not required)
      certificate: {
        content: '-----BEGIN CERTIFICATE-----\n...',  // PEM-encoded certificate
        type: 'PEM',
        key: '-----BEGIN PRIVATE KEY-----\n...',       // Private key
        keyPassword: '<key-password>',                 // Omit if the key is not encrypted
      },

      // Proxy authentication (omit if the proxy does not require login)
      serverAuthentication: {
        credential: {
          username: '<proxy-username>',
          password: '<proxy-password>',
        },
        authenticationType: 'basic',
      },
    },
  },
});

Custom User-Agent

Append a custom string to the SDK's User-Agent header to identify your application in request logs.

The SDK builds the final header as: <SDK version> <system version>/<your custom string>

import Client from '@aliyun/oss';

const client = new Client({
  accessKeyId: '<your-access-key-id>',
  accessKeySecret: '<your-access-key-secret>',
  securityToken: '<your-security-token>',
  region: 'oss-cn-hangzhou',
  // Appended to the User-Agent header, for example: "MySDK/1.0.0 (Windows 10; x64)/CustomApp/2.3.1"
  userAgent: 'CustomApp/2.3.1',
});

Error retry

Configure retry behavior to handle transient network errors automatically.

import Client from '@aliyun/oss';

const client = new Client({
  accessKeyId: '<your-access-key-id>',
  accessKeySecret: '<your-access-key-secret>',
  securityToken: '<your-security-token>',
  region: 'oss-cn-hangzhou',

  // Maximum retry attempts after a failed request. Default: 0 (no retries)
  retryMax: 3,

  // Custom retry logic — return true to retry, false to surface the error immediately.
  // Default: () => true (retry on all errors)
  requestErrorShouldRetry: (err, params) => {
    return true;
  },
});

Finance Cloud

Use the following configuration to access OSS in an Alibaba Finance Cloud region.

import Client from '@aliyun/oss';

const client = new Client({
  accessKeyId: '<your-access-key-id>',
  accessKeySecret: '<your-access-key-secret>',
  securityToken: '<your-security-token>',
  // Finance Cloud region ID for China (Hangzhou) Finance
  region: 'cn-hangzhou-finance',
  // Internal endpoint for China (Hangzhou) Finance — use the HTTP URL if HTTPS is not supported
  endpoint: 'https://oss-cn-hzjbp-a-internal.aliyuncs.com',
});

Finance Cloud configuration example

The following code provides an example of how to configure 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 the region to cn-hangzhou-finance.
  region: 'cn-hangzhou-finance',
   // Specify the internal endpoint for the bucket's region. For China (Hangzhou) Finance, set the 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

Use the following configuration to access OSS in an Alibaba Gov Cloud region.

import Client from '@aliyun/oss';

const client = new Client({
  accessKeyId: '<your-access-key-id>',
  accessKeySecret: '<your-access-key-secret>',
  securityToken: '<your-security-token>',
  // Gov Cloud region ID for China North 2 Ali Gov 1
  region: 'cn-north-2-gov-1',
  // Internal endpoint for China North 2 Ali Gov 1 — use the HTTP URL if HTTPS is not supported
  endpoint: 'https://oss-cn-north-2-gov-1-internal.aliyuncs.com',
});

Reuse the client instance

Treat the OSS client as a singleton — initialize it once and share it across your app. Reinitializing the client for every request adds unnecessary latency and wastes resources, which is especially noticeable on mobile devices.

Common patterns for sharing a single client instance:

• Pass the client as a parameter to functions or classes that need it

• Store it in a module-level variable

• Register it in your dependency injection container

Secure your credentials

• Never hardcode credentials in your source code

• Prefer STS temporary credentials over long-lived AccessKey pairs. Temporary credentials expire automatically, limiting the impact of accidental exposure

• Rotate AccessKey pairs regularly if you must use them directly