# Restful API

> 来源：https://help.gravity-engine.com/docs/server-integration/event-collection/restful-api
> 说明如何通过 Gravity Engine RESTful API 上报用户行为与用户属性，包括认证、请求体、返回结果和混合上报要求。



引力引擎支持使用 API 方式直接上报用户行为事件和用户属性事件，您可以配合引力引擎客户端 SDK 实现混合上报。

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

服务端接入 Restful API，完成事件的服务端报送功能，您需要注意以下几点：

* 服务端仅负责事件的收集上报，不负责用户的注册，用户注册需要调用客户端 SDK 的 `initialize` 方法完成；
* 客户端和服务端使用的用户 `client id` 需要保持一致；
* 在客户端完成 `initialize` 方法调用之后，服务端才能开始做事件采集上报，否则上报不成功；
* 服务端接入事件上报时，请参考 [元事件页面](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 下关于事件的详情属性；
* 请尽量上报事件的公共属性，引力不做强制要求，但是上报足够多属性，可以方便您后续在引力平台使用数据分析功能（`$city`、`$province`、`$country`、`$browser`、`$browser_version` 属性可以不上报，引力后端会自动采集）；
* 关于属性的更多信息，请您参考 [事件属性页面](https://web.gravity-engine.com/#/manage/metadata/eventProperty)。

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

### 请求地址 [#请求地址]

```text
https://backend.gravity-engine.com/event_center/api/v1/event/collect/
```

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

POST

### query 参数 [#query-参数]

| 参数名称           | 必填 | 参数说明                    |
| -------------- | -- | ----------------------- |
| `access_token` | Y  | 当前 app 的 `access_token` |

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

| 参数名          | 必填 | 类型             | 描述                                    |
| ------------ | -- | -------------- | ------------------------------------- |
| `client_id`  | Y  | string         | 用户唯一 ID                               |
| `client_ip`  | N  | string         | 如果有值，则引力引擎会取该 `ip` 作为 `$ip` 字段（强制替换）  |
| `client_ua`  | N  | string         | 如果有值，则引力引擎会取该 `ua` 作为 `$ua` 字段（强制替换）  |
| `event_list` | Y  | EventObject\[] | 事件列表，具体参见 [EventObject](#eventobject) |

### EventObject [#eventobject]

| 参数名          | 必填 | 类型     | 描述                                                                                                                                                                                                          |
| ------------ | -- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`       | Y  | string | 事件类型，可选值：`track`、`profile`，分别对应用户埋点事件、用户属性事件                                                                                                                                                                |
| `event`      | Y  | string | 用户埋点事件英文名称请参考 [引力后台-设置-元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)，用户属性事件名称参考 [这里](/docs/getting-started/data-rules#2-%E7%94%A8%E6%88%B7%E8%A1%A8%E6%93%8D%E4%BD%9C%E9%80%BB%E8%BE%91) |
| `time`       | Y  | number | 事件发生毫秒级时间戳，只接收相对服务器时间在前 10 天至后 1 小时之内的数据，超过范围的数据将不会入库                                                                                                                                                       |
| `time_free`  | N  | bool   | 默认为 `false`，当为 `true` 时会取消对 `time` 参数的校验（一般用于历史数据导入）                                                                                                                                                        |
| `properties` | Y  | struct | 事件属性/用户属性，具体需要参考 [引力引擎后台-设置-元数据](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 中的内容                                                                                                           |

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

```bash
curl 'https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=<ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "client_id": "user_client_id",
    "client_ip": "114.138.179.81",
    "event_list": [
        {
            "type": "track",
            "event": "$MPLaunch",
            "time": 1669860000000,
            "time_free": true,
            "properties": {
                "$is_first_time": false,
                "$scene": "1069",
                "$screen_width": 360,
                "$screen_height": 800,
                "$os": "android",
                "$manufacturer": "realme",
                "$city": "南京市",
                "$trace_id": "c1a953d236db6591661543419e436677"
            }
        },
        {
            "type": "profile",
            "event": "profile_set_once",
            "time": 1669824000000,
            "time_free": true,
            "properties": {
                "$signup_time": "2022-12-01 00:00:00"
            }
        }
    ]
}'
```

### 响应结果 [#响应结果]

如果收到返回参数，`code: 0`，则代表数据传输成功。

响应示例：

```json
{
    "data": {},
    "extra": {
        "error": "",
        "errors": []
    },
    "code": 0,
    "msg": "成功"
}
```