OSS Browser.js SDK のインストールと使用 - Object Storage Service

OSS Browser.js SDK をインストールすると、OSS バケットの管理、ファイルのアップロードとダウンロード、データ管理、画像処理などが可能になります。このトピックでは、OSS Browser.js SDK のインストール方法と使用方法について説明します。

事前準備

RAM ユーザーまたは STS を使用した OSS へのアクセス
Alibaba Cloud アカウントの AccessKey ペアは、すべての API 操作に対する完全な権限を付与します。セキュリティ上の理由から、API アクセスや日常の O&M には Resource Access Management (RAM) ユーザーまたはセキュリティトークンサービス (STS) を使用することを推奨します。SDK をサーバーにデプロイする場合は、RAM ユーザーまたは STS を使用してください。SDK をクライアントにデプロイする場合は、API アクセスに STS を使用してください。詳細については、「Resource Access Management」をご参照ください。
オリジン間リソース共有 (CORS) の設定
ブラウザから直接 OSS にアクセスする場合、次のオリジン間リソース共有 (CORS) ルールを設定する必要があります：
- [オリジン]：このパラメーターを https://www.aliyun.com のような特定のドメイン名、または https://*.aliyun.com のようなワイルドカード文字 (*) を含むドメイン名に設定します。
- [許可されるメソッド]：シナリオに基づいてメソッドを選択します。たとえば、マルチパートアップロードには [PUT] を、ファイルの削除には [DELETE] を選択します。
- [許可されるヘッダー]：このパラメーターを * に設定します。
- [公開されるヘッダー]：シナリオに基づいて公開されるヘッダーを設定します。たとえば、このパラメーターを ETag、x-oss-request-id、x-oss-version-id に設定します。
詳細については、「CORS の設定」をご参照ください。

注意事項

OSS Browser.js SDK は、ブラウザ用のコードを生成するために Browserify と Babel を使用します。ブラウザ環境では、次の機能は利用できません：

ストリーミングアップロード：ブラウザではチャンクエンコーディングを設定できません。代わりにマルチパートアップロードを使用してください。
ローカルファイル操作：ブラウザからローカルファイルシステムに直接アクセスすることはできません。署名付き URL を使用してファイルをダウンロードしてください。
OSS はバケットに対するクロスオリジンリクエストをサポートしていないため、コンソールを使用してバケット関連の操作を実行する必要があります。

SDK のダウンロード

このドキュメントのデモは SDK 6.x に基づいています。6.x より前のバージョンについては、「5.x 開発ドキュメント」をご参照ください。6.x にアップグレードするには、「アップグレードドキュメント」をご参照ください。

SDK のインストール

サポートされるブラウザ
- IE 10 以降
- Microsoft Edge
- 最新バージョンの Chrome、Firefox、Safari
- 最新バージョンの Android、iOS、Windows Phone のデフォルトブラウザ

インストール方法

Browser.js SDK は、次のいずれかの方法でインストールできます。

ブラウザでのインポート

重要

一部のブラウザは Promise をサポートしていません。Promise 互換性ライブラリをインポートする必要があります。たとえば、IE 10 および IE 11 の場合は、promise-polyfill をインポートする必要があります。

<!-- オンラインリソースのインポート -->
<script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.20.0.min.js"></script>      
<!-- ローカルリソースのインポート -->
<script src="./aliyun-oss-sdk-6.20.0.min.js"></script>

説明

オンラインリソースのインポートは、CDN サーバーの安定性に依存します。ローカルリソースを使用するか、リソースを自分でビルドして、SDK をオフラインでインポートすることを推奨します。
ローカルリソースをインポートする場合、`src` 属性をリソースファイルの相対パスに設定してください。
このトピックでは、バージョン 6.20.0 を例として使用します。他のバージョンについては、「ali-oss」をご参照ください。

コードで OSS オブジェクトを使用します：

重要

Browser.js SDK は通常、ブラウザ環境で使用されます。Alibaba Cloud アカウントの AccessKey ペア (AccessKey ID と AccessKey Secret) の漏洩を防ぐため、一時的なアクセス認証情報を使用して OSS 操作を実行してください。

