金山文档开放平台主题
Webhook 订阅修改数据表说明
订阅数据表的说明修改
基本信息
请求方法：POST
请求路径：/api/v1/openapi/dbt/:file_token/webhook/sheets/:sheet_id/description
请求主机：developer.kdocs.cn
注意
一个文档内最多只允许创建 10 个 webhook，超过 10 个时创建会报错：30016 TooManyWebhooks。
限流频次
| 应用类型 | 限额 |
|---|---|
测试应用 | 500 次/天 |
正式应用 | 100,000 次/天 |
权限范围
要调用此 API，需要以下权限
| 权限值 | 显示名称 | 权限说明 |
|---|---|---|
edit_personal_files | 编辑文档内容 | 编辑文档内容 |
Path 参数
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
file_token | 是 | string | 文档 ID |
sheet_id | 是 | integer | 数据表 ID |
Query 参数
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
access_token | 是 | string |
Body 参数
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
callback_url | 是 | string | 当 webhook 触发时，回调通知地址 |
提示
如果 callback_url 中有特殊字符，需要提前做好 URL 转译。
返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
code | integer | 错误码 |
data | data {} | - |
示例
请求示例
curl --request POST \
--url 'https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/webhook/sheets/1/description?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1' \
--data '{"callback_url":"https://foo.bar"}'
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"callback_url\":\"https://foo.bar\"}");
Request request = new Request.Builder()
.url("https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/webhook/sheets/1/description?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1")
.post(body)
.build();
Response response = client.newCall(request).execute();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/webhook/sheets/1/description?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1"
payload := strings.NewReader("{\"callback_url\":\"https://foo.bar\"}")
req, _ := http.NewRequest("POST", url, payload)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
import http.client
conn = http.client.HTTPSConnection("developer.kdocs.cn")
payload = "{\"callback_url\":\"https://foo.bar\"}"
conn.request("POST", "/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/webhook/sheets/1/description?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1", payload)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/webhook/sheets/1/description?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\"callback_url\":\"https://foo.bar\"}",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
const data = JSON.stringify({
"callback_url": "https://foo.bar"
});
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/webhook/sheets/1/description?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1");
xhr.send(data);
const http = require("https");
const options = {
"method": "POST",
"hostname": "developer.kdocs.cn",
"port": null,
"path": "/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/webhook/sheets/1/description?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1",
"headers": {}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({callback_url: 'https://foo.bar'}));
req.end();
CURL *hnd = curl_easy_init();
curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/webhook/sheets/1/description?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1");
curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"callback_url\":\"https://foo.bar\"}");
CURLcode ret = curl_easy_perform(hnd);
var client = new RestClient("https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/webhook/sheets/1/description?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1");
var request = new RestRequest(Method.POST);
request.AddParameter("undefined", "{\"callback_url\":\"https://foo.bar\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
返回示例
{
"code": 0,
"data": {
"webhook_id": "6PWRKA4AN4AAA"
}
}
Webhook 回调通知
当更新数据表说明时，触发此通知。
| 参数 | 类型 | 说明 |
|---|---|---|
webhook_id | string | Webhook ID |
type | string | 固定为 dbt.sheets.desc |
events | event[] | 事件列表 |
示例
{
"webhook_id": "",
"type": "dbt.sheets.desc",
"events": [
{
"timestamp": 16788920,
"content": {
"sheetId": 1,
"originalValue": "foo",
"value": "bar"
}
}
]
}
错误码
请参考错误码说明