OSSClient の設定方法 (Harmony SDK) - Object Storage Service - Alibaba Cloud ドキュメントセンター

Harmony SDK を使用して Object Storage Service (OSS) リクエストを送信する前に、OSS クライアントインスタンスを初期化する必要があります。

注意事項

OSS クライアントを初期化する前に、アクセス認証情報を設定する必要があります。この Topic では、例としてセキュリティトークンサービス (STS) からの一時的なアクセス認証情報を使用します。詳細については、「アクセス認証情報を設定する (Harmony SDK)」をご参照ください。
OSS でサポートされているリージョンとエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。
Resource Access Management (RAM) ユーザーの AccessKey の作成方法の詳細については、「AccessKey の作成」をご参照ください。
STS から一時的なアクセス認証情報を作成する方法の詳細については、「STS が提供する一時的な認証情報を使用した OSS へのアクセス」をご参照ください。

デフォルト設定の例

重要

Harmony SDK はデフォルトで V4 署名を使用します。Client を初期化する際に、リクエストリージョンを識別するために Alibaba Cloud OSS 固有のリージョン ID を指定する必要があります。この例では、中国 (杭州) のリージョン ID である oss-cn-hangzhou を使用します。他のリージョン ID の詳細については、「リージョンとエンドポイント」をご参照ください。

import Client from '@aliyun/oss';

// OSS クライアントインスタンスを作成します。
const client = new Client({
  // STS 一時認証情報の AccessKey ID に置き換えます。
  accessKeyId: 'yourAccessKeyId',
  // STS 一時認証情報の AccessKey Secret に置き換えます。
  accessKeySecret: 'yourAccessKeySecret',
  // STS 一時認証情報の Security Token に置き換えます。
  securityToken: 'yourSecurityToken',
  // バケットが配置されているリージョンを指定します。たとえば、中国 (杭州) の場合は、Region を oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',
});

一般的なシナリオの構成例

カスタムドメイン名の設定例

さまざまな目的で複数の OSS バケットがある場合、各バケットに異なるサブドメインを設定することで、リソースの管理と整理を効率化できます。

次のコードは、カスタムドメイン名で OSSClient インスタンスを設定する例を示しています。

警告

まず、カスタムドメイン名をバケットのデフォルトのドメイン名にマップする必要があります。そうしないと、エラーが発生します。カスタムドメイン名のバインド方法の詳細については、「カスタムドメイン名を使用した OSS へのアクセス」をご参照ください。

import Client from '@aliyun/oss';

// OSS クライアントインスタンスを作成します。
const client = new Client({
  // STS 一時認証情報の AccessKey ID に置き換えます。
  accessKeyId: 'yourAccessKeyId',
  // STS 一時認証情報の AccessKey Secret に置き換えます。
  accessKeySecret: 'yourAccessKeySecret',
  // STS 一時認証情報の Security Token に置き換えます。
  securityToken: 'yourSecurityToken',
  // バケットが配置されているリージョンを指定します。たとえば、中国 (杭州) の場合は、Region を 'oss-cn-hangzhou' に設定します。
  region: 'oss-cn-hangzhou',

  // カスタムドメイン名を使用して OSS データにアクセスします。
  // 例：'https://your-bucket.com' または 'http://your-bucket.com'。
  // 実際のカスタムドメイン名に置き換えてください。
  endpoint: 'https://your-bucket.com',

  // CNAME ドメイン名を使用して OSS にアクセスするには、true に設定します。
  cname: true,
});

プロキシサーバーの設定例

クライアントプロキシサーバーを設定するには、次のコード例をご参照ください。

import Client from '@aliyun/oss';

// OSS クライアントインスタンスを作成します。
const client = new Client({
  // STS 一時認証情報の AccessKey ID に置き換えます。
  accessKeyId: 'yourAccessKeyId',
  // STS 一時認証情報の AccessKey Secret に置き換えます。
  accessKeySecret: 'yourAccessKeySecret',
  // STS 一時認証情報の Security Token に置き換えます。
  securityToken: 'yourSecurityToken',
  // バケットが配置されているリージョンを指定します。たとえば、中国 (杭州) の場合は、Region を 'oss-cn-hangzhou' に設定します。
  region: 'oss-cn-hangzhou',

  // カスタムプロキシサーバー経由で OSS にアクセスするようにプロキシを設定します。
  // 詳細については、公式ドキュメントの ProxyConfiguration セクション (https://developer.huawei.com/consumer/en/doc/harmonyos-references-V13/remote-communication-rcp-V13#section731665213712) をご参照ください。
  proxy: {
    // プロキシサーバーの URL。実際のプロキシサーバーのアドレスに置き換えてください。
    url: 'http://custom-proxy.example.com',

    // トンネル接続を常に作成するかどうかを指定します。有効な値：'always' と 'never'。
    createTunnel: 'always',

    // プロキシアクセスから除外する URL のリスト。
    exclusions: ['http://exclude.example.com'],

    // プロキシサーバーの証明書と ID 検証のためのセキュリティ設定。
    security: {
      // 証明書の設定
      certificate: {
        // 証明書の内容。通常は PEM 形式の文字列です。
        content: '-----BEGIN CERTIFICATE-----\n...',
        // 証明書の種類。PEM など。
        type: 'PEM',
        // 秘密鍵の内容。必要に応じて設定します。
        key: '-----BEGIN PRIVATE KEY-----\n...',
        // 秘密鍵が暗号化されている場合のパスワード。
        keyPassword: 'your-password',
      },

      // サーバー ID 検証の設定
      serverAuthentication: {
        // ID 認証情報
        credential: {
          username: 'proxy-username', // プロキシサーバーのユーザー名。
          password: 'proxy-password', // プロキシサーバーのパスワード。
        },
        // ID 検証の種類。basic など。
        authenticationType: 'basic',
      },
    },
  },
});

