## 概述 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.

说明

本功能目前处于白名单开放阶段，仅华北2（北京）及华东2（上海）区域支持使用。如需使用，请提交工单

申请。开通后，您将获得服务访问端点（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、签名版本、时间戳、区域、服务、签名头列表和最终签名摘要的字符串。关于签名计算的详细步骤、伪代码示例及各语言 SDK 的使用方法，请参考火山引擎官方文档：[签名机制说明](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 = "/iceberg/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 ``` ## 核心 API 说明以下是 Gravitino Server 的核心 OpenAPI 接口说明。所有接口均需通过 HTTP 访问，并遵循“使用前准备”章节中描述的签名认证方式。 ### 查询 Metalake 信息加载指定 Metalake 的详细信息。在火山引擎环境中，这通常对应当前的火山引擎账号。 * **方法**：`GET` * **路径**：`/api/metalakes/{metalake_name}` **路径参数**： |参数名 |类型 |是否必选 |描述 | |---|---|---|---| |`metalake_name` |String |是 |Metalake 的名称，对应火山引擎账号 ID。 | **请求示例**： ```Bash 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}' ``` **返回示例**： ```JSON { "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` **请求示例**： ```Bash 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}' ``` **返回示例**： ```JSON { "code": 0, "identifiers": [ { "namespace": [ "your_account_id" ], "name": "hive_prod" } ] } ``` ### 加载 Catalog 获取指定 Catalog 的详细信息。 * **方法**：`GET` * **路径**：`/api/metalakes/{metalake_name}/catalogs/{catalog_name}` **请求示例**： ```Bash 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}' ``` **返回示例**： ```JSON { "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` **请求示例**： ```Bash 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}' ``` **返回示例**： ```JSON { "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` **请求示例**： ```Bash 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}' ``` **返回示例**： ```JSON { "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 请求签名有误。请仔细检查： 1. AK/SK 是否正确且未过期。 2. `X-Date` 请求头的时间是否与服务器的当前 UTC 时间一致，误差不应超过 15 分钟。 3. 参与签名的 HTTP 请求内容（方法、路径、参数、请求头）是否与实际发送的一致。 4. 签名计算过程是否严格遵循了火山引擎官方文档的规范。 **Q：如何确认应该使用哪个** **`metalake_name`** **？** **A**：`metalake_name` 固定映射为火山引擎账号 ID。您可以在火山引擎控制台的账号管理页面找到它。 **Q：创建 Catalog 时** **`provider`** ** 字段应该填什么？** **A**：`provider` 指定了 Catalog 的类型，例如 `hive`、`iceberg`、`jdbc` 等。在火山引擎托管环境中，通常应填 `hive`，以对接到 LAS 的 Hive Catalog。

AI 数据湖服务