更新记录(PUT)

aki发表于:2016年08月29日 15:23:39更新于:2019年02月03日 09:43:39

Index

更新记录(1条)

  • 有记录编辑权限的用户可更新一条记录。

  • 更新方法有指定记录ID、和指定【值为唯一】的字段代码及其值两种。

HTTP 方法

PUT

URI

https://(子域名).cybozu.cn/k/v1/record.json

来宾空间内的应用

https://(子域名).cybozu.cn/k/guest/(空间的ID)/v1/record.json 

访问权限

如没有记录的编辑权限,向无编辑权限的字段添加值时,将发生错误。

请求参数

参数名称要指定的值必须说明
app数值或字符串必须指定应用的ID。
id数值或字符串可省略
※指定了updateKey时不可指定此项
指定记录ID。
updateKeyObject可省略
※指定了id时不可指定此项
指定【值为唯一】的字段代码和值。
recordObject可省略在对象中指定记录的信息(字段代码和字段的值)。 
※字段的值的规格因字段格式的不同而不同。详情请参考字段格式。 
※如省略此项,将不更新数据。
revision数值或字符串可省略修订号。和实际的修订号不一致时报错(不会更新记录)。 
但值为-1时或不指定时,将不检验修订号。

※参数名称的id和updateKey都指定时将报错。

请求正文的构成(指定记录ID)

{
    "app": (应用的ID),
    "id": (要更新的记录的ID),
    "record": {
        "(字段代码)": {
            "value": (字段值)
        },
        // 表格中的字段的第一行
        "(表格的字段代码)": {
            "value": [
                {
                    "id": (行的ID),
                    "value": {
                        "(字段代码)": {
                            "value": (字段值)
                        }
                    }               
                }
            ]
        }
    },
    "revision": (要更新的记录的修订号) // 不需要时可不用写
}

请求正文的构成(指定【值为唯一】的字段代码及其值)

{
    "app": (应用的ID),
    "updateKey": {
        "field": "(值为唯一的字段代码)",
        "value": "(值)"
    },
    "record": {
        "(字段代码)": {
            "value": (字段值)
        },
        // 表格中的字段的第一行
        "(表格的字段代码)": {
            "value": [
                {
                    "id": (行的ID),
                    "value": {
                        "(字段代码)": {
                            "value": (字段值)
                        }
                    }               
                }
            ]
        }
    },
    "revision": (要更新的记录的修订号) // 不需要时可不写
}

请求范例

请求头部

PUT /k/v1/record.json HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-Type: application/json
  • 在Content-Type中指定application/json。如不指定无法识别JSON,执行时将报错。

正文(指定记录ID)

对应用ID为【1972】的应用更新如下记录时

字段的格式字段代码
要更新的记录的编号
1
要更新的记录的修订号
4
多行文本框string_multicharacter string is changed
{
    "app": 1972,
    "id": 1,
    "revision": 4,
    "record": {
        "string_multi": {
            "value": "character string is changed"
        }
    }
}

正文(指定【值为唯一】的字段代码及其值)

对应用ID为【1972】的应用更新如下记录时

字段的格式字段代码
要作为Key的字段代码及其值string_codeCODE123
要更新的记录的修订号
4
多行文本框string_multicharacter string is changed
{
    "app": 1972,
    "updateKey": {
        "field": "string_code",
        "value": "CODE123"
    },
    "revision": 4,
    "record": {
        "string_multi": {
            "value": "character string is changed"
        }
    }
}

应答

返回更新成功的记录的修订号。

{
    "revision": "5"
}

JavaScript范例

kintone REST API

var body = {
    "app": 1,
    "id": 1001,
    "record": {
        "单行文本框": {
            "value": "ABC"
        }
    }
};

kintone.api(kintone.api.url('/k/v1/record', true), 'PUT', body, function(resp) {
        // success
        console.log(resp);
    }, function(error) {
        // error
        console.log(error);
    }
);

XMLHttpRequest


