文档中心

数据消费接口

最近更新时间：2024.02.29 10:24:17

首次发布时间：2024.01.11 10:56:24

本文档介绍【实时订阅】的【发文流式接口】，和【回溯订阅】的【发文回溯接口】的调用方式。

注意

该接口仅提供给【API对接】场景使用，待下线，建议使用【BMQ对接】,参考【基础配置】中的【BMQ对接】

概述

内容洞察平台在客户侧进行订阅任务配置后，会将命中规则的内容，通过接口的形式，推送给客户侧，按照订阅任务类型的不同，数据消费的接口，也分为以下两种形式：

【发文实时接口】：针对【实时订阅任务】，当发文命中订阅规则时，会实时通过发文流式接口推送给客户，客户侧可监控该接口，消费实时推送的内容数据。
【发文回溯接口】：针对【回溯订阅任务】，当历史内容符合订阅规则时，会批量通过发文回溯接口推送给客户，客户侧可监控该接口，消费批量推送的历史内容数据。

备注：
接口调用前置操作，详见：调用指南

请求接口

发文实时流式接口

基本信息

名称	内容
接口地址	/openapi/item/sse/stream
请求方式	SSE(http-stream)
是否需要鉴权	是

请求参数

Hearder请求参数

字段	类型	是否必填	说明
X-Insight-Biz-Name	string	是	业务名称 -> 即火山账号ID
X-Insight-Access-Token	string	是	API访问凭证access_token

Query请求参数

参数	类型	是否必填	描述
collector	string	否	默认是消费全部。若没有高吞吐扛不住的情况不需要多collector消费。若collector有五个可以指定0-4消费，或者两个接口0-2,3-4分别消费新开通客户默认分区数是10，若分区数不够可以联系火山侧扩容
start_offset	string	否	起始的时间戳，默认为当前时间。务必选取24小时内的时间戳，否则没有数据（若是选择sync_only=true，只会保留过去3小时数据）
sync_only	bool	否	是否指定同步任务消费（仅消费sync_mode为true的任务），默认消费全量任务，若想消费同步队列需与我方产品对齐后开通。

发文回溯流式接口

基本信息

名称	内容
接口地址	/openapi/item/sse/backtrack/stream
请求方式	SSE(http-stream)
是否需要鉴权	是

请求参数

Hearder请求参数

字段	类型	是否必填	说明
X-Insight-Biz-Name	string	是	业务名称 -> 即火山账号ID
X-Insight-Access-Token	string	是	API访问凭证access_token

Query请求参数

参数	类型	位置	是否必填	描述
start_offset	string	Query	否	起始的消费点，回溯任务的消费点默认是0，也可以指定其他消费点消费，消费方注意记录消费到的点位。若程序有异常可以从上一点位重新开始消费。
task_id	string	Query	必填	回溯任务id，默认是任务0，任务id是自增的
collector	string	Query	否	默认是消费全部。建议指定collector来消费，与实时接口逻辑相同，回溯接口的默认collector是20，也就是可以指定0-19中任意collector来消费

客户端调用说明

消息类型

流式接口可能会发送两类消息：加密发文消息、原始文本消息。
加密发文消息消息样例

{
    "msg_id":"{$msg_id}", 建议打印在日志中方便双方问题排查
    "nonce":"{$aes_iv}", 使用Base64编码，客户端解码时注意解码方式
    "encrypt_item": "{$encrypt_item}" 【重要】使用Base64编码，客户端解码时注意解码方式
}

原始文本消息举例

消息内容	备注
no content for the selected range past 15s	实时任务：过去15秒内无新增订阅内容【请确认有正在生效的订阅任务，创建任务见实时任务接口】回溯任务：过去15秒内未找到可推送内容，可能的情况有两种：1. 已回溯到任务最大offset 2. 所选范围内的内容已过期被删除
no content for the selected range past 10min, close now	过去10分钟内无新增订阅内容，服务端会主动断开连接

加密状态

传输的消息体采用AES加密，需要使用Key+IV解密文本
解密方式
AES CBC，解密go代码示例可见：接口调用最佳实践

字段	信息
AES Key	火山控制台-内容洞察平台-概览页
AES IV	nonce字段，随消息体发送

状态变更

关注字段： Status

状态（status）	含义
0	原文已删除，不可公开
1	新增/更新数据，可公开
2	法务原因删除，不可公开

待删除的数据将只包含 post_id, status, publish_time, origin_id

注意

对数据不可公开的情形，需要客户配合将原始数据从数据库中删除

调用示例

调用须知

通过Client获得的消息体为加密后的JSON，需要使用AES完成解密
加密后的消息体示例：

{
    "msg_id": "021693190693342fdbddc01002b021200000000000000174ed1ac",
    "nonce": "S2kzTk5sRFVtYkFjMmlBcg==",
    "encrypt_item": "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"
}

