> For the complete documentation index, see [llms.txt](https://docs.reorc.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reorc.com/cn-reorc-help-center/data-service/kai-fang-api.md). # 开放 API {% hint style="info" %} 拥有查看权限的用户可以通过 API 获取数据 {% endhint %} ## 获取 API KEY * 在数据服务页面内点击“如何调用 API？” * 在弹窗内复制个人的 API 密钥
## 如何调用 API？ ### 请求示例 {% code overflow="wrap" %} ```sh curl --location --request POST 'https://{{ domain_of_your_recurve_address }}/api/data-service/open/services/{{ data_service_id }}/preview' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'Authorization: Bearer {{ your_api_key }}' \ --data-raw '{ "filters": [ { "field": "PaymentMethod", "operator": "=", "value": "Cash" } ], "filter_logic": "all", "sorts": [], "timezone": "Asia/Shanghai" }' ``` {% endcode %} 请将下列参数替换为实际值： * domain\_of\_your\_recurve\_address：根据你使用的 Recurve 的域名。可以在浏览器控制台 - 网络/Network 中查看到 API 的 Request URL
* data\_service\_id：数据服务实体标识 * your\_api\_key：切换为你的 API Key，可以在数据服务的详情页面内获取，详见 [#get\_api\_key](#get_api_key "mention") ### 请求头 * URL：/api/data-service/open/services/{{ data\_service\_id }}/preview * 请求方法：POST * 请求头名称：Authorization * 值：bearer {{ API\_KEY }} ### 请求体 请求体示例： ```json { "filters": [ { "field": "PaymentMethod", "operator": "=", "value": "Cash" }, { "field": "Paydate", "operator": "time_between", "value": ["2023-12-05", "2024-05-06"] }, { "field": "OrderTime", "operator": "time_relative", "value": "last_year" } ], "filter_logic": "all", "sorts": [ { "field": "Paydate", "order": "asc" } ], "timezone": "Asia/Shanghai", "page": 1, "page_size": 200 } ``` 接下来逐一解释各个参数的含义及用法 #### filters 使用 `filters` 定义筛选条件，数组格式，可添加多个筛选条件。每个筛选条件通过以下字段来传参：
参数名类型描述
fieldstring字段名称
operatorstring

操作符。

  • 比较操作符：=, !=, > ,<, <=, ~(包含), !~(不包含)

  • 时间操作符：

    • time_between
    • time_relative：相对时间, 支持 today, yesterday , this_week, last_week, this_month, this_year, last_year
valueint/string/array/datetime...

筛选值, 类型取决于字段类型，例如field为int类型, value可传int类型的数值。

注意 operator 为time_between
时，value 值需要为array，即[start_time, end_time]

#### filter\_logic 筛选条件之间的且或关系，可选值为： * all：表示“且” * any：表示“或” #### sorts 用于定义排序的条件，可添加多个排序条件。每个排序条件使用以下字段定义：
参数名类型描述
fieldstring用于排序的字段名称
orderstring排序顺序, asc (升序), desc (降序）
#### page 及 page\_size 用于分页相关的参数，建议加上排序字段，以确保分页后返回数据的顺序正确无误
参数名类型描述
pageint页数
page_sizeint每页返回的数据量 [100, 10000]，默认100
#### timezone 时区 | 参数名 | 类型 | 描述 | | -------- | ------ | ---------------------------------------------------------------------------- | | timezone | string | 可选值，用于指定时间筛选条件中相对时间(time\_relative)的基准时间时区。 | ## 响应结果示例 {% tabs %} {% tab title="成功示例" %} 成功响应结果示例 ```json { "code": "0", "msg": "success", "data": { "total": 304, "items": [ { "o_orderkey": { "type": "bigint", "name": "o_orderkey", "normalized_type": "integer", "value": "5997922" }, "o_orderdate": { "type": "date", "name": "o_orderdate", "normalized_type": "date", "value": "1992-12-04" }, "o_custkey": { "type": "int", "name": "o_custkey", "normalized_type": "integer", "value": "88970" }, "o_orderstatus": { "type": "varchar", "name": "o_orderstatus", "normalized_type": "string", "value": "F" }, "o_totalprice": { "type": "decimal", "name": "o_totalprice", "normalized_type": "float", "value": "91422.19" }, "o_orderpriority": { "type": "varchar", "name": "o_orderpriority", "normalized_type": "string", "value": "4-NOT SPECIFIED" }, "o_clerk": { "type": "varchar", "name": "o_clerk", "normalized_type": "string", "value": "Clerk#000000108" }, "o_shippriority": { "type": "int", "name": "o_shippriority", "normalized_type": "integer", "value": "0" }, "o_comment": { "type": "varchar", "name": "o_comment", "normalized_type": "string", "value": "oze blithely across the slyly bold packages. dolphin" } }, { "o_orderkey": { "type": "bigint", "name": "o_orderkey", "normalized_type": "integer", "value": "5997921" }, "o_orderdate": { "type": "date", "name": "o_orderdate", "normalized_type": "date", "value": "1997-03-16" }, "o_custkey": { "type": "int", "name": "o_custkey", "normalized_type": "integer", "value": "117583" }, "o_orderstatus": { "type": "varchar", "name": "o_orderstatus", "normalized_type": "string", "value": "O" }, "o_totalprice": { "type": "decimal", "name": "o_totalprice", "normalized_type": "float", "value": "68401.33" }, "o_orderpriority": { "type": "varchar", "name": "o_orderpriority", "normalized_type": "string", "value": "2-HIGH" }, "o_clerk": { "type": "varchar", "name": "o_clerk", "normalized_type": "string", "value": "Clerk#000000101" }, "o_shippriority": { "type": "int", "name": "o_shippriority", "normalized_type": "integer", "value": "0" }, "o_comment": { "type": "varchar", "name": "o_comment", "normalized_type": "string", "value": "xcuses nag slyly. idle dolphins cajole ironically-- regular, bold ex" } }, { "o_orderkey": { "type": "bigint", "name": "o_orderkey", "normalized_type": "integer", "value": "5997920" }, "o_orderdate": { "type": "date", "name": "o_orderdate", "normalized_type": "date", "value": "1992-08-02" }, "o_custkey": { "type": "int", "name": "o_custkey", "normalized_type": "integer", "value": "42044" }, "o_orderstatus": { "type": "varchar", "name": "o_orderstatus", "normalized_type": "string", "value": "F" }, "o_totalprice": { "type": "decimal", "name": "o_totalprice", "normalized_type": "float", "value": "36627.47" }, "o_orderpriority": { "type": "varchar", "name": "o_orderpriority", "normalized_type": "string", "value": "1-URGENT" }, "o_clerk": { "type": "varchar", "name": "o_clerk", "normalized_type": "string", "value": "Clerk#000000205" }, "o_shippriority": { "type": "int", "name": "o_shippriority", "normalized_type": "integer", "value": "0" }, "o_comment": { "type": "varchar", "name": "o_comment", "normalized_type": "string", "value": "al instructions nag carefully until the requests. fluffily re" } }, { "o_orderkey": { "type": "bigint", "name": "o_orderkey", "normalized_type": "integer", "value": "5997895" }, "o_orderdate": { "type": "date", "name": "o_orderdate", "normalized_type": "date", "value": "1996-01-15" }, "o_custkey": { "type": "int", "name": "o_custkey", "normalized_type": "integer", "value": "91180" }, "o_orderstatus": { "type": "varchar", "name": "o_orderstatus", "normalized_type": "string", "value": "O" }, "o_totalprice": { "type": "decimal", "name": "o_totalprice", "normalized_type": "float", "value": "199978.64" }, "o_orderpriority": { "type": "varchar", "name": "o_orderpriority", "normalized_type": "string", "value": "2-HIGH" }, "o_clerk": { "type": "varchar", "name": "o_clerk", "normalized_type": "string", "value": "Clerk#000000075" }, "o_shippriority": { "type": "int", "name": "o_shippriority", "normalized_type": "integer", "value": "0" }, "o_comment": { "type": "varchar", "name": "o_comment", "normalized_type": "string", "value": "ly among the regular, even depend" } } ], "error": null } } ``` {% endtab %} {% tab title="失败示例" %} 失败响应结果示例 ```json { "code": "0", "msg": "success", "data": { "total": 0, "items": [], "error": { "code": "A1402", "reason": "Preview data failed: (1105, \"errCode = 2, detailMessage = Unknown column 'o_orderke' in '_recurve_limit_subquery' in SORT clause\")", "data": null } } } ``` {% endtab %} {% endtabs %}