You need to enable JavaScript to run this app.
导航
内容变更通知
最近更新时间:2023.07.26 15:07:16首次发布时间:2023.07.25 16:42:56

本文档介绍内容定制输出内容发生变更时的通知机制。
当内容定制侧输出的内容发生变更时,内容定制侧将推送变更事件到客户侧配置的回调地址。客户侧根据通知可以调用接口更新内容信息。

接入步骤

接入内容定制对外内容推送,客户侧需要按照如下步骤完成:

  1. 在【内容定制平台-内容同步】的【回调配置】中生成并获取鉴权密钥

  2. 在上述相同页面中配置回调接收地址

  3. 依据接口文档和平台相关配置开发实现业务逻辑

  4. 在上述相同页面中点击“测试”以发送测试数据,测试接口连通性

  5. 在保证接口连通之后,开始内容输出的推送

上述过程如图所示:
alt

接口说明

请求方式

HTTPS

method:POST
	
Content-Type:application/json
	

签名校验

客户侧通过检验 signature 对请求进行校验(下面有校验方式),以确认请求来自内容定制系统。

签名参数

参数描述

timestamp

unix时间戳,单位:秒。为保证安全,与当前时间戳绝对值不要超过3600s。
从请求头中获取,键为:X-Content-Timestamp

nonce

请求随机串。随机串长度为6-32位数字和字母的组合,大小写敏感。
从请求头中获取,键为:X-Content-Nonce

signature

签名字符串。
从请求头中获取,键为:X-Content-Signature

payload业务数据。请求体body字节流。
secret_key鉴权密钥。客户侧可以在内容定制平台的【内容同步】页面,点击【同步配置】的【回调配置】查看。

签名算法

Hmac_SHA256算法

签名步骤

  1. 将 timestamp、nonce 和 payload 依次进行拼接;

  2. 使用 secret_key 对上述拼接的字符串进行 hmac sha256 加密,然后转成十六进制字符串 ;

  3. 得到加密后的字符串可与 signature 对比,标识该请求来源于内容定制的内容事件推送。

签名示例

检验signature的Go示例代码:

func GenSignature(timestamp, nonce, body, secretKey string) string {
    // 按照timestamp,nonce,body 顺序拼接签名字符串
    signatureStr := timestamp + nonce + body
    hmacSha256 := hmac.New(sha256.New, []byte(secretKey))
    hmacSha256.Write([]byte(signatureStr))
    // 将sha256转成16进制字符串
    signature := fmt.Sprintf("%x", hmacSha256.Sum(nil))
    return signature
}

请求参数

请求方指“火山引擎-内容定制”。

KEYVALUE/说明
methodPOST
Content-Typeapplication/json
X-Content-Timestampunix时间戳(单位:秒)
X-Content-Nonce随机串(6-32位数字、字母组成)
X-Content-Signature回调签名(生成逻辑见上文)

Body

字段名字段类型说明
event_idstring事件ID
event_typestring事件类型
group_idstring文章ID
event_datastring事件详情,按事件类型区分(json格式,需要客户侧进行解码)
uniq_keystring幂等键,客户侧可使用该字段做幂等处理,保证唯一性
event_timenumber事件产生时间戳(unixtime,单位:秒)

event_type

枚举事件详情类型说明
status_changeStatusChangeEventData文章状态变更

StatusChangeEventData

字段名字段类型说明
is_availablebool文章当前是否可访问

响应参数

响应方指“客户侧”。

字段名字段类型说明
retnumber响应状态码。0-成功;非0-失败,并在msg中补充说明。
msgstring响应信息。例如:成功时提供"success";失败时提供失败相关信息。

请求示例

POST / HTTP/1.1
Host: xxx.xxx.xxx
Content-Type: application/json
X-Content-Timestamp: 1689585543
X-Content-Nonce: kfcv50
X-Content-Signature: 2d3891cee3dcc777ba27a29f70758c581e93f21f3dad1deeaadf11aa440fe4b2
{
    "event_id": "177165499009xxxx",
    "event_type": "status_change",
    "group_id": "690150925257885xxxx",
    "event_data": "{\"is_available\":false}",
    "uniq_key": "56b74c26a28699e1829a4390dca58f89e54a507dcf8df6a49a4246039c31c190",
    "event_time": 1689585542
}

响应示例

客户侧服务端返回给火山引擎侧的响应数据。

{
    "ret": 0, // 响应状态码
    "msg": "success" // 响应信息
}

注意事项

注意

  1. 【必须】需要客户侧保证对变更消息的幂等性(回调请求中已经提供了幂等键 uniq_key)。

  2. 【必须】事件推送后,客户侧需要使用 MGetSyncArticles 接口再拉一次内容,以获取当前内容的详情和状态。

  3. 【约定】内容定制侧默认会做3次请求尝试,即1次不成功会再次请求,满3次即停。3次请求尝试都失败,则视为该次请求失败。

  4. 【约定】一次请求尝试的超时时间为5秒。

  5. 【约定】当该渠道的回调配置“测试”连通后,即满足推送条件,推送近半年内已同步内容发生的变更。

  6. 【建议】如果推送过去的事件已经过时了1分钟(参考event_time),建议忽略这条变更消息。

  7. 【建议】如果客户侧收到变更消息处理比较耗时,建议采用异步的方式处理。