var url = 'https://{subdomain}.cybozu.cn/k/v1/record.json';
var body = {
    "app": 1,
    "id": 1001,
    "record": {
        "单行文本框": {
            "value": "ABC"
        }
    },
    // CSRF TOKEN: 在kintone上执行API(POST, PUT, DELETE)时需要设置
    "__REQUEST_TOKEN__": kintone.getRequestToken()
};
var xhr = new XMLHttpRequest();
xhr.open('PUT', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onload = function() {
    if (xhr.status === 200) {
        // success
        console.log(JSON.parse(xhr.responseText));
    } else {
        // error
        console.log(JSON.parse(xhr.responseText));
    }
};
xhr.send(JSON.stringify(body));


记录的批量更新

有记录的编辑权限的用户可批量更新多条记录。

  • 一次最多可更新100条记录。

  • 更新方法有指定记录ID和指定【值为唯一】的字段代码及其值两种。

  • 如有必填项,请求中必须包含其值。

  • 批量更新失败时,请求中包含的所有记录的处理都将被取消。

HTTP 方法

PUT

URI

https://(子域名).cybozu.cn/k/v1/records.json

来宾空间内的应用

https://(子域名).cybozu.cn/k/guest/(空间的ID)/v1/records.json 

访问权限

如没有记录的编辑权限,向无编辑权限的字段添加值时,将发生错误。

请求参数

参数名称要指定的值必须说明
app数值或字符串必须指定应用的 ID。
records数组必须指定要更新的记录的信息。
作为参数的值,用数组形式指定对象,对象中须包含记录ID和记录信息的组合。
id数值或字符串可省略
※指定了updateKey时不可指定此项
要更新的记录的编号。 在records数组中指定。
updateKeyObject可省略
※指定了id时不可指定此项
指定值为唯一的字段代码和值。
recordObject可省略

在对象中指定记录的信息(字段代码和字段的值)。 
※字段的值的规格因字段格式的不同而不同。详情请参考字段格式。 
※如省略此项,将不更新数据。

revision数值或字符串可省略修订号。和实际的修订号不一致时报错(不会更新记录)。 

但值为-1时或不指定时,将不检验修订号。

※参数名称的id和updateKey都指定时将报错。

请求正文的构成(※更新n条记录时)

{
    "app": (应用的ID),
    "records": [
        {   // 第1条记录
            "id": (要更新的记录的ID),
            "revision": (要更新的记录的修订号),// 不需要时可不写
            "record": {
                "(字段代码)": {
                    "value": (字段值)
                },
                "(字段代码)": {
                    "value": (字段值)
                }
            }
        },
        {   // 第2条数据
            "id": (要更新的记录的ID),
            "revision": (要更新的记录的修订号),// 不需要时可不写
            "record": {
                "(字段代码)": {
                    "value": (字段值)
                },
                "(字段代码)": {
                    "value": (字段值)
                }
            }
        },
       {   // 第n条数据
            "id": (要更新的记录的ID),
            "revision": (要更新的记录的修订号),// 不需要时可以不写
            "record": {
                "(字段代码)": {
                    "value": (字段值)
                },
                "(字段代码)": {
                    "value": (数组值)
                }
            }
        }
    ]
}

请求的范例

正文

对应用ID为【1972】的应用,更新如下两条记录时

第1条
字段的格式字段代码
要更新的记录的编号
1
要更新的Key字段string_codeCODE123
要更新的记录的修订号
4
单行文本框string_1abcdef
第2条
字段的格式字段代码
要更新的记录的编号
2
要更新的Key字段string_codeCODE456
要更新的记录的修订号
1
多行文本框string_multiopqrstu
// 以记录ID为Key时的请求范例
{
    "app": 1972,
    "records": [
        {
            "id": 1,
            "revision": 4,
            "record": {
                "string_1": {
                    "value": "abcdef"
                }
            }
        },
        {
            "id": 2,
            "revision": 1,
            "record": {
                "string_multi": {
                    "value": "opqrstu"
                }
            }
        }
    ]
}
 
// 以值为唯一的记录为Key时的请求范例
{
    "app": 1972,
    "records": [
        {
            "updateKey": {
                "field": "string_code",
                "value": "CODE123"
            },
            "revision": 4,
            "record": {
                "string_1": {
                    "value": "abcdef"
                }
            }
        },
        {
            "updateKey": {
                "field": "string_code",
                "value": "CODE456"
            },
            "revision": 1,
            "record": {
                "string_multi": {
                    "value": "opqrstu"
                }
            }
        }
    ]
}

应答

返回更新成功的各记录的id和修订号。

{
    "records": [
        {   // 第1条数据
            "id": "1",
            "revision": "5"
        },
        {   // 第2条数据
            "id": "2",
            "revision": "2"
        }
    ]
}

JavaScript范例

kintone REST API

var body = {
    "app": kintone.app.getId(),
    "records": [
        {
            "id": 1001,
            "record": {
                "单行文本框": {
                    "value": "ABC"
                }
            }
        },
        {
            "id": 1002,
            "record": {
                "单行文本框": {
                    "value": "ABC"
                }
            }
        }
    ]
};
kintone.api(kintone.api.url('/k/v1/records', true), 'PUT', body, function(resp) {
        // success
        console.log(resp);
    }, function(error) {
        // error
        console.log(error);
    }
);

XMLHttpRequest



var url = 'https://{subdomain}.cybozu.cn/k/v1/records.json';
var body = {
    "app": 1,
    "records": [
        {
            "id": 1001,
            "record": {
                "单行文本框": {
                    "value": "ABC"
                }
            }
        },
        {
            "id": 1002,
            "record": {
                "单行文本框": {
                    "value": "ABC"
                }
            }
        }
    ],
    // CSRF TOKEN: 在kintone上执行API(POST, PUT, DELETE)时需要设置
    "__REQUEST_TOKEN__": kintone.getRequestToken()
};
var xhr = new XMLHttpRequest();
xhr.open('PUT', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onload = function() {
    if (xhr.status === 200) {
        // success
        console.log(JSON.parse(xhr.responseText));
    } else {
        // error
        console.log(JSON.parse(xhr.responseText));
    }
};
xhr.send(JSON.stringify(body));

注意事项

附件字段的更新和删除

  • 已添加多个附件的情况下,要再添加新的附件时,需要在请求中指定已添加的fileKey。无法更新已添加的附件。

  • 删除文件时,如不将该文件的fileKey传给请求,将删除该文件。

表格的数据更新

未包含在请求的JSON数据中的记录不被更新。但,在表单中设置的【表格】内的数据有以下注意事项。

表格数据的有无数据的保留
更新时不包含表格的数据
  • 保留表格的数据。

更新时包含表格的数据
  • 请求的JSON数据中未包含的表格内的字段值将被删除。

  • 如要保留字段的值,请在请求的JSON数据中指定表格内的字段的值。

  • 使用获取记录的API获取表格的行的【id】,指定该【id】可更新特定的记录和字段。

限制事项

  • 无法更新以下字段的值。


    • 通过Lookup字段输入值的字段

    • 状态

    • 类别

    • 计算

    • 执行者

其他请参考共通规格的限制事项




    您需要登录后才可以回复