Node.js SDK を使用してオブジェクトタグを設定する方法 - Object Storage Service

OSS は、バケット内のオブジェクトを分類するためのオブジェクトタグ付けをサポートしています。同じタグを持つオブジェクトに対して、ライフサイクルルールやアクセス権限を設定できます。

注意事項

オブジェクトタグを設定する前に、この機能について理解しておく必要があります。詳細については、「オブジェクトタグ付け」をご参照ください。

このトピックでは、中国 (杭州) リージョンのパブリックエンドポイントを使用します。同一リージョン内の他の Alibaba Cloud サービスから OSS にアクセスする場合は、内部エンドポイントを使用してください。サポートされているリージョンとエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。
このトピックでは、アクセス認証情報は環境変数から取得します。アクセス認証情報の設定方法の詳細については、「アクセス認証情報の設定」をご参照ください。
このトピックでは、OSS エンドポイントを使用して OSSClient インスタンスを作成します。カスタムドメイン名または Security Token Service (STS) を使用して OSSClient インスタンスを作成する場合は、「一般的なシナリオの設定例」をご参照ください。
オブジェクトタグ付けは、Java SDK 3.5.0 以降でのみサポートされています。
オブジェクトタグを設定するには、oss:PutObjectTagging 権限が必要です。詳細については、「RAM ユーザーへのカスタムアクセスポリシーの付与」をご参照ください。

オブジェクトアップロード時のオブジェクトタグの追加

シンプルアップロード時のオブジェクトタグの追加

次のコードは、PutObject メソッドを使用してシンプルアップロード中にオブジェクトタグを追加する方法を示しています。

const OSS = require('ali-oss')

const client = new OSS({
  // バケットが配置されているリージョンに設定します。たとえば、中国 (杭州) の場合は 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,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: 'yourbucketname'
});

// オブジェクトの完全なパスを指定します。完全なパスにバケット名を含めることはできません。例：exampledir/exampleobject.txt。
const objectName = 'exampledir/exampleobject.txt'
// ローカルファイルの完全なパスを指定します。例：D:\\localpath\\examplefile.txt。
// 完全なパスを指定せずにローカルファイル名 (例：examplefile.txt) のみを指定した場合、ファイルはサンプルプログラムのプロジェクトに対応するローカルパスからアップロードされます。
const localFilepath = 'D:\\localpath\\examplefile.txt'

// リクエストヘッダーを設定します。
const headers = {
  // オブジェクトタグのキー (例：owner) と値 (例：John) を指定します。
  'x-oss-tagging': 'owner=John&type=document', 
}

client.put(objectName, localFilepath, {
  headers
})

マルチパートアップロード時のオブジェクトタグの追加

次のコードは、multipartUpload メソッドを使用してマルチパートアップロード中にオブジェクトタグを追加する方法を示しています。

const OSS = require('ali-oss')

const client = new OSS({
  // バケットが配置されているリージョンに設定します。たとえば、中国 (杭州) の場合は 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,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: 'yourbucketname'
});

// オブジェクトの完全なパスを指定します。完全なパスにバケット名を含めることはできません。例：exampledir/exampleobject.txt。
const objectName = 'exampledir/exampleobject.txt'
// ローカルファイルの完全なパスを指定します。例：D:\\localpath\\examplefile.txt。
// 完全なパスを指定せずにローカルファイル名 (例：examplefile.txt) のみを指定した場合、ファイルはサンプルプログラムのプロジェクトに対応するローカルパスからアップロードされます。
const localFilepath = 'D:\\localpath\\examplefile.txt'

// リクエストヘッダーを設定します。
const headers = {
  // オブジェクトタグのキー (例：owner) と値 (例：John) を指定します。
  'x-oss-tagging': 'owner=John&type=document', 
}


async function setTag() {
  await client.multipartUpload(objectName, localFilepath, {
    // パートサイズをバイト単位で設定します。最小パートサイズは 100 KB です。最後のパートのサイズに制限はありません。
    partSize: 100 * 1024,
    headers
  });
  const tag = await client.getObjectTagging(objectName);
  console.log(tag);
}

setTag()

追加アップロード時のオブジェクトタグの追加

次のコードは、AppendObject メソッドを使用して追加アップロード中にオブジェクトタグを追加する方法を示しています。

const OSS = require('ali-oss')

const client = new OSS({
  // バケットが配置されているリージョンに設定します。たとえば、中国 (杭州) の場合は 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,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: 'yourbucketname'
});

// オブジェクトの完全なパスを指定します。完全なパスにバケット名を含めることはできません。例：exampledir/exampleobject.txt。
const objectName = 'exampledir/exampleobject.txt'
// ローカルファイルの完全なパスを指定します。例：D:\\localpath\\examplefile.txt。
// 完全なパスを指定せずにローカルファイル名 (例：examplefile.txt) のみを指定した場合、ファイルはサンプルプログラムのプロジェクトに対応するローカルパスからアップロードされます。
const localFilepath = 'D:\\localpath\\examplefile.txt'

