帮你快速理解、总结文档立即下载

空间扩展属性

最近更新时间:2026-10-22 17:31:33
我的收藏

简介

本文介绍对象存储 COS 通过 Java SDK 设置和查询智能体存储桶空间扩展属性的示例代码和描述。

注意事项

本文介绍的接口仅适用于智能体存储桶。
智能体存储桶相关接口需 COS Java SDK 5.6.283 及以上版本,SDK 的安装请参见 快速入门。
空间 ID(SpaceId)对应对象键的一级目录,需要预先通过上传对象接口上传一个大小为 0 的一级目录对象(例如 my-space/)来创建空间,详情请参见本文 前期准备 -> 创建空间。

相关示例

功能名称
描述
示例代码
设置空间扩展属性
设置指定空间的空间标签
查询空间扩展属性
查询指定空间的扩展属性

前期准备

创建 COSClient

调用 COS 的接口之前,必须先创建一个 COSClient 的实例。
说明:
COSClient 实例是并发安全的,这里推荐一个进程只创建一个 COSClient 实例,当不会再通过这个实例发起请求的时候,再选择关闭这个实例。
// 创建 COSClient 实例,这个实例用来后续调用请求
COSClient createCOSClient() {
// 设置用户身份信息。
// SECRETID 和 SECRETKEY 请登录访问管理控制台 https://console.cloud.tencent.com/cam/capi 进行查看和管理
String secretId = System.getenv("secretId");//用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
String secretKey = System.getenv("secretKey");//用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);

// ClientConfig 中包含了后续请求 COS 的客户端设置:
ClientConfig clientConfig = new ClientConfig();

// 设置 bucket 的地域
// COS_REGION 请参见 https://cloud.tencent.com/document/product/436/6224
clientConfig.setRegion(new Region("COS_REGION"));

// 以下的设置,是可选的:

// 设置 socket 读取超时,默认 30s
// clientConfig.setSocketTimeout(30*1000);
// 设置建立连接超时,默认 30s
// clientConfig.setConnectionTimeout(30*1000);

// 如果需要的话,设置 http 代理,ip 以及 port
// clientConfig.setHttpProxyIp("httpProxyIp");
// clientConfig.setHttpProxyPort(80);

// 生成 cos 客户端。
return new COSClient(cred, clientConfig);
}

使用临时密钥创建 COSClient

如果要使用临时密钥请求 COS,则需要用临时密钥创建 COSClient 实例。
说明:
COSClient 实例是并发安全的,这里推荐一个进程只创建一个 COSClient 实例,当不会再通过这个实例发起请求的时候,再选择关闭这个实例。
使用临时密钥创建 COSClient 实例之前,需要先生成临时密钥,本 SDK 并不能生成临时密钥,而需要使用额外的操作来生成,参考 临时密钥生成及使用指引。
// 创建 COSClient 实例,这个实例用来后续调用请求
COSClient createCOSClient() {
// 这里需要已经获取到临时密钥的结果。
// 临时密钥的生成参见 https://cloud.tencent.com/document/product/436/14048#cos-sts-sdk
String tmpSecretId = "TMPSECRETID";
String tmpSecretKey = "TMPSECRETKEY";
String sessionToken = "SESSIONTOKEN";

COSCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);

// ClientConfig 中包含了后续请求 COS 的客户端设置:
ClientConfig clientConfig = new ClientConfig();

// 设置 bucket 的地域
// COS_REGION 请参见 https://cloud.tencent.com/document/product/436/6224
clientConfig.setRegion(new Region("COS_REGION"));

// 以下的设置,是可选的:

// 设置 socket 读取超时,默认 30s
// clientConfig.setSocketTimeout(30*1000);
// 设置建立连接超时,默认 30s
// clientConfig.setConnectionTimeout(30*1000);

// 如果需要的话,设置 http 代理,ip 以及 port
// clientConfig.setHttpProxyIp("httpProxyIp");
// clientConfig.setHttpProxyPort(80);

// 生成 cos 客户端。
return new COSClient(cred, clientConfig);
}

创建空间

