通知接口
更新时间：2019-06-14
用户通过本接口在创建/注册文档时配置“自定义通知”，或者在管理控制台设置“默认通知”后，当在文档处理完成后（发布成功/失败），文档转码服务会通过 HTTP 请求将通知消息 POST 到您所配置的通知接口。
说明
- 每个用户最多可以创建的5个通知。建议复用通知，搭建并维护少量回调服务器，能够处理所有文档的回调通知消息。
- 通过 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