开放 API

拥有查看权限的用户可以通过 API 获取数据

获取 API KEY

• 在数据服务页面内点击“如何调用 API？”

• 在弹窗内复制个人的 API 密钥

如何调用 API？

请求示例

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"
}'

请将下列参数替换为实际值：

• domain_of_your_recurve_address：根据你使用的 Recurve 的域名。可以在浏览器控制台 - 网络/Network 中查看到 API 的 Request URL

• data_service_id：数据服务实体标识

• your_api_key：切换为你的 API Key，可以在数据服务的详情页面内获取，详见 获取 API KEY

请求头

• URL：/api/data-service/open/services/{{ data_service_id }}/preview

• 请求方法：POST

• 请求头名称：Authorization

• 值：bearer {{ API_KEY }}

请求体

请求体示例：

{
    "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 定义筛选条件，数组格式，可添加多个筛选条件。每个筛选条件通过以下字段来传参：

参数名	类型	描述
field	string	字段名称
operator	string	操作符。 比较操作符：=, !=, > ,<, <=, ~(包含), !~(不包含) 时间操作符： time_between time_relative：相对时间, 支持 today, yesterday , this_week, last_week, this_month, this_year, last_year
value	int/string/array/datetime...	筛选值, 类型取决于字段类型，例如field为int类型, value可传int类型的数值。 注意 operator 为time_between 时，value 值需要为array，即[start_time, end_time]

filter_logic

筛选条件之间的且或关系，可选值为：

• all：表示“且”

• any：表示“或”

sorts

用于定义排序的条件，可添加多个排序条件。每个排序条件使用以下字段定义：

参数名	类型	描述
field	string	用于排序的字段名称
order	string	排序顺序, asc (升序), desc (降序）

page 及 page_size

用于分页相关的参数，建议加上排序字段，以确保分页后返回数据的顺序正确无误

参数名	类型	描述
page	int	页数
page_size	int	每页返回的数据量 [100, 10000]，默认100

timezone 时区

参数名	类型	描述
timezone	string	可选值，用于指定时间筛选条件中相对时间(time_relative)的基准时间时区。

响应结果示例

成功示例

成功响应结果示例

{
    "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
    }
}

失败示例

失败响应结果示例

{
    "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
        }
    }
}