Configure and query object metadata using Harmony SDK - Object Storage Service

Use OSS SDK for HarmonyOS to set object metadata when uploading, or retrieve it later without downloading the object body.

OSS provides two methods for retrieving metadata:

Method	Returns	Use when
`headObject`	All metadata, including HTTP headers and user metadata	You need the full set of metadata
`getObjectMeta`	Partial metadata only: `ContentLength`, `ETag`, `LastModified`, `LastAccessTime`, `VersionId`, `HashCRC64`	You only need basic file properties and want to minimize response overhead

Prerequisites

Before you begin, ensure that you have:

The oss:PutObject permission to set object metadata
The oss:GetObject permission to retrieve object metadata

For details, see Grant custom permissions to a RAM user.

Usage notes

For the list of regions and their endpoints, see Regions and endpoints.

Set object metadata when uploading

Pass metadata parameters directly in putObject. The example below sets the object access control list (ACL) to private.

import Client, { EObjectAcl, RequestError } from '@aliyun/oss';

// Initialize the OSSClient with STS credentials.
const client = new Client({
  accessKeyId: 'yourAccessKeyId',        // AccessKey ID from Security Token Service (STS)
  accessKeySecret: 'yourAccessKeySecret', // AccessKey secret from STS
  securityToken: 'yourSecurityToken',    // Security token from STS
  region: 'oss-cn-hangzhou',             // Region where the bucket is located
});

const bucket = 'yourBucketName';
const key = 'yourObjectName';

const putObject = async () => {
  try {
    const res = await client.putObject({
      bucket,
      key,
      data: 'hello world',
      objectAcl: EObjectAcl.PRIVATE,     // Set the object ACL to private
    });

    console.log(JSON.stringify(res));
  } catch (err) {
    if (err instanceof RequestError) {
      console.log('code: ', err.code);
      console.log('message: ', err.message);
      console.log('requestId: ', err.requestId);
      console.log('status: ', err.status);
      console.log('ec: ', err.ec);
    } else {
      console.log('unknown error: ', err);
    }
  }
};

putObject();

Retrieve object metadata

Get all metadata with headObject

headObject returns all metadata without downloading the object body.

import Client, { RequestError } from '@aliyun/oss';

const client = new Client({
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  securityToken: 'yourSecurityToken',
  region: 'oss-cn-hangzhou',
});

const bucket = 'yourBucketName';
const key = 'yourObjectName';

const headObject = async () => {
  try {
    const res = await client.headObject({ bucket, key });

    console.log(JSON.stringify(res));
  } catch (err) {
    if (err instanceof RequestError) {
      console.log('code: ', err.code);
      console.log('message: ', err.message);
      console.log('requestId: ', err.requestId);
      console.log('status: ', err.status);
      console.log('ec: ', err.ec);
    } else {
      console.log('unknown error: ', err);
    }
  }
};

headObject();

Get partial metadata with getObjectMeta

getObjectMeta returns only six fields: ContentLength, ETag, LastModified, LastAccessTime, VersionId, and HashCRC64. Use it when you do not need the full set of HTTP headers.

import Client, { RequestError } from '@aliyun/oss';

const client = new Client({
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  securityToken: 'yourSecurityToken',
  region: 'oss-cn-hangzhou',
});

const bucket = 'yourBucketName';
const key = 'yourObjectName';

const getObjectMeta = async () => {
  try {
    const res = await client.getObjectMeta({ bucket, key });

    console.log(JSON.stringify(res));
  } catch (err) {
    if (err instanceof RequestError) {
      console.log('code: ', err.code);
      console.log('message: ', err.message);
      console.log('requestId: ', err.requestId);
      console.log('status: ', err.status);
      console.log('ec: ', err.ec);
    } else {
      console.log('unknown error: ', err);
    }
  }
};

getObjectMeta();