文档中心

AI 数据湖服务

Apache Gravitino

Apache® Gravitino Iceberg REST Catalog 使用说明

Catalog 是一项面向企业数据平台的托管服务，严格遵循 Apache Iceberg REST API 规范，为各类计算引擎提供统一、标准的 Iceberg 元数据读写功能。该服务旨在简化多引擎、多租户环境下的数据管理和安全治理工作。

核心优势

统一接入：通过单一的 REST 端点为多个计算引擎和工作负载提供服务，可显著降低接入与运维成本。

多租户与多目录管理：以火山引擎账号和 Catalog 为边界进行资源隔离与治理，能够简化权限管理与审计工作。

开放规范兼容：完全兼容 Iceberg REST v1 规范，支持命名空间、表的创建、查询、删除等全套标准操作。

说明

本功能目前处于白名单开放阶段，仅华北2（北京）及华东2（上海）区域支持使用。如需使用，请提交工单申请。开通后，您将获得服务访问端点（Endpoint），结合火山引擎访问密钥（AK/SK）即可在计算引擎中进行配置并使用。

概念映射

在使用前，请务必理解以下关键概念在火山引擎环境中的映射关系：

Metalake：对应您的火山引擎账号 ID (AccountId)。所有资源和权限均以此为边界进行隔离与管理。

Catalog：统一映射到火山引擎 LAS 元数据管理服务中的 Hive Catalog。

使用前准备

在配置客户端前，请完成以下准备工作，以确保服务能被顺利调用。

服务 Endpoint 与区域 (Region)

您需要从火山引擎获取服务的访问端点（Endpoint）。请确保客户端部署在与服务相同的区域（Region），或具备网络可达性。Region 的取值示例包括 cn-beijing、cn-shanghai 等。

获取访问密钥 (AK/SK)

所有 API 请求都必须经过签名认证。请前往火山引擎控制台的“访问控制”页面创建并获取访问密钥（Access Key ID 和 Secret Access Key）。

API 签名

Apache® Gravitino Iceberg REST Catalog 采用火山引擎标准的 API 签名机制，以确保请求的机密性、完整性和身份验证。您需要在每个请求的 Header 中添加 Authorization 和 X-Date 字段。

Apache Gravitino, the names of other Apache projects, and the ASF logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries.

详细签名算法与实现，请参考官方文档：访问密钥（AK/SK）签名认证。

签名步骤概览：

构建规范请求 (Canonical Request)：拼接 HTTP 方法、URI、查询字符串、请求头和请求体哈希值。

创建待签名字符串 (String to Sign)：组合签名算法、时间戳、凭证范围和规范请求的哈希值。

计算签名密钥 (Signing Key)：使用 SK 和时间、区域、服务等信息派生出签名密钥。

计算最终签名 (Signature)：使用签名密钥对待签名字符串进行 HMAC-SHA256 哈希计算。

组装 Authorization 头：将 AK 和计算出的签名信息组合成最终的 Authorization 请求头。

以下是一个生成签名的伪代码示例，帮助您理解签名过程：

注意：上述伪代码主要用于演示核心签名流程。实际使用中，如果需要控制签名有效期，请在请求头中额外加入 X-Expire 字段。该字段与 X-Date 协同工作，用于控制有效天数，例如 -1 表示永不过期。为保持兼容性，SignedHeaders 中可不包含 X-Expire。

API 参考

以下是核心 API 的详细说明。所有请求均需包含正确的签名头 Authorization 和 X-Date。

列出 Namespaces

查询指定 Catalog 下的所有 Namespaces。

方法: GET

路径: /v1/namespaces

查询参数:

参数名	类型	是否必选	描述
pageToken	string	否	分页标识，用于获取下一页结果。首次请求时无需提供。
pageSize	integer	否	每页返回的结果数量，默认为 100。

请求示例:

响应示例 (成功):

状态码与错误码:

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://..."} 指定存储位置。

请求示例:

响应示例 (成功):

状态码与错误码:

200 OK: 创建成功。

409 Conflict: Namespace 已存在。

查询 Namespace 详情

获取指定 Namespace 的元数据信息。

方法: GET

路径: /v1/namespaces/{namespace}

请求示例:

响应示例 (成功):

状态码与错误码:

200 OK: 查询成功。

404 Not Found: Namespace 不存在。

删除 Namespace

删除一个空的 Namespace。

方法: DELETE

路径: /v1/namespaces/{namespace}

请求示例:

响应示例 (成功):

状态码与错误码:

204 No Content: 删除成功。

404 Not Found: Namespace 不存在。

409 Conflict: Namespace 不为空，无法删除。

列出 Tables

查询指定 Namespace 下的所有表。

方法: GET

路径: /v1/namespaces/{namespace}/tables

请求示例:

响应示例 (成功):

创建 Table

在指定的 Namespace 中创建一个新表。

方法: POST

路径: /v1/namespaces/{namespace}/tables

请求体:

请求体是一个复杂的 JSON 对象，包含表名、Schema、分区规范、写入模式和属性等。详细结构请参考 Iceberg 官方 REST API 文档。

请求示例:

响应示例 (成功):

返回完整的表元数据 JSON 对象。

更多接口详情可参考 REST Catalog Spec - Apache Iceberg™。

最近更新时间：2026.08.31 13:51:45

这个页面对您有帮助吗？

有用

无用