文档接口

更新时间：2022-04-27

注册文档

注册文档接口用于生成文档的唯一标识documentId、用于存储源文档文件的BOS Bucket相关信息。注册成功后，对应文档状态为UPLOADING，对应Bucket对用户开放写权限，对于用户的BOS空间不可见。

注册文档是文档三步创建法（注册文档、上传BOS、发布文档）的第一步。

请求语法

POST /v<version>/document?register HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

无特殊请求头域。

请求参数

参数	类型	描述	是否必须
title	String	文档标题，不超过50字符	是
format	String	文档格式。有效值：doc, docx, ppt, pptx, xls, xlsx, vsd, pot, pps, rtf, wps, et, dps, pdf, txt, epub	是
targetType	String	转码结果类型：h5, image，默认值为h5。（目前暂不支持txt格式文档转码成image类型）	否
notification	String	通知名称	否
access	String	文档权限。有效值：PUBLIC、PRIVATE，默认值：PUBLIC，表示公开文档，设为PRIVATE时表示私有文档	否

请求示例

POST /v2/document?register HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

{
    "title":"my_doc",
    "format":"doc"
}

响应头域

无特殊响应头域。

响应参数

头域	类型	描述
documentId	String	系统生成的文档的唯一标识
bucket	String	该文档对应的源文件上传地址在BOS存储中的Bucket
object	String	该文档对应的源文件上传地址在BOS存储中的Object
bosEndpoint	String	该文档对应的源文件上传地址对应的BOS存储的Endpoint

响应示例

HTTP/1.1 200 OK

{
  "documentId" : "doc-ggkf13g87d8iiik",
  "bucket" : "bktmgejppds85z6c29rm",
  "object" : "upload/doc-ggkf13g87d8iiik.txt",
  "bosEndpoint" : "http://bj.bcebos.com"
}

根据BOS Object创建文档

通过BOS Object路径，用从BOS导入的方法创建文档。

注意：

源文档所在BOS Bucket所属地域须为"华北-北京(bj)"。

源文档所在BOS Bucket权限须设置为公共读，或在自定义权限设置中为DOC文档服务账号（183db8cd3d5a4bf9a94459f89a7a3a91）添加READ权限。

请求语法

POST /v<version>/document?source=bos HTTP/1.1
host: doc.bj.baidubce.com
authorization: <bce-authorization-string>
content-type: application/json

请求头域

无特殊请求头域。

请求参数

参数	类型	描述	是否必须
bucket	String	BOS Bucket	是
object	String	BOS Object	是
title	String	文档标题，不超过50字符	是
format	String	文档格式。有效值：doc, docx, ppt, pptx, xls, xlsx, vsd, pot, pps, rtf, wps, et, dps, pdf, txt, epub。默认值：BOS Object后缀名（当BOS Object有后缀时）	BOS Object有后缀时可选，否则必选
targetType	String	转码结果类型：h5, image，默认值为h5。（目前暂不支持txt格式文档转码成image类型）	否
notification	String	通知名称	否
access	String	文档权限。有效值：PUBLIC、PRIVATE，默认值：PUBLIC，表示公开文档，设为PRIVATE时表示私有文档	否

请求示例

POST /v2/document?source=bos HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

响应头域

无特殊响应头域。

响应参数

头域	类型	描述
documentId	String	系统生成的文档的唯一标识

响应示例

HTTP/1.1 200 OK

{
    "documentId":"doc-fhepatsnpn4rk9z"
}

上传至BOS

请求示例

https://bj.bcebos.com/{bucket}/upload/{docId}.{format}?authorization

Method：POST

请求参数与响应参数

https://cloud.baidu.com/doc/BOS/s/Njwvyseb4

发布文档

用于对已完成注册和BOS上传的文档进行发布处理。仅对状态为UPLOADING的文档有效。处理过程中，文档状态为PROCESSING；处理完成后，状态转为PUBLISHED。

发布文档是文档三步创建法（注册文档、上传BOS、发布文档）的第三步。

请求语法

PUT /v<version>/document/<documentId>?publish HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

无特殊请求头域。

请求参数

