Posts 文档接口

JSON 格式

NameTypeRead-onlyComment
idintegeryes文档id，由系统自动分配
urlstringyes资源url
forum_idintegerno该文档所属的文档分类id
forum_namestringno该文档所属的文档分类名称
titlestringno文档名称
contentstringno文档内容
author_idintegerno文档创建者id
author_namestringyes文档创建者名称
disable_commentsbooleanno是否关闭评论
count_commentsintegeryes评论数目
count_voteintegeryes点赞数目
count_viewintegeryes浏览次数
is_homebooleanno是否放置首页
is_highlightbooleanno是否高亮
is_topbooleanno是否置顶
is_draftbooleanno是否为草稿
is_dashboardbooleanno是否在控制台首页显示
sortintegerno文档所在当前分类下的排序号，按倒序排列
created_atdateno创建时间
updated_atdateyes最后更新时间
tagsarrayno标签数组
uploadsarrayyes文档所带的附件，请参照 Attachments API

JSON 示例

{
  "id": 421,
  "url": "https://support.kf5.com/apiv2/posts/129.json",
  "forum_id": 438,
  "title": "代理指南样本的测试",
  "content": "这些是此章节可以涵盖的指南，以帮助代理解决工单。",
  "author_id": 915,
  "disable_comments": false,
  "count_comments": 5,
  "count_vote": 3,
  "count_view": 299,
  "is_home": true,
  "is_highlight": true,
  "is_top": true,
  "is_draft": false,
  "is_dashboard": false,
  "created_at": "2012-08-10 14:50:13",
  "updated_at": "2012-08-10 14:50:13",
  "tags": ["tag1","tag2"],
  "uploads": [
    {
     "id": 2131,
     "url": "https://support.kf5.com/apiv2/attachments/2131.json",
     "name": "shuimu.jpg",
     "size": 775702,
     "content_url": "https://support.kf5.com/attachments/download/2131/00154f57388ef86589b76a23d30cd7f/",
     "token": "00154f57388ef86589b76a23d30cd7f"
    }
   ]
}

正式文档列表

GET /apiv2/posts.json
GET /apiv2/posts.json?sort=count_view:desc,id:asc
查看草稿列表
GET /apiv2/posts/draft.json
查看指定文档分类的正式文档列表
GET /apiv2/forums/{forum_id}/posts.json
GET /apiv2/forums/{forum_id}/posts.json?sort=count_view:desc,updated_at:desc
还可以调用下列API查看指定客服创建的正式文档:
GET /apiv2/users/{user_id}/posts.json
GET /apiv2/users/{user_id}/posts.json?sort=count_view:desc,sort:desc
调用权限

all users

请求参数

sort：自定义组合排序规则，可选，格式为：'排序字段:排序方式'，支持的排序字段：id(ID), created_at(创建时间), updated_at(更新时间), is_top(是否置顶), count_view(浏览数), count_comments(评论数), sort(排序序号)，支持的排序方式：asc(升序), desc(降序)

注意：如果某文档属于一个查看权限为客服的文档分类，则普通用户无法查看该文档
curl 示例
curl https://{subdomain}.kf5.com/apiv2/posts.json \
  -v -u {email_address}:{password}
返回示例
Status: 200 OK

{
  "posts": [
    {
      "id":   421,
      "title": "代理指南样本的测试",
      ...
    },
    {
      "id":   425,
      "title": "帮助指南",
      ...
    }
  ]
}

查看文档

GET /apiv2/posts/{id}.json
调用权限

all users

curl 示例
curl https://{subdomain}.kf5.com/apiv2/posts.json \
  -v -u {email_address}:{password}
返回示例
Status: 200 OK

{
  "posts": {
   	  "id":   421,
      "title": "建议提交",
      ...
   }
}

查看多个文档

GET /apiv2/posts/show_many.json?ids={ids}

最多返回100条数据

调用权限

all users

