Lance REST 命名空间¶

在企业环境中，通常需要将表存储在元数据服务中，以实现更高级的治理功能，如访问控制、审计、血缘跟踪等。Lance REST 命名空间是一个 OpenAPI 协议，它通过连接这些元数据服务或以标准化方式构建自定义元数据服务器，实现 Lance 表的读、写和管理。REST 服务器定义可在 OpenAPI 规范中找到。

配置¶

Lance REST 命名空间接受以下配置属性

属性	必填	描述	默认值	示例
`uri`	是	REST API 的 URI 端点		`https://api.example.com/lance`
`delimiter`	否	用于解析 REST 路由中对象字符串标识符的分隔符	`.`	`.`, `/`, `::`, `#`
`headers.*`	否	随每个请求发送的附加请求头		`headers.Authorization=Bearer...`

请求头¶

带有 headers. 前缀的属性在移除前缀后，将作为 HTTP 请求头随每个请求发送到 REST 服务器。例如，headers.Authorization 变为 Authorization 请求头。

常见的请求头配置包括：- headers.Authorization：身份验证令牌（Bearer、Basic 等）- headers.X-API-Key：API 密钥身份验证- headers.X-Request-ID：请求跟踪

REST 路由¶

操作的 REST 路由通常遵循 POST /<version>/<object>/{id}/<action> 的模式，例如 POST /v1/namespace/{id}/list 用于 ListNamespace。请求和响应模式用作路由的实际请求和响应。

REST 路由的关键设计原则是，反向代理（例如负载均衡、认证、授权）所需的所有信息都应该可以访问，而无需反序列化请求体。

对于涉及多个对象的路由，所有相关对象都应存在于路由中。例如，RenameTable 的路由因此是 POST /v1/table/{from_id}/rename/to/{to_id}。

标准操作¶

标准操作应接受与任何其他实现相同的请求并返回相同的响应。

路由中的信息也可以出现在请求体中。当路由和请求体中的信息都存在但不匹配时，服务器必须抛出 400 Bad Request 错误。当请求体中的信息缺失时，服务器必须使用路由中的信息。

非标准操作¶

对于无法简单描述为 JSON 对象的请求和响应，REST 服务器需要进行特殊处理，通过路径参数、查询参数和请求头来描述等效信息。具体的处理在 OpenAPI 规范中描述。以下是非标准操作

命名空间服务器和适配器¶

任何实现此 OpenAPI 协议的 REST HTTP 服务器都称为 Lance 命名空间服务器。如果您是元数据服务提供商，正在构建 Lance 命名空间的自定义实现，那么构建 REST 服务器可以为您提供与 Lance 的标准化集成，而无需担心工具支持和持续分发新版本的库，这与使用实现不同。

如果此服务器的主要目的是作为现有元数据服务之上的代理，在 Lance REST API 模型和元数据服务的原生 API 模型之间来回转换，那么此 Lance 命名空间服务器称为 Lance 命名空间适配器。

选择适配器还是实现¶

任何适配器都可以通过绕过 REST 服务器直接成为 Lance 命名空间实现，反之亦然。事实上，实现本质上是适配器的后端。例如，我们原生支持 Lance HMS 命名空间实现，以及通过使用 HMS 命名空间实现在 Lance REST 服务器中满足请求的 Lance 命名空间适配器。

如果您正在考虑在您的环境中构建或使用 Lance 命名空间适配器或实现，这里有一些需要考虑的标准

多语言可行性和维护成本：如果您想要一种适用于所有 Lance 语言绑定的单一策略，则首选适配器。有时，集成甚至不可能采用实现方法，因为它无法支持所有语言。有时，一个集成足够流行或重要，以至于构建一个实现并为每种语言维护一个库是可行的。
工具支持：每个工具都需要声明它支持的 Lance 命名空间实现。这意味着工具将始终优先支持 REST 命名空间，但可能不总是支持特定的实现。这有利于适配器方法。
安全性：如果您担心适配器是中间人，您应该选择一个实现。
性能：毕竟，适配器增加了一层间接性，因此不是性能最佳的解决方案。如果您对性能敏感，您应该选择一个实现。