参数	类型	描述	是否必须
documentId	String	系统生成的文档的唯一标识	是

请求示例

PUT /v2/document/doc-fhepatsnpn4rk9z?publish HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

响应头域

无特殊响应头域。

响应参数

N/A

响应示例

HTTP/1.1 200 OK

重新发布文档

接口描述

重新发布文档，仅对状态为FAILED/PUBLISHED的文档有效。

对转码失败的文档进行重新转码（适用转码超时或者内部错误的文档，对于无法进行转码的文档在百度智能云转码服务升级后也可尝试进行重新发布）。
对转码成功的文档进行重新转码，可以通过该接口修改文档标题、转码结果类型、文档权限等配置，然后重新转码。

请求语法

PUT /v{version}/document/{documentId}?rerun HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: {bce-authorization-string}

请求头域

无特殊Header参数

请求参数

参数	类型	描述	是否必须
documentId	String	系统生成的文档的唯一标识	是
title	String	文档标题，不超过50字符。如果传递了format、targetType、notification、access中任意一项参数，必须同时传递title参数	否
format	String	文档格式，有效值：doc、docx、ppt、pptx、xls、xlsx、vsd、pot、pps、rtf、wps、et、dps、pdf、txt、epub	否
targetType	String	转码结果类型：h5、image，默认值为h5（目前暂不支持txt格式文档转码成image格式)	否
notification	String	通知	否
access	String	文档权限，有效值PUBLIC、PRIVATE，默认值：PUBLIC，表示公开文档，PRIVATE表示私有文档	否

请求示例

PUT /v2/document/doc-ggkf5h4g2dqqvgp?rerun HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

响应头域

无特殊Header参数

响应参数

无

响应示例

HTTP/1.1 200 OK

查询文档

通过文档的唯一标识 documentId 查询指定文档的详细信息。

请求语法

GET /v<version>/document/<documentId> HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

无特殊请求头域。

请求参数

参数	类型	描述	是否必须
documentId	String	系统生成的文档的唯一标识	是
https	Boolean	是否支持https阅读，默认为false。当https=true时，返回的coverUrl是https地址。	否

请求示例

GET /v2/document/doc-ggkf5h4g2dqqvgp?https=false HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

响应头域

无特殊响应头域。

响应参数

头域	类型	描述
documentId	String	系统生成的文档的唯一标识
title	String	文档标题
format	String	文档格式
targetType	String	转码结果类型
status	Object	文档状态。有效值：UPLOADING/PROCESSING/PUBLISHED/FAILED。详见DOC核心概念-文档状态
uploadInfo	Object	文档上传信息。仅当`status=UPLOADING`时有效
+bucket	String	BOS Bucket
+object	String	BOS Object
+bosEndpoint	String	BOS Endpoint
publishInfo	Object	文档发布信息。仅当`status=PUBLISHED`时有效
+pageCount	Number	文档总页数
+sizeInBytes	Number	源文档字节数
+coverUrl	String	文档封面图
+publishTime	Date	文档发布时间
error	Object	文档转码错误信息。仅当`status=FAILED`时有效
+code	String	错误代码
+message	String	错误信息
notification	String	通知名称
access	String	文档权限
createTime	Date	文档创建时间

响应示例

HTTP/1.1 200 OK

{
  "documentId" : "doc-ggkf5h4g2dqqvgp",
  "title" : "download_document_v2_dIelRe9zMv",
  "format" : "txt",
  "targetType" : "h5",
  "status" : "UPLOADING",
  "uploadInfo" : {
    "bucket" : "bktmgejppds85z6c29rm",
    "object" : "upload/doc-ggkf5h4g2dqqvgp.txt",
    "bosEndpoint" : "http://bj.bcebos.com"
  },
  "access" : "PUBLIC",
  "createTime" : "2016-07-10T21:08:28Z"
}

使用图片服务处理文档封面图

使用图片服务可对文档封面图进行缩放、裁剪、格式转换、旋转、添加水印等实时处理，URL格式如下所示：

# 例1：将文档封面图（109×154）缩略成宽度为100，高度按原图比例等比例缩放

