金山文档开放平台主题
创建记录
创建表记录，需要指定 sheetId，可一次创建多条记录
基本信息
请求方法：POST
请求路径：/api/v1/openapi/dbt/:file_token/sheets/:sheet_id/records
请求主机：developer.kdocs.cn
限流频次
| 应用类型 | 限额 |
|---|---|
测试应用 | 10,000 次/天 |
正式应用 | 10,000,000 次/天 |
权限范围
要调用此 API，需要以下权限
| 权限值 | 显示名称 | 权限说明 |
|---|---|---|
edit_personal_files | 编辑文档内容 | 编辑文档内容 |
注意
记录相关接口是批量的，允许在一个请求中创建/更新多条记录。
Path 参数
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
file_token | 是 | string | 文档 ID |
sheet_id | 是 | integer | Sheet ID |
Query 参数
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
access_token | 是 | string |
Body 参数
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
records | 是 | records[] | 记录列表 |
特殊字段说明
下列字段需要传入符合格式的参数才能正确设置单元格的值。
- 双向关联：参数是结构体，其中必须有名为 recordIds 的参数，它是一个数组，元素以字符串形式给出要关联的各记录 ID，不合法的 recordId 将会被忽略。
// 双向关联示例
"记录关联": {
"recordIds": [
"I", "G"
]
}
- 图片与附件：参数是数组，元素的格式是结构体，每个结构体必须包含 uploadId, fileName 参数，可选 source/type/size 参数。uploadId, fileName 及 source 均为字符串，source 参数必须为"upload_ks3"或"cloud"，否则所在结构体元素将会被跳过。不填写 source 时，默认处理为"upload_ks3"，type 及 size 参数为选填。type 是字符串，size 是数字，表示文件的字节数。通过 server api 设值时，这两个数据不会做校验。
// 图片和附件示例
"图片和附件": [
{
"fileName": "导入cloud测试.dbt",
"source": "cloud",
"uploadId": "100006023858"
},
{
"fileName": "123.xlsx",
"uploadId": "rxKtgtbuTC6D73xM4EgP45",
"source": "upload_ks3"
}
]
- 联系人：参数是数组，元素的格式是结构体，每个结构体必须包含 id 参数，可选 nickname 及 avatar_url 参数，id, nickname 及 avatar_url 均为字符串，同时存在 nickname 及 avatar_url 参数时，会用它们设置/更新 id 的联系人信息。
// 联系人示例
"联系人": [
{
"id": "13476457643",
"nickname": "asdfasdf",
"avatar_url": "https://gimg2.baidu.com/image_search/src=http%3A%2F%2Fimg.jj20.com%2Fup%2Fallimg%2F1114%2F113020142315%2F201130142315-1-1200.jpg&refer=http%3A%2F%2Fimg.jj20.com&app=2002&size=f9999,10000&q=a80&n=0&g=0n&fmt=auto?sec=1656239875&t=f6f6c8d67064da63fcebfcdf1718eea7"
},
{
"id": "12345"
}
]
- 单选项：参数是字符串。preferId 为 true 时，字符串必须是一个合法的 ID，且字段在这个 ID 上有选项；preferId 为 false 时，字符串内容必须是字段上已配置的可选值之一。
- 多选项：参数是字符串的数组。preferId 为 true 时，数组内各字符串必须全部是合法的 ID，且字段在这个 ID 上有选项；preferId 为 false 时，数组内各字符串必须是字段上已配置的可选值之一（对于包含英文半角逗号、英文半角双引号的选项，暂不支持通过 API 配置）。
返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
code | integer | 错误码 |
data | data {} | 响应数据 |
示例
请求示例
curl --request POST \
--url 'https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1' \
--header 'Content-Type: application/json' \
--data '{"records":[{"fields":{"字段名1":"item1"}},{"fields":{"字段名1":"item2"}}]}'
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"records\":[{\"fields\":{\"字段名1\":\"item1\"}},{\"fields\":{\"字段名1\":\"item2\"}}]}");
Request request = new Request.Builder()
.url("https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1")
.post(body)
.addHeader("Content-Type", "application/json")
.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/sheets/583/records?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1"
payload := strings.NewReader("{\"records\":[{\"fields\":{\"字段名1\":\"item1\"}},{\"fields\":{\"字段名1\":\"item2\"}}]}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
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 = "{\"records\":[{\"fields\":{\"字段名1\":\"item1\"}},{\"fields\":{\"字段名1\":\"item2\"}}]}"
headers = { 'Content-Type': "application/json" }
conn.request("POST", "/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1", payload, headers)
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/sheets/583/records?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 => "{\"records\":[{\"fields\":{\"字段名1\":\"item1\"}},{\"fields\":{\"字段名1\":\"item2\"}}]}",
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
const data = JSON.stringify({
"records": [
{
"fields": {
"字段名1": "item1"
}
},
{
"fields": {
"字段名1": "item2"
}
}
]
});
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/sheets/583/records?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);
const http = require("https");
const options = {
"method": "POST",
"hostname": "developer.kdocs.cn",
"port": null,
"path": "/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1",
"headers": {
"Content-Type": "application/json"
}
};
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({records: [{fields: {'字段名1': 'item1'}}, {fields: {'字段名1': 'item2'}}]}));
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/sheets/583/records?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1");
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"records\":[{\"fields\":{\"字段名1\":\"item1\"}},{\"fields\":{\"字段名1\":\"item2\"}}]}");
CURLcode ret = curl_easy_perform(hnd);
var client = new RestClient("https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\"records\":[{\"fields\":{\"字段名1\":\"item1\"}},{\"fields\":{\"字段名1\":\"item2\"}}]}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
返回示例
{
"code": 0,
"data": {
"detail": {
"records": [
{ "fields": { "字段名1": "item1" }, "id": "PP" },
{ "fields": { "字段名1": "item2" }, "id": "PQ" }
]
},
"result": "ok"
}
}
请求失败
当 fields 参数不合法（例如传入的文本内容不符合字段的类型、配置等要求）时，响应的 message 中将会带上首个非法的 field 信息
{
...
"message": "Update record failed. Failed due to field: <field name>"
...
}
错误码
请参考错误码说明