You need to enable JavaScript to run this app.
导航

内容引入接口

最近更新时间2024.02.02 16:49:38

首次发布时间2021.07.05 21:23:10

概述

本文档提供标准API内容引入协议,客户侧研发人员,需要按照API引入协议,实现内容的同步。

内容引入主要分为两部分:【内容同步】和【结果查询】

  • 【内容同步】:该流程是必须接入的;
  • 【结果查询】:若不关注同步结果,可忽略结果查询。

说明

  • 测试阶段请勿大批量引入: 测试阶段有调用次数、内容理解、内容质检量的限制;
  • 产品上线前大批量引入: 产品上线前大批量引入自有内容,请提前与火山研发联系,因为:
    • 大批量引入会将内容理解额度消耗完,走超量计费;
    • 管理平台只支持下发发文时间为近365天的内容;
    • 大批量引入的内容发文时间,不要全部为同一发文时间。

注意

  • 离线内容同步: 大批量引入存量内容,建议使用离线内容同步(Action:BatchCreateSourceArticleInBulk),该流程使用的接口入参和出参与实时内容同步(Action:BatchCreateSourceArticle)相同,区别在于使用离线内容同步的接口导入的内容会被限速以避免影响其他内容的处理与上线速度。
内容同步

调前准备

  1. 接口鉴权
    详见:接口鉴权
  2. 接口配置
    详见:新建Api源
  3. 调用接口
    注意参数 是否必填,并确保 ServiceName、Action、Version 等url信息正确
    详见:下方接口信息

请求接口

请求方式

post

请求url:

https://cms.volcengineapi.com?Action=BatchCreateSourceArticle&Version=2021-01-01

请求header:

ServiceName: volc_content_platform

url组成:

Host: https://cms.volcengineapi.com

Action: BatchCreateSourceArticle

Version: 2021-01-01

请求参数

字段名
字段类型
是否必填
说明
Articles
list<ArticleDTO>
文章列表,最大值:100

相关字段取值

GroupType描述
article图文
video视频
short_video小视频

short_content

短内容

  • 图文短内容请使用short_content类型,视频短内容请使用short_video类型;
  • Title、Abstract、Content、GroupImages 四个字段不能同时为空;
  • Title、Abstract字段字数不超过400,Content字段字数不超过2000;
  • GroupImages 配图不超过18张;
  • 除上述说明字段,其它字段不受影响。

响应字段

字段名
字段类型
是否必填
说明
ResponseMetadata
ResponseMetadata
Result
BatchArticleCreateResult
请求结果

说明

  • Content字段的作用: 用于在平台侧 详情展示,客户C端信息流内容详情依赖客户自主维护:
    - 接口提供 Link 内容详情页字段,内容推荐接口返回该字段
    - 接口提供 OpenId 内容外部主键ID,内容推荐接口返回该字段,客户通过该id查询自有内容库,获取内容详情
  • PublishTime字段: 平台支持推荐下发最近一年(365天)的内容,引入时请注意内容发布时间,超过365天的内容无法推荐,平台不支持内容修改

请求示例

{
    "Articles": [
        {
            "OpenId": "",
            "Title": "今年可能是对房地产影响巨大的一年",
            "Abstract":"我买卖过好几次房,现在每个月也去看房,这个问题思考得也多,所以有点想法,跟大家分享下。",
            "GroupType": "article",
            "GroupSource": "api",
            "Link":"",
            "Tags":[
                ""
            ],
            "Author": {
                "AuthorName": "某某作者",
                "AuthorAvatarUrl":"https://is3-ssl.mzstatic.com/image/thumb/Purple71/v4/ef/4b/***.jpg"
            },
            "CoverImages":[
                {
                    "Url":"https://p1-tt.byteimg.com/origin/pgc-image/***"
                }
            ],
            "PublishTime":1626334737,
            "GroupImages": [
                 {
                    "Url":""
                }
            ],
            "SourceName": "某某作者",
            "GenerateType": "moumouzhengqvan",
            "Content":"<p data-track=\"121\"><span style=\"letter-spacing: 1px;\">1994年之前地方富,中央穷,于是在1994年重新规划了税制,也就是那个“分税制”,分税制的核心是容易收的税种归国家,不容易收的归地方,大头归国家,小头归地方。这下很多地方本来富裕,一下子不够花了。</span></p>"
        }
    ]
}

响应示例

正常响应示例

{
    "ResponseMetadata": {
        "RequestId": "02162856507451900000000000000000000ffff0aca593165b22e",
        "Action": "BatchCreateSourceArticle",
        "Version": "2021-01-01",
        "Service": "volc_content_platform",
        "Region": "cn-north-1"
    },
    "Result": {
        "BatchId": "1707961755910349"
    }
}

异常响应示例

{
    "ResponseMetadata": {
        "RequestId": "02162856379562500000000000000000000ffff0a9669e95918cd",
        "Action": "BatchCreateSourceArticle",
        "Version": "2021-01-01",
        "Service": "volc_content_platform",
        "Region": "cn-north-1",
        "Error": {
            "CodeN": 100010,
            "Code": "SignatureDoesNotMatch",
            "Message": "The request signature we calculated does not match the signature you provided. Check your Secret Access Key and signing method. Consult the service documentation for details."
        }
    }
}

错误代码

详见:错误代码表 - volc_content_platform

