UpdateTableMetadataLocation -

調用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	請求與之前的寫入操作存在衝突。