# 开放 API

{% hint style="info" %}
拥有查看权限的用户可以通过 API 获取数据
{% endhint %}

## 获取 API KEY <a href="#get_api_key" id="get_api_key"></a>

* 在数据服务页面内点击“如何调用 API？”
* 在弹窗内复制个人的 API 密钥

<figure><img src="/files/zmhe6E9apBUfVdrXfuHd" alt=""><figcaption></figcaption></figure>

## 如何调用 API？ <a href="#how_to_call_api" id="how_to_call_api"></a>

### 请求示例

{% 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

<figure><img src="/files/DCKRTONKzio6A93Bwa7O" alt=""><figcaption></figcaption></figure>

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

<table><thead><tr><th width="123.4921875">参数名</th><th width="148.8125">类型</th><th width="460.28125">描述</th></tr></thead><tbody><tr><td>field</td><td>string</td><td>字段名称</td></tr><tr><td>operator</td><td>string</td><td><p>操作符。</p><ul><li><code>比较操作符：=</code>, <code>!=</code>, <code>></code> ,<code>&#x3C;</code>, <code>&#x3C;=</code>, <code>~</code>(包含), <code>!~</code>(不包含)</li><li><p><code>时间操作符：</code></p><ul><li><code>time_between</code></li><li><code>time_relative：</code>相对时间, 支持 <code>today</code>, <code>yesterday</code> , <code>this_week</code>, <code>last_week</code>, <code>this_month</code>, <code>this_year</code>, <code>last_year</code> </li></ul></li></ul></td></tr><tr><td>value</td><td>int/string/array/datetime...</td><td><p>筛选值, 类型取决于字段类型，例如field为int类型, value可传int类型的数值。</p><p>注意 operator 为<code>time_between</code><br>时，value 值需要为array，即[start_time, end_time]</p></td></tr></tbody></table>

#### filter\_logic

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

* all：表示“且”
* any：表示“或”

#### sorts

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

<table><thead><tr><th width="198.71484375">参数名</th><th width="118.5546875">类型</th><th>描述</th></tr></thead><tbody><tr><td>field</td><td>string</td><td>用于排序的字段名称</td></tr><tr><td>order</td><td>string</td><td>排序顺序, <code>asc</code> (升序), <code>desc</code> (降序）</td></tr></tbody></table>

#### page 及 page\_size

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

<table><thead><tr><th width="197.12109375">参数名</th><th width="121.828125">类型</th><th>描述</th></tr></thead><tbody><tr><td>page</td><td>int</td><td>页数</td></tr><tr><td>page_size</td><td>int</td><td>每页返回的数据量 [100, 10000]，默认100</td></tr></tbody></table>

#### timezone 时区

| 参数名      | 类型     | 描述                                                                           |
| -------- | ------ | ---------------------------------------------------------------------------- |
| timezone | string | 可选值，用于指定时间筛选条件中相对时间(<mark style="color:blue;">time\_relative</mark>)的基准时间时区。 |

## 响应结果示例

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.reorc.com/cn-reorc-help-center/data-service/kai-fang-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.