空间 ID(SpaceId)对应对象键的一级目录。使用空间相关接口前,需要先上传一个大小为 0、以 / 结尾的一级目录对象来创建空间。
// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建
// 详细代码参见本页:前期准备 -> 创建 COSClient
COSClient cosClient = createCOSClient();

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 空间 ID,对应对象键的一级目录
String spaceId = "my-space";

ObjectMetadata objectMetadata = new ObjectMetadata();
objectMetadata.setContentLength(0);
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, spaceId + "/",
new ByteArrayInputStream(new byte[0]), objectMetadata);

try {
cosClient.putObject(putObjectRequest);
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
}

关闭 COSClient

当不会再通过一个 COSClient 实例发起请求的时候,请及时将其关闭,防止资源泄露。
cosClient.shutdown();

使用案例

设置空间扩展属性

设置指定空间的扩展属性(Put Space Extension)。

方法原型

public void putSpaceExtension(PutSpaceExtensionRequest putSpaceExtensionRequest)
throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建
// 详细代码参见本页:前期准备 -> 创建 COSClient
COSClient cosClient = createCOSClient();

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 空间 ID,对应对象键的一级目录
String spaceId = "my-space";
// 空间标签
String spaceTag = "personal";

PutSpaceExtensionRequest putSpaceExtensionRequest = new PutSpaceExtensionRequest(bucketName, spaceId, spaceTag);

try {
cosClient.putSpaceExtension(putSpaceExtensionRequest);
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
}
// 确认本进程不再使用 cosClient 实例之后,关闭即可
cosClient.shutdown();

参数说明

参数名称
描述
类型
putSpaceExtensionRequest
设置空间拓展属性请求
PutSpaceExtensionRequest
Request 成员说明:
参数名称
描述
类型
bucketName
Bucket 的命名格式为 BucketName-APPID ,详情请参见 命名规范
String
spaceId
空间 ID,即对象键的一级目录名,例如 my-space,不支持多级目录
String
spaceTag
空间标签,用于区分空间类型,例如个人空间与团队空间,不能为空
String

返回结果说明

成功:无返回值。
失败:发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

查询空间扩展属性

查询指定空间的扩展属性(Get Space Extension)。

方法原型

public SpaceExtensionResult getSpaceExtension(GetSpaceExtensionRequest getSpaceExtensionRequest)
throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建
// 详细代码参见本页:前期准备 -> 创建 COSClient
COSClient cosClient = createCOSClient();

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 空间 ID,对应对象键的一级目录
String spaceId = "my-space";

GetSpaceExtensionRequest getSpaceExtensionRequest = new GetSpaceExtensionRequest(bucketName, spaceId);

try {
SpaceExtensionResult spaceExtensionResult = cosClient.getSpaceExtension(getSpaceExtensionRequest);
Boolean isPublicRead = spaceExtensionResult.getIsPublicRead();
Boolean recognizeSensitiveContent = spaceExtensionResult.getRecognizeSensitiveContent();
String spaceTag = spaceExtensionResult.getSpaceTag();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
}
// 确认本进程不再使用 cosClient 实例之后,关闭即可
cosClient.shutdown();

参数说明

参数名称
描述
类型
getSpaceExtensionRequest
查询空间拓展属性请求
GetSpaceExtensionRequest
Request 成员说明:
参数名称
描述
类型
bucketName
Bucket 的命名格式为 BucketName-APPID ,详情请参见 命名规范
String
spaceId
空间 ID,即对象键的一级目录名,例如 my-space,不支持多级目录
String

返回结果说明

成功:返回 SpaceExtensionResult,包含空间的扩展属性。
失败:发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。
SpaceExtensionResult 成员说明:
参数名称
描述
类型
isPublicRead
是否为公有读
Boolean
recognizeSensitiveContent
是否检测敏感内容
Boolean
spaceTag
空间标签
String

API 操作

关于设置空间扩展属性的 API 接口说明,请参见 Put Space Extension 文档。
关于查询空间扩展属性的 API 接口说明,请参见 Get Space Extension 文档。