curl示例
curl https://{subdomain}.kf5.com/apiv2/posts/show_many.json?ids={ids} \
 -v -u {email_address}:{password}
返回示例

请参照 文档列表

GET /apiv2/posts/search.json?query={keyword}&sort={sort}
搜索标题中包含keyword的文档
调用权限

all users

请求参数

query：搜索关键字，必填

sort：自定义搜索结果排序规则，可选，格式为：'排序字段:排序方式'，支持的排序字段：id(ID), created_at(创建时间), updated_at(更新时间), is_top(是否置顶), count_view(浏览数), count_comments(评论数), sort(排序序号)，支持的排序方式：asc(升序), desc(降序)

curl示例
curl https://{subdomain}.kf5.com/apiv2/posts/search.json?query={keyword} \
 -v -u {email_address}:{password}

curl https://{subdomain}.kf5.com/apiv2/posts/search.json?query={keyword}&sort=sort:desc,created_at:asc \
 -v -u {email_address}:{password}
返回示例
Status: 200 OK

{
  "posts": [
    {
      "id":   421,
      "title": "代理指南样本的测试",
      ...
    },
    {
      "id":   425,
      "title": "帮助指南",
      ...
    }
  ]
}

创建文档

POST /apiv2/posts.json
调用权限

admin

curl 示例
curl https://{subdomain}.kf5.com/apiv2/posts.json \
  -H "Content-Type: application/json" -d '{"post": {"title": "this is post title","content": "this is content",
  										   "uploads":["00154f57388ef86589b76a23d30cd7f"]}}' \
  -v -u {email_address}:{password} -X POST
返回示例
Status: 200 OK
Location: https://{subdomain}.kf5.com/apiv2/posts/{id}.json

{
  "post": {
      "id":   489,
      "title": "this is forums title",
      ...
   }
}

修改文档

PUT /apiv2/posts/{id}.json
调用权限

admin

curl 示例
curl https://{subdomain}.kf5.com/apiv2/posts/{id}.json \
  -H "Content-Type: application/json" -d '{"post": {"title": "this is new title"}}' \
  -v -u {email_address}:{password} -X PUT
返回示例
Status: 200 OK

{
  "post": {
      "id":   715,
      "title": "this is new title",
      ...
   }
}

删除文档

DELETE /apiv2/posts/{id}.json
调用权限

admin

curl 示例
curl https://{subdomain}.kf5.com/apiv2/posts/{id}.json \
  -v -u {email_address}:{password} -X DELETE
返回示例
Status: 200 OK

文档回复列表

GET /apiv2/posts/{id}/comments.json
调用权限

all users

curl 示例
curl https://{subdomain}.kf5.com/apiv2/posts/{id}/comments.json \
  -v -u {email_address}/token:{api_token}
请求参数

sort_order：按回复ID正序排列，可选值：asc 注：若不传此参数，则默认按回复ID倒序排列

返回示例
Status: 200 OK

{
  "comments": [
    {
      "id": 340,
      "content": "this is content",
      ...
    },
    {
      "id": 345,
      "content": "the other content",
      ...
    },
    ...
  ]
}

查看指定文档回复

GET /apiv2/posts/{post_id}/comments/{id}.json
调用权限

all users

curl 示例
curl https://{subdomain}.kf5.com/apiv2/posts/{post_id}/comments/{id}.json \
  -v -u {email_address}/token:{api_token}
返回示例
Status: 200 OK

{
  "comment":{
      "id": 340,
      "content": "the api test content",
      ...
   }
}

回复文档

POST /apiv2/posts/{posts_id}/comments.json
调用权限

all users

curl 示例
curl https://{subdomain}.kf5.com/apiv2/posts/{posts_id}/comments.json \
  -H "Content-Type: application/json" -d '{"post_comment": {"content": "this is api test content"}}' \
  -v -u {email_address}:{password} -X POST
返回示例
Status: 201 Created

{
  "post_comment": {
      "id": 331,
      "content": "this is api test content",
      ...
  }
}