http://gkjry0kfyyanqka4k2h.exp.bcedocument.com/target/doc-gkjraanw4f89uu5/doc-gkjraanw4f89uu5.jpg@w_100

# 例2：将文档封面图（109×154）拉伸到100×150的比例，再等比例缩放至宽100，高150

http://gkjry0kfyyanqka4k2h.exp.bcedocument.com/target/doc-gkjraanw4f89uu5/doc-gkjraanw4f89uu5.jpg@s_1,w_100,h_150

# 例3：将文档封面图（109×154）等比例缩小80/120倍，再居中裁剪至宽80，高120

http://gkjry0kfyyanqka4k2h.exp.bcedocument.com/target/doc-gkjraanw4f89uu5/doc-gkjraanw4f89uu5.jpg@s_2,w_80,h_120

错误返回格式

此接口的错误返回格式与通用错误返回格式不同，具体如下：

{
    "requestId":"<bce-request-id>",
    "code":"<error-code>",
    "message":{"global":"<error-message>"},
    "success":false
}

文档列表

查询所有文档，以列表形式返回，支持用文档状态作为筛选条件进行筛选。

请求语法

GET /v<version>/document/?status=<status> HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

无特殊请求头域。

请求参数

参数	类型	描述	是否必须
status	Object	文档状态。有效值：UPLOADING/PROCESSING/PUBLISHED/FAILED。详见DOC核心概念-文档状态	否
marker	String	本次请求的marker，标记查询的起始位置。默认值：空字符串。	否
maxSize	Integer	本次请求的文档数目，不超过200。默认值：200。	否

请求示例

按documentId升序查询maxSize数目（默认200）的文档

  GET /v2/document HTTP/1.1
  host: doc.bj.baidubce.com
  content-type: application/json
  authorization: <bce-authorization-string>

查询PROCESSING状态的文档

  GET /v2/document?status=PROCESSING HTTP/1.1
  host: doc.bj.baidubce.com
  content-type: application/json
  authorization: <bce-authorization-string>

指定marker查询文档

  GET /v2/document?marker=doc-ggjz6snf4qmzxxz&maxSize=100 HTTP/1.1
  host: doc.bj.baidubce.com
  content-type: application/json
  authorization: <bce-authorization-string>

响应头域

无特殊响应头域。

响应参数

头域	类型	描述
documents	Array	文档列表
+documentId	String	系统生成的文档的唯一标识
+title	String	文档标题
+format	String	文档格式
+targetType	String	转码结果类型
+status	Object	文档状态。有效值：UPLOADING/PROCESSING/PUBLISHED/FAILED。详见DOC核心概念-文档状态
+error	Object	文档转码错误信息。仅当`status=FAILED`时有效
++code	String	错误代码
++message	String	错误信息
+notification	String	通知名称
+access	String	文档权限
+createTime	Date	文档创建时间

响应示例

HTTP/1.1 200 OK

{
  "documents" : [ {
    "documentId" : "doc-ggjz6sne4qmz185",
    "title" : "download_document_v2_T6qgyh0JEu",
    "format" : "txt",
    "targetType" : "h5",
    "status" : "UPLOADING",
    "access" : "PUBLIC",
    "createTime" : "2016-07-10T15:42:56Z"
  }, {
    "documentId" : "doc-ggkf1yznae32sq6",
    "title" : "create_document_by_bosObject",
    "format" : "dps",
    "targetType" : "h5",
    "status" : "PROCESSING",
    "access" : "PUBLIC",
    "createTime" : "2016-07-10T21:07:23Z"
  }, {
    "documentId" : "doc-ggjz2ak3hsndzx4",
    "title" : "download_document_v2_ZohAwjqj88",
    "format" : "txt",
	"targetType" : "h5",
    "status" : "PUBLISHED",
    "access" : "PUBLIC",
    "createTime" : "2016-07-10T15:42:56Z"
  } ]
}

阅读文档

通过文档的唯一标识 documentId 获取指定文档的阅读信息，以便在PC/Android/iOS设备上阅读。仅对状态为PUBLISHED的文档有效。

请求语法

GET /v<version>/document/<documentId>?read HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

