## 概述 Gravitino Iceberg REST Catalog 是一项面向企业数据平台的托管服务，严格遵循 Apache Iceberg REST API 规范，为各类计算引擎提供统一、标准的 Iceberg 元数据读写功能。该服务旨在简化多引擎、多租户环境下的数据管理和安全治理工作。 ## **核心优势** * **统一接入**：通过单一的 REST 端点为多个计算引擎和工作负载提供服务，可显著降低接入与运维成本。 * **多租户与多目录管理**：以火山引擎账号和 Catalog 为边界进行资源隔离与治理，能够简化权限管理与审计工作。 * **开放规范兼容**：完全兼容 Iceberg REST v1 规范，支持命名空间、表的创建、查询、删除等全套标准操作。 :::tip 本功能目前处于白名单开放阶段，仅华北2（北京）及华东2（上海）区域支持使用。如需使用，请[提交工单](https://console.volcengine.com/workorder/create)申请。开通后，您将获得服务访问端点（Endpoint），结合火山引擎访问密钥（AK/SK）即可在计算引擎中进行配置并使用。 ::: ## 概念映射在使用前，请务必理解以下关键概念在火山引擎环境中的映射关系： * **Metalake**：对应您的**火山引擎账号 ID (AccountId)** 。所有资源和权限均以此为边界进行隔离与管理。 * **Catalog**：统一映射到火山引擎 LAS 元数据管理服务中的 **Hive Catalog**。 ## 使用前准备在配置客户端前，请完成以下准备工作，以确保服务能被顺利调用。 ### 服务 Endpoint 与区域 (Region) 您需要从火山引擎获取服务的访问端点（Endpoint）。请确保客户端部署在与服务相同的区域（Region），或具备网络可达性。Region 的取值示例包括 `cn-beijing`、`cn-shanghai` 等。 ### 获取访问密钥 (AK/SK) 所有 API 请求都必须经过签名认证。请前往火山引擎控制台的“[访问控制](https://console.volcengine.com/iam/keymanage/)”页面创建并获取访问密钥（Access Key ID 和 Secret Access Key）。 ### API 签名 Gravitino Iceberg REST Catalog 采用火山引擎标准的 API 签名机制，以确保请求的机密性、完整性和身份验证。您需要在每个请求的 Header 中添加 `Authorization` 和 `X-Date` 字段。详细签名算法与实现，请参考官方文档：[访问密钥（AK/SK）签名认证](https://www.volcengine.com/docs/6369/67269)。 **签名步骤概览**： 1. **构建规范请求 (Canonical Request)** ：拼接 HTTP 方法、URI、查询字符串、请求头和请求体哈希值。 2. **创建待签名字符串 (String to Sign)** ：组合签名算法、时间戳、凭证范围和规范请求的哈希值。 3. **计算签名密钥 (Signing Key)** ：使用 SK 和时间、区域、服务等信息派生出签名密钥。 4. **计算最终签名 (Signature)** ：使用签名密钥对待签名字符串进行 HMAC\-SHA256 哈希计算。 5. **组装 Authorization 头**：将 AK 和计算出的签名信息组合成最终的 `Authorization` 请求头。以下是一个生成签名的伪代码示例，帮助您理解签名过程： ```Bash # 1. 准备输入 AK = "{ak}" # 您的 Access Key ID SK = "{sk}" # 您的 Secret Access Key Region = "{region}" # 例如：cn-beijing Service = "las" # 服务名称固定为 las Host = "{endpoint}" # 服务端点 Method = "POST" Path = "/v1/namespaces/{namespace}/tables" Timestamp = "20251117T100000Z" # ISO8601 格式的 UTC 时间 Headers = "host;x-date" RequestPayload = "{...}" # 请求体 JSON 内容 # 2. 构造规范化请求 (Canonical Request) CanonicalRequest = Method + '\n' + Path + '\n' + '' + '\n' + 'host:' + Host + '\n' + 'x-date:' + Timestamp + '\n' + '\n' + Headers + '\n' + Hex(SHA256(RequestPayload)) # 3. 构造签名字符串 (String to Sign) StringToSign = "HMAC-SHA256" + '\n' + Timestamp + '\n' + Date(Timestamp) + '/' + Region + '/' + Service + '/request' + '\n' + Hex(SHA256(CanonicalRequest)) # 4. 计算签名密钥 (Signing Key) DateKey = HMAC-SHA256(Date(Timestamp), "VOLC" + SK) DateRegionKey = HMAC-SHA256(Region, DateKey) DateRegionServiceKey = HMAC-SHA256(Service, DateRegionKey) SigningKey = HMAC-SHA256("request", DateRegionServiceKey) # 5. 计算最终签名 (Signature) Signature = Hex(HMAC-SHA256(StringToSign, SigningKey)) # 6. 构造 Authorization Header AuthorizationHeader = "HMAC-SHA256 Credential=" + AK + "/" + Date(Timestamp) + "/" + Region + "/" + Service + "/request, SignedHeaders=" + Headers + ", Signature=" + Signature ``` **注意**：上述伪代码主要用于演示核心签名流程。实际使用中，如果需要控制签名有效期，请在请求头中额外加入 `X-Expire` 字段。该字段与 `X-Date` 协同工作，用于控制有效天数，例如 `-1` 表示永不过期。为保持兼容性，`SignedHeaders` 中可不包含 `X-Expire`。 ## API 参考以下是核心 API 的详细说明。所有请求均需包含正确的签名头 `Authorization` 和 `X-Date`。 ### 列出 Namespaces 查询指定 Catalog 下的所有 Namespaces。 * **方法**: `GET` * **路径**: `/v1/namespaces` **查询参数:** |参数名 |类型 |是否必选 |描述 | |---|---|---|---| |`pageToken` |string |否 |分页标识，用于获取下一页结果。首次请求时无需提供。 | |`pageSize` |integer |否 |每页返回的结果数量，默认为 100。 | **请求示例:** ```Bash curl --location 'https://{endpoint}/iceberg/v1/namespaces?pageSize=10' \ --header 'X-Date: 20251117T100000Z' \ --header 'X-Expire: -1' \ --header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/grlavitinos/request, SignedHeaders=host;x-date, Signature={signature}' \ --header 'Region: {region}' ``` **响应示例 (成功):** ```JSON { "namespaces": [ ["default"], ["production"] ], "next-page-token": "..." } ``` **状态码与错误码:** * `200 OK`: 请求成功。 * `401 Unauthorized`: 签名无效或权限不足。 * `500 Internal Server Error`: 服务器内部错误。 ### 创建 Namespace 在 Catalog 中创建一个新的 Namespace。 * **方法**: `POST` * **路径**: `/v1/namespaces` **请求体:** |参数名 |类型 |是否必选 |描述 | |---|---|---|---| |`namespace` |array[string] |是 |要创建的 Namespace，支持多级，例如 `["accounting", "tax"]`。 | |`properties` |map[string, string] |否 |附加属性，例如 `{"location": "tos://..."}` 指定存储位置。 | **请求示例:** ```Bash curl --location 'https://{endpoint}/iceberg/v1/namespaces' \ --header 'X-Date: 20251117T100000Z' \ --header 'X-Expire: -1' \ --header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/grlavitinos/request, SignedHeaders=host;x-date, Signature={signature}' \ --header 'Region: {region}' \ --header 'Content-Type: application/json' \ --data '{ "namespace": ["sales"], "properties": { "location": "tos://my-bucket/sales_data" } }' ``` **响应示例 (成功):** ```JSON { "namespace": ["sales"], "properties": { "location": "tos://my-bucket/sales_data" } } ``` **状态码与错误码:** * `200 OK`: 创建成功。 * `409 Conflict`: Namespace 已存在。 ### 查询 Namespace 详情获取指定 Namespace 的元数据信息。 * **方法**: `GET` * **路径**: `/v1/namespaces/{namespace}` **请求示例:** ```Bash curl --location 'https://{endpoint}/iceberg/v1/namespaces/sales' \ --header 'X-Date: 20251117T100000Z' \ --header 'X-Expire: -1' \ --header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/grlavitinos/request, SignedHeaders=host;x-date, Signature={signature}' \ --header 'Region: {region}' ``` **响应示例 (成功):** ```JSON { "namespace": ["sales"], "properties": { "location": "tos://bucket-path/sales_data" } } ``` **状态码与错误码:** * `200 OK`: 查询成功。 * `404 Not Found`: Namespace 不存在。 ### 删除 Namespace 删除一个空的 Namespace。 * **方法**: `DELETE` * **路径**: `/v1/namespaces/{namespace}` **请求示例:** ```Bash curl --location --request DELETE 'https://{endpoint}/iceberg/v1/namespaces/temp_ns' \ --header 'X-Date: 20251117T100000Z' \ --header 'X-Expire: -1' \ --header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/grlavitinos/request, SignedHeaders=host;x-date, Signature={signature}' \ --header 'Region: {region}' ``` **响应示例 (成功):** ```Plain (无响应体，状态码 204 No Content) ``` **状态码与错误码:** * `204 No Content`: 删除成功。 * `404 Not Found`: Namespace 不存在。 * `409 Conflict`: Namespace 不为空，无法删除。 ### 列出 Tables 查询指定 Namespace 下的所有表。 * **方法**: `GET` * **路径**: `/v1/namespaces/{namespace}/tables` **请求示例:** ```Bash curl --location 'https://{endpoint}/iceberg/v1/namespaces/sales/tables' \ --header 'X-Date: 20251117T100000Z' \ --header 'X-Expire: -1' \ --header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/grlavitinos/request, SignedHeaders=host;x-date, Signature={signature}' \ --header 'Region: {region}' ``` **响应示例 (成功):** ```JSON { "identifiers": [ {"namespace": ["sales"], "name": "orders"}, {"namespace": ["sales"], "name": "customers"} ] } ``` ### 创建 Table 在指定的 Namespace 中创建一个新表。 * **方法**: `POST` * **路径**: `/v1/namespaces/{namespace}/tables` **请求体:** 请求体是一个复杂的 JSON 对象，包含表名、Schema、分区规范、写入模式和属性等。详细结构请参考 Iceberg 官方 REST API 文档。 **请求示例:** ```Bash curl --location 'https://{endpoint}/iceberg/v1/namespaces/sales/tables' \ --header 'X-Date: 20251117T100000Z' \ --header 'X-Expire: -1' \ --header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/grlavitinos/request, SignedHeaders=host;x-date, Signature={signature}' \ --header 'Region: {region}' \ --header 'Content-Type: application/json' \ --data '{ "name": "new_orders", "schema": { ... }, "partition-spec": { ... } }' ``` **响应示例 (成功):** 返回完整的表元数据 JSON 对象。 ```JSON { "metadata-location": "tos://.../metadata.json", "metadata": { ... } } ``` 更多接口详情可参考 [REST Catalog Spec - Apache Iceberg™](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml)。

AI 数据湖服务