文档

创建文档

接口调用说明:

POST https://lxapi.lexiangla.com/cgi-bin/v1/docs

请求document

{
    "data":{
        "type":"doc",
        "attributes":{
            "title":"通过开放接口创建的文档",
            "content":"<h1>富文本内容</h1>",
            "is_markdown":0,
            "privilege_type":1,
            "source":"reship",
            "reship_url":"https://lexiangla.com"
        },
        "relationships":{
            "category":{
                "data":{
                    "type":"category",
                    "id":"uuid123"
                }
            },
            "team":{
                "data":{
                    "type":"team",
                    "id":"uuid123"
                }
            },
            "directory":{
                "data":{
                    "type":"directory",
                    "id":"uuid123"
                }
            },
            "privilege": {
                "data": [
                    {
                        "type": "staff",
                        "id": "StaffID"
                    },
                    {
                        "type": "department",
                        "id": 1
                    }
                ]
            },
            "attachments": {
                "data": [
                    {
                        "type": "attachment",
                        "id": "uuid123"
                    },
                    {
                        "type": "attachment",
                        "id": "uuid123"
                    }
                ]
            }
        }
    }
}

参数说明:

参数 是否必须 默认值 说明
doc.type 资源对象类型,必须为 doc,表示文档
doc.title 文档标题
doc.content 文档内容
doc.is_markdown 0表示 HTML 格式,1表示 Markdown 格式
doc.privilege_type 0 0表示文档公开
1表示部分人可见,需要配合 privilege 参数使用
2表示仅创建者可见
doc.source original original 表示原创,reship 表示转载
doc.reship_url 当 source 为 reship 时,reship_url表示转载来源
doc.category 关联的资源对象,类型为 category,表示文档所属分类
doc.team 关联的资源对象,类型为 team,表示文档所属K吧
doc.directory 关联的资源对象,类型为 directory,表示文档所属目录
目录仅附属于K吧下,仅传入K吧ID时有意义
若传入K吧时缺省此项则默认文档创建于K吧根目录
doc.privilege 关联的资源对象,类型为 privilege,仅当 privilege_type 为1时有效
可传入多个 staff,department,team,contacttag 对象
doc.attachments 关联的资源对象,类型为 attachments,表示附件
category.id 分类ID
team.id K吧ID
directory.id 目录ID
attachment.id 附件ID

SDK封装方法使用示例:

$attributes = [
    'title' => '通过开放接口创建的文档',
    'content' => '<h1>富文本内容</h1>',
    'is_markdown' => 0,
];
$options = [
    'privilege_type' => 2,
    'source' => 'reship',
    'reship_url' => 'https://lexiangla.com',
    'category_id' => null,
    'team_id' => 'uuid123',
    'directory_id' => 'uuid123',
    'attachments' => [uuid1, uuid2, uuid3],
];
$Lxapi = new \Lexiangla\Openapi\Api(AppKey, AppSecret);
$response = $Lxapi->postDoc(StaffID, $attributes, $options);

响应document

201 Created 状态码
{
    "data":{
        "type":"doc",
        "id":"65185ea6540311e895d2fb755adc6cb4",
        "attributes":{
            "name":"通过开放接口创建的文档标题",
            "privilege_type":"2",
            "is_star":"0",
            "created_at":"2018-05-10 11:36:59",
            "updated_at":"2018-05-10 11:36:59"
        },
        "links":{
            "platform":"https://xxx.lexiangla.com/teams/k00001/docs/65185ea6540311e895d2fb755adc6cb4"
        },
        "relationships":{
            "category":{
                "data":{
                    "type":"category",
                    "id":"3dc4337252dc11e693940800278acc25"
                }
            },
            "owner":{
                "data":{
                    "type":"staff",
                    "id":"StaffID"
                }
            },
            "target":{
                "data":{
                    "type":"document",
                    "id":"6517eaf2540311e8b59b57582a142694"
                }
            }
        }
    },
    "included":[
        {
            "type":"category",
            "id":"3dc4337252dc11e693940800278acc25",
            "attributes":{
                "name":"其他",
                "created_at":"2016-07-26 10:54:16"
            }
        },
        {
            "type":"staff",
            "id":"StaffID",
            "attributes":{
                "name":"张三",
                "english_name":"ThreeZhang",
                "organization":"运营组"
            }
        },
        {
            "type":"document",
            "id":"6517eaf2540311e8b59b57582a142694",
            "attributes":{
                "is_markdown":"0",
                "content":"<h1>富文本内容</h1>",
                "source":"reship",
                "reship_url":"https://lexiangla.com",
                "read_count":"0",
                "comment_count":"0",
                "like_count":"0",
                "favorite_count":"0",
                "md_content":null
            }
        }
    ],
    "links":{
        "self":{
            "href":"https://lxapi.lexiangla.com/cgi-bin/v1/docs/65185ea6540311e895d2fb755adc6cb4"
        }
    }
}