这里只展示了基本的调用方法
如果需要获得完善的状态管理和最大化的消费能力，
参考：接口调用最佳实践

Curl示例

#获取access_token
curl --location --request GET 'https://insight.volcengineapi.com/oauth/access_token' \
--header 'X-Insight-Biz-Name: <BIZ_NAME>' \
--header 'X-Insight-Biz-Secret: <YOUR_BIZ_SECRET>' 

#通过access_token获取发文
curl --no-buffer --location --request GET 'https://insight.volcengineapi.com/openapi/item/sse/stream?collector=0-10' \
--header 'X-Insight-Biz-Name: <BIZ_NAME>' \
--header 'X-Insight-Access-Token: <THE_TOKEN_FROM_AUTH>'

Wget示例

# 获取token
wget --no-check-certificate --quiet \
   --method GET \
   --timeout=0 \
   --header 'X-Insight-Biz-Name: <BIZ_NAME>' \
   --header 'X-Insight-Biz-Secret: <YOUR_BIZ_SECRET>' 
    'https://insight.volcengineapi.com/oauth/access_token'
    
# 获取发文
wget --no-check-certificate --quiet \
   --method GET \
   --timeout=0 \
   --header 'X-Insight-Biz-Name: <BIZ_NAME>' \
   --header 'X-Insight-Access-Token: <THE_TOKEN_FROM_AUTH>' 
    'https://insight.volcengineapi.com/openapi/item/sse/stream?collector=0-10'

Golang示例

// 获取token
package main

import (
   "fmt"
   "net/http"
   "io/ioutil"
)

func main() {

   url := "https://insight.volcengineapi.com/oauth/access_token"
   method := "GET"

   client := &http.Client {
   }
   req, err := http.NewRequest(method, url, nil)

   if err != nil {
      fmt.Println(err)
      return
   }
   req.Header.Add("X-Insight-Biz-Name", "<YOUR_BIZ_NAME>")
   req.Header.Add("X-Insight-Biz-Secret", "<YOUR_BIZ_SECRET>")

   res, err := client.Do(req)
   if err != nil {
      fmt.Println(err)
      return
   }
   defer res.Body.Close()

   body, err := ioutil.ReadAll(res.Body)
   if err != nil {
      fmt.Println(err)
      return
   }
   fmt.Println(string(body))
}

// 获取发文
package main

import (
    "bufio"
    "fmt"
    "net/http"
)

func main() {
    url := "https://insight.volcengineapi.com/openapi/item/sse/stream?collector=0-10"
    method := "GET"

    client := &http.Client{}
    req, err := http.NewRequest(method, url, nil)
    if err != nil {
        fmt.Println(err)
        return
    }
    req.Header.Add("X-Insight-Access-Token", "<YOUR_ACCESS_TOKEN>")
    req.Header.Add("X-Insight-Biz-Name", "<YOUR_BIZ_NAME>")

    res, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
        return
    }
    defer res.Body.Close()

    const maxTokenSize = 1024 * 1024 // 1 MB
    scanner := bufio.NewScanner(res.Body)
    scanner.Buffer(make([]byte, maxTokenSize), maxTokenSize)
    // Set the scanner to split on newlines
    scanner.Split(bufio.ScanLines)
    for scanner.Scan() {
        line := scanner.Text()
        fmt.Println(line) // TODO: 通过AES解密接收到的JSON
    }
}

Python示例

# 获取token
import requests

url = "https://insight.volcengineapi.com/oauth/access_token"

payload={}
headers = {
   'X-Insight-Biz-Name': '<YOUR_BIZ_NAME>',
   'X-Insight-Biz-Secret': '<YOUR_SECRET>',
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

# 获取发文
import requests

url = "https://insight.volcengineapi.com/openapi/item/sse/stream?collector=0-10"

payload = {}
headers = {
    'X-Insight-Access-Token': '<YOUR_ACCESS_TOKEN>',
    'X-Insight-Biz-Name': '<YOUR_BIZ_NAME>',
}

response = requests.request("GET", url, headers=headers, data=payload, stream=True)
for line in response.iter_lines():
    if line.decode():
        print(line.decode())

注意

在网络条件较差时，SSE可能发生断连；可以通过简单的等待重试策略来保持数据的持续消费，为了保持消费数据的连贯性，建议记录下最新消费数据的时间戳，作为重试时的参数来保持消费。

接口优势

由于使用http-stream作为协议，SSE相比WSS的优势在于：

SSE是轻量化的，可以用更简单的方式来完成请求
SSE有更小的开销，发文接口的单接口消费QPS提高：12->35

数据格式

内容洞察数据输出格式详见：数据格式