// リクエストヘッダーを設定します。
const headers = {
  // オブジェクトタグのキー (例：owner) と値 (例：John) を指定します。
  'x-oss-tagging': 'owner=John&type=document',
}


// オブジェクトにデータを追加します。追加操作でヘッダーを指定すると、オブジェクトにタグが設定されます。
// 最初の追加操作で設定されたタグのみが有効になります。後続の追加操作で設定されたタグは無視されます。
async function setTag() {
  await client.append(objectName, localFilepath, {
    // パートサイズをバイト単位で設定します。最小パートサイズは 100 KB です。最後のパートのサイズに制限はありません。
    partSize: 100 * 1024,
    headers
  });
  const tag = await client.getObjectTagging(objectName);
  console.log(tag);
}


setTag()

再開可能なアップロード時のオブジェクトタグの追加

次のコードは、multipartUpload メソッドを使用して再開可能なアップロード中にオブジェクトタグを追加する方法を示しています。

const OSS = require('ali-oss')

const client = new OSS({
  // バケットが配置されているリージョンに設定します。たとえば、中国 (杭州) の場合は 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,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: 'yourbucketname'
});

// オブジェクトの完全なパスを指定します。完全なパスにバケット名を含めることはできません。例：exampledir/exampleobject.txt。
const objectName = 'exampledir/exampleobject.txt'
// ローカルファイルの完全なパスを指定します。例：D:\\localpath\\examplefile.txt。
// 完全なパスを指定せずにローカルファイル名 (例：examplefile.txt) のみを指定した場合、ファイルはサンプルプログラムのプロジェクトに対応するローカルパスからアップロードされます。
const localFilepath = 'D:\\localpath\\examplefile.txt'
// チェックポイント情報を設定します。
let checkpoint;

// リクエストヘッダーを設定します。
const headers = {
  // オブジェクトタグのキー (例：owner) と値 (例：John) を指定します。
  'x-oss-tagging': 'owner=John&type=document',
}


async function setTag() {
  await client.multipartUpload(objectName, localFilepath, {
    checkponit,
    async progress(percentage, cpt) {
      checkpoint = cpt;
    },
    headers
  });
  const tag = await client.getObjectTagging(objectName);
  console.log(tag);
}

setTag()

既存オブジェクトのオブジェクトタグの追加または変更

オブジェクトのアップロード時にオブジェクトタグを追加しなかった場合、または既存のタグが要件を満たさない場合は、アップロード後にオブジェクトのタグを追加または変更できます。

次のコードは、既存のオブジェクトのオブジェクトタグを追加または変更する方法を示しています。

const OSS = require('ali-oss')

const client = new OSS({
  // バケットが配置されているリージョンに設定します。たとえば、中国 (杭州) の場合は 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,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: 'yourbucketname'
});

// オブジェクトの完全なパスを指定します。完全なパスにバケット名を含めることはできません。例：exampledir/exampleobject.txt。
const objectName = 'exampledir/exampleobject.txt'
// オブジェクトタグのキー (例：owner) と値 (例：John) を指定します。
const tag = { owner: 'John', type: 'document' };