无特殊请求头域。

请求参数

参数	类型	描述	是否必须
documentId	String	系统生成的文档的唯一标识	是
expireInSeconds	Long	阅读Token有效期，仅当阅读私有文档（`"access" : "PRIVATE"`）时有效。单位：秒，默认值：3600	否

请求示例

GET /v2/document/doc-fhepatsnpn4rk9z?read HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

响应头域

无特殊响应头域。

响应参数

头域	类型	描述
documentId	String	系统生成的文档的唯一标识
docId	String	文档阅读ID，与documentId取值相同
host	String	文档阅读Host，用于阅读器SDK，取固定值`BCEDOC`
token	String	文档阅读Token，对于公开文档（`"access" : "PUBLIC"`）会返回固定值"TOKEN"，对于私有文档（`"access" : "PRIVATE"`）会返回随机字符串
createTime	Date	阅读Token创建时间，仅当阅读私有文档时返回
expireTime	Date	阅读Token失效时间，仅当阅读私有文档时返回

响应示例

HTTP/1.1 200 OK

{
    "documentId":"doc-fhepatsnpn4rk9z",
    "docId":"doc-fhepatsnpn4rk9z",
    "host":"BCEDOC",
    "token":"<Token>"
}

禁用阅读Token

禁用阅读文档接口生成的某个阅读Token。

请求语法

PUT /v<version>/document/<documentId>?disableReadToken HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

无特殊请求头域。

请求参数

参数	类型	描述	是否必须
token	String	阅读token	否

请求示例

PUT /v2/document/doc-gctkh1muycqbyzj?disableReadToken&token=39b3b3d0013f9fda17bc321aa41556d54ae6f60ba814f137677786b6f29d6cf6c5ef|1471339902 HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

响应头域

无特殊响应头域。

响应参数

N/A

响应示例

HTTP/1.1 200 OK

下载文档

通过文档的唯一标识 documentId 获取指定文档的下载链接。仅对状态为PUBLISHED/FAILED的文档有效。

请求语法

GET /v<version>/document/<documentId>?download HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

无特殊请求头域。

请求参数

参数	类型	描述	是否必须
documentId	String	系统生成的文档的唯一标识	是
expireInSeconds	Integer	源文档下载地址有效时长；默认值：-1表示永久有效	否
https	Boolean	是否支持https，默认为false。当https=true时，返回的downloadUrl是https地址。	否

请求示例

GET /v2/document/doc-gctkh1muycqbyzj?download&expireInSeconds=-1&https=false HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

响应头域

无特殊响应头域。

响应参数

头域	类型	描述
documentId	String	系统生成的文档的唯一标识
downloadUrl	String	源文档Url
createTime	Date	源文档Url生成时间
expireTime	Date	源文档Url过期时间，仅当expireInSeconds不等于-1时有效

响应示例

HTTP/1.1 200 OK

{
    "documentId": "doc-gctkh1muycqbyzjk",
    "downloadUrl": "http://ggtkzfubv4ycxw6upb3.exp.bcedocument.com/download/doc-gctkh1muycqbyzjk.docx?authorization=bce-auth-v1%2F6107180b80ae42c0a821a5fe53ba615e%2F2016-08-22T09%3A03%3A57Z%2F-1%2Fhost%2Ff5dc2b861818dfd7b67329572af1a9e6a617306f298314cc40786903ddcd1656",
    "createTime": "2016-08-22T09:03:57Z"   
}

查询文档转码结果图片列表

对于转码结果类型为图片的文档，通过本接口可以在文档转码完成后，获取转码结果图片的URL列表。

请求语法

GET /v{version}/document/{documentId}?getImages HTTP/1.1
host: doc.baidubce.com
content-type: application/json
authorization: {bce-authorization-string}

请求头域

无特殊Header参数

请求参数

无

请求示例

GET /v2/document/doc-ggkf5h4g2dqqvgp?getImages HTTP/1.1

响应头域

无特殊Header参数

响应参数

字段名称	字段类型	字段描述
images	Array	图片列表
+ pageIndex	Integer	页码，从1开始
+ url	String	图片URL

响应示例