カスタムユーザーエージェントの設定例

カスタム User-Agent を設定するには、次のコード例をご参照ください。

import Client from '@aliyun/oss';

// OSS クライアントインスタンスを作成します。
const client = new Client({
  // STS 一時認証情報の AccessKey ID に置き換えます。
  accessKeyId: 'yourAccessKeyId',
  // STS 一時認証情報の AccessKey Secret に置き換えます。
  accessKeySecret: 'yourAccessKeySecret',
  // STS 一時認証情報の Security Token に置き換えます。
  securityToken: 'yourSecurityToken',
  // バケットが配置されているリージョンを指定します。たとえば、中国 (杭州) の場合は、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 一時認証情報の AccessKey ID に置き換えます。
  accessKeyId: 'yourAccessKeyId',
  // STS 一時認証情報の AccessKey Secret に置き換えます。
  accessKeySecret: 'yourAccessKeySecret',
  // STS 一時認証情報の Security Token に置き換えます。
  securityToken: 'yourSecurityToken',
  // バケットが配置されているリージョンを指定します。たとえば、中国 (杭州) の場合は、Region を 'oss-cn-hangzhou' に設定します。
  region: 'oss-cn-hangzhou',

  // 失敗したリクエストの最大リトライ回数を 3 に設定します。デフォルトは 0 で、リトライしないことを意味します。
  retryMax: 3,

  // カスタムの `requestErrorShouldRetry` メソッドを実装して、失敗したリクエストをリトライするかどうかを決定します。
  // デフォルトの実装は `() => true` で、すべてのエラーでリトライがトリガーされることを意味します。
  requestErrorShouldRetry: (err, params) => {
    // err: 失敗したリクエストからのエラーオブジェクト。
    // params: 現在のリクエストのパラメーター。
    // リトライする場合は true を、リトライしない場合は false を返します。
    return true;
  },
});

Finance Cloud の設定例

次のコードは、Finance Cloud ドメイン名で OSSClient インスタンスを設定する例を示しています。

import Client from '@aliyun/oss';

// OSS クライアントインスタンスを作成します。
const client = new Client({
  // STS 一時認証情報の AccessKey ID に置き換えます。
  accessKeyId: 'yourAccessKeyId',
  // STS 一時認証情報の AccessKey Secret に置き換えます。
  accessKeySecret: 'yourAccessKeySecret',
  // STS 一時認証情報の Security Token に置き換えます。
  securityToken: 'yourSecurityToken',
  // リージョンとエンドポイントを指定します。
  // バケットが配置されているリージョンを指定します。中国 (杭州) 金融リージョンの場合は、Region を cn-hangzhou-finance に設定します。
  region: 'cn-hangzhou-finance',
   // バケットのリージョンの内部エンドポイントを指定します。中国 (杭州) 金融リージョンの場合は、Endpoint を 'https://oss-cn-hzjbp-a-internal.aliyuncs.com' に設定します。
   // HTTP プロトコルを使用するには、ドメイン名を 'http://oss-cn-hzjbp-a-internal.aliyuncs.com' に設定します。
  endpoint: 'https://oss-cn-hzjbp-a-internal.aliyuncs.com',
});

Alibaba Gov Cloud の設定例

次のコードは、Alibaba Gov Cloud ドメイン名を使用して OSSClient インスタンスを設定する方法を示しています。

import Client from '@aliyun/oss';

// OSS クライアントインスタンスを作成します。
const client = new Client({
  // STS 一時認証情報の AccessKey ID に置き換えます。
  accessKeyId: 'yourAccessKeyId',
  // STS 一時認証情報の AccessKey Secret に置き換えます。
  accessKeySecret: 'yourAccessKeySecret',
  // STS 一時認証情報の Security Token に置き換えます。
  securityToken: 'yourSecurityToken',
  // リージョンとエンドポイントを指定します。
  // バケットが配置されているリージョンを指定します。中国北部 2 Ali Gov 1 の場合は、Region を cn-north-2-gov-1 に設定します。
  region: 'cn-north-2-gov-1',
  // バケットのリージョンの内部エンドポイントを指定します。中国北部 2 Ali Gov 1 の場合は、Endpoint を 'https://oss-cn-north-2-gov-1-internal.aliyuncs.com' に設定します。
  // HTTP プロトコルを使用するには、ドメイン名を 'http://oss-cn-north-2-gov-1-internal.aliyuncs.com' に設定します。
  endpoint: 'https://oss-cn-north-2-gov-1-internal.aliyuncs.com',
});