Node.js SDK を初期化して OSS に接続する - - Alibaba Cloud ドキュメントセンター

クライアントは、Node.js SDK を介して Object Storage Service (OSS) とやり取りするための主要なオブジェクトです。バケットやファイルなどの OSS リソースを管理します。Node.js SDK を使用して OSS リクエストを送信するには、クライアントインスタンスを初期化し、必要に応じてデフォルトの構成を変更します。

注意事項

OSSClient インスタンスを初期化する前に、アクセス認証情報を構成する必要があります。このトピックでは、環境変数を使用する例を示します。詳細については、「アクセス認証情報の設定 (Node.js SDK)」をご参照ください。
OSS のリージョンと対応するエンドポイントについては、「リージョンとエンドポイント」をご参照ください。
Resource Access Management (RAM) ユーザーの AccessKey ペアを作成する方法については、「AccessKey ペアの作成」をご参照ください。

前提条件

重要

クライアントを構成する前に、RAM ユーザーの AccessKey を使用して環境変数を設定する必要があります。

デフォルト構成の例

以下のコード例は、署名バージョン 4 (V4) と署名バージョン 1 (V1) を使用して OSSClient インスタンスを構成する方法を示しています。

署名バージョン 4 (V4) (推奨)

重要

署名バージョン 4 (V4) アルゴリズムで OSSClient インスタンスを初期化する場合、OSS 固有のリージョン ID を指定します。この ID は、リクエストの送信先リージョンを識別します。たとえば、中国 (杭州) リージョンの場合、リージョンを oss-cn-hangzhou に設定します。その他のリージョン ID については、「リージョンとエンドポイント」をご参照ください。
コード内で、署名バージョン 4 (V4) アルゴリズムの使用を明示的に宣言する必要があります。例： authorizationV4: true。

以下のコードは、OSS ドメイン名と署名バージョン 4 (V4) を使用して OSSClient インスタンスを構成する例です。

デフォルトでは、以下のコード例はバケットのパブリックドメイン名と RAM ユーザーの AccessKey 情報を使用します。

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

const client = new OSS({
  // 環境変数からアクセス認証情報を取得します。このコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // バケットが配置されているリージョンに region を設定します。たとえば、中国 (杭州) の場合は、region を oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',
  // 署名バージョン 4 (V4) アルゴリズムを使用します。
  authorizationV4: true,
  // bucket をご使用のバケット名に設定します。
  bucket: 'yourBucketName',
  // endpoint をバケットが配置されているリージョンのパブリックエンドポイントに設定します。たとえば、中国 (杭州) の場合は、endpoint を https://oss-cn-hangzhou.aliyuncs.com に設定します。
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
});

署名バージョン 1 (V1) (非推奨)

重要

2025 年 3 月 1 日以降、OSS の V1 署名アルゴリズムは、新しい UID を持つ新規のお客様にはご利用いただけなくなります。2025 年 9 月 1 日以降、OSS は V1 署名アルゴリズムの更新とメンテナンスを終了し、V1 署名アルゴリズムは新しいバケットでは利用できなくなります。ビジネスへの影響を防ぐため、できるだけ早く V1 署名を V4 署名にアップグレードしてください。

以下のコードは、OSS ドメイン名を使用して OSSClient インスタンスを構成します。さまざまなリージョンの OSS ドメイン名については、「リージョンとエンドポイント」をご参照ください。

OSS ドメイン名を使用したクライアントインスタンスの作成

以下のコードは、OSS ドメイン名を使用してインスタンスを初期化する方法を示しています。

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

const client = new OSS({
  // バケットが配置されているリージョンに region を設定します。たとえば、中国 (杭州) の場合は、region を oss-cn-hangzhou に設定します。
  region: 'yourRegion',
  // 環境変数からアクセス認証情報を取得します。このコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // bucket をご使用のバケット名に設定します。
  bucket: 'yourBucketName',
});

カスタムドメイン名を使用したクライアントインスタンスの作成

以下のコードは、カスタムドメイン名を使用してクライアントインスタンスを作成する方法を示しています。カスタムドメイン名を使用した OSS へのアクセスに関する詳細については、「カスタムドメイン名を使用した OSS へのアクセス」をご参照ください。

重要

カスタムドメイン名を使用する場合、`client.listBuckets()` メソッドは使用できません。

const OSS = require('ali-oss')

const client = new OSS({  
 // カスタムドメイン名をエンドポイントとして使用します。
 endpoint: 'http://img.example.com', 
 // 環境変数からアクセス認証情報を取得します。このコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
 accessKeyId: process.env.OSS_ACCESS_KEY_ID,
 accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
 cname: true,
 // bucket をご使用のバケット名に設定します。
 bucket: 'yourBucketName',
});

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

以下のコード例は、他のドメイン名を構成する方法を示しています。デフォルトでは、これらの例は署名バージョン 4 (V4) と RAM ユーザーの AccessKey 情報を使用します。

内部ドメイン名の構成例

アプリケーションが Alibaba Cloud Elastic Compute Service (ECS) インスタンスにデプロイされており、同じリージョン内の OSS リソースに頻繁にアクセスする必要がある場合は、内部ドメイン名を使用してトラフィックコストを削減し、アクセス速度を向上させることができます。

以下のコードは、OSS の内部ドメイン名を使用して OSSClient インスタンスを構成する例を示しています。

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

const client = new OSS({
  // 環境変数からアクセス認証情報を取得します。このコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // バケットが配置されているリージョンに region を設定します。たとえば、中国 (杭州) の場合は、region を oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',
  // 署名バージョン 4 (V4) を使用します。
  authorizationV4: true,
  // bucket をご使用のバケット名に設定します。
  bucket: 'yourBucketName',
  // endpoint をバケットが配置されているリージョンの内部エンドポイントに設定します。たとえば、中国 (杭州) の場合は、endpoint を https://oss-cn-hangzhou-internal.aliyuncs.com に設定します。
  endpoint: 'yourEndpoint',
});

カスタムドメイン名の構成例

以下のコードは、カスタムドメイン名を使用して OSSClient インスタンスを構成する例を示しています。

警告

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

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

const client = new OSS({
  // 環境変数からアクセス認証情報を取得します。このコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // バケットが配置されているリージョンに region を設定します。たとえば、中国 (杭州) の場合は、region を oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',
  // 署名バージョン 4 (V4) アルゴリズムを使用します。
  authorizationV4: true,
  // bucket をご使用のバケット名に設定します。
  bucket: 'yourBucketName',
  // endpoint をカスタムドメイン名に設定します。例： https://static.example.com。
  endpoint: 'yourEndpoint',
  // cname を true に設定して CNAME オプションを有効にします。
  cname: true,
});

アクセラレーションエンドポイントの構成例

以下のコードは、アクセラレーションエンドポイントを使用して OSSClient インスタンスを構成する例を示しています。

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

const client = new OSS({
  // 環境変数からアクセス認証情報を取得します。このコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // バケットが配置されているリージョンに region を設定します。たとえば、中国 (杭州) の場合は、region を oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',
  // 署名バージョン 4 (V4) を使用します。
  authorizationV4: true,
  // bucket をご使用のバケット名に設定します。
  bucket: 'yourBucketName',
  // endpoint をアクセラレーションエンドポイントに設定します。例： oss-accelerate.aliyuncs.com。
  endpoint: 'oss-accelerate.aliyuncs.com',
});

:初期化 (Node.js SDK)