HTTP/1.1 200 OK
{
    "images": [ {
        "pageIndex": 1,
        "url": "http://ggtkzfubv4ycxw6upb3.exp.bcedocument.com/target/doc-gkxq3ktua00zu43/doc-gkxq3ktua00zu43/0.jpg?x-bce-range=0-12975"
    }, {
        "pageIndex": 2,
        "url": "http://ggtkzfubv4ycxw6upb3.exp.bcedocument.com/target/doc-gkxq3ktua00zu43/doc-gkxq3ktua00zu43/0.jpg?x-bce-range=12975-"
    } ]
}

删除文档

删除文档，仅对状态status不是PROCESSING时的文档有效，清除文档占用的存储空间。

注意：

文档一经删除，无法通过查询文档/文档列表等接口获取，并且无法阅读、下载，请谨慎操作。

请求语法

DELETE /v{version}/document/{documentId} HTTP/1.1
host: doc.baidubce.com
content-type: application/json
authorization: {bce-authorization-string}

请求头域

无特殊请求头域。

请求参数

N/A

请求示例

DELETE /v2/document/doc-ggkf5h4g2dqqvgp HTTP/1.1

响应头域

无特殊响应头域。

响应参数

N/A

响应示例

HTTP/1.1 200 OK

OPTIONS

浏览器在发送跨域请求之前会发送一个preflight请求（OPTIONS）并带上特定的来源域、HTTP方法和Header信息等给DOC文档服务以决定是否发送真正的请求，OPTIONS接口即响应这种请求。调用时无需进行鉴权。

请求语法

OPTIONS /v<version>/document/[<documentId>] HTTP/1.1
Host: doc.bj.baidubce.com
Origin: <Origin>
Access-Control-Request-Method: <method>
Access-Control-Request-Headers: <headers>

请求头域

请求头域	类型	描述	是否必须
Origin	String	请求来源域，用来标识跨域请求	是
Access-Control-Request-Method	String	在实际请求中将会用到的HTTP方法，只允许一个方法	是
Access-Control-Request-Headers	String	在实际请求中会用到的除了简单头部之外的Headers，多个headers用逗号分割	否

请求参数

参数	类型	描述	是否必须
documentId	String	系统生成的文档的唯一标识	否

请求示例

OPTIONS /v2/document/doc-fhepatsnpn4rk9z HTTP/1.1
Host: doc.bj.baidubce.com
Origin: http://www.example.com
Access-Control-Request-Method: GET
Access-Control-Request-Headers: x-bce-date

响应头域

头域	类型	描述
Access-Control-Allow-Origin	String	请求中包含的Origin
Access-Control-Allow-Methods	String	允许请求的HTTP方法
Access-Control-Allow-Headers	String	请求中包含的Header列表，多个Headers用逗号分隔
Access-Control-Max-Age	Number	允许浏览器缓存preflight结果的时间，单位：秒
Access-Control-Allow-Credentials	String	文档转码服务是否允许客户端在请求中带cookie

注意：

目前文档服务仅仅校验OPTIONS请求中是否包含Origin和Access-Control-Request-Method两个header，且Access-Control-Request-Method的合法值为GET/POST/PUT/DELETE。如果不通过校验，则返回400，且不包含所有Access-Control-*相关的头部。

响应头域Access-Control-Allow-Headers的值和请求头域Access-Control-Request-Headers保持一致；响应头域Access-Control-Max-Age统一为3600，响应头域Access-Control-Allow-Credentials统一为true。

响应参数

N/A

响应示例

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://www.example.com 
Access-Control-Allow-Methods: GET, POST, PUT, DELETE 
Access-Control-Allow-Headers: x-bce-date
Access-Control-Max-Age: 3600
Access-Control-Allow-Credentials: true

公共头域

通知接口

百度智能云

文档服务 DOC

文档服务 DOC

文档接口

注册文档

根据BOS Object创建文档

上传至BOS

发布文档

重新发布文档

查询文档

使用图片服务处理文档封面图

文档列表

阅读文档

禁用阅读Token

下载文档

查询文档转码结果图片列表

删除文档

OPTIONS