# 导出用户行为事件

> 来源：https://help.gravity-engine.com/docs/server-integration/reporting/export-user-events
> 说明如何通过 Gravity Engine OpenAPI 创建用户行为事件导出任务并按条件分批导出数据，涵盖认证、请求参数、筛选条件和返回字段。



引力引擎支持使用 `API` 方式直接导出应用内用户行为事件，本接口会返回导出任务的查询 ID，您可以根据此 ID 调用 [查询导出进度](/docs/server-integration/reporting/export-status) 接口查询事件导出任务进度和详情。

在开始对接此接口前，建议您先阅读 [数据规则](/docs/getting-started/data-rules) 章节，在熟悉引力引擎的数据格式与数据规则后，再阅读本指南进行对接。

## 申请引力开发者应用 [#申请引力开发者应用]

在正式接入本接口之前，您需要在引力后台-[引力开发者](https://web.gravity-engine.com/#/manage/develop)页面申请引力开发者应用，申请之后，我们将在一个工作日内完成审核，审核通过之后，您的开发者应用才可以正常拉取数据。

创建好开发者应用之后，请复制 `app_key` 参数，并发送给研发同学以供后续接口调用使用。

## 接口限频 [#接口限频]

默认接口限频：每 10 秒 100 次。接口限频按开发者应用维度统计，即同一个 `app_key` 下的应用共用同一套频次限制。如果开发者绑定应用过多导致频繁触发限频，请联系引力运营评估后提升限频等级。

## 接口信息 [#接口信息]

> **为保障导出性能，单次最多可导出 100 万条事件。如果您的数据量较大，建议结合筛选条件进行分批导出。**

### 接口地址 [#接口地址]

```text
https://api-insight.gravity-engine.com/openapi/api/v1/download/event/submit_task/
```

### 请求方法 [#请求方法]

POST

### 请求参数 [#请求参数]

#### Header 参数 [#header-参数]

| 字段            | 类型     | 描述                                                            |
| ------------- | ------ | ------------------------------------------------------------- |
| Authorization | string | 具体如何生成，请参考 [【签名生成】](/docs/server-integration/request-signing) |

#### Body 参数 [#body-参数]

| 字段                | 必填 | 参数类型            | 描述                                                          |
| ----------------- | -- | --------------- | ----------------------------------------------------------- |
| `app_id`          | Y  | int             | 待获取数据的引力应用的 `appid`                                         |
| `task_type`       | Y  | string          | 固定值：`origin_event_data`                                     |
| `cond_logic`      | Y  | string          | 条件连接符，枚举值：`AND` / `OR`                                      |
| `conditions`      | Y  | FilterObject\[] | 数据筛选条件数组，具体参见 [FilterObject](#filterobject-筛选条件对象)          |
| `event_name_list` | Y  | string\[]       | 导出事件列表                                                      |
| `time_range`      | Y  | string\[]       | 导出事件的日期范围，最长支持 30 天                                         |
| `sign`            | Y  | string          | 签名，详情请参考 [【签名生成】](/docs/server-integration/request-signing) |

#### FilterObject 筛选条件对象 [#filterobject-筛选条件对象]

| 字段         | 必填 | 参数类型   | 描述                                                                            |
| ---------- | -- | ------ | ----------------------------------------------------------------------------- |
| `field`    | Y  | string | 要筛选的属性名，默认属性见下表                                                               |
| `operator` | Y  | string | 筛选操作符，具体参见 [【操作符说明(operator)】](/docs/appendix/multidimensional-report-fields) |
| `type`     | Y  | string | 属性类型，枚举值：`user`（用户自定义属性）、`default_user`（默认属性）                                 |
| `values`   | Y  | any\[] | 筛选值数组，根据属性类型传入对应值                                                             |

#### 默认属性字段说明表 [#默认属性字段说明表]

| 字段名                             | 参数类型      | 描述                              |
| ------------------------------- | --------- | ------------------------------- |
| `client_id_list`                | string\[] | 用户唯一 ID                         |
| `wx_openid_list`                | string\[] | 用户的 OpenID                      |
| `create_time_list`              | date\[]   | 用户注册时间，只支持 `RANGE_IN` 筛选操作符     |
| `ad_click_time_list`            | date\[]   | 广告点击时间，只支持 `RANGE_IN` 筛选操作符     |
| `ad_platform_list`              | string\[] | 媒体平台名称                          |
| `aid_list`                      | string\[] | 广告 ID                           |
| `gid_list`                      | string\[] | 广告计划 ID                         |
| `cid_list`                      | string\[] | 广告创意 ID                         |
| `advertiser_id_list`            | string\[] | 广告账户 ID                         |
| `channel_list`                  | string\[] | 客户端渠道信息                         |
| `version_list`                  | int\[]    | 用户注册时的版本号                       |
| `turbo_promoted_object_id_list` | string\[] | 推广活动 ID                         |
| `modify_time_list`              | date\[]   | 用户数据最后更新时间，只支持 `RANGE_IN` 筛选操作符 |
| `latest_login_day_list`         | date\[]   | 用户最近活跃日期，只支持 `RANGE_IN` 筛选操作符   |

### 请求示例 [#请求示例]

```bash
curl 'https://api-insight.gravity-engine.com/openapi/api/v1/download/event/submit_task/' \
-H 'Content-Type: application/json' \
-H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiMWMyOGU2MDNlNzE2NGNiYWFjZWEwMGU5ODkxNTNhNGQifQ.efuTqAmvh3klVyt05Qjr4ZrYpPlNCtEstlVWozjk_9o' \
-d '{
    "app_id": 21295084,
    "cond_logic": "AND",
    "task_type": "origin_event_data",
    "conditions": [
        {
            "field": "$province",
            "operator": "NOT_EQUALS",
            "type": "user",
            "value": [
                "云南"
            ]
        },
        {
            "field": "create_date_list",
            "operator": "RANGE_IN",
            "type": "default_user",
            "value": [
                "2025-10-01 00:00:00",
                "2025-10-31 23:59:59"
            ]
        }
    ],
    "event_name_list": [
        "$PayEvent",
        "$CreateRole",
        "$UserAttribution",
        "$ViewMallContent"
    ],
    "sign": "0b8550f1f5a9c96bed5d06a47b55a5de",
    "time_range": [
        "2025-10-20",
        "2025-10-26"
    ]
}'
```

### 响应参数 [#响应参数]

| 字段        | 描述                                                                                                   |
| --------- | ---------------------------------------------------------------------------------------------------- |
| `task_id` | 应用事件导出的任务的任务 ID。可根据此任务 ID 调用 [任务进度查询接口](/docs/server-integration/reporting/export-status) 查询事件导出任务进度 |

### 响应示例 [#响应示例]

```json
{
    "code": 0,
    "data": {
        "task_id": "56b98c5a9a774e458db441d7e9885972"
    },
    "extra": {
        "error": "",
        "request_id": "56b98c5a9a774e458db441d7e9885972"
    },
    "msg": "成功"
}
```