AI 数据湖服务
AI 数据湖服务
开发参考
请输入
- 文档首页
AI 数据湖服务组件操作指南Apache GravitinoApache® Gravitino Server OpenAPI 使用说明
复制全文
下载 pdfApache® Gravitino Server OpenAPI 使用说明
文档反馈
问问助手概述
Apache® Gravitino Server OpenAPI 是基于 Apache® Gravitino 的托管元数据服务，通过提供标准化的 REST API，助力用户集中管理和发现分散在不同系统中的数据及 AI 资产。本文档旨在为外部客户提供 Gravitino Server 核心 OpenAPI 的使用说明，帮助客户快速将该服务集成至现有的数据应用与工作流中。
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.
说明
申请。开通后，您将获得服务访问端点（Endpoint），结合火山引擎访问密钥（AK/SK）即可在计算引擎中配置并使用。
概念与映射
为确保与火山引擎生态系统的兼容性和一致性，在使用 Gravitino Server OpenAPI 前，需理解以下核心概念的映射关系：
- Metalake: 对应您的 火山引擎账号 ID (Volcengine AccountId)。Metalake 是元数据隔离的最高层级单元，所有资源、权限和治理策略都以此为边界。
- Catalog：映射到 LAS（Lakehouse Analytics Service）元数据服务中的 Hive Catalog。Catalog 是组织和管理元数据的容器，如数据库、表等。
- Schema：指代数据库或库，是表的集合。
- Table：结构化数据的定义，包含列、分区、属性等信息。
- Fileset：面向非结构化数据的元数据抽象，通常指一组文件。
- Topic：消息队列（如 Kafka）中的主题。
- Model：AI/ML 场景下的模型元数据。
使用前准备
在调用 API 之前，需完成以下准备工作：
获取服务接入信息
- 服务 Endpoint：https://{endpoint}（请替换为火山引擎提供的实际服务地址）。
- 火山引擎访问密钥 (AK/SK)：用于 API 请求签名，请从火山引擎控制台安全地获取和管理您的 Access Key ID (AK) 和 Secret Access Key (SK)。
API 请求签名
所有对 Gravitino Server OpenAPI 的请求都必须经过签名，以验证请求者身份并确保数据在传输过程中的完整性。签名机制遵循火山引擎的统一标准。
- 签名算法：HMAC-SHA256
- 核心请求头：
- X-Date：UTC 时间，格式为 YYYYMMDDTHHMMSSZ，例如 20251117T083000Z。
- Authorization：包含 AK、签名版本、时间戳、区域、服务、签名头列表和最终签名摘要的字符串。
签名步骤概览：
- 构建规范请求 (Canonical Request)：拼接 HTTP 方法、URI、查询字符串、请求头和请求体哈希值。
- 创建待签名字符串 (String to Sign)：组合签名算法、时间戳、凭证范围和规范请求的哈希值。
- 计算签名密钥 (Signing Key)：使用 SK 和时间、区域、服务等信息派生出签名密钥。
- 计算最终签名 (Signature)：使用签名密钥对待签名字符串进行 HMAC-SHA256 哈希计算。
- 组装 Authorization 头：将 AK 和计算出的签名信息组合成最终的 Authorization 请求头。
以下是一个生成签名的伪代码示例，帮助您理解签名过程：
# 1. 准备输入
AK = "{ak}" # 您的 Access Key ID
SK = "{sk}" # 您的 Secret Access Key
Region = "{region}" # 例如：cn-beijing
Service = "gravitino" # 服务名称固定为 gravitino
Host = "{endpoint}" # 服务端点
Method = "POST"
Path = "/api/metalakes/{metalake_name}/catalogs"
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
核心 API 说明
以下是 Gravitino Server 的核心 OpenAPI 接口说明。所有接口均需通过 HTTP 访问，并遵循“使用前准备”章节中描述的签名认证方式。
查询 Metalake 信息
加载指定 Metalake 的详细信息。在火山引擎环境中，这通常对应当前的火山引擎账号。
- 方法：GET
- 路径：/api/metalakes/{metalake_name}
路径参数：
参数名 | 类型 | 是否必选 | 描述 |
metalake_name | String | 是 | Metalake 的名称，对应火山引擎账号 ID。 |
请求示例：
curl -X GET 'https://{endpoint}/api/metalakes/your_account_id' \
--header 'X-Date: 20251117T090000Z' \
--header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/gravitino/request, SignedHeaders=host;x-date, Signature={signature}'
返回示例：
{
"code": 0,
"metalake": {
"name": "your_account_id",
"comment": "This is a metalake for the current account.",
"properties": {},
"audit": {
"creator": "system",
"createTime": "2025-11-17T08:00:00Z"
}
}
}
状态码与常见错误：
- 200 OK：请求成功。
- 404 Not Found：指定的 Metalake 不存在。
列出 Catalog
列出指定 Metalake 下的所有 Catalog。
- 方法：GET
- 路径：/api/metalakes/{metalake_name}/catalogs
请求示例：
curl -X GET 'https://{endpoint}/api/metalakes/your_account_id/catalogs' \
--header 'X-Date: 20251117T090500Z' \
--header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/gravitino/request, SignedHeaders=host;x-date, Signature={signature}'
返回示例：
{
"code": 0,
"identifiers": [
{
"namespace": [
"your_account_id"
],
"name": "hive_prod"
}
]
}
加载 Catalog
获取指定 Catalog 的详细信息。
- 方法：GET
- 路径：/api/metalakes/{metalake_name}/catalogs/{catalog_name}
请求示例：
curl -X GET 'https://{endpoint}/api/metalakes/your_account_id/catalogs/hive_prod' \
--header 'X-Date: 20251117T091000Z' \
--header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/gravitino/request, SignedHeaders=host;x-date, Signature={signature}'
返回示例：
{
"code": 0,
"catalog": {
"name": "hive_prod",
"type": "RELATIONAL",
"provider": "hive",
"comment": "Production Hive catalog",
"properties": {
"metastore.uris": "thrift://localhost:9083"
},
"audit": {
"creator": "user1",
"createTime": "2025-11-10T10:00:00Z"
}
}
}
列出 Schema
列出指定 Catalog 下的所有 Schema（数据库）。
- 方法：GET
- 路径：/api/metalakes/{metalake_name}/catalogs/{catalog_name}/schemas
请求示例：
curl -X GET 'https://{endpoint}/api/metalakes/your_account_id/catalogs/hive_prod/schemas' \
--header 'X-Date: 20251117T091500Z' \
--header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/gravitino/request, SignedHeaders=host;x-date, Signature={signature}'
返回示例：
{
"code": 0,
"identifiers": [
{
"namespace": [
"your_account_id",
"hive_prod"
],
"name": "default"
},
{
"namespace": [
"your_account_id",
"hive_prod"
],
"name": "sales_db"
}
]
}
列出 Table
列出指定 Schema 下的所有 Table。
- 方法：GET
- 路径：/api/metalakes/{metalake_name}/catalogs/{catalog_name}/schemas/{schema_name}/tables
请求示例：
curl -X GET 'https://{endpoint}/api/metalakes/your_account_id/catalogs/hive_prod/schemas/sales_db/tables' \
--header 'X-Date: 20251117T092000Z' \
--header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/gravitino/request, SignedHeaders=host;x-date, Signature={signature}'
返回示例：
{
"code": 0,
"identifiers": [
{
"namespace": [
"your_account_id",
"hive_prod",
"sales_db"
],
"name": "orders"
},
{
"namespace": [
"your_account_id",
"hive_prod",
"sales_db"
],
"name": "customers"
}
]
}
Fileset, Model, Topic
当前产品能力上仅支持Hive Catalog，如需使用其余类型Catalog，请联系技术支持人员。
分页参数说明
对于返回列表的 API（如列出 Catalog、Schema、Table），支持使用分页参数来控制返回结果的数量和位置。
- pageSize：指定每页返回的条目数，默认为 100。
- pageToken：用于获取下一页结果的令牌。首次请求时无需提供，后续请求可将上一次响应中返回的 nextPageToken 值作为此参数传入。
Region 示例值
在进行 API 请求时，需在签名凭证范围和（或）请求头中指定正确的 Region。以下是火山引擎部分可用区的示例值，具体请以服务所在区域为准：
- cn-beijing
- cn-shanghai
- cn-guangzhou（待发布）
常见问题与故障排查
Q：调用 API 返回 401 Unauthorized 或 SignatureDoesNotMatch 错误是什么原因？
A：这通常表示 API 请求签名有误。请仔细检查：
- AK/SK 是否正确且未过期。
- X-Date 请求头的时间是否与服务器的当前 UTC 时间一致，误差不应超过 15 分钟。
- 参与签名的 HTTP 请求内容（方法、路径、参数、请求头）是否与实际发送的一致。
- 签名计算过程是否严格遵循了火山引擎官方文档的规范。
Q：如何确认应该使用哪个 metalake_name？
A：metalake_name 固定映射为火山引擎账号 ID。您可以在火山引擎控制台的账号管理页面找到它。
Q：创建 Catalog 时 provider 字段应该填什么？
A：provider 指定了 Catalog 的类型，例如 hive、iceberg、jdbc 等。在火山引擎托管环境中，通常应填 hive，以对接到 LAS 的 Hive Catalog。
最近更新时间：2026.08.04 11:28:44
这个页面对您有帮助吗？
有用
有用
无用
无用