如何配置OSSClient_对象存储(OSS)-阿里云帮助中心

使用Harmony SDK发起OSS请求前，您需要初始化一个OSS client实例.

注意事项

初始化OSS client前，您需要配置访问凭证，本文以STS临时访问凭证为例，详情请参见配置访问凭证。
关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。
关于创建RAM用户的AccessKey，请参见创建AccessKey。
关于创建STS临时访问凭证，请参见使用STS临时访问凭证访问OSS。

默认配置示例

重要

Harmony SDK默认使用V4签名，在初始化Client时，您需要指定阿里云OSS专用地域ID作为发起请求地域的标识，本示例代码使用华东1（杭州）专用地域ID：oss-cn-hangzhou。如需查询其它专用地域ID请参见OSS地域和访问域名。

import Client from '@aliyun/oss';

// 创建OSS客户端实例
const client = new Client({
  // 请替换为STS临时访问凭证的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 请替换为STS临时访问凭证的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 请替换为STS临时访问凭证的Security Token
  securityToken: 'yourSecurityToken',
  // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为oss-cn-hangzhou
  region: 'oss-cn-hangzhou',
});

常见场景配置示例

自定义域名配置示例

当您有多个不同的OSS Bucket用于不同的目的时，可以通过为每个Bucket设置不同的子域名来更好地管理和组织资源。

以下是使用自定义域名配置OSSClient的示例代码。

警告

您需要先将自定义域名绑定至Bucket默认域名，否则将引发报错！关于绑定自定义域名的详细操作，请参见绑定自定义域名至Bucket默认域名。

import Client from '@aliyun/oss';

// 创建OSS客户端实例
const client = new Client({
  // 请替换为STS临时访问凭证的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 请替换为STS临时访问凭证的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 请替换为STS临时访问凭证的Security Token
  securityToken: 'yourSecurityToken',
  // 填写Bucket所在的地域。例如，华东1（杭州）的Region为'oss-cn-hangzhou'
  region: 'oss-cn-hangzhou',

  // 使用自定义域名访问OSS数据。
  // 例如：'https://your-bucket.com' 或 'http://your-bucket.com'。
  // 请替换为您实际使用的自定义域名。
  endpoint: 'https://your-bucket.com',

  // 设置为true时，表示使用CNAME方式访问OSS
  cname: true,
});

代理服务器配置示例

如果您有配置客户端代理服务器的需求，请参考以下代码示例。

import Client from '@aliyun/oss';

// 创建OSS客户端实例
const client = new Client({
  // 请替换为STS临时访问凭证的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 请替换为STS临时访问凭证的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 请替换为STS临时访问凭证的Security Token
  securityToken: 'yourSecurityToken',
  // 填写Bucket所在的地域。例如，华东1（杭州）的Region为'oss-cn-hangzhou'
  region: 'oss-cn-hangzhou',

  // 配置代理（proxy）以支持通过自定义代理服务器访问OSS。
  // 具体请参考官方文档https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V13/remote-communication-rcp-V13#section731665213712的ProxyConfiguration部分以获取更多详细信息。
  proxy: {
    // 代理服务器的URL地址，请替换为您实际使用的代理服务器地址
    url: 'http://custom-proxy.example.com',

    // 指定是否始终创建隧道连接。可选值为'always'或'never'。
    createTunnel: 'always',

    // 排除不需要通过代理访问的URL列表。
    exclusions: ['http://exclude.example.com'],

    // 安全配置，用于设置代理服务器的安全证书和身份验证。
    security: {
      // 证书配置
      certificate: {
        // 证书内容，通常为PEM格式的证书字符串
        content: '-----BEGIN CERTIFICATE-----\n...',
        // 证书类型，例如PEM
        type: 'PEM',
        // 私钥内容，根据您的服务需求设置
        key: '-----BEGIN PRIVATE KEY-----\n...',
        // 私钥密码（如果私钥加密）
        keyPassword: 'your-password',
      },

      // 服务器身份验证配置
      serverAuthentication: {
        // 身份验证凭据
        credential: {
          username: 'proxy-username', // 代理服务器用户名
          password: 'proxy-password', // 代理服务器密码
        },
        // 身份验证类型，例如basic（基本认证）
        authenticationType: 'basic',
      },
    },
  },
});

自定义用户代理配置示例

如果您有配置自定义UserAgent的需求，请参考以下代码示例。

import Client from '@aliyun/oss';

// 创建OSS客户端实例
const client = new Client({
  // 请替换为STS临时访问凭证的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 请替换为STS临时访问凭证的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 请替换为STS临时访问凭证的Security Token
  securityToken: 'yourSecurityToken',
  // 填写Bucket所在的地域。例如，华东1（杭州）的Region为'oss-cn-hangzhou'
  region: 'oss-cn-hangzhou',

  /**
   * 此处传入的自定义userAgent为最终生成user-agent请求头的一部分，
   * 最终生成的user-agent请求头格式为 `<SDK版本信息> <系统版本信息>/${userAgent}`
   *
   * 示例：
   * 假如SDK版本信息为 "MySDK/1.0.0"，系统版本信息为 "(Windows 10; x64)"，
   * 您传入的自定义UserAgent字符串为 "CustomApp/2.3.1"，
   * 则最终生成的user-agent将是 "MySDK/1.0.0 (Windows 10; x64)/CustomApp/2.3.1"
   *
   */
  userAgent: 'CustomApp/2.3.1', //填写您的自定义userAgent字符串，例如为CustomApp/2.3.1
});

错误重试配置示例

如果您有配置客户端发起请求错误后进行重试的需求，请参考以下代码示例。

import Client from '@aliyun/oss';

// 创建OSS客户端实例
const client = new Client({
  // 请替换为STS临时访问凭证的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 请替换为STS临时访问凭证的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 请替换为STS临时访问凭证的Security Token
  securityToken: 'yourSecurityToken',
  // 填写Bucket所在的地域。例如，华东1（杭州）的Region为'oss-cn-hangzhou'
  region: 'oss-cn-hangzhou',

  // 设置请求失败时的最大重试次数，例如设置为3次。默认为0次，不重试。
  retryMax: 3,

  // 自定义实现`requestErrorShouldRetry`方法，用于决定是否在请求失败时进行重试。
  // 默认实现为`() => true`，即所有错误都会触发重试。
  requestErrorShouldRetry: (err, params) => {
    // err: 请求失败时的错误对象。
    // params: 当前请求的参数。
    // 返回true表示需要重试，返回false表示不重试。
    return true;
  },
});