レコード更新におけるテーブル操作のテクニック

著者名:後迫 孝(サイボウズ株式会社)

目次

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": []
        }
    }
}

このようにテーブル更新のテクニックを理解するだけで、さまざまな利用シーンに活用できるかと思います。
ぜひ、お試しください。

information

この Tips は、2014 年 4 月版 kintone で動作を確認しています。