OSS SDK for Browser.jsのOSSClientインスタンスを初期化するためのパラメータ - Object Storage Service

OSSClientは、Object Storage Service (OSS) のBrowser.jsクライアントです。バケットやオブジェクトなどのOSSリソースの管理に使用されます。 OSS SDK for Browser.jsを使用してリクエストを開始するには、OSSClientインスタンスを初期化し、ビジネス要件に基づいてClientConfiguration設定クラスのデフォルト設定項目を変更する必要があります。

前提条件

OSS SDK for Browser.jsがインストールされています。詳細については、「インストール」をご参照ください。

OSSClientインスタンスの作成

(推奨) V4署名アルゴリズムの使用

より良いセキュリティを提供するV4署名アルゴリズムを使用することを推奨します。この場合、authorizationV4を宣言する必要があります。 OSS SDK for Browser.js 6.20.0以降は、V4署名アルゴリズムをサポートしています。

次のサンプルコードは、V4署名アルゴリズムを使用してOSSエンドポイントを使用してOSSClientインスタンスを作成する方法の例を示しています。 V4署名アルゴリズムを使用して他の方法でOSSClientインスタンスを作成する場合は、次のサンプルコードを参照して変数を変更します。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>
  <body>
    <!-- Import the SDK file -->
    <script
      type="text/javascript"
      src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.20.0.min.js"
    ></script>
    <script type="text/javascript">
      const client = new OSS({
        // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
        region: 'yourRegion',
	authorizationV4: true,
        // Specify the temporary AccessKey pair obtained from Security Token Service (STS). The AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
        accessKeyId: 'yourAccessKeyId',
        accessKeySecret: 'yourAccessKeySecret',
        // Specify the security token obtained from STS. 
        stsToken: 'yourSecurityToken',
        // Specify the name of the bucket. Example: examplebucket. 
        bucket: "examplebucket",
      });
    </script>
  </body>
</html>

(非推奨) V1署名アルゴリズムの使用

重要

2024年12月1日以降、Object Storage Service (OSS) のV1署名アルゴリズムは、新しいUIDを持つ新規顧客は利用できなくなります。 2025年6月1日以降、OSSはV1署名アルゴリズムを更新および維持しなくなり、V1署名アルゴリズムは新しいバケットで使用できなくなります。ビジネスへの影響を防ぐため、できるだけ早い機会にV1シグネチャをV4シグネチャにアップグレードします。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>
  <body>
    <!-- Import the SDK file -->
    <script
      type="text/javascript"
      src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
    ></script>
    <script type="text/javascript">
      const client = new OSS({
        // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
        region: 'yourRegion',
        // Specify the temporary AccessKey pair obtained from STS. 
        accessKeyId: 'yourAccessKeyId',
        accessKeySecret: 'yourAccessKeySecret',
        // Specify the security token obtained from STS. 
        stsToken: 'yourSecurityToken',
        // Specify the name of the bucket. Example: examplebucket. 
        bucket: "examplebucket",
      });
    </script>
  </body>
</html>

OSSClient インスタンスの設定

OSSClientインスタンスを初期化するときに、ビジネス要件に基づいてパラメーターを指定できます。たとえば、timeoutを指定してリクエストタイムアウト期間を指定したり、stsTokenを指定して一時的なアクセス資格情報を指定したりできます。 OSS SDK For Browser.jsでサポートされているパラメーターと設定例の詳細については、次の項目を参照してください。

パラメータ:

