帮你快速理解、总结文档立即下载
文档中心>对象存储>高性能存储>SDK 文档>Python SDK>对象操作>重命名对象

重命名对象

最近更新时间：2026-10-21 18:34:05
本文档已由 AI 辅助审校
我的收藏

本页目录：

在同一高性能桶内原子重命名对象。该操作原子地将源对象移至目标对象键。对高性能桶发起请求时，SDK 自动完成会话鉴权。

注意事项

RenameSource 与 Key 的末尾 / 严格区分文件对象与目录对象，两者必须同为文件键（均不以 / 结尾）或目录键（均以 / 结尾），否则返回 400 InvalidArgument。
源键与源对象实际类型不匹配时，不做容错，按源对象不存在处理，返回 404 NoSuchKey。
Key 与 RenameSource 均不能为空或为 /，且不能包含独立的 .或.. 路径段。
文件对象可设置 ForbidOverwrite='true' 防止覆盖已有目标。目录对象不覆盖已有同名对象。
重命名请求遇到连接异常、超时、响应截断或 5xx 时，结果可能不确定；SDK 不自动重发，调用方应先确认结果，避免重复操作。
重命名属于数据面接口，SDK 使用 session 临时凭证签名。

请求

方法原型

def rename_object(self, Bucket, Key, RenameSource, ForbidOverwrite=None, **kwargs)

参数说明

参数名称
参数描述
类型
是否必选
Bucket
高性能桶完整名称，格式为 <BucketName>-x--<APPID>
string
是
Key
目标对象键（Object Key）
string
是
RenameSource
源对象键（Object Key），按原始对象键填写，无需自行 URL 编码
string
是
ForbidOverwrite
文件对象的防覆盖条件，字符串 "true" 表示不覆盖已有目标
string
否
kwargs
可选请求参数，使用本文列出的参数
dict
否

响应

返回值为响应头部字典：
参数名称
参数描述
类型
响应头 dict
成功时返回响应头部字典
dict

错误码

本接口遵循统一的错误响应和错误码，详情请参见 错误码文档。

实际案例

# -*- coding=utf-8 -*-
import os
from qcloud_cos import CosConfig, CosS3Client

# 高性能桶经 VPC 内网 HTTP 80 端口接入，SDK 的网关 DNS 负载均衡也仅对 HTTP 请求生效；SDK 默认 https，此处需显式指定 http。
config = CosConfig(
    Scheme='http',
    Region='ap-guangzhou',
    SecretId=os.environ['COS_SECRET_ID'],
    SecretKey=os.environ['COS_SECRET_KEY'],
    Token=os.environ.get('COS_SECURITY_TOKEN'),
    EnableRapidDomain=True)
client = CosS3Client(config)

bucket = 'examplebucket-x--1250000000'

# 原子重命名，并开启防覆盖。
client.rename_object(
    Bucket=bucket,
    Key='newname.txt',
    RenameSource='oldname.txt',
    ForbidOverwrite='true')
print('RenameObject OK')

中国站