上传文档

此接口只用于创建文档实体,不负责文件传输。开发者需先通过 文件上传 接口将文件上传于腾讯云,再把state通过此接口把文件和实体关联起来。

接口调用说明:

POST https://lxapi.lexiangla.com/cgi-bin/v1/docs/upload?state={$state}

请求document

{
    "data":{
        "type":"doc",
        "attributes":{
            "name": "文档名",
            "downloadable": 0,
            "privilege_type":1,
            "picture_url": ""
        },
        "relationships":{
            "category":{
                "data":{
                    "type":"category",
                    "id":"uuid123"
                }
            },
            "team": {
                "data": {
                    "type": "team",
                    "id": "uuid124"
                }
            },
            "directory":{
                "data":{
                    "type":"directory",
                    "id":"uuid123"
                }
            },
            "privilege": {
                "data": [
                    {
                        "type": "staff",
                        "id": "StaffID"
                    },
                    {
                        "type": "contacttag",
                        "id": 1
                    }
                ]
            }
        }
    }
}

参数说明:

参数 是否必须 默认值 说明
doc.type 资源对象类型,必须为 doc,表示文件
doc.name 自定义文档名,若不填则默认使用上传的文档名
doc.downloadable 1 是否允许下载:0表示不能下载,1表示允许下载
doc.privilege_type 0表示文档公开
1表示部分人可见,需要配合 privilege 参数使用
2表示仅创建者可见
doc.picture_url 文件配图
doc.category 关联的资源对象,类型为 category,表示文档所属分类
doc.team 关联的资源对象,类型为 team,表示文档所属K吧
doc.directory 关联的资源对象,类型为 directory,表示文档所属目录
目录仅附属于K吧下,仅传入K吧ID时有意义
若传入K吧时缺省此项则默认文档创建于K吧根目录
doc.privilege 关联的资源对象,类型为 privilege,仅当 privilege_type 为1时有效
可传入多个 staff,department,team,contacttag 对象
category.id 分类ID
team.id K吧ID
directory.id 目录ID
state 腾讯云直传-获取资源签名接口中object.state

SDK封装方法使用示例:

$options = [
    'name' => '文档名',
    'downloadable' => 0, // 是否可下载
    'privilege_type' => 1,
    'picture_url' => '', // 文档配图
    'category_id' => '5b3109d6dd7611e88d4f5254009b5a66',  // 文档分类
    'team_id' => 'uuid124', // 文档所属k吧
    'directory_id' => 'uuid124', // 文档所属目录
    'privilege_type' => 1, 
    'privilege' => [
            ['type' => 'department', 'id' => 1],
            ['type' => 'contacttag', 'id' => 1],
    ],// 文档的可见范围
];
$Lxapi = new \Lexiangla\Openapi\Api(AppKey, AppSecret);
$file_path =  '/path/to/测试.xlsx'; // 文件的绝对路径
$response = $Lxapi->uploadDoc($staff_id, $file_path, $options);

响应document

201 Created 状态码
{
    "data":{
        "type":"doc",
        "id":"65e14486efb811e98dcd10e7c61c70fc",
        "links":{
            "platform":{
                "href":"https://lexiangla.com/teams/xxx/docs/65e14486efb811e98dcd10e7c61c70fc"
            }
        },
        "attributes":{
            "name":"测试",
            "privilege_type":1,
            "updated_at":"2019-10-16 09:58:07",
            "created_at":"2019-10-16 09:58:07"
        },
        "relationships":{
            "target":{
                "data":{
                    "type":"file",
                    "id":"65c9cf90efb811e9a2ca10e7c61c70fc"
                }
            }
        }
    },
    "included":[
        {
            "type":"file",
            "id":"65c9cf90efb811e9a2ca10e7c61c70fc",
            "attributes":{
                "name":"测试"
            }
        }
    ],
    "links":{
        "self":{
            "href":"https://lxapi.lexiangla.com/cgi-bin/v1/docs/65e14486efb811e98dcd10e7c61c70fc"
        }
    }
}