accessKeyId {String}: Alibaba Cloudコンソールで作成されたAccessKey ID。
accessKeySecret {String}: Alibaba Cloudコンソールで作成されたAccessKeyシークレット。
[stsToken] {String}: 一時的な承認に使用されるセキュリティトークン。
[refreshSTSToken] {Function}: STSから取得したセキュリティトークンの有効期限が切れると、stsToken、accessKeyId、およびaccessKeySecretを自動的に更新する関数です。戻り値は、stsToken、accessKeyId、およびaccessKeySecretを含むオブジェクトである必要があります。
[refreshSTokenInterval] {number}: STSから取得したセキュリティトークンが更新される間隔。単位：ミリ秒。 STSから取得したセキュリティトークンの有効期間よりも短くする必要があります。デフォルト値は300000で、5分に相当します。
[bucket] {String}: アクセスするデフォルトのバケットの名前。バケットがない場合は、putBucket() を呼び出してバケットを作成します。
[endpoint] {String}: バケットが配置されているリージョンのエンドポイント。このパラメーターは、リージョンパラメーターよりも優先されます。ビジネス要件に基づいて、パブリックエンドポイント、インターナルエンドポイント、またはアクセラレーションエンドポイントにパラメーターを設定できます。
[region] {String}: バケットが配置されているリージョン。デフォルト値: oss-cn-hangzhou
[internal] {Boolean}: 内部ネットワーク経由でOSSにアクセスするかどうかを指定します。デフォルト値：false クラウドサーバーがAlibaba cloudにデプロイされている場合、このパラメーターをtrueに設定すると、大幅なコストを削減できます。
[secure] {Boolean}: OSSクライアントがHTTPS(secure: true) またはHTTP(secure: false) を使用するかどうかを指定します。
[timeout] {String | Number}: すべての操作のインスタンスレベルのタイムアウト期間。デフォルト値: 60。単位は秒です。
[cname] {Boolean}: カスタムドメイン名を使用してOSSにアクセスするかどうかを指定します。デフォルト値：false このパラメーターをtrueに設定すると、エンドポイントパラメーターをカスタムドメイン名に設定できます。
[isRequestPay] {Boolean}: バケットのpay-by-requesterを有効にするかどうかを指定します。値がtrueの場合、'x-oss-request-payer: 'requester' ヘッダーがOSSサーバーに送信されます。デフォルト値：false
[useFetch] {Boolean}: フェッチを有効にするかどうかを指定します。このパラメータはブラウザでのみ有効です。デフォルト値：false このパラメーターをtrueに設定すると、オブジェクトはフェッチモードでアップロードされます。それ以外の場合、XMLHttpRequestが使用されます。
[enableProxy] {Boolean}: プロキシ要求を有効にするかどうかを指定します。デフォルト値：false プロキシ要求を有効にする前に、proxy-agentがインストールされていることを確認してください。
[proxy] {String | Object}: プロキシURIまたはオプション。デフォルト値：null
[retryMax] {Number}: ネットワークエラーまたはタイムアウトによりリクエストが失敗した場合のリトライの最大回数。ストリームは1回しか使用できないため、ストリーミングアップロード (put、putStream、appendなど) はサポートされていません。
[maxSockets] {Number}: ホストごとに許可されるソケットの最大数。デフォルトでは、最大数は制限されていません。
[authorizationV4] {Boolean}: V4署名を使用するかどうかを指定します。デフォルト値：false

例

基本構造

const OSS = require('ali-oss');

const store = new OSS({
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  bucket: 'your bucket name',
  region: 'oss-cn-hangzhou'
});

アクセラレーションエンドポイントを使用する:

説明

グローバルアクセラレーションエンドポイント: oss-accelerate.aliyuncs.com

中国本土以外のリージョンの高速化エンドポイント: oss-accelerate-overseas.aliyuncs.com

const OSS = require('ali-oss');

const store = new OSS({
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  bucket: 'your bucket name',
  endpoint: 'oss-accelerate.aliyuncs.com'
});

カスタムドメイン名を使用する

const OSS = require('ali-oss');

const store = new OSS({
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  cname: true,
  endpoint: 'your custome domain'
});

セキュリティトークンの使用

const OSS = require('ali-oss');

const store = new OSS({
  accessKeyId: 'your STS key',
  accessKeySecret: 'your STS secret',
  stsToken: 'your STS token',
  refreshSTSToken: async () => {
    const info = await fetch('you sts server');
    return {
      accessKeyId: info.accessKeyId,
      accessKeySecret: info.accessKeySecret,
      stsToken: info.stsToken
    };
  },
  refreshSTSTokenInterval: 300000
});

ストリームを使用してリクエストを再試行する

for (let i = 0; i <= store.options.retryMax; i++) {
  try {
    const result = await store.putStream('<example-object>', fs.createReadStream('<example-path>'));
    console.log(result);
    break; // break if success
  } catch (e) {
    console.log(e);
  }
}

V4シグネチャを使用する: ヘッダーを追加して、オプションのadditionalHeadersオプション (type: string array) を指定してV4シグネチャを計算し、リクエストヘッダーにadditionalHeadersオプションの値を含める

const OSS = require('ali-oss');

const store = new OSS({
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  bucket: 'your bucket name',
  region: 'oss-cn-hangzhou',
  authorizationV4: true
});

try {
  const bucketInfo = await store.getBucketInfo('your bucket name');
  console.log(bucketInfo);
} catch (e) {
  console.log(e);
}

try {
  const putObjectResult = await store.put('your bucket name', 'your object name', {
    headers: {
      // The headers of this request
      header1: 'value1',
      header2: 'value2'
    },
    // The keys of the request headers that need to be calculated into the V4 signature. Please ensure that these additional headers are included in the request headers.
    additionalHeaders: ['additional header1', 'additional header2']
  });
  console.log(putObjectResult);
} catch (e) {
  console.log(e);
}