一時的なアクセス認証情報には、一時的な AccessKey ペア (AccessKey ID と AccessKey Secret) とセキュリティトークンが含まれます。STS の AssumeRole API 操作を呼び出すか、プログラミング言語用の STS SDK を使用して、一時的なアクセス認証情報を取得できます。STS サービスを構築する方法の詳細については、「STS が提供する一時的なアクセス認証情報を使用して OSS にアクセスする」をご参照ください。

<script type="text/javascript">
  const client = new OSS({
    // バケットが配置されているリージョンに region を設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、region を oss-cn-hangzhou に設定します。
    region: 'yourRegion',
    // V4 署名を有効にします。
    authorizationV4: true,
    // STS から取得した一時的な AccessKey ペア (AccessKey ID と AccessKey Secret)。
    accessKeyId: 'yourAccessKeyId',
    accessKeySecret: 'yourAccessKeySecret',
    // STS から取得したセキュリティトークン。
    stsToken: 'yourSecurityToken',
    refreshSTSToken: async () => {
    // STS サービスから一時的なアクセス認証情報を取得します。
      const info = await fetch('your_sts_server');
      return {
        accessKeyId: info.accessKeyId,
        accessKeySecret: info.accessKeySecret,
        stsToken: info.stsToken
      }
    },
    // 一時的なアクセス認証情報を更新する間隔。単位：ミリ秒。
    refreshSTSTokenInterval: 300000,
    // バケット名を指定します。
    bucket: 'examplebucket'
  });
</script>

npm を使用した SDK パッケージのインストール

npm install ali-oss

インストールが完了したら、`import` または `require` を使用してパッケージを参照できます。ブラウザはネイティブで require パターンをサポートしていないため、開発環境では webpack や browserify などのパッケージングツールを使用してください。

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

const client = new OSS({
    // バケットが配置されているリージョンに region を設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、region を oss-cn-hangzhou に設定します。
    region: 'yourRegion',
    // V4 署名を有効にします。
    authorizationV4: true,
    // STS から取得した一時的な AccessKey ペア (AccessKey ID と AccessKey Secret)。
    accessKeyId: 'yourAccessKeyId',
    accessKeySecret: 'yourAccessKeySecret',
    // STS から取得したセキュリティトークン。
    stsToken: 'yourSecurityToken',
    refreshSTSToken: async () => {
    // STS サービスから一時的なアクセス認証情報を取得します。
      const info = await fetch('your_sts_server');
      return {
        accessKeyId: info.accessKeyId,
        accessKeySecret: info.accessKeySecret,
        stsToken: info.stsToken
      }
    },
    // 一時的なアクセス認証情報を更新する間隔。単位：ミリ秒。
    refreshSTSTokenInterval: 300000,
    // バケット名を指定します。
    bucket: 'examplebucket'
});

使用方法

OSS Browser.js SDK は、同期操作と非同期操作をサポートしています。どちらのタイプの操作でも、new OSS() を使用してクライアントを作成します。

同期操作

async/await 構文は ES7 仕様に基づいており、非同期コードを同期スタイルで記述できます。

次の例では、ファイルを同期的にアップロードする方法を説明します。

// OSS クライアントをインスタンス化します。
const client = new OSS(...);

async function put () {
  try {
    // object は OSS にアップロードするファイルの名前を指定します。
    // file はブラウザからアップロードするファイルを指定します。HTML5 ファイルと BLOB 型がサポートされています。
    const r1 = await client.put('object', file);
    console.log('put success: %j', r1);
    const r2 = await client.get('object');
    console.log('get success: %j', r2);
  } catch (e) {
    console.error('error: %j', e);
  }
}

put();

非同期操作

コールバックメソッドと同様に、API 操作は Promise を返します。then() を使用して結果を処理し、catch() を使用してエラーを処理できます。

次の例では、ファイルを非同期にダウンロードする方法を説明します。

// OSS クライアントをインスタンス化します。
const client = new OSS(...);

// object は OSS にアップロードするファイルの名前を指定します。
// file はブラウザからアップロードするファイルを指定します。HTML5 ファイルと BLOB 型がサポートされています。
client.put('object', file).then(function (r1) {
  console.log('put success: %j', r1);
  return client.get('object');
}).then(function (r2) {
  console.log('get success: %j', r2);
}).catch(function (err) {
  console.error('error: %j', err);
});