Object Storage Service:Node.js 用 OSS SDK

環境の準備

Node.js ランタイム環境をダウンロードしてインストールします。最適な互換性とパフォーマンスを確保するために、Node.js 8.0 以降の使用を推奨します。

• node -v コマンドを実行して、Node.js のバージョンを確認します。

• npm -v コマンドを実行して、npm のバージョンを確認します。

SDK のインストール

Node.js のバージョンに基づいて SDK のバージョンを選択します。

• Node.js 8.0 以降：最新の SDK 6.x バージョンを使用します。

• Node.js 8.0 より前：SDK 4.x バージョンを使用します。

npm install ali-oss@^6.x --save

npm install ali-oss@^4.x --save

インストールが完了したら、npm list ali-oss コマンドを実行してインストールを検証できます。インストールが成功すると、SDK のバージョンが表示されます。

アクセス認証情報の設定

Resource Access Management (RAM) ユーザーの AccessKey ペアを使用してアクセス認証情報を設定します。

1. RAM コンソールで、[永続的な AccessKey ペア] を持つ RAM ユーザーを作成します。AccessKey ペアを保存し、ユーザーに AliyunOSSFullAccess 権限を付与します。

2. RAM ユーザーの AccessKey ペアを使用して環境変数を設定します。

   Linux

   1. コマンドラインインターフェイスで次のコマンドを実行して、環境変数の設定を ~/.bashrc ファイルに追加します。

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

   2. 次のコマンドを実行して変更を適用します。

      source ~/.bashrc

   3. 次のコマンドを実行して、環境変数が設定されていることを確認します。

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. ターミナルで次のコマンドを実行して、デフォルトのシェルタイプを表示します。

      echo $SHELL

   2. デフォルトのシェルタイプに基づいて、次の操作を実行します。

      Zsh

      1. 次のコマンドを実行して、環境変数の設定を ~/.zshrc ファイルに追加します。

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

      2. 次のコマンドを実行して変更を適用します。

         source ~/.zshrc

      3. 次のコマンドを実行して、環境変数が設定されていることを確認します。

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. 次のコマンドを実行して、環境変数の設定を ~/.bash_profile ファイルに追加します。

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

      2. 次のコマンドを実行して変更を適用します。

         source ~/.bash_profile

      3. 次のコマンドを実行して、環境変数が設定されていることを確認します。

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. CMD で次のコマンドを実行します。

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

   2. 次のコマンドを実行して、環境変数が設定されていることを確認します。

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. PowerShell で次のコマンドを実行します。

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

   2. 次のコマンドを実行して、環境変数が設定されていることを確認します。

      [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

クライアントの初期化

次のサンプルコードでは、中国 (杭州) リージョンのパブリックエンドポイントを使用してクライアントを初期化し、アカウント内のバケットを一覧表示することで SDK 設定を検証します。リージョンとエンドポイントの完全なリストについては、「リージョンとエンドポイント」をご参照ください。

// Node.js 用 OSS SDK を使用して OSS クライアントを初期化するサンプルコード

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

async function main() {
    
    // 環境変数からアクセス認証情報を取得します。環境変数 OSS_ACCESS_KEY_ID と OSS_ACCESS_KEY_SECRET を設定する必要があります。
    const client = new OSS({
        // リージョンを oss-cn-hangzhou (中国 (杭州) リージョン) に設定します。
        region: 'oss-cn-hangzhou',
        // 環境変数からアクセス認証情報を取得します。
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // 署名 V4 を有効にします。
        authorizationV4: true,
    });

    try {
        // すべてのバケットを一覧表示します。
        const result = await client.listBuckets();
        
        // バケットのリストを出力します。
        console.log(`Found ${result.buckets.length} buckets:`);
        
        for (const bucket of result.buckets) {
            console.log(bucket.name);
        }
        
    } catch (err) {
        console.log('Failed to list buckets. Details:');
        console.error(err);
        return;
    }
}

// main 関数を実行します。
main().catch(console.error);

内部エンドポイントの使用

内部ネットワーク経由で OSS にアクセスすることで、データ転送料金を回避し、高速なアクセスと高いセキュリティを実現できます。内部ネットワーク経由で OSS にアクセスするには、クライアントの初期化時にエンドポイントを内部エンドポイントに設定します。

const client = new OSS({
    // リージョンを oss-cn-hangzhou (中国・杭州) に設定します。
    region: 'oss-cn-hangzhou',
    // 環境変数からアクセス認証情報を取得します。
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    // 署名バージョン 4 を有効にします。
    authorizationV4: true,
    // 中国 (杭州) リージョンの内部エンドポイントを使用します。
    endpoint: 'https://oss-cn-hangzhou-internal.aliyuncs.com',
});

カスタムドメイン名の使用

カスタムドメイン名を使用して OSS にアクセスするには、クライアントの初期化時にエンドポイントをカスタムドメイン名に設定し、cname: true パラメータを設定して CNAME オプションを有効にします。

カスタムドメイン名を使用する前に、カスタムドメイン名がバケットにマッピングされていることを確認してください。詳細については、「カスタムドメイン名を使用した OSS へのアクセス」をご参照ください。

// 環境変数からアクセス認証情報を取得します。 OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数を設定する必要があります。
const client = new OSS({
    // リージョンを oss-cn-hangzhou (中国・杭州) に設定します。
    region: 'oss-cn-hangzhou',
    // 環境変数からアクセス認証情報を取得します。
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    // 署名バージョン 4 を有効にします。
    authorizationV4: true,
    // カスタムドメイン名を使用します。
    endpoint: 'http://example.com',
    // バケット名を指定します。バケット名はカスタムドメイン名にマッピングされている必要があります。
    bucket: 'example-bucket',
    // CNAME オプションを有効にします。
    cname: true,
});

アクセラレーションエンドポイントの使用

アクセスを高速化するには、OSS クライアントの初期化時にエンドポイントをアクセラレーションエンドポイントに設定します。

// 環境変数からアクセス認証情報を取得します。 OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数を設定する必要があります。
const client = new OSS({
    // リージョンを oss-cn-hangzhou (中国・杭州) に設定します。
    region: 'oss-cn-hangzhou',
    // 環境変数からアクセス認証情報を取得します。
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    // 署名バージョン 4 を有効にします。
    authorizationV4: true,
    // アクセラレーションエンドポイントを使用します。
    endpoint: 'https://oss-accelerate.aliyuncs.com',
    // 転送アクセラレーションが有効なバケット名を指定します。
    bucket: 'example-bucket',
});

署名バージョン

次のサンプルコードは、署名バージョン 1 を使用してクライアントを初期化する例です。署名バージョン 4 を使用してクライアントを初期化する方法のサンプルについては、クライアントの初期化をご参照ください。

// OSS SDK for Node.js を使用して OSS クライアントを初期化するサンプルコード

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

async function main() {
    
    // 環境変数からアクセス認証情報を取得します。 OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数を設定する必要があります。
    const client = new OSS({
        // 環境変数からアクセス認証情報を取得します。
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    });

    try {
        // すべてのバケットを一覧表示します。
        const result = await client.listBuckets();
        
        // バケットのリストを出力します。
        console.log(`Found ${result.buckets.length} buckets:`);
        
        for (const bucket of result.buckets) {
            console.log(bucket.name);
        }
        
    } catch (err) {
        console.log('Failed to list buckets. Details:');
        console.error(err);
        return;
    }
}

// main 関数を実行します。
main().catch(console.error);

ファイルのアップロード

次の例は、ローカルファイルを OSS バケットにアップロードする方法を示します。また、カスタムリクエストヘッダーを使用してファイルプロパティを設定し、ストレージクラス、アクセス権限、タグをきめ細かく制御する方法も示します。

// OSS SDK for Node.js を使用してファイルをアップロードするサンプルコード

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

async function main() {
    
    // 環境変数からアクセス認証情報を取得します。環境変数 OSS_ACCESS_KEY_ID と OSS_ACCESS_KEY_SECRET を設定する必要があります。
    const client = new OSS({
        // リージョンを oss-cn-hangzhou (China (Hangzhou) リージョン) に設定します。
        region: 'oss-cn-hangzhou',
        // 環境変数からアクセス認証情報を取得します。
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // 署名 V4 を有効にします。
        authorizationV4: true,
        // バケット名を指定します。
        bucket: 'example-bucket',
    });

    // カスタムリクエストヘッダー。
    const headers = {
        // オブジェクトのストレージクラスを指定します。
        'x-oss-storage-class': 'Standard',
        // オブジェクトのアクセス制御リスト (ACL) を指定します。
        'x-oss-object-acl': 'private',
        // URL 経由でアクセスした場合に、ファイルを添付ファイルとしてダウンロードするよう指定します。
        'Content-Disposition': 'attachment',
        // オブジェクトにタグを設定します。複数のタグを設定できます。
        'x-oss-tagging': 'Tag1=1&Tag2=2',
        // 同名のオブジェクトの上書きを禁止するかどうかを指定します。この例では、このパラメーターを `true` に設定し、上書きを禁止します。
        'x-oss-forbid-overwrite': 'true',
    };

    try {
        // ファイル情報を設定します。
        const key = 'dest.jpg';                    // OSS 内のファイルのパス。
        const localFilePath = path.normalize('dest.jpg'); // ローカルファイルのフルパス。
        
        // ローカルファイルを OSS の指定されたパスにアップロードします。
        const result = await client.put(key, localFilePath, { headers });
        
        console.log(`File uploaded: ${localFilePath} -> ${key}`);
        console.log('Upload result:', result);
        
    } catch (err) {
        console.log('Upload failed. Details:');
        console.error(err);
        return;
    }
}

// main 関数を実行します。
main().catch(console.error);

ファイルのダウンロード

次の例は、OSS バケットから指定されたローカルパスにファイルをダウンロードする方法を示します。

// OSS SDK for Node.js を使用してファイルをダウンロードするサンプルコード

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

async function main() {
    
    // 環境変数からアクセス認証情報を取得します。環境変数 OSS_ACCESS_KEY_ID と OSS_ACCESS_KEY_SECRET を設定する必要があります。
    const client = new OSS({
        // リージョンを oss-cn-hangzhou (China (Hangzhou) リージョン) に設定します。
        region: 'oss-cn-hangzhou',
        // 環境変数からアクセス認証情報を取得します。
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // 署名 V4 を有効にします。
        authorizationV4: true,
        // バケット名を指定します。
        bucket: 'example-bucket',
    });

    try {
        // ファイル情報を設定します。
        const key = 'dest.jpg';       // OSS 内のファイルのパス。
        const filePath = 'dest.jpg';  // ファイルを保存するローカルパス。
        
        // OSS から指定されたローカルパスにファイルをダウンロードします。
        const result = await client.get(key, filePath);
        
        console.log(`File downloaded: ${key} -> ${filePath}`);
        
    } catch (err) {
        console.log('Download failed. Details:');
        console.error(err);
        return;
    }
}

// main 関数を実行します。
main().catch(console.error);

ファイルの削除

次の例は、OSS バケットから指定されたファイルを削除する方法を示します。

// OSS SDK for Node.js を使用してファイルを削除するサンプルコード

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

async function main() {
    
    // 環境変数からアクセス認証情報を取得します。環境変数 OSS_ACCESS_KEY_ID と OSS_ACCESS_KEY_SECRET を設定する必要があります。
    const client = new OSS({
        // リージョンを oss-cn-hangzhou (China (Hangzhou) リージョン) に設定します。
        region: 'oss-cn-hangzhou',
        // 環境変数からアクセス認証情報を取得します。
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // 署名 V4 を有効にします。
        authorizationV4: true,
        // バケット名を指定します。
        bucket: 'example-bucket',
    });

    try {
        // ファイル情報を設定します。
        const key = 'dest.jpg';  // OSS 内で削除するファイルのパス。
        
        // OSS から指定されたファイルを削除します。
        const result = await client.delete(key);
        
        console.log(`File deleted: ${key}`);
        console.log('Delete result:', result);
        
    } catch (err) {
        console.log('Delete failed. Details:');
        console.error(err);
        return;
    }
}

// main 関数を実行します。
main().catch(console.error);

ファイルの一覧表示

次の例は、OSS バケット内のファイルを一覧表示する方法を示します。デフォルトでは、最大 100 件のファイルの詳細が返されます。

// OSS SDK for Node.js を使用してファイルを一覧表示するサンプルコード

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

async function main() {
    
    // 環境変数からアクセス認証情報を取得します。環境変数 OSS_ACCESS_KEY_ID と OSS_ACCESS_KEY_SECRET を設定する必要があります。
    const client = new OSS({
        // リージョンを oss-cn-hangzhou (China (Hangzhou) リージョン) に設定します。
        region: 'oss-cn-hangzhou',
        // 環境変数からアクセス認証情報を取得します。
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // 署名 V4 を有効にします。
        authorizationV4: true,
        // バケット名を指定します。
        bucket: 'example-bucket',
    });

    try {
        // デフォルトでは、パラメーターが指定されていない場合、最大 100 件のファイルが返されます。
        const result = await client.list();
        
        console.log(`Found ${result.objects ? result.objects.length : 0} files:`);
        
        // ファイルのリストを出力します。
        if (result.objects && result.objects.length > 0) {
            for (const object of result.objects) {
                console.log(`File name: ${object.name}, Size: ${object.size} bytes, Last modified: ${object.lastModified}`);
            }
        } else {
            console.log('No files found in the bucket.');
        }
        
    } catch (err) {
        console.log('Failed to list files. Details:');
        console.error(err);
        return;
    }
}

// main 関数を実行します。
main().catch(console.error);

RAM ユーザーの AccessKey ペアの使用

この方法は、安全で安定した環境にデプロイされ、OSS への長期アクセスが必要で、認証情報の頻繁なローテーションを必要としないアプリケーションに適しています。Alibaba Cloud アカウントまたは RAM ユーザーの AccessKey ペア (AccessKey ID と AccessKey シークレット) を使用して認証情報プロバイダーを初期化できます。この方法では AccessKey ペアを手動で管理する必要があり、セキュリティリスクが生じ、メンテナンスの複雑さが増す可能性があります。

1. RAM ユーザーの AccessKey ペアを使用して環境変数を設定します。

   Linux

   1. コマンドラインインターフェイスで次のコマンドを実行して、環境変数の設定を ~/.bashrc ファイルに追加します。

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

   2. 次のコマンドを実行して変更を適用します。

      source ~/.bashrc

   3. 次のコマンドを実行して、環境変数が設定されていることを確認します。

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. ターミナルで次のコマンドを実行して、デフォルトのシェルタイプを表示します。

      echo $SHELL

   2. デフォルトのシェルタイプに基づいて、次の操作を実行します。

      Zsh

      1. 次のコマンドを実行して、環境変数の設定を ~/.zshrc ファイルに追加します。

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

      2. 次のコマンドを実行して変更を適用します。

         source ~/.zshrc

      3. 次のコマンドを実行して、環境変数が設定されていることを確認します。

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. 次のコマンドを実行して、環境変数の設定を ~/.bash_profile ファイルに追加します。

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

      2. 次のコマンドを実行して変更を適用します。

         source ~/.bash_profile

      3. 次のコマンドを実行して、環境変数が設定されていることを確認します。

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. CMD で次のコマンドを実行します。

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

   2. 次のコマンドを実行して、環境変数が設定されていることを確認します。

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. PowerShell で次のコマンドを実行します。

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

   2. 次のコマンドを実行して、環境変数が設定されていることを確認します。

      [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

2. システム環境変数を変更した後は、最新のシステム環境変数が読み込まれるよう、IDE、コマンドラインインターフェイス、その他のデスクトップアプリケーション、バックエンドサービスなどのコンパイルおよびランタイム環境を再起動または更新してください。

3. 環境変数を使用して認証情報を渡します。

   const OSS = require("ali-oss");
   
   // OSS を初期化します。
   const client = new OSS({
     // 環境変数から AccessKey ID の値を取得します。
     accessKeyId: process.env.OSS_ACCESS_KEY_ID,
     // 環境変数から AccessKey シークレットの値を取得します。
     accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);

STS トークンの使用

この方法は、OSS への一時的なアクセスが必要なアプリケーションに適しています。STS から取得した一時的な ID 認証情報 (AccessKey ID、AccessKey シークレット、セキュリティトークン) を使用して認証情報プロバイダーを初期化できます。この方法では STS トークンを手動で管理する必要があり、セキュリティリスクが生じ、メンテナンスの複雑さが増す可能性があります。OSS に複数回一時的にアクセスするには、STS トークンを手動で更新する必要があります。

1. 一時的な ID 認証情報を使用して環境変数を設定します。

   macOS、Linux、Unix

   重要

   • RAM ユーザーの AccessKey ペアではなく、STS から取得した一時的な ID 認証情報 (AccessKey ID、AccessKey シークレット、セキュリティトークン) を使用してください。

   • STS から取得した AccessKey ID は「STS」で始まります。例：「STS.****************」。

   export OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
   export OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
   export OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

   Windows

   重要

   • RAM ユーザーの AccessKey ペア (AccessKey ID と AccessKey シークレット) ではなく、STS から取得した一時的な ID 認証情報 (AccessKey ID、AccessKey シークレット、セキュリティトークン) を使用してください。

   • STS から取得した AccessKey ID は「STS」で始まります。例：「STS.****************」。

   set OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
   set OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
   set OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

2. 環境変数を使用して認証情報を渡します。

   const OSS = require("ali-oss");
   
   // OSS を初期化します。
   const client = new OSS({
     // 環境変数から AccessKey ID の値を取得します。
     accessKeyId: process.env.OSS_ACCESS_KEY_ID,
     // 環境変数から AccessKey シークレットの値を取得します。
     accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
     // 環境変数から STS トークンの値を取得します。
     stsToken: process.env.OSS_SESSION_TOKEN
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);

RAM ロール ARN の使用

この方法は、クロスアカウントアクセスなど、OSS への認可されたアクセスが必要なアプリケーションに適しています。RAM ロールの Alibaba Cloud リソースネーム (ARN) を指定して認証情報プロバイダーを初期化できます。この方法は STS トークンに基づいています。認証情報ツールは STS から STS トークンを取得し、現在のトークンが期限切れになる前に AssumeRole API を呼び出して新しい STS トークンを要求します。policy パラメーターに値を割り当てて、RAM ロールの権限をさらに制限することもできます。

1. credentials 依存関係を追加します。

   npm install @alicloud/credentials

2. AccessKey ペアと RAM ロール ARN をアクセス認証情報として設定します。

   const Credential = require("@alicloud/credentials");
   const OSS = require("ali-oss");
   
   // RAM ロール ARN を使用して Credentials クライアントを初期化します。
   const credentialsConfig = new Credential.Config({
     // 認証情報タイプ。
     type: "ram_role_arn",
     // 環境変数から AccessKey ID の値を取得します。
     accessKeyId: process.env.OSS_ACCESS_KEY_ID,
     // 環境変数から AccessKey シークレットの値を取得します。
     accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
     // 引き受ける RAM ロールの ARN。例：acs:ram::123456789012****:role/adminrole。ALIBABA_CLOUD_ROLE_ARN 環境変数を使用して roleArn を設定できます。
     roleArn: '<RoleArn>',
     // ロールセッションの名前。ALIBABA_CLOUD_ROLE_SESSION_NAME 環境変数を使用して RoleSessionName を設定できます。
     roleSessionName: '<RoleSessionName>',
     // より制限的なアクセスポリシー。このパラメーターはオプションです。例：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
     // policy: '<Policy>',
     roleSessionExpiration: 3600
   });
   const credentialClient = new Credential.default(credentialsConfig);
   const credential = await credentialClient.getCredential();
   
   // OSS を初期化します。
   const client = new OSS({
     accessKeyId:credential.accessKeyId,
     accessKeySecret: credential.accessKeySecret,
     stsToken: credential.securityToken,
     refreshSTSTokenInterval: 0, // 認証情報プロバイダーが accessKeyId、accessKeySecret、stsToken の更新を制御します。
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);

ECS RAM ロールの使用

この方法は、ECS インスタンス、ECI インスタンス、または Container Service for Kubernetes のワーカーノードで実行されるアプリケーションに適しています。ECS RAM ロールを使用して認証情報プロバイダーを初期化することを推奨します。この方法は STS トークンに基づいています。ECS RAM ロールを使用すると、ECS インスタンス、ECI インスタンス、または Container Service for Kubernetes のワーカーノードにロールをアタッチして、インスタンス内で STS トークンを自動的に更新できます。この方法では AccessKey ペアや STS トークンを提供する必要がなく、手動メンテナンスに伴うリスクが軽減されます。ECS RAM ロールを取得する方法については、「信頼できる Alibaba Cloud アカウント用の RAM ロールを作成」をご参照ください。ECS インスタンスにロールをアタッチする方法については、「インスタンス RAM ロールのアタッチ」をご参照ください。

1. credentials 依存関係を追加します。

   npm install @alicloud/credentials

2. ECS RAM ロールをアクセス認証情報として設定します。

   const Credential = require("@alicloud/credentials");
   const OSS = require("ali-oss");
   
   // ECS RAM ロールを使用して Credentials クライアントを初期化します。
   const credentialsConfig = new Credential.Config({
     // 認証情報タイプ。
     type: "ecs_ram_role",
     // オプション。ECS ロールの名前。このパラメーターを指定しない場合、ロール名は自動的に取得されます。リクエスト数を減らすため、このパラメーターを指定することを推奨します。ALIBABA_CLOUD_ECS_METADATA 環境変数を使用して roleName を設定できます。
     roleName: '<RoleName>'
   });
   const credentialClient = new Credential.default(credentialsConfig);
   
   const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
   
   // OSS クライアントを初期化します。
   const client = new OSS({
     accessKeyId,
     accessKeySecret,
     stsToken: securityToken,
     refreshSTSTokenInterval: 0, // 認証情報プロバイダーが accessKeyId、accessKeySecret、stsToken の更新を制御します。
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
       
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);

OIDC ロール ARN の使用

Container Service for Kubernetes のワーカーノード用に RAM ロールを設定すると、それらのノード上の Pod 内のアプリケーションは、グローバルメタサービスを通じてアタッチされたロールの STS トークンを取得できます。このプロセスは、ECS にデプロイされたアプリケーションが認証情報を取得する方法と似ています。ただし、クローズドソースコードの顧客のアプリケーションなど、信頼できないアプリケーションがコンテナクラスターにデプロイされている場合、それらがワーカーノードにアタッチされたインスタンス RAM ロールの STS トークンを取得することは望ましくない場合があります。クラウドリソースのセキュリティを確保しながら、これらの信頼できないアプリケーションが必要な STS トークンを安全に取得し、アプリケーションレベルでの権限最小化を実現するために、サービスアカウント用の RAM ロール (RRSA) 機能を使用できます。この方法は STS トークンに基づいています。Alibaba Cloud コンテナクラスターは、異なるアプリケーション Pod 用に対応するサービスアカウント OIDC トークンファイルを作成してマウントし、関連する設定情報を環境変数に注入します。認証情報ツールは環境変数から設定情報を取得し、STS の AssumeRoleWithOIDC API を呼び出して、バインドされたロールの STS トークンと交換します。この方法では AccessKey ペアや STS トークンを提供する必要がなく、手動メンテナンスに伴うリスクが軽減されます。詳細については、「RRSA を使用して ServiceAccount の RAM 権限を設定し、Pod レベルの権限分離を実現」をご参照ください。

1. credentials 依存関係を追加します。

   npm install @alicloud/credentials

2. OIDC RAM ロールをアクセス認証情報として設定します。

   const OSS = require("ali-oss");
   const Credential = require("@alicloud/credentials");
   
   const credentialsConfig = new Credential.Config({
     // 認証情報タイプ。
     type: "oidc_role_arn",
     // RAM ロールの ARN。ALIBABA_CLOUD_ROLE_ARN 環境変数を使用して roleArn を設定できます。
     roleArn: '<RoleArn>',
     // OIDC プロバイダーの ARN。ALIBABA_CLOUD_OIDC_PROVIDER_ARN 環境変数を使用して oidcProviderArn を設定できます。
     oidcProviderArn: '<OidcProviderArn>',
     // OIDC トークンファイルのパス。ALIBABA_CLOUD_OIDC_TOKEN_FILE 環境変数を使用して oidcTokenFilePath を設定できます。
     oidcTokenFilePath: '<OidcTokenFilePath>',
     // ロールセッションの名前。ALIBABA_CLOUD_ROLE_SESSION_NAME 環境変数を使用して roleSessionName を設定できます。
     roleSessionName: '<RoleSessionName>',
     // より制限的なアクセスポリシー。このパラメーターはオプションです。例：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
     // policy: "<Policy>",
     // セッションの有効期限を設定します。
     roleSessionExpiration: 3600
   });
   const credentialClient = new Credential.default(credentialsConfig);
   const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
   const client = new OSS({
     accessKeyId,
     accessKeySecret,
     stsToken: securityToken,
     refreshSTSTokenInterval: 0, // 認証情報プロバイダーが accessKeyId、accessKeySecret、stsToken の更新を制御します。
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
       
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   const buckets = await client.listBuckets();
   
   console.log(buckets);

認証情報 URI の使用

この方法は、柔軟な認証情報管理とキーレスアクセスのために、外部システムから Alibaba Cloud 認証情報を取得する必要があるアプリケーションに適しています。認証情報 URI を使用して認証情報プロバイダーを初期化できます。この方法は STS トークンに基づいています。認証情報ツールは、提供された URI から STS トークンを取得して認証情報クライアントを初期化します。この方法では AccessKey ペアや STS トークンを提供する必要がなく、手動メンテナンスに伴うリスクが軽減されます。

1. 認証情報ツールが STS トークンを正しく解析して使用できるようにするため、URI は次のレスポンスプロトコルに準拠する必要があります。

   • レスポンスステータスコード：200

   • レスポンスボディ構造：

     {
         "Code": "Success",
         "AccessKeySecret": "AccessKeySecret",
         "AccessKeyId": "AccessKeyId",
         "Expiration": "2021-09-26T03:46:38Z",
         "SecurityToken": "SecurityToken"
     }

2. credentials 依存関係を追加します。

   npm install @alicloud/credentials

3. 認証情報 URI をアクセス認証情報として設定します。

   const OSS = require("ali-oss");
   const Credential = require("@alicloud/credentials");
   
   // 認証情報 URI を使用して Credentials クライアントを初期化します。
   const credentialsConfig = new Credential.Config({
     // 認証情報タイプ。
     type: "credentials_uri",
     // 認証情報を取得する URI。形式は http://local_or_remote_uri/ です。ALIBABA_CLOUD_CREDENTIALS_URI 環境変数を使用して credentialsUri を設定できます。
     credentialsURI: '<CredentialsUri>'
   });
   const credentialClient = new Credential.default(credentialsConfig);
   const credential = await credentialClient.getCredential();
   
   // OSS を初期化します。
   const client = new OSS({
     accessKeyId: credential.accessKeyId,
     accessKeySecret: credential.accessKeySecret,
     stsToken: credential.securityToken,
     refreshSTSTokenInterval: 0, // 認証情報プロバイダーが accessKeyId、accessKeySecret、stsToken の更新を制御します。
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
   
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);