服务端集成 · 其他 · 推广活动列表

通过 Gravity Engine OpenAPI 分页查询推广活动，了解应用与项目范围、活动筛选、分页参数、请求示例及返回字段。

此接口用于分页查询指定应用或项目下的引力推广活动，支持按活动 ID、名称、状态、创建人及创建日期筛选。

接入准备

在引力后台－引力开发者申请开发者应用，审核通过并启用后，获取 app_key。所在主体需已开通 OpenAPI 功能；请求只能操作当前主体有权限的应用。

app_key 是开发者应用的凭证；请求中的 app_id 是引力业务应用 ID，两者用途不同。业务应用 ID 可通过应用信息查询获取。

认证方式

Header	类型	必填	说明
`Authorization`	string	是	按签名生成生成的 JWT 字符串，直接填写，不添加 `Bearer` 前缀
`Content-Type`	string	是	`application/json`

将本次实际发送的全部 body 参数（不含 sign）用于生成 sign，再使用 sign 与 app_key 生成 Authorization。修改任何参数后都需要重新生成两者。以下示例中的 ID、签名、认证字符串和返回数据均为示意值，调用时请替换。

接口信息

请求地址：https://api-insight.gravity-engine.com/openapi/api/v1/user/promoted_object/list/
请求方法：POST
请求格式：JSON body。分页与筛选参数均放在 body 中。
默认排序：按创建时间倒序；不支持自定义排序。

body 参数

参数名	必填	类型	说明
`app_id`	条件必填	int	查询单个应用时填写引力业务应用 ID
`app_ids`	条件必填	string	查询多个应用时填写整数 ID 数组的 JSON 字符串，例如 `"[12345678,23456789]"`；不可直接传 JSON 数组
`project_id`	条件必填	int	查询项目下有权限的应用时填写项目 ID
`many_meaning`	否	string	同时匹配活动 ID（精确）或活动名称（包含）
`page`	否	int	页码，从 `1` 开始，默认 `1`，最大 `2000`；超出最大值按 `2000` 处理
`page_size`	否	int	每页条数，默认 `100`，最大 `5000`；超出最大值按 `5000` 处理
`filters`	否	object[]	筛选条件数组，结构见下表；省略表示不附加筛选条件
`sign`	是	string	本次请求的签名，参考签名生成

app_id、app_ids、project_id 至少选择一种查询范围。传入非零 project_id 时，以项目内有权限的应用为准；否则，优先使用非空 app_ids，再使用 app_id。建议一次只使用一种范围参数。page 和 page_size 必须为正整数。

筛选条件

每个条件包含 field（字段名）、operator（数字操作符）和 values（取值数组）；多个条件按 AND 组合。支持以下字段：

field	operator	values 类型与数量	说明
`turbo_promoted_object_id`	`1`	string[]，恰好 1 项	活动 ID 精确匹配
`turbo_promoted_object_name`	`8`	string[]，恰好 1 项	活动名称包含指定文本
`create_user_id`	`6`	int[]，1～1000 项	创建人 ID 在指定集合内
`operator_id`	`6`	int[]，1～1000 项	操作人 ID 在指定集合内
`create_time`	`7`	string[]，恰好 2 项	创建日期范围，例如 `["2026-10-01", "2026-10-17"]`，格式为 `YYYY-MM-DD`
`state`	`1`	int[]，恰好 1 项	状态：`1` 启用、`2` 关停

values 即使只有一个值也必须是数组。不要直接在 body 顶层传活动名称或 state 来代替 filters。未传 state 条件时，列表包含启用及关停的活动。

请求示例

查询指定应用下名称包含“秋季”、状态为启用的推广活动：

curl --request POST 'https://api-insight.gravity-engine.com/openapi/api/v1/user/promoted_object/list/' \
  --header 'Authorization: YOUR_AUTHORIZATION' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "app_id": 12345678,
    "page": 1,
    "page_size": 100,
    "filters": [
      {"field": "turbo_promoted_object_name", "operator": 8, "values": ["秋季"]},
      {"field": "state", "operator": 1, "values": [1]}
    ],
    "sign": "YOUR_SIGN"
  }'

多应用查询时，将上述 app_id 替换为 "app_ids": "[12345678,23456789]"，并重新生成签名和认证字符串。

返回结果

应答示例

{
  "data": {
    "page_info": {
      "page": 1,
      "page_size": 100,
      "total_number": 1,
      "total_page": 1
    },
    "list": [
      {
        "app_id": 12345678,
        "turbo_promoted_object_id": "a1b2c3d4e5f6g7h8",
        "turbo_promoted_object_name": "秋季推广活动",
        "callback_url": "",
        "redirect_url": "",
        "remark": "秋季投放",
        "state": 1,
        "create_time": "2026-10-17 10:00:00",
        "modify_time": "2026-10-17 10:00:00",
        "create_user_id": 10001,
        "create_user_name": "管理员",
        "operator_id": 10001,
        "operator_name": "管理员",
        "update_user_id": 0,
        "update_user_name": ""
      }
    ]
  },
  "extra": {
    "error": "",
    "request_id": "0123456789abcdef0123456789abcdef"
  },
  "code": 0,
  "msg": "成功"
}

返回字段

字段	类型	说明
`code`	int	外层业务状态码，`0` 表示外层处理成功
`msg`	string	状态描述
`extra.error`	string	错误描述，正常时为空字符串
`extra.request_id`	string	请求标识，排查问题时请提供
`data.list`	object[]	当前页推广活动列表，无匹配记录时为 `[]`
`data.page_info.page`	int	当前页码
`data.page_info.page_size`	int	实际每页条数
`data.page_info.total_number`	int	匹配的记录总数
`data.page_info.total_page`	int	总页数，无记录时为 `0`

data.list 中每个对象包含以下字段，时间按北京时间（UTC+8）返回：

字段	类型	说明
`app_id`	int	所属引力业务应用 ID
`turbo_promoted_object_id`	string	系统生成的 16 位推广活动 ID
`turbo_promoted_object_name`	string	推广活动名称
`callback_url`	string	回调链接；未设置时为空字符串
`redirect_url`	string	重定向地址；未设置时为空字符串
`remark`	string	备注
`state`	int	活动状态：`1` 启用、`2` 关停
`create_time`	string	创建时间，格式 `YYYY-MM-DD HH:mm:ss`
`modify_time`	string	最后修改时间，格式 `YYYY-MM-DD HH:mm:ss`
`create_user_id` / `create_user_name`	int / string	创建人 ID / 名称
`operator_id` / `operator_name`	int / string	操作人 ID / 名称
`update_user_id` / `update_user_name`	int / string	最后更新人 ID / 名称；尚未更新时通常为 `0` / 空字符串

调用注意事项

根据 data.page_info.total_page 逐页查询；修改 page 后重新生成 sign 和 Authorization。超出结果总页数时，data.list 为空。
同时检查 code、extra.error 及 data 结构。当前接口在部分分页、筛选校验失败场景下，可能仍返回外层 code=0，且不包含具体错误；缺少 data.list 或 data.page_info 时应视为异常。空列表也可能由错误筛选触发，不能仅凭 code=0 判断筛选条件有效。
缺少认证信息、签名错误、开发者应用不可用或请求被限流时，请检查 code、msg 和 extra.error。限流额度以开发者应用实际配置为准；遇到限流请降低调用频率并退避重试。
如需新建活动，请使用推广活动创建。

推广活动列表

本页内容