OSSClient インスタンスを構成する方法 - Object Storage Service

OSS SDK for Harmony を使用して Object Storage Service (OSS) リクエストを開始するには、まず OSSClient インスタンスを初期化する必要があります。

注意事項

OSSClient インスタンスを初期化する前に、アクセス認証情報を構成する必要があります。このトピックでは、アクセス認証情報は環境変数から取得されます。詳細については、「アクセス認証情報の構成」をご参照ください。
OSS でサポートされているリージョンとエンドポイントについては、「リージョンとエンドポイント」をご参照ください。
RAM ユーザーの AccessKey ペアを作成する方法については、「RAM ユーザーの AccessKey ペアの作成」をご参照ください。
Security Token Service (STS) から一時的なアクセス認証情報を取得する方法については、「STS によって提供される一時的な認証情報を使用して OSS にアクセスする」をご参照ください。

デフォルトの構成例

重要

OSS SDK for Harmony は、デフォルトで V4 署名アルゴリズムを使用します。[クライアント] を初期化するときは、リクエストが開始されるリージョンの識別子として Alibaba Cloud リージョン ID を指定する必要があります。この例では、中国 (杭州) リージョンの ID である oss-cn-hangzhou が使用されています。他のリージョンの ID については、「リージョンとエンドポイント」をご参照ください。

import Client from '@aliyun/oss';

// OSSClient インスタンスを作成します。
const client = new Client({
  // STS から取得した AccessKey ID を指定します。
  accessKeyId: 'yourAccessKeyId',
  // STS から取得した AccessKey シークレットを指定します。
  accessKeySecret: 'yourAccessKeySecret',
  // STS から取得したセキュリティトークンを指定します。
  securityToken: 'yourSecurityToken',
  // バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',
});

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

カスタムドメイン名を使用して OSSClient インスタンスを構成する

用途の異なる複数のバケットがある場合は、リソースをより適切に管理および整理するために、バケットごとに異なるサブドメインを指定できます。

次のサンプルコードは、カスタムドメイン名を使用して OSSClient インスタンスを構成する方法の例を示しています。

警告

最初に、カスタムドメイン名をバケットのデフォルトドメイン名にマッピングする必要があります。そうしないと、エラーが報告されます。カスタムドメイン名をバケットのデフォルトドメイン名にマッピングする方法の詳細については、「カスタムドメイン名をバケットのデフォルトドメイン名にマッピングする」をご参照ください。

import Client from '@aliyun/oss';

// OSSClient インスタンスを作成します。
const client = new Client({
  // STS から取得した AccessKey ID を指定します。
  accessKeyId: 'yourAccessKeyId',
  // STS から取得した AccessKey シークレットを指定します。
  accessKeySecret: 'yourAccessKeySecret',
  // STS から取得したセキュリティトークンを指定します。
  securityToken: 'yourSecurityToken',
  // バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',

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

  // CNAME を有効にするには、このパラメーターを true に設定します。
  cname: true,
});

プロキシサーバーを使用して OSSClient インスタンスを構成する

次のサンプルコードは、プロキシサーバーを使用して OSSClient インスタンスを構成する方法の例を示しています。

import Client from '@aliyun/oss';

// OSSClient インスタンスを作成します。
const client = new Client({
  // STS から取得した AccessKey ID を指定します。
  accessKeyId: 'yourAccessKeyId',
  // STS から取得した AccessKey シークレットを指定します。
  accessKeySecret: 'yourAccessKeySecret',
  // STS から取得したセキュリティトークンを指定します。
  securityToken: 'yourSecurityToken',
  // バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',

  // カスタムプロキシサーバーを使用して OSS にアクセスできるようにプロキシを構成します。
  // 詳細については、https://developer.huawei.com/consumer/en/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'],

    // セキュリティ構成を指定します。これは、プロキシサーバーの SSL 証明書と認証を設定するために使用されます。
    security: {
      // SSL 証明書を構成します。
      certificate: {
        // SSL 証明書のコンテンツを指定します。通常は PEM 形式の証明書文字列です。
        content: '-----BEGIN CERTIFICATE-----\n...',
        // SSL 証明書のタイプを指定します (例: PEM)。
        type: 'PEM',
        // サービス要件に基づいて秘密鍵のコンテンツを指定します。
        key: '-----BEGIN PRIVATE KEY-----\n...',
        // 秘密鍵が暗号化されている場合は、秘密鍵のパスワードを指定します。
        keyPassword: 'your-password',
      },

      // サーバー認証を構成します。
      serverAuthentication: {
        // 認証資格情報を指定します。
        credential: {
          username: proxy-username, // プロキシサーバーのユーザー名を指定します。
          password: 'proxy-password', // プロキシサーバーのパスワードを指定します。
        },
        // 認証タイプを指定します (例: basic)。
        authenticationType: 'basic',
      },
    },
  },
});