编辑文档

目前文档编辑仅支持修改:title、content、category_id、source、reship_url、privilege。仅修改参数中存在的字段属性,未传入的字段不会变更。

其他属性如:所属K吧,所在目录,附件等,后续计划开放。

is_markdown 属性不能修改,若文档本身是 markdown 格式的,要修改 content 字段也要使用 markdown 格式。

接口调用说明:

PATCH https://lxapi.lexiangla.com/cgi-bin/v1/docs/{DocID}

请求document

{
    "data":{
        "type":"doc",
        "attributes":{
            "title":"通过开放接口创建的文档",
            "content":"<h1>富文本内容</h1>",
            "source":"reship",
            "reship_url":"https://lexiangla.com"
        },
        "relationships":{
            "category":{
                "data":{
                    "type":"category",
                    "id":"uuid123"
                }
            },
            "attachments": {
                "data": [
                    {
                        "type": "attachment",
                        "id": "uuid123"
                    },
                    {
                        "type": "attachment",
                        "id": "uuid123"
                    }
                ]
            }
        }
    }
}

SDK封装方法使用示例:

$options = [
    'title' => '编辑后的标题',
    'content' => '修改后的内容',
    'source' => 'reship',
    'reship_url' => 'https://lexiangla.com',
    'category_id' => uuid123,
    'attachments' => [uuid1, uuid2, uuid3],
];
$Lxapi = new \Lexiangla\Openapi\Api(AppKey, AppSecret);
$response = $Lxapi->patchDoc(StaffID, $doc_id, $options);

响应document

200 OK 状态码

删除文档

接口调用说明:

DELETE https://lxapi.lexiangla.com/cgi-bin/v1/docs/{DocID}

参数说明:

参数 是否必须 默认值 说明
DocID 资源对象类型为 doc 的资源对象ID,即文档ID

SDK封装方法使用示例:

