客服电话：13904310313 
SPI订阅
简介
本文主要介绍订阅服务的使用步骤
订阅服务：提供主动推送信息的接口
订阅方式：推送的数据类型，消息/数据
创建订阅：目前订阅服务是以任务的形式展示，使用也同样是基于一条条的任务
优势：目前通过数据生产完成的消息，再去通过API网关进行主动的接口调用，可以减少绝大多数的无效调用，减少对于接口调用频控的浪费，减少对于相关接口的压力
使用简述
- 订阅人：目前使用者面向所有开发者，需要在认证完成且应用创建完成，因为订阅服务依赖于应用基础以及授权基础
- 可订阅内容：获得客户授权的投放账户下所有在数据报表中披露的数据
- 推送失败机制：此处指消息，因为数据需要开发者主动通过API网关获取，消息发送策略规则可以在创建订阅的时候在一定选项中选择，包括超时时间，重试间隔，最大重试次数
注意事项
- 每个应用下（APPID）针对同一个订阅服务类型，最多创建10个订阅任务。
- 订阅账号是在api已授权的账号范围内。
- 客户账号、代理商、旧版巨量引擎工作台账号下管理的客户的变更（解除或者新增投放账号）无需在订阅任务中进行二次修改。如订阅任务订阅的账号取消授权，将不会推送该账号下的客户数据，同时建议在订阅任务中手动勾掉订阅的账号
- SPI的鉴权依赖于API token，如果api接口对某一个adv账号的授权过期，将不会产生推送
流程图
使用流程
第一步：第三方开发者通过开放平台订阅需要的数据，配置推送规则
第二步：SPI网关进行数据推送或消息通知，客户接收并进行处理
数据生产完成后，会向订阅者预留的http地址发送订阅消息，告知数据生产就绪
- 消息接收 通过订阅任务中预留的http地址，巨量引擎按照规则向 预设的http地址发送消息
- 消息失败以及重试机制 依据的是创建订阅中，基础规则设置项（订阅规则、策略规则、通知规则）
- 消息具体内容 推送消息内容详见 【订阅服务类型】
第三步：开发者通过API网关进行数据拉取（可选）
收到数据订阅完成的消息后，表示数据生产过程已经完成，需要主动调用API提供的服务进行数据获取
收到推送的数据信息后，可直接对数据进行处理，无需重复调用api接口
- 调用API提供服务 对提供的API接口进行调用
订阅服务类型
SPI目前支持的订阅服务类型及对应类型返回的参数结构
目前支持订阅服务类型：report.advertiser.beforeday 客户报表稳定性数据
report.advertiser.activeprogram 客户报表实时数据
change.site.realtime 落地页事件推送
action.quota.realtime 在投计划配额
status.promotion.realtime营销投放升级版营销状态实时推送
status.project.realtime营销投放升级版项目状态实时推送
report.project.activeprogram营销投放升级版项目报表实时数据
report.promotion.activeprogram营销投放升级版营销报表实时数据
report.material.activeprogram营销投放升级版素材报表实时数据
status.qualification.ad.realtime 巨量营销投放资质状态推送
status.material.ad.realtime 巨量营销素材状态推送（仅支持巨量投放账户素材库下素材新增/删除变更通知）
settings.promotion.realtime 营销配置实时变更推送
settings.project.realtime 项目配置实时变更推送
agent_reject_promotion 代理商营销违规信息推送
adv.violation.score 违规积分事件推送
adv.disposal.score 积分处置事件推送
adv.reject_material.ai_repair 拒审素材修复成功事件
compensate.status.realtime 项目/营销成本保障状态变动
部分事件文档可从此目录【订阅服务类型】下的子文档中查找，本文档不包含
请求地址
订阅任务设置回调地址
请求方式
POST
请求Header
字段 | 类型 | 描述 |
Content-Type | string | 请求消息类型，允许值： |
X-Open-Signature | string | 签名，用来验证此次请求的合法性，具体算法见【X-Open-Signature签名校验】 |
请求参数
基础信息
字段 | 类型 | 描述 |
message_id | string | 消息ID，唯一标识 |
subscribe_task_id | number | 订阅任务ID |
advertiser_ids | number[] | 消息对应的客户账号， |
account_relation | object | 账号对应关系，包含所有 |
cc_ids | number[] | 旧版巨量引擎工作台账号 |
agent_ids | number[] | 代理商授权 |
advertiser_ids | number[] | 客户id直接授权 |
core_user_ids | number[] | 用户授权账号 |
service_label | string | 订阅服务类型
|
publish_time | number | 消息实际产生时间，毫秒时间戳 |
timestamp | number | 毫秒时间戳，本条消息实际推送时间，获取推送数据列表时无该参数数据 |
nonce | number | 随机数，和timestamp组合防重放，获取推送数据列表时无该参数数据 |
data | json string | 推送数据信息，订阅服务类型不同，返回结构不同 |
客户报表稳定性消息 report.advertiser.beforeday
无data内容，advertiser_ids返回已产出客户ID
客户报表实时数据 report.advertiser.activeprogram
注意：该data返回内容为客户数组列表
字段 | 类型 | 描述 |
advertiser_id | number | 客户id |
core_user_ids | number[] | 登陆用户ids |
落地页事件推送 change.site.realtime
字段 | 类型 | 描述 |
event | string | 事件名称，枚举值： |
user_id | string | 触发事件的客户ID（advertiser_id） |
content | object | 事件内容 |
site_id | number | 站点ID |
event_type | object | 事件变更类型，枚举值：
|
adv_id | number | 客户ID |
from | object | 变更前数据
|
to | object | 变更后数据 |
extra | string | 额外数据 |
在投计划配额
账户健康
参数名称 | 类型 | 描述 |
message_id | number | 唯一标识一条推送数据 |
service_label | string | 事件名称， |
data | object | 触发推送的事件消息 |
event | string |
|
user_id | number | 触发事件的用户id，营销场景即为advertiser_id |
content | object | 事件内容 |
message | string | 通知内容，示例：'尊敬的客户，您好！因您当前账户下的【所有营销】低效在投计划数过多，已经严重影响您的账户健康度，根据平台相关规则，【所有营销】已被【限制投放】。限制不会自动解除。建议您及时清理账户中的低效计划，完成清理后，可以联系和您对接的销售同学进行解除限制申诉（如您没有对接销售可通过平台右下方智能客服提工单反馈），感谢您对巨量引擎的支持。' |
campaign_type | string | 计划组类型， |
delivery_range | string | 允许值:
|
punish_type | string | 惩罚类型，枚举值： |
status | string |
|
publish_time | number | 本条消息实际产生时间 |
timestamp | number | 推送时间 |
nonce | number | 随机数，和timestamp组合防重 |
subscribe_task_id | number | 产生推送数据的订阅任务id |
计划超配额暂停
参数名称 | 类型 | 描述 |
message_id | number | 唯一标识一条推送数据 |
service_label | string | 事件名称， |
data | object | 触发推送的事件消息 |
event | string |
|
user_id | number | 触发事件的用户id，营销场景即为advertiser_id |
content | object | 事件内容 |
ad_ids | number[] | 被暂停的计划列表 |
group_ids | number[] | 被暂停的旧版巨量引擎工作台项目列表 |
promotion_ids | number[] | 被暂停的巨量引擎营销投放升级版的营销列表(暂不支持) |
publish_time | number | 本条消息实际产生时间 |
timestamp | number | 推送时间 |
nonce | number | 随机数，和timestamp组合防重 |
subscribe_task_id | number | 产生推送数据的订阅任务id |
计划占用配额
参数名称 | 类型 | 描述 |
message_id | number | 唯一标识一条推送数据 |
service_label | string | 事件名称， |
data | object | 触发推送的事件消息 |
event | string |
|
user_id | number | 触发事件的用户id，营销场景即为advertiser_id |
content | object | 事件内容 |
ad_ids | number[] | 成功占用配额的计划列表 |
group_ids | number[] | 成功占用配额的旧版巨量引擎工作台项目列表 |
promotion_ids | number[] | 成功占用配额的巨量引擎营销投放升级版的营销列表 |
campaign_type | string | 计划组类型， |
delivery_range | string | 允许值:
|
publish_time | number | 本条消息实际产生时间 |
timestamp | number | 推送时间 |
nonce | number | 随机数，和timestamp组合防重 |
subscribe_task_id | number | 产生推送数据的订阅任务id |
计划释放配额
参数名称 | 类型 | 描述 |
message_id | number | 唯一标识一条推送数据 |
service_label | string | 事件名称， |
data | object | 触发推送的事件消息 |
event | string |
|
user_id | number | 触发事件的用户id，营销场景即为advertiser_id |
content | object | 事件内容 |
ad_ids | number[] | 不再占用配额的计划列表 |
group_ids | number[] | 不再占用配额的旧版巨量引擎工作台项目列表 |
promotion_ids | number[] | 不再占用配额的巨量引擎营销投放升级版的营销列表 |
campaign_type | string | 计划组类型， |
delivery_range | string | 允许值:
|
publish_time | number | 本条消息实际产生时间 |
timestamp | number | 推送时间 |
nonce | number | 随机数，和timestamp组合防重 |
subscribe_task_id | number | 产生推送数据的订阅任务id |
在投计划配额档位变化
参数名称 | 类型 | 描述 |
message_id | number | 唯一标识一条推送数据 |
service_label | string | 事件名称， |
data | object | 触发推送的事件消息 |
event | string |
|
user_id | number | 触发事件的用户id，营销场景即为advertiser_id |
content | object | 事件内容 |
sum_quota | number | 变化后在投计划配额 |
sum_quota_before | number | 变化前在投计划配额 |
campaign_type | string | 计划组类型， |
delivery_range | string | 允许值:
|
publish_time | number | 本条消息实际产生时间 |
timestamp | number | 推送时间 |
nonce | number | 随机数，和timestamp组合防重 |
subscribe_task_id | number | 产生推送数据的订阅任务id |
营销投放升级版营销状态实时推送 status.promotion.realtime
参数名称 | 类型 | 描述 |
event | string | 事件名称，枚举值
|
user_id | number | 营销归属的客户ID |
content | object | 事件内容 |
status_first | string | 营销一级状态 |
status_second | string[] | 营销二级状态 |
promotion_ids | number[] | 状态发生变更的营销ids |
营销投放升级版项目状态实时推送 status.project.realtime
参数名称 | 类型 | 描述 |
event | string | 事件名称，枚举值
|
user_id | number | 营销归属的客户ID |
content | object | 事件内容 |
status_first | string | 项目一级状态 |
status_second | string[] | 项目二级状态 |
project_ids | number[] | 状态发生变更的项目ids |
营销投放升级版项目报表实时数据 report.project.activeprogram
字段 | 类型 | 描述 |
app_id | number | 应用APPID |
core_user_id | number | 登陆用户id |
project_ids | number[] | 聚合周期内发生指标变更的计划列表，service_label 为 |
promotion_ids | number[] | 聚合周期内发生指标变更的创意列表，service_label 为 |
营销投放升级版营销报表实时数据 report.promotion.activeprogram
字段 | 类型 | 描述 |
app_id | number | 应用APPID |
core_user_id | number | 登陆用户id |
project_ids | number[] | 聚合周期内发生指标变更的计划列表，service_label 为 |
promotion_ids | number[] | 聚合周期内发生指标变更的创意列表，service_label 为 |
营销投放升级版素材报表实时数据 report.material.activeprogram
字段 | 类型 | 描述 |
app_id | number | 应用APPID |
core_user_id | number | 登陆用户id |
material_ids | number[] | 聚合周期内发生指标变更的素材列表，service_label 为 |
巨量营销投放资质状态推送 status.qualification.ad.realtime
event | string | 事件名称，即投放资质变更后的状态，枚举值：
|
user_id | number | 资质归属客户ID |
content | object | 消息内容 |
qualification_type | string | 资质类型
|
qualification_id | number[] | 资质ID |
status | string | 资质状态
|
巨量营销素材状态推送 status.material.ad.realtime
注意：仅支持巨量投放账户素材库下素材新增/删除变更通知
event | string | 事件名称，即素材变更后的状态枚举值，对应素材库是否有新增/删除素材
|
user_id | number | 素材归属客户ID |
content | object | 推送内容 |
material_ids | number[] | 聚合周期内发生指标变更的素材列表 |
material_type | string | 素材类型： image：图片 video：视频 |