カスタムプロキシを指定して OSSClient インスタンスを構成する

次のサンプルコードは、カスタムプロキシを指定して OSSClient インスタンスを構成する方法の例を示しています。

import Client from '@aliyun/oss';

// OSSClient インスタンスを作成します。
const client = new Client({
  // STS から取得した AccessKey ID を指定します。
  accessKeyId: 'yourAccessKeyId',
  // STS から取得した AccessKey シークレットを指定します。
  accessKeySecret: 'yourAccessKeySecret',
  // STS から取得したセキュリティトークンを指定します。
  securityToken: 'yourSecurityToken',
  // バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',

  /**
   * 最終的に生成される user-agent リクエストヘッダーの一部としてカスタム userAgent を渡します。
   * 生成される 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)。
});

リクエストの失敗後にリクエストを再試行する

次のサンプルコードは、OSSClient インスタンスから開始されたリクエストが失敗した後にリクエストを再試行する方法の例を示しています。

import Client from '@aliyun/oss';

// OSSClient インスタンスを作成します。
const client = new Client({
  // STS から取得した AccessKey ID を指定します。
  accessKeyId: 'yourAccessKeyId',
  // STS から取得した AccessKey シークレットを指定します。
  accessKeySecret: 'yourAccessKeySecret',
  // STS から取得したセキュリティトークンを指定します。
  securityToken: 'yourSecurityToken',
  // バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',

  // リクエストが失敗した場合の最大再試行回数を 3 に設定します。デフォルト値は 0 で、システムがリクエストを再試行しないことを示します。
  retryMax: 3,

  // requestErrorShouldRetry メソッドを指定して、リクエストが失敗した場合にリクエストを再試行するかどうかを決定します。
  // デフォルト値は「() => true」で、すべてのエラーで再試行がトリガーされることを意味します。
  requestErrorShouldRetry: (err, params) => {
    // err: リクエストが失敗したときのエラーオブジェクト。
    // params: 現在のリクエストのパラメーター。
    // true が返された場合は再試行が必要で、false が返された場合は再試行は不要です。
    return true;
  },
});

Alibaba Finance Cloud の構成例

以下は、金融クラウドのエンドポイントを使用して OSSClient インスタンスを構成するサンプルコードです。

import Client from '@aliyun/oss';

// OSSClient インスタンスを作成します。
const client = new Client({
  // STS から取得した AccessKey ID を指定します。
  accessKeyId: 'yourAccessKeyId',
  // STS から取得した AccessKey シークレットを指定します。
  accessKeySecret: 'yourAccessKeySecret',
  // STS から取得したセキュリティトークンを指定します。
  securityToken: 'yourSecurityToken',
  // リージョンとエンドポイントを指定します。
  // バケットが配置されているリージョンを指定します。たとえば、バケットが中国東部 1 金融リージョンにある場合は、リージョンを cn-hangzhou-finance に設定します。
  region: 'cn-hangzhou-finance',
   // バケットが配置されているリージョンの内部エンドポイントを指定します。たとえば、バケットが中国東部 1 金融リージョンにある場合は、エンドポイントを 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 の構成例

以下は、政務クラウドのエンドポイントを使用して OSSClient インスタンスを構成するサンプルコードです。

import Client from '@aliyun/oss';

// OSSClient インスタンスを作成します。
const client = new Client({
  // STS から取得した AccessKey ID を指定します。
  accessKeyId: 'yourAccessKeyId',
  // STS から取得した AccessKey シークレットを指定します。
  accessKeySecret: 'yourAccessKeySecret',
  // STS から取得したセキュリティトークンを指定します。
  securityToken: 'yourSecurityToken',
  // リージョンとエンドポイントを指定します。
  // バケットが配置されているリージョンを指定します。たとえば、バケットが中国北部 2 Ali Gov 1 リージョンにある場合は、リージョンを cn-north-2-gov-1 に設定します。
  region: 'cn-north-2-gov-1',
  // バケットが配置されているリージョンの内部エンドポイントを指定します。たとえば、バケットが中国北部 2 Ali Gov 1 リージョンにある場合は、エンドポイントを 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',
});