腾讯乐享所提供的应用接口请求/响应格式均遵循 JSON API 格式规范,建议开发者先了解 JSON API 格式再行接入。
目前采用1.0版本。
应用接口中,所有的请求包体和响应包体都将用document
来指
在没特殊说明情况下,以下所有应用接口遵循 JSON API 规范,同时也支持以下 JSON API 中约定的参数。
参数 | 说明 | 适用接口 |
---|---|---|
include | 关联资源属性 | 没特别说明情况,可适用所有列表或单个实体查看接口 |
sort | 列表排序属性 | 没特别说明情况,可适用所有列表接口,降序在字段前加- 表示 |
page | 分页属性 | 没特别说明情况,可适用所有列表接口 |
filter | 过滤属性 | 根据具体接口说明使用 |
目前不支持 JSON API 中提到的 fields 参数
此外,支持 page 参数的接口,一般情况下也会支持 per_page 参数,此参数不在 JSON API 规范中。
参数 | 说明 | 适用接口 |
---|---|---|
per_page | 每页返回数 | 没特别说明情况,支持1-100之间所有整数,不传入时默认为20 |
当第三方需要创建/更新资源时,需要向服务器提交一个符合 JSON API 规范的document
。
由于拼凑标准格式也有一定复杂,本文提供的 SDK 中会进行一层封装,降低接入门槛。
开发者也可以从 JSON API 官网中选择合适的代码库进行开发。
一般写操作的应用接口都需要以某个员工的身份去请求,这个信息需在 HTTP Header 中设置。
StaffID: TX000001
某些列表接口和实体查看接口会返回。
{
"links":{
"platform":"https://lexiangla.com/teams/k00001/docs/docid_123456",
"download":"https://file.lexiang-asset.com/xxxxx/attachments/2019/11/4983d116-0b45-11ea-8b68-10e7c61c70fc.png?hc=6d59851821bb3f460c79e13ef4505372&sign=xxxxx"
}
}
链接类型 | 说明 | 适用场景 | 备注 |
---|---|---|---|
platform | 该资源在乐享平台中的具体链接地址,方便企业成员打开页面查看 | 查看单个实体或实体列表 | 无 |
download | 该资源对外提供下载的地址 | 文档下载、附件下载 | 链接中如有带签名,默认有效时间为3分钟 |
一般写操作行为都需要触发某些事件,如创建文档需要生成动态展示于公司首页和个人空间,评论同事的文档需要给对方发消息提醒等。 但为了防止批量导入数据时对员工做成干扰,开放接口的写操作会默认不触发这些事件。
开发者可通过document
中的meta.listeners
字段绑定这些默认不触发的事件。目前支持的事件如下:
事件名 | 说明 | 适用接口 |
---|---|---|
notice | 乐享消息中心提醒 | 创建评论、创建K吧 |
feed | 动态流,展示于公司首页和个人空间首页 | 创建文档、上传文档、乐问创建问题、回答问题、创建K吧 |
以创建文档需要生成动态和创建消息中心提醒(实际上该接口不支持消息中心提醒事件)为例:
POST https://lxapi.lexiangla.com/cgi-bin/v1/docs
{
"data":{
"type":"doc",
"attributes":{
"title":"通过开放接口创建的文档",
"content":"<h1>富文本内容</h1>",
"is_markdown":0
}
},
"meta":{
"listeners":["notice", "feed"]
}
}
SDK封装方法使用示例:
$attributes = [
'title' => '通过开放接口创建的文档',
'content' => '<h1>富文本内容</h1>',
'is_markdown' => 0,
];
$Lxapi = new \Lexiangla\Openapi\Api(AppKey, AppSecret);
$response = $Lxapi->setListeners(['notice', 'feed'])->postDoc(StaffID, $attributes);