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

（著者：サイボウズ 後迫 孝）

kintone アプリのレコードには、テーブルという複数の行を作成できます。 見積もりや月間タイムカード、訪問記録など、テーブルを利用するシーンは多いです。
このページでは、kintone REST APIを使ったテーブル操作を紹介します。

kintone REST APIを使って、レコード内のテーブルを更新するときには注意点があります。

• レコード更新時にテーブルのデータを含まない場合には、テーブルのデータは保持される
• レコード更新時にテーブルのデータを含む場合には、リクエストに含まれないデータは更新されない

これらの注意点を考慮し、さまざまなケースを紹介します。

まず、レコードを用意しましょう

事前に次のようにレコードのテキストとテーブルの2行を作成しておきましょう。
kintone APIはフィールドコードを使うため、今回は便宜上、フィールド名とフィールドコードは同じ名称にしておきます。

レコードの値を取得しましょう

レコードの値は、次のJSON形式で取得できます。

{
  "フィールドコード": {
    "type": "RECORD_NUMBER", // フィールドタイプ
    "value": "1" // フィールドの値
  }
}

テーブルフィールドの値は、次の形式で取得できます。

{
  "テーブルのフィールドコード": {
    "type": "SUBTABLE",
    "value": [ // 行のデータ
      {
        "id": "48290", // 行の ID
        "value": {
          "フィールドコード": {
            "type": "SINGLE_LINE_TEXT", // テーブル内のフィールドのフィールドタイプ
            "value": "TableText1" // テーブル内のフィールドの値
          }
        }
     }
    ]
  }
}

1 件のレコードを取得する API を使って、先ほど作ったアプリのレコードを取得して、実際のレコードの内容を確認してみましょう。
 GET https://{subdomain}.cybozu.com/k/v1/record.json?app=2364&id=1
app にはアプリ ID、id にはレコード ID を指定します。

レコードのテーブルを更新しましょう

では、1件のレコードを更新する API を使って、テーブルフィールドを更新してみましょう。

テーブルの最後に値を追加する

行を追加する場合、既存の行のIDをリクエストに含める必要があります。
※ 行の各フィールド の値を更新しない場合は、既存の行の値を省略することができます。

• "app" ・・・更新するアプリのアプリID
• "id" ・・・更新するレコードID
• "Table" "value" 内の配列に含まれる "id"・・・既存の行のID
• "Table" "value" 内の配列に含まれる "value"・・・追加する行の値

既存の行のIDを省略し、既にテーブルにあった行の値をすべてリクエストに含めることで
テーブルへ値の追加を行うこともできます。
※ 実際の挙動としては「既存の行をすべて削除し、リクエストに含まれるデータをテーブルに追加する」というものになります。

• "app" ・・・更新するアプリのアプリID
• "id" ・・・更新するレコードID
• "Table" "value" 内の配列に含まれる "value"・・・既存の行の値＋追加する行の値

実行後の画面

テーブルの1行目に挿入する

挿入の場合にも、テーブルの行追加と同様の処理になります。テーブルに表示したい順番でリクエストします。

• "app" ・・・更新するアプリのアプリID
• "id" ・・・更新するレコードID
• "Table" "value" 内の配列に含まれる "id"・・・既存の行のID
• "Table" "value" 内の配列に含まれる "value"・・・追加する行の値

こちらも行追加と同様に、既存行のIDを省略してテーブルに含めたい値をすべて含めることでもテーブルの更新が可能です。

実行後の画面

テーブルの1行の特定のフィールドのみを更新する

更新する行のIDを指定することで、その行の特定のフィールドのみを更新できます。
同じ行の他のフィールドを更新しない場合にはそのフィールドを省くことができます。
※ 既存の行のIDを省略した場合、対象行は削除されます。

• "app" ・・・更新するアプリのアプリID
• "id" ・・・更新するレコードID
• "Table"内の"id" ・・・更新する行ID

実行後の画面

赤枠の部分のみが更新されています。

注意事項

存在しない行IDを指定した場合、エラーは出ず、新規追加として扱われます。
その際、テーブルに存在するが API で指定していない既存の行IDは削除されます。

補足）テーブルの内容をすべて削除する

Table オブジェクト内の value 配列を空にして指定し、更新することで削除できます。

• "app" ・・・更新するアプリのアプリID
• "id" ・・・更新するレコードID

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

このTipsは、2014年4月版で確認したものになります。