FAQ

  • 如何确保作者唯一:
    - 第一次引入时,请确保作者信息(相关字段)完整,后续无法修改作者信息
    - 管理平台以第一次引入的作者信息在管理平台创建作者,后续内容只要保持 AuthorName、AuthorOpenId、GenerateType 不变,即可确保后续内容作者唯一
    - 内容(OpenId)变化的同时,AuthorName、AuthorOpenId、GeneratorType 任何一个发生变化,都会生成一个新的作者
  • 不支持已引入内容的修改:
    - 因无法判断修改后的内容如何继承原有的 内容状态,建议删除该内容或修改OpenId,重新引入
    - 在内容管理平台控制台删除:控制台删除
    - Api删除:内容删除接口
  • 图片大小:可自行根据C端设计进行尺寸规划后引入,图片大小不得超过50MB,否则可能引入失败;
  • 视频在管理平台上无法播放: 检查 Content 字段值是否符合字段要求;
  • 管理平台上显示内容上传失败: 检查 GroupImages 或者 GroupVideos 字段值是否符合字段要求,不可混用。

注意

若需排查日志,请提供接口返回的 RequestId


结果查询

该接口提供内容同步结果查询的功能。

调前准备

  1. 该接口可按需对接
  2. 接口鉴权
    详见:接口鉴权
  3. 调用接口
    注意参数 是否必填,并确保 ServiceName、Action、Version 等url信息正确
    详见:下方接口信息

请求接口

请求方式

post

请求url:

https://cms.volcengineapi.com/?Action=GetArticleBatchUploadDetail&Version=2021-01-01

请求header:

ServiceName: volc_content_platform

url组成:

Host: https://cms.volcengineapi.com

Action: GetArticleBatchUploadDetail

Version: 2021-01-01

请求参数

字段名
字段类型
是否必填
说明
BatchId
string
调用内容同步接口返回的BatchId

响应字段

字段名
字段类型
是否必填
说明
ResponseMetadata
ResponseMetadata
Result
UploadResult
基本请求结果

相关字段取值

FailedType
描述
param_illegal
参数错误
update_illegal
文章暂不支持更新操作
save_error
存储失败
inner_error
内部异常
not_bind_queue_error
没有绑定质检队列
api_source_error
API来源不存在
api_source_type_error
API来源对应的内容类型不存在

请求示例

{
"BatchId": "1707952822088727"
}

响应示例

正常响应示例

{
    "ResponseMetadata": {
        "RequestId": "2021081316425701021121001820B79E86",
        "Action": "GetArticleBatchUploadDetail",
        "Version": "2021-01-01",
        "Service": "volc_content_platform",
        "Region": "cn-north-1"
    },
    "Result": {
        "BatchId": "1707961755960349",
        "UploadVOList": [
            {
                "OpenId": "",
                "GroupId": "1707966728131629",
                "Reason": "[\"\"]",
                "CreateTime": 1628844120,
                "UploadStatus": "success",
                "FailedType": "",
                "ReqBody":"{\"OpenId\":\"\",\"Title\":\"今年可能是对房地产影响巨大的一年\",\"Abstract\":\"上次写了一篇文章讲1994年的改革,很多小伙伴说没写完,这次我尝试补充一下,本文的内容其实算不上啥经济学,更类似“常识”,我来北京有十年了,买卖过好几次房,现在每个月也要去看房,平时这个问题思考得也多,所以有点想法,跟大家分享下。\",\"GroupType\":\"article\",\"GroupSource\":\"api\",\"Author\":{\"AuthorName\":\"某某作者\",\"AuthorAvatarUrl\":\"https://is3-ssl.mzstatic.com/image/thumb/Purple71/v4/ef/4b/75/***\",\"FollowerCount\":0,\"Description\":\"\",\"HomePageUrl\":\"\"},\"PublishTime\":1626334737,\"Content\":\"\<p data-track=\"121\"><span style=\"letter-spacing: 1px;\">1994年之前地方富,中央穷,于是在1994年重新规划了税制,也就是那个“分税制”,分税制的核心是容易收的税种归国家,不容易收的归地方,大头归国家,小头归地方。这下很多地方本来富裕,一下子不够花了。</span></p>\",\"CoverImages\":[{\"Url\":\"https://p1-tt.byteimg.com/origin/pgc-image/***\"}],\"GroupImages\":[{\"Url\":\"\"}],\"SourceName\":\"某某作者\",\"GenerateType\":\"moumouzhengqvan\",\"Link\":\"\",\"DiggCount\":0,\"CommentCount\":0,\"CommentUrl\":\"\"}",
                "SourceName": "某某作者",
                "GroupSource": "api",
                "GenerateType": "moumouzhengqvan",
                "RequestId": "1707966851821575"
            }
        ]
    }
}

异常响应示例

{
    "ResponseMetadata": {
        "RequestId": "202108131643390102100581671EBAC2EE",
        "Action": "GetArticleBatchUploadDetail",
        "Version": "2021-01-01",
        "Service": "volc_content_platform",
        "Region": "cn-north-1",
        "Error": {
            "CodeN": 600400,
            "Code": "600400",
            "Message": "参数错误"
        }
    },
    "Result": null
}

错误代码

详见:错误代码表 - volc_content_platform

FAQ

  • 查询内容引入结果:提供两种方式查看内容引入结果
    - 平台查看:内容源管理界面查看引入失败原因,原始内容库查看引入的内容
    - Api查询
  • 调用接口无结果返回:
    • 引入结果取决于引入队列长度和内容理解速度;内容理解速度受限于引入内容大小,快可至秒级;如有需求,可定时任务5秒查询一次,对于没有查到的,以递增延迟来做轮询。

注意

若需排查日志,请提供接口返回的 RequestId