通知接口

用户通过本接口在创建/注册文档时配置“自定义通知”,或者在管理控制台设置“默认通知”后,当在文档处理完成后(发布成功/失败),文档转码服务会通过 HTTP 请求将通知消息 POST 到您所配置的通知接口。

说明

  1. 每个用户最多可以创建的5个通知。建议复用通知,搭建并维护少量回调服务器,能够处理所有文档的回调通知消息。
  2. 通过 API 创建通知接口创建的通知均为“自定义通知”,如果需要指定某个通知作为“默认通知”,需要在管理控制台进行操作。

通知类型及格式

DOC 支持“自定义通知”和“默认通知”两种类型,目前“默认通知”仅支持在控制台进行操作。

通知格式

DOC通过HTTP请求将通知消息POST到您所配置的通知接口,用户通知接口收到的HTTP POST请求BODY示例:

{
    "messageId": "<message_id>",
    "messageBody": "{\"documentId\":\"doc-gkideq542yb44diy\",\"title\":\"doc_title\",\"status\":\"PUBLISHED\",\"publishInfo\":{\"pageCount\":1,\"sizeInBytes\":33,\"publishTime\":\"2016-12-08T08:45:37Z\"},\"notifyTime\":\"2016-12-08T08:45:37Z\"}",
    "notification": "<notification_name>",
    "server": "doc.bj.baidubce.com"
}

messageBody字段的值为字符串类型,可以通过常用的JSON库转为标准的JSON格式。

messageBody转为JSON标准格式后形如:

{
    "documentId": "doc-fkigwn0r8uxszh3f",
    "title": "doc_title",
    "status": "PUBLISHED",
    "publishInfo" : {
        "pageCount": 1,
        "sizeInBytes": 33,
        "publishTime": "2016-12-08T08:45:37Z"
    },
    "notifyTime": "2016-12-08T08:45:37Z"
}

字段说明见下表:

字段 描述
documentId 系统生成的文档的唯一标识
title 文档标题
status 文档状态。有效值:PUBLISHED/FAILED
publishInfo 文档发布信息,仅status=PUBLISHED时存在
+ pageCount 文档总页数
+ sizeInBytes 源文档字节数
+ publishTime 文档发布时间
error 文档转码错误信息。仅当status=FAILED时有效
+code 错误码
+message 错误信息
notifyTime 通知消息生成时间

创建通知

通过用户提供的回调地址进行创建通知。如果用户在创建/申请文档时指定了通知,在文档处理完成后,DOC文档服务会向用户指定的回调地址推送通知消息。

请求语法

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

请求头域

无特殊请求头域。

请求参数

参数 类型 描述 是否必须
name String 通知名称。小写字母开头,小写字母、下划线(_)或数字组成的字符串,长度不超过40个字符
endpoint String 通知消息接收地址,长度不超过256字符

请求示例

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

{
  "name": "doc_notification", 
  "endpoint": "http://doc.domain.com/notify"
}

响应头域

无特殊响应头域。

响应参数

N/A

响应示例

HTTP/1.1 200 OK

查询通知

查询指定通知的详细信息。

请求语法

GET /v<version>/notification/{name} HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

无特殊请求头域。

请求参数

参数 类型 描述 是否必须
name String 通知名称

请求示例

GET /v2/notification/doc_notification HTTP/1.1
content-length: 0
accept-encoding: gzip, deflate
x-bce-date: 2015-07-03T09:28:13Z
connection: keep-alive
accept: */*
user-agent: python-requests/2.4.0 CPython/2.7.9 Darwin/14.3.0
host: doc.bj.baidubce.com
x-bce-request-id: 8776558c-81d9-4f97-8e2c-f977a286095d
content-type: application/json
authorization: bce-auth-v1/e8e4a9ced6794355a9a1b8a20b58d37b/2015-07-03T09:28:13Z/1800/content-type;host;x-bce-date/4a1692dc4bab84f5801f79ea0c1fece3601cf73ecd94409d2a94b3942b971715

响应头域

无特殊响应头域。

响应参数

头域 类型 描述
name String 通知名称
endpoint String 通知消息接收地址
createTime Date 通知创建时间
isDefault Boolean 是否为默认通知

响应示例

HTTP/1.1 200 OK
x-bce-request-id: 8776558c-81d9-4f97-8e2c-f977a286095d
Date: Fri, 03 Jul 2015 09:28:13 GMT
Transfer-Encoding: chunked
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache

{
  "name" : "doc_notification",
  "endpoint" : "http://doc.domain.com/notify",
  "isDefault" : false,
  "createTime" : "2016-01-01T13:37:10Z"
}

通知列表

获取已创建的全部通知。

请求语法

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

请求头域

无特殊请求头域。

请求参数

N/A

请求示例

GET /v2/notification HTTP/1.1
content-length: 0
accept-encoding: gzip, deflate
x-bce-date: 2015-07-03T09:28:13Z
connection: keep-alive
accept: */*
user-agent: python-requests/2.4.0 CPython/2.7.9 Darwin/14.3.0
host: doc.bj.baidubce.com
x-bce-request-id: 8776558c-81d9-4f97-8e2c-f977a286095d
content-type: application/json
authorization: bce-auth-v1/e8e4a9ced6794355a9a1b8a20b58d37b/2015-07-03T09:28:13Z/1800/content-type;host;x-bce-date/4a1692dc4bab84f5801f79ea0c1fece3601cf73ecd94409d2a94b3942b971715

响应头域

无特殊响应头域。

响应参数

头域 类型 描述
notification Object 通知列表
+name String 通知名称
+endpoint String 通知消息接收地址
+isDefault Boolean 是否为默认通知
+createTime Date 通知创建时间

响应示例

HTTP/1.1 200 OK
x-bce-request-id: 8776558c-81d9-4f97-8e2c-f977a286095d
Date: Fri, 03 Jul 2015 09:28:13 GMT
Transfer-Encoding: chunked
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache

{
  "notifications" : [ {
    "name" : "doc_notification",
    "endpoint" : "http://doc.domain.com/notify",
    "createTime" : "2016-01-01T13:37:10Z"
  }, {
    "name" : "new_notification",
    "endpoint" : "http://doc.domain.com/notify2",
    "isDefault" : false,
    "createTime" : "2016-01-01T13:47:10Z"
  } ]
}

删除通知

删除指定通知。

请求语法

DELETE /v<version>/notification/<name> HTTP/1.1
host: doc.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

无特殊请求头域。

请求参数

参数 类型 描述 是否必须
name String 通知名称

请求示例

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

响应头域

无特殊响应头域。

响应参数

N/A

响应示例

HTTP/1.1 200 OK