Index
レコードの更新(1件)
- 1件のレコードを更新できます。
- レコードIDを指定する方式と重複禁止フィールドコードと値を指定する方式があります。
HTTP メソッド
PUT
URI
https://(サブドメイン名).cybozu.com/k/v1/record.json
ゲストスペース内のアプリの場合
https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/record.json
必要なアクセス権
- アプリのレコード編集権限
- 値を更新するレコードの編集権限
- 値を更新するフィールドの編集権限
リクエストパラメータ
パラメータ名 | 指定する値 | 必須 | 説明 |
---|---|---|---|
app | 数値又は文字列 | 必須 | アプリのID を指定します。 |
id | 数値又は文字列 | 条件付き必須 |
レコードID を指定します。 ※updateKeyを指定する際には指定不可。 |
updateKey | Object | 条件付き必須 |
重複禁止フィールドコードと値を指定します。 ※idを指定する際には指定不可。 |
record | Object | 省略可 | レコードの情報(フィールドコードとフィールドの値)をオブジェクトで指定します。 ※フィールド値の仕様についてはフィールドの形式により異なります。 詳細については フィールド形式をご確認ください。 ※省略した場合は、データは更新されません。 |
revision | 数値又は文字列 | 省略可 | 期待しているリビジョン番号。 実際のリビジョン番号と一致しない場合はエラーとなります(レコードは更新しない)。 ただし、値が-1あるいは指定しなかった場合はリビジョン番号の検証を行いません。 |
リクエストボディの構造(レコードIDを指定する)
リクエストボディの構造(重複禁止のフィールドコードと値を指定する)
リクエストの例
リクエストヘッダ
PUT /k/v1/record.json HTTP/1.1 Host: example.cybozu.com:443 X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU= Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU= Content-Type: application/json
- Content-Type に application/json を指定して下さい。 指定しない場合は JSON が解釈できないため、実行時エラーとなります。
ボディ(レコードIDを指定する)
アプリID「1972」のアプリ対して以下のレコード更新をする場合
フィールドの形式 | フィールドコード | 値 |
---|---|---|
更新するレコードの番号 | 1 | |
更新するレコードのリビジョン | 4 | |
文字列(複数行) | string_multi | character string is changed |
ボディ(重複禁止のフィールドコードと値を指定する)
アプリID「1972」のアプリ対して以下のレコード更新をする場合
フィールドの形式 | フィールドコード | 値 |
---|---|---|
キーにするフィールドコードと値 | string_code | CODE123 |
更新するレコードのリビジョン | 4 | |
文字列(複数行) | string_multi | character string is changed |
レスポンス
更新したレコードのリビジョンが返されます。
JavaScriptサンプル
kintone REST APIリクエストを送信する API を使ったリクエスト
XMLHttpRequest を使ったリクエスト
レコードの一括更新
レコードの編集権限のあるユーザーが、複数のレコードを一括で更新できます。
- 一度に更新できるレコードは 100 件までです。
- レコード更新には、レコードIDを指定する方式と重複禁止フィールドコードと値を指定する方式があります。
- 一括更新に失敗すると、リクエストに含まれるレコードの処理はすべてキャンセルされます。
HTTP メソッド
PUT
URI
https://(サブドメイン名).cybozu.com/k/v1/records.json
ゲストスペース内のアプリの場合
https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/records.json
必要なアクセス権
- アプリのレコード編集権限
- 値を更新するレコードの編集権限
- 値を更新するフィールドの編集権限
リクエストパラメータ
※パラメータ名 idとupdateKeyのどちらかを指定する必要があります。両方を指定すると、エラーになります。
パラメータ名 | 指定する値 | 必須 | 説明 |
---|---|---|---|
app | 数値又は文字列 | 必須 | アプリの ID を指定します。 |
records | 配列 | 必須 | 更新するレコードの情報を指定します。 本パラメータの値は、更新したいレコードIDと更新したいレコード情報をセットにしたオブジェクトを配列で記述します。 |
records.id | 数値又は文字列 | 省略可 ※updateKeyを指定する際には指定不可 |
更新するレコードの番号。 records 配列内に記述します。 |
records.updateKey | Object | 省略可 ※idを指定する際には指定不可 |
重複禁止フィールドコードと値を指定します。 指定できるフィールドは重複を禁止が設定された文字列(1行)と数値のみです。 |
records.record | Object | 省略可 | レコードの情報(フィールドコードとフィールドの値)をオブジェクトで指定します。 ※フィールド値の仕様についてはフィールドの形式により異なります。 詳細については フィールド形式をご確認ください。 ※省略した場合は、データは更新されません。 |
records.revision | 数値又は文字列 | 省略可 | 期待しているリビジョン番号。 実際のリビジョン番号と一致しない場合はエラーとなります(いずれのレコードも更新しない)。 ただし、値が-1あるいは指定しなかった場合はリビジョン番号の検証を行いません。 |
リクエストボディの構造(※n件のレコードを更新する場合)
リクエストの例
ボディ
アプリID「1972」のアプリに対し、以下の2件のレコード更新をする場合
1件目
フィールドの形式 | フィールドコード | 値 |
---|---|---|
更新するレコードの番号 | 1 | |
更新対象のキーフィールド | string_code | CODE123 |
更新するレコードのリビジョン | 4 | |
文字列(1行) | string_1 | abcdef |
2件目
フィールドの形式 | フィールドコード | 値 |
---|---|---|
更新するレコードの番号 | 2 | |
更新対象のキーフィールド | string_code | CODE456 |
更新するレコードのリビジョン | 1 | |
文字列(複数行) | string_multi | opqrstu |
レコードIDをキーにしたリクエスト例
重複禁止フィールドをキーにしたリクエスト例
レスポンス
レコードごとに更新したレコードのidとリビジョンが返されます。
JavaScriptサンプル
kintone REST APIリクエストを送信する API を使ったリクエスト
XMLHttpRequest を使ったリクエスト
注意事項
添付ファイルフィールドの更新と削除
- 複数ファイルを添付している状態で、新たにファイルを追加する場合には、登録済みのfileKeyをリクエストに含める必要があります。 すでに添付しているファイルを更新することはできません。
- ファイルを削除する場合には、そのファイルのfileKeyをリクエストに渡さなければそのファイルは削除されます。
テーブルのデータ更新
リクエストのJSONデータに記述しないフィールドは更新されません。ただし、フォームに設定した「テーブル」内のデータは、次の注意点があります。
テーブルデータの有無 | データの保持 |
---|---|
更新時にテーブルのデータを含まない |
|
更新時にテーブルのデータを含む |
|
制限事項
- 次のフィールドは、値を更新できません。
- ルックアップ元からコピーされるフィールド
- ステータス
- カテゴリー
- 計算
- 作業者
- 作成者
- 作成日時
- 更新者
- 更新日時
- 自動計算が設定されている文字列(1行)フィールド
その他につきましては、共通仕様の制限事項 をご確認ください。
関連Tips
- レコード更新におけるテーブル操作のテクニック
- 安全に在庫管理を行うテクニック
- レコードに値がなかったら登録、あったら更新するUPSERT
- 後で追加した計算フィールドに一括で値を反映する方法
- CSRFトークン利用時の注意点
サブテーブルの更新をJavascriptで実装している際に気が付きましたが、
サブテーブルの更新部分の記載に誤りがあるように思います。
(誤)
(正)
テーブルのフィールドコードのvalueに対応するものはオブジェクトではなく配列かと思います。
Hiroyuki Nakamuraさん
cybozu.com developer network事務局です。
リクエストボディのサブテーブルの記載内容を修正致しました。
ご指摘いただきありがとうございました。
テーブルのデータ更新で質問です。
「•リクエストのJSONデータに記述しないテーブル内のフィールド値は削除されます。」
とありますが、複数あるテーブル行のうち、1行だけ書き換えたて、ほかのテーブル行は残したい場合、
他のテーブル行は「テーブル行の『id』」だけを記入しておけば、現在のkintoneでは消えないようなのですが、
これは将来のバージョンアップも含めて消えることはないのでしょうか?
よろしくお願いいたします。
吉村啓治郎さん
ご質問いただきありがとうございます。
cybozu developer network運営事務局です。
複数あるテーブル行のうち1行だけ書き換えたい場合は、
吉村さんのおっしゃる通りテーブルのidを指定することで実現できます。
APIにつきましては、APIを利用して開発されたアプリなどに影響を与えないよう、
原則として機能の追加のみを行います。
ただし、次のような場合は API の仕様を変更することがありますので、その点はご了承ください。
・データ破壊やセキュリティ障害などの原因を除去するなど運用上、仕様の変更が必要な場合
・cybozu及び その各サービスの改修により派生的に変更が必要な場合
なお、API の仕様変更を伴うアップデートがある場合、それが適用される定期アップデートの 4 週間前までに、
変更の詳細を以下のサイトで公開致します。
サイトのお知らせ(http://developers.cybozu.com/ja/category/news/)
▼参考リンク
https://cybozudev.zendesk.com/hc/ja/articles/201793494
いつもお世話になっております。
レコードの一括更新の章に
「必須項目が設定されている場合には、その値をリクエストに含めてください。」
と記載がございますが、こちらは誤りではないでしょうか。
PUTの時は更新する項目のみを指定する認識でおります。
細かい点で恐縮でございますが、ご確認よろしくお願いいたします。
みなとん様
ご指摘をありがとうございます。
当方の環境でも確認し、該当の記述を削除いたしました。
POSTの記述と混同した可能性があり、大変申し訳ございませんでした。
今後ともどうぞよろしくお願いいたします。
お世話になっております。
以下ご確認いただけるでしょうか。
PUTのupdateKeyは日付は使えないのでしょうか。マニュアルには指定する値にObjectとありますが、下記のエラーが出ます。
{
"code": "GAIA_IN06",
"id": "1505999166-127152590",
"message": "レコードの更新に失敗しました。「updateKey」に指定したフィールド(code: DeliverDate)が不正です。「updateKey」には、文字列(1行)フィールドか数値フィールドのみ指定できます。また、フィールドの設定で、値の重複を禁止する必要があります。"
}
よろしくお願いします。
hana 様
ご連絡をありがとうございます。cybozu Development teamでございます。
仕様を確認したところ、2016年5月版より、updateKeyに指定できるフィールドは重複を禁止が設定された文字列(1行)と数値のみとなっており、日付フィールドについては遅くともそのタイミングから対象外となっております。
ドキュメントに記載がなかったため、リクエストパラメーター欄の説明欄に追記させていただきました。記載がなかった点について、申し訳ございませんでした。
どうぞよろしくお願いいたします。
お世話になっております。Javascript始めたてです。
上記の「レコードの更新(1件)」XMLHttpRequest
のコードを利用して処理をしているのですが、
code:"CB_VA01"
errors:Object
id:"vENH5GSOKnZozs2DsrK8"
message:"入力内容が正しくありません。
のエラーが出て正しく動作しません。
恐らくbody部分の必須項目の記入が抜けているのかもしれませんが、原因がわかりません。
実際のコードになります。
var body = {
"app": 85, (更新先アプリID)
"id": 30, (更新先レコードID)
"record": {
"last_lead_contents": { (更新先フィールド)
"value": "ABC"
}
},
// CSRF TOKEN: kintone上からAPI(POST, PUT, DELETE)を実行する場合に設定する必要あり
"__REQUEST_TOKEN__": kintone.getRequestToken()
};
更新先フィールドはすべて記述すべきなのでしょうか。
すみません。自己解決しました。ご迷惑をお掛けしました。
いつもお世話になっております。
外部システムと連携する際に、上記の「リクエストボディの構造(重複禁止のフィールドコードと値を指定する)」を参考にし、
レコードの更新をするJSONを書いているのですが、試してもkintoneのレコードの更新がされず、レコードの新規追加がされてしまいます。
======================
【実装しているJSON】
{
"app": (アプリのID),
"updateKey": {
"field": "(重複禁止のフィールドコード)",
"value": "(値)"
},
"record": {
"(フィールドコード)": {
"value": {{外部システムトークン}}
}
}
}
======================
kintone側では、updateKeyに指定するフィールドコードは、数値型で値の重複を禁止にし、
紐づける外部システムと同じ値を入れ混んでおります。
なぜ、更新ではなく新規追加になってしまうのか原因がわかりません。
更新する際は上記の設定以外に何か必要となるのでしょうか。
ご教授頂けますと幸いです。
何卒、よろしくお願い致します。
佐々木 様
ご質問ありがとうございます。
cybozu Development teamでございます。
JSONは特に問題がなさそうですね。
updateKeyのvalueに指定した値は、kintoneに存在しているものでしょうか?
存在しないvalueを指定すると新規登録されます。
"updateKey": {
"field": "(重複禁止のフィールドコード)",
"value": "(値)"
ご確認お願いします。
ご回答いただき、有難うございます。
JSONは問題ないとのこと、安心しました。
ご教授頂いた通り、updateKeyのvalueはkintoneに入れているのですが、
やはり新規レコードが追加されてしまいます。
もう一度よく設定を見直したてみたいと思います。
ありがとうございます。
いつもお世話になっております。
updateKeyに関しまして、重複禁止のフィールドコードを設けているのですが、
値を指定しないで、変数のような形でそれぞれの値によって対象のレコードの情報を更新したく思っております。
そのようなことは可能なのでしょうか。
初歩的な質問で申し訳ございません。
何卒よろしくお願い致します。
佐々木 様
お世話になっております。cybozu developer network事務局でございます。
updateKeyのvalueに変数を使いたいということでしたら、下記のような形で記載が可能です。
恐れ入りますが、こちらは記事のフィードバック欄です。
APIの使い方等の技術的なご質問につきましては、コミュニティをご活用いただけますと幸いです。
お世話になっております。
PUTリクエストで更新したいものだけをrecordにいれリクエストを投げて更新されたことを確認したのですが、
ラジオボタンがデフォルト値で上書きされるようでした。
こちらラジオボタンは変更点がないことからrecordに含めず実行したのですが、リクエストパラメータに入れなくても空だと判断されデフォルト値で上書きされるのでしょうか?
注意事項やラジオボタン詳細を調べても分からずで教えて頂けると助かりますmm
あだち 様
cybozu developer network運営事務局です。
基本的には、指定していないフィールドに対してはPUTリクエストでは書き換えません。
しかしながら、ラジオボタンでは下記の手順により指定していなくてもデフォルト値とされるケースはあります。
1. 既存のアプリに対し、設定からラジオボタンのフォームを追加する
2. 既存のレコードにおいてはこのとき、1で追加したラジオボタンには値が入っていない状態となる
3. PUTリクエストや画面上から既存のレコードを書き換える
4. 3によってラジオボタンに自動的に値が入る
ラジオボタンは選択項目の内どれかが選ばれる仕様のためこのようになっております。
他にも同様に、計算フィールドなど、保存する状況によっては指定していないフィールドが一部書き換えられることがあります。
回答ありがとうございます。
再度質問で申し訳ないです。
サブテーブル内のラジオボタンのみデフォルト値で上書きされるような動きをこちらで確認しております。
【質問】サブテーブルの一部だけ書き換える際にラジオボタンのパラメータは送っていないのですが、サブテーブル仕様で全部更新される動きをし、送っていないので空判定でデフォルト値になるみたいな動きをしますでしょうか?
サブテーブル特有の何かなのか知りたいです。
よろしくお願いいたしますmm
あだち 様
cybozu developer network運営事務局です。
> 【質問】サブテーブルの一部だけ書き換える際にラジオボタンのパラメータは送っていないのですが、サブテーブル仕様で全部更新される動きをし、送っていないので空判定でデフォルト値になるみたいな動きをしますでしょうか?
パラメータの指定の内容によっては起こり得うるかと思います。
テーブルに対しレコード更新APIを使う際、各行のidを指定しなければ新しいデータと見做しますので、その際にデフォルト値が反映されてしまったものだと考えられます。
レコード更新におけるテーブル操作のテクニックで説明があるように、テーブルに対しレコード更新APIを利用する際には、各行のidを指定することで、任意の部分のみ変更することは可能ですので、一度お試しください。
なるほど、idを指定していなかったせいでdeleteinsertしているという状態ということですね。
現状理解できました。ありがとうございます。
お世話になっております。
一覧画面で、2件目までの更新例を展示して頂き、ありがとうございます。
n件がある複数件の一括更新は、for の回すloop言語で、更新可能でしょうか。
ou 様
お世話になっております。cybozu developer network 運営でございます。
はい、一括更新の上限である100件以上を一括更新をしたい場合は、リクエストをわけて繰り返していただくイメージです。
REST APIの制限事項についてはこちらを御覧ください。
https://developer.cybozu.io/hc/ja/articles/201941754#step12
また、恐れ入りますが、こちらのコメント欄は記事内容のフィードバック目的となっているため、
試してみてわからない場合などの技術的なご質問があればcybozu developer コミュニティをご活用ください。
よろしくお願い致します。
いつもお世話になります。
REST APIのPUTのことでお聞きしたいことがあります。
GETで取得した日付型のデータはPUTできないのでしょうか?
PUTする前のJSONファイルを見るとしっかりデータは入っているのにされておらず、解決方法がわからないためお聞きしました。
お願いいたします。
tech2 様
お世話になっております。cybozu developer network 運営でございます。
> GETで取得した日付型のデータはPUTできないのでしょうか?
仕様としては可能です。
プログラムを書いていればプログラムの問題や、権限などの問題も可能性としてはあるかもしれません。
恐れ入りますが、詳細をいただけておらず原因までは存じかねますが、
こちらのコメント欄は記事内容のフィードバック目的となっているため、
cybozu developer コミュニティをご活用ください。
その際詳しい再現条件などを示してくださると、より解答をもらいやすいかと存じます。
よろしくお願い致します。
cybozu Development team 様
ご返信ありがとうございます。
昨日、違うJavascriptを組んだ際もう一度確認したら、GETもPUTもできるようになっておりましたのと、そのファイルはできないものだと削除してしまったため単純に私のミスかも判断ができませんでした。申し訳ございません。
次から同じことになった際はコミュニティの方で質問させていただきます。