# 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) 中的内容                                                                                                           |

通过 API 上报时，请在每个事件的 `properties` 中设置 `"$lib": "api"`，与 [混合上报模式](/docs/client-sdk/hybrid-reporting) 保持一致。

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

先填写测试应用的 Access Token 和已初始化成功的 ClientID。下面在发送时生成当前毫秒时间戳；生产业务应使用订单实际支付时间。此命令会向真实采集接口上报一条 6 元测试付费事件，请只在确认过的测试应用中执行，并使用未重复的测试订单号。

```bash
ACCESS_TOKEN='YOUR_ACCESS_TOKEN'
CLIENT_ID='YOUR_INITIALIZED_CLIENT_ID'
EVENT_TIME_MS=$(node -p 'Date.now()')

curl "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=${ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"client_id\": \"${CLIENT_ID}\",
    \"event_list\": [{
      \"type\": \"track\",
      \"event\": \"\$PayEvent\",
      \"time\": ${EVENT_TIME_MS},
      \"time_free\": false,
      \"properties\": {
        \"\$lib\": \"api\",
        \"\$pay_amount\": 600,
        \"\$pay_type\": \"CNY\",
        \"\$order_id\": \"YOUR_UNIQUE_TEST_ORDER_ID\",
        \"\$pay_reason\": \"测试商品\",
        \"\$pay_method\": \"微信\",
        \"\$is_first_pay\": false
      }
    }]
  }"
```

上述命令依赖本地 Node.js 生成时间戳。美元符号前的反斜杠用于避免 shell 将预置事件和属性名当作变量展开，复制时请保留。用户属性操作仍使用同一外层结构，并按 [数据规则](/docs/getting-started/data-rules) 设置 `type`、`event` 和 `properties`。

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

响应中 `code: 0` 表示接口返回传输成功。仍需在 [事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 按 ClientID 核对实际入库情况，包括订单号、金额和属性类型；HTTP `200` 本身不能代替业务结果检查。

响应示例：

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