Objects in Object Storage Service (OSS) consist of a key, data, and metadata. Object metadata describes the object and falls into two categories:
Standard HTTP headers — control cache behavior, content type, and download behavior (for example,
Cache-Control,Content-Type)User metadata — arbitrary key-value pairs you define to store purpose or attribute information about an object
Usage notes
The examples in this topic use the public endpoint for the China (Hangzhou) region. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint instead. For more information, see Regions and endpoints.
The examples create an OSSClient instance using an OSS endpoint. To create an OSSClient using a custom domain name or Security Token Service (STS), see Create an OSSClient instance.
To set object metadata, you need the
oss:PutObjectpermission. To query object metadata, you need theoss:GetObjectpermission. For more information, see Attach a custom policy to a RAM user.
Set object metadata
Set standard HTTP headers and user metadata in a PutObject call by attaching an ObjectMetaData object.
#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;
int main(void)
{
/* Endpoint for the region where your bucket is located.
Example: https://oss-cn-hangzhou.aliyuncs.com */
std::string Endpoint = "yourEndpoint";
/* Region where your bucket is located. Example: cn-hangzhou */
std::string Region = "yourRegion";
/* Bucket name. Example: examplebucket */
std::string BucketName = "examplebucket";
/* Full object path, excluding the bucket name.
Example: exampledir/exampleobject.txt */
std::string ObjectName = "exampledir/exampleobject.txt";
/* Initialize network resources. */
InitializeSdk();
ClientConfiguration conf;
conf.signatureVersion = SignatureVersionType::V4;
/* Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. */
auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
OssClient client(Endpoint, credentialsProvider, conf);
client.SetRegion(Region);
/* Set standard HTTP headers. */
auto meta = ObjectMetaData();
meta.setContentType("text/plain");
meta.setCacheControl("max-age=3");
/* Set user metadata as key-value pairs. */
meta.UserMetaData()["meta"] = "meta-value";
std::shared_ptr<std::iostream> content = std::make_shared<std::stringstream>();
*content << "Thank you for using Alibaba Cloud Object Storage Service!";
auto outcome = client.PutObject(BucketName, ObjectName, content, meta);
if (!outcome.isSuccess()) {
std::cout << "PutObject fail"
<< ", code: " << outcome.error().Code()
<< ", message: " << outcome.error().Message()
<< ", requestId: " << outcome.error().RequestId() << std::endl;
return -1;
}
/* Release network resources. */
ShutdownSdk();
return 0;
}Get object metadata
OSS provides two methods for retrieving object metadata. Choose based on how much information you need:
| Method | Returns | When to use |
|---|---|---|
GetObjectMeta | ETag, size (Content-Length), Last-Modified | Lightweight check — no need for full metadata |
HeadObject | All metadata: Content-Type, Content-Length, Cache-Control, user metadata, and more | Full metadata retrieval |
Get partial metadata with GetObjectMeta
GetObjectMeta returns only ETag, object size, and Last-Modified time. Use it when you need a quick, low-overhead metadata check.
#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;
int main(void)
{
std::string Endpoint = "yourEndpoint";
std::string Region = "yourRegion";
std::string BucketName = "examplebucket";
std::string ObjectName = "exampledir/exampleobject.txt";
InitializeSdk();
ClientConfiguration conf;
conf.signatureVersion = SignatureVersionType::V4;
auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
OssClient client(Endpoint, credentialsProvider, conf);
client.SetRegion(Region);
auto outcome = client.GetObjectMeta(BucketName, ObjectName);
if (!outcome.isSuccess()) {
std::cout << "GetObjectMeta fail"
<< ", code: " << outcome.error().Code()
<< ", message: " << outcome.error().Message()
<< ", requestId: " << outcome.error().RequestId() << std::endl;
return -1;
}
auto metadata = outcome.result();
std::cout << "GetObjectMeta success"
<< ", ETag: " << metadata.ETag()
<< ", LastModified: " << metadata.LastModified()
<< ", Size: " << metadata.ContentLength() << std::endl;
ShutdownSdk();
return 0;
}Get all metadata with HeadObject
HeadObject returns all metadata for an object, including standard HTTP headers and user metadata.
#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;
int main(void)
{
std::string Endpoint = "yourEndpoint";
std::string Region = "yourRegion";
std::string BucketName = "examplebucket";
std::string ObjectName = "exampledir/exampleobject.txt";
InitializeSdk();
ClientConfiguration conf;
conf.signatureVersion = SignatureVersionType::V4;
auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
OssClient client(Endpoint, credentialsProvider, conf);
client.SetRegion(Region);
auto outcome = client.HeadObject(BucketName, ObjectName);
if (!outcome.isSuccess()) {
std::cout << "HeadObject fail"
<< ", code: " << outcome.error().Code()
<< ", message: " << outcome.error().Message()
<< ", requestId: " << outcome.error().RequestId() << std::endl;
return -1;
}
auto headMeta = outcome.result();
std::cout << "HeadObject success"
<< ", ContentType: " << headMeta.ContentType()
<< ", ContentLength: " << headMeta.ContentLength()
<< ", CacheControl: " << headMeta.CacheControl() << std::endl;
ShutdownSdk();
return 0;
}