调用UpdateTableMetadataLocation接口更新指定表的Metadata文件位置。
注意事项
通过此接口可以将表指向新的metadata文件，实现表schema变更、数据提交等操作。
必须传入当前有效的versionToken进行乐观锁控制，确保并发更新的一致性。
versionToken可通过GetTableMetadataLocation或GetTable接口获取。
新的metadataLocation必须指向一个有效的Iceberg metadata JSON文件。
权限说明
API | Action | 说明 |
UpdateTableMetadataLocation | oss:UpdateTableMetadataLocation | 更新表metadata位置（同时检查Table Policy） |
请求语法
PUT /tables/{tableBucketARN}/{namespace}/{name}/metadata-location HTTP/1.1
Content-type: application/json
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
{
"versionToken": "string",
"metadataLocation": "string"
}请求参数
名称 | 数据类型 | 是否必选 | 示例值 | 描述 |
tableBucketARN | 字符串 | 是 | acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket | Table Bucket的ARN，格式为acs:osstables:{region}:{uid}:bucket/{bucketName}。位于URI中。 |
namespace | 字符串 | 是 | my_namespace | 表所在的命名空间名称。位于URI中。 |
name | 字符串 | 是 | my_table | 表名称。位于URI中。 |
versionToken | 字符串 | 是 | aaabbb | 当前版本token（乐观锁），可通过GetTableMetadataLocation或GetTable接口获取。位于请求体中。 |
metadataLocation | 字符串 | 是 | oss://data-bucket/metadata/00001-xxx.metadata.json | 新的metadata文件OSS路径，必须指向一个有效的Iceberg metadata JSON文件。位于请求体中。 |
响应参数
名称 | 数据类型 | 示例值 | 描述 |
metadataLocation | 字符串 | oss://bucket/metadata/00000-xxx.metadata.json | 更新后的metadata文件OSS路径。 |
name | 字符串 | my_table | 表名称。 |
namespace | 数组 | - | 表所在的命名空间名称数组。 |
tableARN | 字符串 | acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table-id | 表的ARN。 |
versionToken | 字符串 | abc123def456 | 更新后的版本token。 |
示例
请求示例
PUT /tables/acs%3Aosstables%3Acn-hangzhou%3A1234567890%3Abucket%2Fmy-table-bucket/my_namespace/my_table/metadata-location HTTP/1.1
Content-type: application/json
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: Thu, 10 Apr 2025 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/osstables/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c****
{
"versionToken": "aaabbb",
"metadataLocation": "oss://data-bucket/metadata/00001-xxx.metadata.json"
}返回示例
HTTP/1.1 200 OK
Server: AliyunOSS
x-oss-request-id: 5C06A3B67B8B5A3DA422****
x-oss-server-time: 3
Content-Type: application/json
{
"metadataLocation": "oss://data-bucket/metadata/00001-xxx.metadata.json",
"name": "my_table",
"namespace": ["my_namespace"],
"tableARN": "acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table_id",
"versionToken": "cccbbb"
}SDK
UpdateTableMetadataLocation接口所对应的各语言SDK如下：
命令行工具ossutil
UpdateTableMetadataLocation接口所对应的ossutil命令，请参见update-table-metadata-location。
错误码
错误码 | HTTP状态码 | 描述 |
BadRequestException | 400 | 请求无效或格式错误。 |
ForbiddenException | 403 | 调用者无权执行此请求。 |
NotFoundException | 404 | 请求的资源不存在。 |
ConflictException | 409 | 请求与之前的写入操作存在冲突。 |