kintoneアプリのレコードには、テーブルという複数の行を作成できます。 見積もりや月間タイムカード、訪問記録など、テーブルを利用するシーンは多いです。
このページでは、kintone REST APIを使ったテーブル操作を紹介します。
kintone REST APIを使って、レコード内のテーブルを更新するときには注意点があります。
レコード更新時にテーブルのデータを含まない場合には、テーブルのデータは保持される。
レコード更新時にテーブルのデータを含む場合には、リクエストに含まれないデータは更新されない。
これらの注意点を考慮し、さまざまなケースを紹介します。
準備:アプリとレコードの作成
固定リンクがコピーされました
文字列(1行)と、テーブルを配置したアプリを作成します。
テーブルには、文字列(1行)と数値フィールドを追加します。
フィールドコードはなんでもかまいませんが、わかりやすさのためにフィールド名とフィールドコードを同じ値に設定しました。
アプリを作成したら、レコードを1つ追加してください。
次に、レコードの値を取得しましょう。
レコードの値は、次のJSON形式で取得できます。
1
2
3
4
5
6
{
"フィールドコード": {
"type": "RECORD_NUMBER" , // フィールドタイプ
"value": "1" // フィールドの値
}
}
テーブルフィールドの値は、次の形式で取得できます。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"テーブルのフィールドコード": {
"type": "SUBTABLE" ,
"value": [ // 行のデータ
{
"id": "48290" , // 行のID
"value": {
"フィールドコード": {
"type": "SINGLE_LINE_TEXT" , // テーブル内のフィールドのフィールドタイプ
"value": "TableText1" // テーブル内のフィールドの値
}
}
}
]
}
}
1件のレコードを取得するAPI を使って、先ほど作ったアプリのレコードを取得して、実際のレコードの内容を確認してみましょう。
GET https://sample.cybozu.com/k/v1/record.json?app=2364&id=1
appにはアプリIDを指定し、idにはレコードIDを指定します。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
"record": {
"レコード番号": {
"type": "RECORD_NUMBER" ,
"value": "1"
},
"Title": {
"type": "SINGLE_LINE_TEXT" ,
"value": "Sample"
},
"$revision": {
"type": "__REVISION__" ,
"value": "1"
},
"Table": {
"type": "SUBTABLE" ,
"value": [
{
"id": "48290" ,
"value": {
"Text": {
"type": "SINGLE_LINE_TEXT" ,
"value": "TableText1"
},
"Number": {
"type": "NUMBER" ,
"value": "1"
}
}
},
{
"id": "48291" ,
"value": {
"Text": {
"type": "SINGLE_LINE_TEXT" ,
"value": "TableText2"
},
"Number": {
"type": "NUMBER" ,
"value": "2"
}
}
}
]
},
"作成日時": {
"type": "CREATED_TIME" ,
"value": "2014-03-26T15:27:00Z"
},
・・・
}
}
では、
1件のレコードを更新するAPI を使って、テーブルフィールドを更新してみましょう。
テーブルの最後に値を追加する
固定リンクがコピーされました
行を追加する場合、既存の行のIDをリクエストに含める必要があります。
行の各フィールドの値を更新しない場合は、既存の行の値を省略できます。
"app":更新するアプリのアプリID
"id":更新するレコードID
"Table" "value" 内の配列に含まれる "id":既存の行のID
"Table" "value" 内の配列に含まれる "value":追加する行の値
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
"app": 2364 ,
"id": 1 ,
"record": {
"Table": {
"value": [
{
"id": "48290"
},
{
"id": "48291"
},
{
"value": {
"Text": {
"value": "追加するテキスト"
},
"Number": {
"value": "3"
}
}
}
]
}
}
}
既存の行のIDを省略し、すでにテーブルにあった行の値をすべてリクエストに含めると、テーブルに値の追加ができます。
実際の挙動は「既存の行をすべて削除し、リクエストに含まれるデータをテーブルへ追加する」となります。
"app":更新するアプリのアプリID
"id":更新するレコードID
"Table" "value" 内の配列に含まれる "value":既存の行の値+追加する行の値
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
"app": 2364 ,
"id": 1 ,
"record": {
"Table": {
"value": [
{
"value": {
"Text": {
"value": "TableText1"
},
"Number": {
"value": "1"
}
}
},
{
"value": {
"Text": {
"value": "TableText2"
},
"Number": {
"value": "2"
}
}
},
{
"value": {
"Text": {
"value": "追加するテキスト"
},
"Number": {
"value": "3"
}
}
}
]
}
}
}
実行後の画面
テーブルの1行目に挿入する
固定リンクがコピーされました
挿入の場合にも、テーブルの行追加と同様の処理になります。テーブルに表示したい順番でリクエストします。
"app":更新するアプリのアプリID
"id":更新するレコードID
"Table" "value" 内の配列に含まれる "id":既存の行のID
"Table" "value" 内の配列に含まれる "value":追加する行の値
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
"app": 2364 ,
"id": 1 ,
"record": {
"Table": {
"value": [
{
"value": {
"Text": {
"value": "TableText1"
},
"Number": {
"value": "1"
}
}
},
{
"value": {
"Text": {
"value": "TableText2"
},
"Number": {
"value": "2"
}
}
},
{
"value": {
"Text": {
"value": "追加するテキスト"
},
"Number": {
"value": "3"
}
}
}
]
}
}
}
こちらも行追加と同様に、既存行のIDを省略してテーブルに含めたい値をすべて含めることでもテーブルの更新が可能です。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
"app": 2364 ,
"id": 1 ,
"record": {
"Table": {
"value": [
{
"value": {
"Text": {
"value": "1行目に挿入する"
},
"Number": {
"value": "0"
}
}
},
{
"value": {
"Text": {
"value": "TableText1"
},
"Number": {
"value": "1"
}
}
},
{
"value": {
"Text": {
"value": "TableText2"
},
"Number": {
"value": "2"
}
}
}
]
}
}
}
実行後の画面
テーブルの1行の特定のフィールドのみを更新する
固定リンクがコピーされました
更新する行のIDを指定することで、その行の特定のフィールドのみを更新できます。
同じ行の他のフィールドを更新しない場合にはそのフィールドを省くことができます。
既存の行のIDを省略した場合、対象行は削除されます。
"app":更新するアプリのアプリID
"id":更新するレコードID
"Table"内の"id":更新する行ID
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
"app": 2364 ,
"id": 1 ,
"record": {
"Table": {
"value": [
{
"id": "48300" ,
"value": {
"Text": {
"value": "特定のフィールドのみを更新する"
}
}
},
{
"id": "48301" ,
"value": {
"Number": {
"value": "200"
}
}
}
]
}
}
}
実行後の画面
赤枠の部分のみが更新されています。
注意事項
存在しない行IDを指定した場合、エラーは出ず、新規追加として扱われます。
その際、テーブルに存在するがAPIで指定していない既存の行IDは削除されます。
補足)テーブルの内容をすべて削除する
Tableオブジェクト内のvalue配列を空にして指定し、更新することで削除できます。
"app":更新するアプリのアプリID
"id":更新するレコードID
1
2
3
4
5
6
7
8
9
{
"app": 2364 ,
"id": 1 ,
"record": {
"Table": {
"value": []
}
}
}
このようにテーブル更新のテクニックを理解するだけで、さまざまな利用シーンに活用できるかと思います。
ぜひ、お試しください。