OpenAPI 接入说明

Instant API 的原始运行态接口有三种常见入口：

入口	路径规则	鉴权	请求体	覆盖范围
WebAPI	/api/{appCode}/{datasetCode}/{method}	Cookie	直接传业务参数	支持 9 个核心 Instant API
Client API	/client/{appCode}/{datasetCode}/{method}	个人身份认证，X-User-AK	直接传业务参数	支持 9 个核心 Instant API
OpenAPI	/openapi/data/{method}	HMAC Header	{ appCode, datasetCode, paramMap } 或 paramList	支持部分数据操作

如果目标是“把 9 个 Instant API 都 curl 一遍”，优先看 Instant API：9 个原始接口与 Node.js SDK 封装，其中使用的是 WebAPI 原始路径。

1. OpenAPI 的定位

OpenAPI 是给外部系统、服务端任务、Agent 网关、低代码平台使用的 HMAC 签名入口。它不依赖用户 Cookie，适合服务端到服务端调用。

OpenAPI 不是 WebAPI 的逐项同名镜像。当前 Node.js SDK 的 OpenAPI 模式使用这些路径：

Instant API	OpenAPI 路径	请求体形态	支持情况
filter	/openapi/data/filter	{ appCode, datasetCode, paramMap }	支持
aggregate	/openapi/data/aggregate	{ appCode, datasetCode, paramMap }	支持
getOne	/openapi/data/get-one	{ appCode, datasetCode, paramMap: { id } }	支持
create	/openapi/data/create	{ appCode, datasetCode, paramMap }	支持
batchCreate	/openapi/data/batch-create	{ appCode, datasetCode, paramList }	支持
update	/openapi/data/update	{ appCode, datasetCode, paramMap }	支持
delete	-	-	暂不支持
getSelectOptions	-	-	暂不支持
excelExport	-	-	暂不支持

2. 原始 OpenAPI curl 形态

export RUNTIME_DOMAIN="https://runtime.lovrabet.com"
export APP_CODE="app_xxx"
export DATASET_CODE="dataset_xxx"
export TIMESTAMP="$(date +%s000)"
export TOKEN="hmac-token-generated-by-server"

curl -X POST "$RUNTIME_DOMAIN/openapi/data/filter" \
  -H "Content-Type: application/json" \
  -H "X-Time-Stamp: $TIMESTAMP" \
  -H "X-App-Code: $APP_CODE" \
  -H "X-Dataset-Code: $DATASET_CODE" \
  -H "X-Token: $TOKEN" \
  -d '{
    "appCode": "'"$APP_CODE"'",
    "datasetCode": "'"$DATASET_CODE"'",
    "paramMap": {
      "where": { "status": { "$eq": "paid" } },
      "currentPage": 1,
      "pageSize": 20
    }
  }'

TOKEN 由服务端根据 AccessKey、时间戳、appCode、datasetCode 生成。不要把 AccessKey 写入前端代码、公开仓库或日志。

3. Node.js SDK 封装

使用 OpenAPI 模式时，SDK 会自动生成签名并切到 /openapi/data/{method}：

import { createClient } from "@lovrabet/sdk";

const client = createClient({
  appCode: process.env.LOVRABET_APP_CODE,
  authMode: "openapi",
  accessKey: process.env.LOVRABET_ACCESS_KEY,
  runtimeDomain: process.env.LOVRABET_RUNTIME_DOMAIN || "https://runtime.lovrabet.com",
  models: [
    {
      tableName: "orders",
      datasetCode: process.env.LOVRABET_DATASET_CODE!,
      alias: "orders",
    },
  ],
});

const result = await client.models.orders.filter({
  where: { status: { $eq: "paid" } },
  currentPage: 1,
  pageSize: 20,
});

如果需要调用 delete、getSelectOptions、excelExport，不要使用 OpenAPI 模式，改用 WebAPI Cookie 或 Client API。

4. 详细参考

文档	用途
OpenAPI	OpenAPI 认证、签名、路径、请求体和完整接口说明
TypeScript SDK	Node.js / TypeScript SDK 的完整接入和 SDK 方法说明
Java SDK	Java 服务端 SDK 的完整接入和调用示例