kintone REST APIの新機能として、複数のレコードを更新するAPIに「UPSERT」モードが追加されました。

• 2025年1月12日kintone APIアップデート情報
• 複数のレコードを更新する

UPSERTとは「指定したレコードが存在する場合は更新し、存在しない場合に新規作成する処理」を1回のAPI呼び出しで実行できる機能です。
この機能により、レコードの更新処理がより効率的に行えるようになりました。

従来のレコード更新処理では、更新対象のレコードが存在するかどうかを確認してから、存在する場合は更新、存在しない場合に新規作成という2段階の処理が必要でした。
特にアプリの登録レコード件数が多いと、APIリクエスト数の増加や、処理時間の増加につながります。

UPSERTモードを使用することで、次の3つのメリットが得られます。

• APIリクエスト数の削減
• 処理時間の短縮
• コードの簡素化

UPSERTモードは、外部システムのデータを定期的にkintoneアプリに同期するようなケースで特に効果を発揮します。
具体的には、次の2つのケースが考えられます。

• 外部の顧客管理システムの情報をkintoneの顧客管理マスターアプリに反映する。
• 基幹システムの商品マスターをkintoneの商品マスターアプリに同期する。

それでは、実際にUPSERTを使ったレコードの登録と更新をしていきます。

このサンプルでは、次のフィールドをもつアプリを想定します。

また、次の値をもつレコードを作成します。

UPSERTを使って、登録した顧客コード「CUSTOMER-001」のデータを更新し、新たに顧客コード「CUSTOMER-002」のデータを追加していきます。

複数のレコードを更新するAPIを実行します。
ここでは、curlを使用した例を示します。
API_TOKENおよびappの値は適宜置き換えてください。

 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

curl -X PUT 'https://sample.cybozu.com/k/v1/records.json' \
  -H 'X-Cybozu-API-Token: API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "app": 1,
    "upsert": true,
    "records": [
      {
        "updateKey": {
          "field": "code",
          "value": "CUSTOMER-001"
        },
        "record": {
          "name": {
            "value": "顧客A変更"
          },
          "age": {
            "value": 40
          }
        }
      },
      {
        "updateKey": {
          "field": "code",
          "value": "CUSTOMER-002"
        },
        "record": {
          "name": {
            "value": "顧客B"
          },
          "age": {
            "value": 25
          }
        }
      }
    ]
  }'

レスポンスは以下のようになります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "records": [
    {
      "id": "1",
      "revision": "2",
      "operation": "UPDATE"
    },
    {
      "id": "2",
      "revision": "1",
      "operation": "INSERT"
    }
  ]
}

リクエストパラメーターに"upsert": trueを指定することで、UPSERTモードで実行できます。
それ以外のパラメーターは従来どおり指定します。

なお、複数のレコードを更新するAPIにおいて、更新するレコードを指定するためのパラメーターはidを使用する方式と、updateKeyを使用する方式があります。
今回のサンプルではupdateKeyを使用しています。
詳細は 複数のレコードを更新する | リクエスト を参照してください。

また、レスポンスに含まれるoperationプロパティはINSERTまたはUPDATEの値を取ります。
この値により、レコードが更新されたか新規作成されたかを確認できます。

UPSERTモードの導入により、kintoneアプリとの外部システム連携がより効率的になりました。
特に大量のデータを扱う場合や、定期的なデータ同期が必要な場合に、この機能を活用することで開発効率と実行効率の両方を向上させることができます。

また、コードがシンプルになることで保守性も向上し、エラーの発生リスクも低減できます。外部システムとのデータ連携を検討している場合は、ぜひUPSERTモードの使用を検討してみてください。

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