$Lxapi = new \Lexiangla\Openapi\Api(AppKey, AppSecret);
$response = $Lxapi->deleteDoc(StaffID, DocID');

响应document

204 No Content 状态码

获取单个文档

接口调用说明:

GET https://lxapi.lexiangla.com/cgi-bin/v1/docs/{DocID}

参数说明:

参数 是否必须 默认值 说明
DocID document中资源对象类型为doc的资源对象ID,即文档ID

SDK封装方法使用示例:

$Lxapi = new \Lexiangla\Openapi\Api(AppKey, AppSecret);
$response = $Lxapi->getDoc('3754ef90540611e88b15cbea5266a5e7');

响应document

200 OK 状态码
{
    "data":{
        "type":"doc",
        "id":"3754ef90540611e88b15cbea5266a5e7",
        "attributes":{
            "name":"通过开放接口创建的文档标题",
            "privilege_type":"0",
            "is_star":"0",
            "created_at":"2018-05-10 11:57:10",
            "updated_at":"2018-05-10 11:57:10"
        },
        "links":{
            "platform":"https://xxx.lexiangla.com/docs/3754ef90540611e88b15cbea5266a5e7"
        },
        "relationships":{
            "category":{
                "data":{
                    "type":"category",
                    "id":"3dc4337252dc11e693940800278acc25"
                }
            },
            "owner":{
                "data":{
                    "type":"staff",
                    "id":"StaffID"
                }
            },
            "target":{
                "data":{
                    "type":"document",
                    "id":"37547e02540611e89a0737323e67fe70"
                }
            }
        }
    },
    "included":[
        {
            "type":"category",
            "id":"3dc4337252dc11e693940800278acc25",
            "attributes":{
                "name":"其他"
            }
        },
        {
            "type":"staff",
            "id":"StaffID",
            "attributes":{
                "name":"张三",
                "english_name":"ThreeZhang",
                "organization":"运营组"
            }
        },
        {
            "type":"document",
            "id":"37547e02540611e89a0737323e67fe70",
            "attributes":{
                "is_markdown":"0",
                "content":"<h1>富文本内容</h1>",
                "source":"reship",
                "reship_url":"https://lexiangla.com",
                "read_count":"0",
                "comment_count":"0",
                "like_count":"0",
                "favorite_count":"0",
                "md_content":null
            }
        }
    ],
    "links":{
        "self":{
            "href":"https://lxapi.lexiangla.com/cgi-bin/v1/docs/3754ef90540611e88b15cbea5266a5e7"
        }
    }
}
404 Not Found 状态码
{
    "errors":{
        "detail":"不存在ID为`3754ef90540611e88b15cbea5266a5e7`的doc资源"
    }
}

获取文档列表

接口调用说明:

GET https://lxapi.lexiangla.com/cgi-bin/v1/docs

参数说明:

参数 是否必须 默认值 说明
filter public hot:最热文档;public:公开可见的文档;all:全部文档;
date_range 获取最热文档时(filter=hot)时必传;
值为1到100之间的整数,表示获取距今多少天内的最热文档
category_id 指定分类的文档,仅当filterpublicall时有效
page 1 当前页数
per_page 20 每页返回的数量
sort -created_at 排序方式,目前仅支持created_at

SDK封装方法使用示例:

获取公开可见的文档列表(支持指定分类)

$Lxapi = new \Lexiangla\Openapi\Api(AppKey, AppSecret);
$response = $Lxapi->get('docs',[
    'filter' => 'public',
    // 'category_id' => 'xxxxxx', // 支持指定文档分类
    'page' => 1,
    'per_page' => 3
]);

获取所有的文档列表(支持指定分类)

$Lxapi = new \Lexiangla\Openapi\Api(AppKey, AppSecret);
$response = $Lxapi->get('docs',[
    'filter' => 'all',
    // 'category_id' => 'xxxxxx', // 支持指定文档分类
    'page' => 1,
    'per_page' => 3
]);

获取公开可见的最热文档(不支持指定分类)

$Lxapi = new \Lexiangla\Openapi\Api(AppKey, AppSecret);
$response = $Lxapi->get('docs',[
    'filter' => 'hot',
    'date_range' => 30, // 获取30天的最热文档
    'page' => 1,
    'per_page' => 3
]);

响应document

200 OK 状态码
{
    "data":[
        {
            "type":"doc",
            "id":"42c09da4a9d111e8bed25254009b5a66",
            "attributes":{
                "name":"K吧内新建一个文档去",
                "privilege_type":0,
                "is_star":0,
                "created_at":"2018-08-27 16:14:46",
                "read_count":4,
                "comment_count":1,
                "updated_at":"2018-08-28 10:53:05",
                "recommended_at":null
            },
            "links":{
                "platform":"https://xxx.lexiangla.com/teams/k100301/docs/42c09da4a9d111e8bed25254009b5a66"
            },
            "relationships":{
                "category":{
                    "data":{
                        "type":"category",
                        "id":"eaa1ce22d57d11e7bcc65254002b6735"
                    }
                },
                "owner":{
                    "data":{
                        "type":"staff",
                        "id":"StaffID1"
                    }
                },
                "team":{
                    "data":{
                        "type":"team",
                        "id":"87bcad06a75811e88c9d5254009b5a66"
                    }
                },
                "target":{
                    "data":{
                        "type":"document",
                        "id":"42bd3970a9d111e8ae6a5254009b5a66"
                    }
                }
            }
        },
        {
            "type":"doc",
            "id":"e75489e4a9d011e8a0965254009b5a66",
            "attributes":{
                "name":"我不止一次来到你的世界",
                "privilege_type":0,
                "is_star":0,
                "created_at":"2018-08-27 16:12:13",
                "read_count":1,
                "comment_count":0,
                "updated_at":"2018-08-27 16:12:13",
                "recommended_at":null
            },
            "links":{
                "platform":"https://xxx.lexiangla.com/teams/K10/docs/e75489e4a9d011e8a0965254009b5a66"
            },
            "relationships":{
                "category":{
                    "data":{
                        "type":"category",
                        "id":"eaa1ce22d57d11e7bcc65254002b6735"
                    }
                },
                "owner":{
                    "data":{
                        "type":"staff",
                        "id":"StaffID2"
                    }
                },
                "team":{
                    "data":{
                        "type":"team",
                        "id":"fc59bc42781711e797c25254002b6735"
                    }
                },
                "target":{
                    "data":{
                        "type":"document",
                        "id":"e7515bc0a9d011e89e115254009b5a66"
                    }
                }
            }
        },
        {
            "type":"doc",
            "id":"7790dfe2a45111e8bab25254009b5a66",
            "attributes":{
                "name":"文档api",
                "privilege_type":0,
                "is_star":0,
                "created_at":"2018-08-20 16:17:24",
                "read_count":1,
                "comment_count":0,
                "updated_at":"2018-08-20 16:17:24",
                "recommended_at":null
            },
            "links":{
                "platform":"https://km.lexiangla.com/teams/k100289/docs/7790dfe2a45111e8bab25254009b5a66"
            },
            "relationships":{
                "category":{
                    "data":{
                        "type":"category",
                        "id":"54cc51cc2af311e7b3595254002b6735"
                    }
                },
                "owner":{
                    "data":{
                        "type":"staff",
                        "id":"StaffID3"
                    }
                },
                "team":{
                    "data":{
                        "type":"team",
                        "id":"519df2d6a05811e885555254009b5a66"
                    }
                },
                "target":{
                    "data":{
                        "type":"document",
                        "id":"778d89e6a45111e88d625254009b5a66"
                    }
                }
            }
        }
    ],
    "links":{
        "first":"https://lxapi.lexiangla.com/cgi-bin/v1/docs?filter=latest&per_page=3&page=1",
        "last":"https://lxapi.lexiangla.com/cgi-bin/v1/docs?filter=latest&per_page=3&page=272",
        "prev":null,
        "next":"https://lxapi.lexiangla.com/cgi-bin/v1/docs?filter=latest&per_page=3&page=2"
    },
    "meta":{
        "current_page":1,
        "from":1,
        "last_page":272,
        "path":"https://lxapi.lexiangla.com/cgi-bin/v1/docs",
        "per_page":"3",
        "to":3,
        "total":814
    },
    "included":[
        {
            "type":"category",
            "id":"eaa1ce22d57d11e7bcc65254002b6735",
            "attributes":{
                "name":"皮皮虾"
            }
        },
        {
            "type":"category",
            "id":"54cc51cc2af311e7b3595254002b6735",
            "attributes":{
                "name":"专业技能"
            }
        },
        {
            "type":"staff",
            "id":"StaffID1",
            "attributes":{
                "name":"张三",
                "english_name":"ThreeZhang",
                "organization":"运营组"
            }
        },
        {
            "type":"staff",
            "id":"StaffID2",
            "attributes":{
                "name":"李四",
                "english_name":"FourLee",
                "organization":"产品组"
            }
        },
        {
            "type":"staff",
            "id":"StaffID3",
            "attributes":{
                "name":"王二",
                "english_name":"TwoWang",
                "organization":"开发组"
            }
        },
        {
            "type":"team",
            "id":"87bcad06a75811e88c9d5254009b5a66",
            "attributes":{
                "name":"team1"
            }
        },
        {
            "type":"team",
            "id":"fc59bc42781711e797c25254002b6735",
            "attributes":{
                "name":"team2"
            }
        },
        {
            "type":"team",
            "id":"519df2d6a05811e885555254009b5a66",
            "attributes":{
                "name":"team3"
            }
        },
        {
            "type":"document",
            "id":"42bd3970a9d111e8ae6a5254009b5a66",
            "attributes":{
                "source":"original",
                "reship_url":null,
                "read_count":4,
                "comment_count":1,
                "like_count":1,
                "favorite_count":1
            }
        },
        {
            "type":"document",
            "id":"e7515bc0a9d011e89e115254009b5a66",
            "attributes":{
                "source":"original",
                "reship_url":null,
                "read_count":1,
                "comment_count":0,
                "like_count":0,
                "favorite_count":0
            }
        },
        {
            "type":"document",
            "id":"778d89e6a45111e88d625254009b5a66",
            "attributes":{
                "source":"original",
                "reship_url":null,
                "read_count":1,
                "comment_count":0,
                "like_count":0,
                "favorite_count":0
            }
        }
    ]
}
400 Bad Request 状态码

当没有传递参数filter=hot时,没有传递date_range,会返回400状态码,且响应体如下所示:

{
    "errors":{
        "detail":{"date_range":["date range 是必须的当 filter 是 hot."]}
    }
}

当传递错误的filter时,会返回400状态码,且响应体如下所示:

{
    "errors":{
        "detail":{"filter":["选定的 filter 是无效的."]}
    }
}

当传递的category_id对应的分类不存在时,会返回300状态码,且响应体如下所示:

{
    "errors":{
        "detail":{"category_id":["category id 是无效的."]}
    }
}