图文列表小组件外部API

图文列表小组件的数据源，除了支持在组件内容配置页进行手动配置，也支持通过 API 的方式获取。一般适合企业内部拥有自建内容管理系统时使用。即前端样式由WPS协作定制工作台提供，企业通过后端接口将数据同步至前端，加载数据时通过WPS协作工作台前端拉取接口获取数据。

实现步骤：

1. 企业按照图文列表 API 的格式规范，实现数据获取 API。具体接口实现要求如下文所示
   
2. 企业将已实现的接口请求地址，配置到图文列表小组件的内容配置页面
   

数据获取 API 格式要求

接口方法（Method）：固定为 GET
secret_key：小组件的签名秘钥，由平台随机生成，一个组件对应一个唯一可用的 secret_key。secret_key 可选使用，用于验证请求是否来自WPS协作，以及返回的参数信息是否可信任。
签名说明：
签名方式：HMAC-SHA256
签名过程：
1. 将请求参数按 ascii 字符顺序排序，例如: block_id=1&third_union_id=2323232
2. 使用 HMAC-SHA256 构造签名（secret_key 从自定义工作台-图文列表组件页面获取）
3. 将签名输出为 base64 编码字符串
4. 将签名添加至请求参数，例如：signature=****
验签过程：
1. 获取请求参数，分离签名参数 signature 及除 signature 其他参数
2. 使用签名过程中 1,2,3 生成验签签名 signature
3. 判断上面 1 中的 signature 和步骤 2 中的 signature 是否一致

签名伪代码示例

params := make(url.Values)
params.Set("block_id", strconv.FormatInt(blockId, 10))
params.Set("timestamp", strconv.FormatInt(time.Now().Unix(), 10))
params.Set("third_union_id", thirdUnionId)

encodedParams := params.Encode()

// 构造签名, 签名方式为：HMAC-SHA256
hm := hmac.New(sha256.New, []byte(secretKey))
hm.Write([]byte(encodedParams))
signatureStr := base64.RawURLEncoding.EncodeToString(hm.Sum(nil))

params.Set("signature", signatureStr)
apiParamsStr := params.Encode()

client := &http.Client{
    Timeout: 3 * time.Second,
}
uri := fmt.Sprintf("%s?%s", apiUrl, apiParamsStr)

请求参数

名称	类型	是否必传	说明
block_id	integer	是	图文组件 id
timestamp	integer	是	时间戳
third_union_id	integer	否	当前设备登录用户的第三方用户id，该id一般在企业自有数据源向WPS同步通讯录时创建
signature	string	是	参数签名

响应参数

由于图文列表支持分组和不分组两种展示形式，因此两种形式对应的响应体有所区别，主要体现在是否有分组信息。

不分组

名称	类型	是否必传	说明
display_type	integer	是	显示类型 1 不分组 2 分组
view_more_url	string	是	查看更多页面链接地址
articles	array	是	图文列表内容（不分组）
∟ id	integer	是	文章 id
∟ title	string	是	文章标题
∟ uri	string	是	文章外链 URL
∟ open_mode	integer	是	桌面端打开方式：0-客户端内打开、1-外部浏览器打开
∟ description	string	否	文章摘要
∟ date	string	否	文章发布日期(格式示例： 2024-01-15)
∟ tag	string	否	文章标签
∟ image_url	string	否	文章图片地址。图片推荐尺寸 198*138px。请注意：图片链接可能存在跨域问题，可参考跨域解决方法
∟ is_read	bool	否	已读未读：false-未读，true-已读

响应体示例

{
  "articles": [
    {
      "id": 1,
      "title": "图文1",
      "uri": "https://woa.wps.cn/****",
      "open_mode": 0,
      "description": "图文1摘要",
      "date": "2024-01-15",
      "tag": "咨询",
      "image_url": "https://woa.wps.cn/****/***.png",
      "is_read": true
    }
  ],
  "display_type": 1,
  "view_more_url": "https://woa.wps.cn/****"
}

分组

名称	类型	是否必传	说明
display_type	integer	是	显示类型 1 不分组 2 分组
view_more_url	string	是	查看更多页面链接地址
article_groups	array	是	图文列表内容（分组）
∟ id	integer	是	分组 id
∟ name	string	是	分组名称
∟ list	array	是	文章列表
∟ ∟ id	integer	是	文章 id
∟ ∟ title	string	是	文章标题
∟ ∟ uri	string	是	文章外链 URL
∟ ∟ open_mode	integer	是	桌面端打开方式：0-客户端内打开、1-外部浏览器打开
∟ ∟ description	string	否	文章摘要
∟ ∟ date	string	否	文章发布日期(格式示例： 2024-01-15)
∟ ∟ tag	string	否	文章标签
∟ ∟ image_url	string	否	文章图片地址。图片推荐尺寸 xx。请注意：图片链接可能存在跨域问题，可参考跨域解决方法
∟ ∟ is_read	bool	否	已读未读：false-未读，true-已读

响应体示例

{
  "article_groups": [
    {
      "id": 1,
      "name": "分组1",
      "list": [
        {
          "id": 1,
          "title": "图文1",
          "uri": "https://woa.wps.cn/****",
          "open_mode": 0,
          "description": "图文1摘要",
          "date": "2024-01-15",
          "tag": "咨询",
          "image_url": "https://woa.wps.cn/****/***.png",
          "is_read": true
        }
      ]
    }
  ],
  "display_type": 2,
  "view_more_url": "https://woa.wps.cn/****"
}