async function putObjectTagging(objectName, tag) {
  try {
    const result = await client.putObjectTagging(objectName, tag);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

putObjectTagging(objectName, tag)

特定バージョンのオブジェクトのオブジェクトタグの追加または変更

バージョン管理が有効なバケットでは、バージョン ID を指定することで、オブジェクトの特定のバージョンのオブジェクトタグを追加または変更できます。

次のコードは、オブジェクトの特定のバージョンのオブジェクトタグを追加または変更する方法を示しています。

説明

バージョン ID の取得方法の詳細については、「オブジェクトのリスト (Node.js SDK)」をご参照ください。

const OSS = require('ali-oss')

const client = new OSS({
  // バケットが配置されているリージョンに設定します。たとえば、中国 (杭州) の場合は 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,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: 'yourbucketname'
});

// オブジェクトの完全なパスを指定します。完全なパスにバケット名を含めることはできません。例：exampledir/exampleobject.txt。
const objectName = 'exampledir/exampleobject.txt'
// オブジェクトタグのキー (例：owner) と値 (例：John) を指定します。
const tag = { owner: 'John', type: 'document' };
// オブジェクトのバージョン ID を指定します。
const versionId='CAEQIRiBgMDqvPqA3BciIDJhMjE4MWZkN2ViYTRmYzJhZjkxMzk2YWM2NjJk****'

async function putObjectTagging(objectName, tag) {
  try {
    const options = {
      versionId
    };
    const result = await client.putObjectTagging(objectName, tag, options);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

putObjectTagging(objectName, tag)

オブジェクトコピー時のオブジェクトタグの設定

オブジェクトをコピーするときに、宛先オブジェクトのタグをどのように設定するかを指定できます。有効な値は次のとおりです。

Copy (デフォルト)：ソースオブジェクトのタグを宛先オブジェクトにコピーします。
Replace：ソースオブジェクトのタグを無視し、リクエストで指定されたタグを宛先オブジェクトに適用します。

次の例は、オブジェクトをコピーするときにオブジェクトタグを設定する方法を示しています。1 GB 未満のオブジェクトにはシンプルコピーが使用され、1 GB を超えるオブジェクトにはマルチパートコピーが使用されます。

シンプルコピー時のオブジェクトタグの追加

次のコードは、1 GB 未満のオブジェクトのシンプルコピーを実行するときにオブジェクトタグを設定する方法を示しています。

const OSS = require('ali-oss')

const client = new OSS({
  // バケットが配置されているリージョンに設定します。たとえば、中国 (杭州) の場合は 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,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: 'yourbucketname'
});

// ソースオブジェクトの完全なパスを指定します。完全なパスにバケット名を含めることはできません。例：srcexampledir/exampleobject.txt。
const sourceObjectName = 'srcexampledir/exampleobject.txt';
// 宛先オブジェクトの完全なパスを指定します。完全なパスにバケット名を含めることはできません。例：destexampledir/exampleobject.txt。
const targetObjectName = 'destexampledir/exampleobject.txt';

// リクエストヘッダーを設定します。
const headers = {
  // オブジェクトタグのキー (例：owner) と値 (例：John) を指定します。
  'x-oss-tagging': 'owner=John&type=document',
  // 宛先オブジェクトのタグの設定方法を指定します。有効な値：Copy および Replace。デフォルト値は Copy です。Copy は、ソースオブジェクトのタグが宛先オブジェクトにコピーされることを示します。Replace は、ソースオブジェクトのタグが無視され、リクエストで指定されたタグが使用されることを示します。
  'x-oss-tagging-directive': 'Replace' 
}

async function setTag() {
  const result = await client.copy(targetObjectName, sourceObjectName, {
    headers
  });
  const tag = await client.getObjectTagging(targetObjectName)
  console.log(tag)
}

setTag()

マルチパートコピー時のオブジェクトタグの追加

次のコードは、1 GB を超えるオブジェクトのマルチパートコピーを実行するときにオブジェクトタグを設定する方法を示しています。

const OSS = require('ali-oss')

const client = new OSS({
  // バケットが配置されているリージョンに設定します。たとえば、中国 (杭州) の場合は 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,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: 'yourbucketname'
});

// ソースオブジェクトの完全なパスを指定します。完全なパスにバケット名を含めることはできません。例：srcexampledir/exampleobject.txt。
const sourceObjectName = 'srcexampledir/exampleobject.txt'
// 宛先オブジェクトの完全なパスを指定します。完全なパスにバケット名を含めることはできません。例：destexampledir/exampleobject.txt。
const targetObjectName = 'destexampledir/exampleobject.txt'

// リクエストヘッダーを設定します。
const headers = {
  // オブジェクトタグのキー (例：owner) と値 (例：John) を指定します。
  'x-oss-tagging': 'owner=John&type=document',
}

async function setTag() {
  await client.multipartUploadCopy(targetObjectName, {
    sourceKey: sourceObjectName,
    sourceBucketName: 'examplebucket'
  }, {
    // パートサイズをバイト単位で設定します。最小パートサイズは 100 KB です。最後のパートのサイズに制限はありません。
    partSize: 256 * 1024,
    headers
  });
  const tag = await client.getObjectTagging(targetObjectName)
  console.log(tag)
}

setTag()

シンボリックリンクのタグ設定

次のコードは、シンボリックリンクのタグを設定する方法を示しています。

const OSS = require('ali-oss')

const client = new OSS({
  // バケットが配置されているリージョンに設定します。たとえば、中国 (杭州) の場合は 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,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: 'yourbucketname'
});

// シンボリックリンクの完全なパスを指定します。例：shortcut/myobject.txt。
const symLink = "shortcut/myobject.txt";
// オブジェクトの完全なパスを指定します。完全なパスにバケット名を含めることはできません。例：exampledir/exampleobject.txt。
const targetObjectName = 'exampledir/exampleobject.txt'
                
// リクエストヘッダーを設定します。
const headers = {
  // オブジェクトタグのキー (例：owner) と値 (例：John) を指定します。
  'x-oss-tagging': 'owner=John&type=document',
}

async function setTag() {
  await client.putSymlink(symLink, targetObjectName, {
    storageClass: 'IA',
    meta: {
      uid: '1',
      slus: 'test.html'
    },
    headers
  });
  const tag = await client.getObjectTagging(targetObjectName)
  console.log(tag)
}

setTag()

Object Storage Service:オブジェクトタグの設定 (Node.js SDK)