文档接口

注册文档

注册文档接口用于生成文档的唯一标识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上传的文档进行发布处理。仅对状态为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参数

请求参数

请求示例

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