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": []
}
}
}
|
このようにテーブル更新のテクニックを理解するだけで、さまざまな利用シーンに活用できるかと思います。
ぜひ、お試しください。