本記事の公開以降、kintone API で正式に「UPSERT モード」の提供が開始され、CData Arc 2025 のKintone コネクタでも「UPSERT モード」がサポートされました。本記事にご関心いただいた方は、ぜひこちらの記事をご確認いただき、CData Arc のKintone コネクタをお試しください。
こんにちは。CData Software Japan の色川です。
ある仕組みから別の仕組みへデータ連携をする場合に、既に同じkey を持つデータが存在していれば更新（Update）を。存在していなければ登録（Insert）をしたいケースはとても多いと思います。いわゆる「Upsert したいケース」です。
少し前に、kintone でもついに「複数のレコードを更新する API」で「UPSERT モード」が利用できるようになったとアナウンスがありました。この記事の時点（2024/12/20）では「API ラボ」で「開発中の機能」ですが、今週には正式リリース予定もアナウンスがありましたね。正式リリースが待ち遠しいです。
この記事では、CData Arc を利用して「kintone のUPSERT モード（開発中の機能）での連携」を試してみます。
この記事は、CData Software Advent Calendar 2024（シリーズ 1）20日目の記事です。
kintone のUPSERT モード（開発中の機能）
kintone で提供されている「複数のレコードを更新するAPI」で「UPSERTモード」が利用できるようになりました。API の仕様については、こちらをごらんください。なお、この記事の時点では「開発中の機能」です。
なお、Upsert をサポートするAPI が提供されているデータソースはまだまだ一部に限られており、Arc ではそれを疑似的に実現できるUpsert アクションを提供しています。このUpsert アクションは「連携対象のレコードが既に存在するかを確認するためにSelect して、その結果をもとにInsert するかUpdate するかを自動的に判別・実行できる」利便性の高い強力な機能ですが、その仕組み上、1レコードずつAPI リクエストが発生することは避けられず、一定規模のデータを連携したい場合には検討すべきポイントも出てきます。そのため、kintone API 自体でのUpsert サポートはArc としても大変楽しみなニュースです。
この記事のシナリオ
この記事では、おなじみの「顧客リスト」アプリを連携先として「複数のレコードを更新するAPI」の「UPSERTモード」を試していきます。
この記事では、このようなデータ連携フローを作成していきます。
事前準備
kintone が提供する「複数のレコードを更新する API」の「UPSERT モード」は、この記事の時点では「開発中の機能」です。kintone の「システム管理」「アップデートオプションの設定」で、この機能を有効化しました。
kintone アプリでの準備
実際にUpsert で連携したいユースケースでは、kintone のRecord Id をkey とできるケースは少ない（kintone 以外のデータソース側でkey としている項目をUpsert 判断のkey としたい）と思います。この記事では、そのイメージで「顧客リスト」の「メールアドレス」をUpdate 判断のkey（updateKey）として利用します。updateKey として指定できるフィールドは「重複禁止を設定した「文字列（1行）」または「数値」フィールドに限られます」ので、この記事では「メールアドレス」フィールドを「重複禁止」にしました。
API 連携での認証は、API トークンを利用します。
API リクエストではアプリID の指定が必要になりますので、確認しておきます。
API リクエスト（JSON）用のテンプレート
この記事では、Arc のREST コネクタを利用して、kintone のREST API をリクエストします。そのためAPI リクエストのリクエストボディを構成するためのJSON テンプレートを、kintone API の仕様に従って事前に用意しています。この記事では「メールアドレスをupdateKey」「会社名をUpsert 対象のフィールド」にして試してみます。この記事では、example.json として用意しました。
連携元とするデータソース（CSV ファイル）
この記事では、以下のようなCSV ファイルをUpsert の連携元データソースとして試してみます。この記事では、にexample.csv として用意しました。
kintone のUPSERT モード（開発中の機能）を利用した連携フロー
それでは実際に連携フローを作成していきます。
File コネクタ
最初にファイルシステムからCSV ファイルを取得するためのFile コネクタを構成します。「パス」と「ファイルマスク」を設定します。
CSV コネクタ
次に取得したCSV ファイルをArc のフローで扱うためにXML 形式に変換するCSV コネクタを構成します。「カラムヘッダーが存在します」を有効にします。
XML Map コネクタでマッピングする時に必要なスキーマファイルを「テストファイルをアップロード」を利用して、example.csv から自動生成しておきます。
JSON コネクタ
次にXML Map コネクタでマッピングした後のデータ（XML 形式）を、kintone API へのリクエストボディとして利用するJSON 形式に変換するJSON コネクタを構成します。
XML Map コネクタでマッピングする時に必要なスキーマファイルを「テストファイルをアップロード」を利用して、example.json から自動生成しておきます。
XML Map コネクタ
次にXML Map コネクタを構成して、CSV コネクタで変換した連携元データを、JSON コネクタで生成したスキーマファイルの形式にマッピングします。
「テスト」機能でマッピングをテストしてみます。期待通りのマッピングになっていることが確認できました。
REST コネクタ
最後にkintone の「複数のレコードを更新する API」へ「UPSERT モード」でリクエストするREST コネクタを構成します。この記事ではAPI レスポンスを確認するためにアクションを「Transform」で構成しました。API 仕様に沿うように「メソッド」「URL」およびAPI トークン認証に必要なリクエストヘッダ（X-Cybozu-API-Token）を「ヘッダ」に指定します。
これでkintone のUPSERT モード（開発中の機能）を利用した連携フローが完成しました。
連携フローの実行
トリガー開始の「手動で受信」から実行します。
期待通りにREST コネクタは成功しています。
REST コネクタのインプットタブで、kintone へのAPI リクエスト内容を確認します。
REST コネクタのアウトプットタブで、kintone からのAPI レスポンスも確認しておきます。UPSERT モードでリクエストしたときに「新たに追加される項目」も確認できました。
「顧客リスト」アプリのデータが期待通りにUpsert されています。
まとめ
この記事では、kintone の「複数のレコードを更新するAPI」で新たに提供された「UPSERTモード」を試してみました。この記事の時点では「開発中の機能」です。UPSERT モードの正式リリースが待ち遠しいですね。kintoneの改善に協力できるように、試してみた感想をフィードバックしました。
この記事で作成したフローでは、Arc のREST コネクタの分かりやすい設定と豊富な機能、CSV コネクタやJSON コネクタのテストファイル機能でのマッピングテンプレート自動生成など、Arc を利用すれば任意のREST API への連携フローも効率よく作成いただけるのがご紹介できたかと思います。
ただ、REST コネクタを利用した連携では、今回の記事のように連携先のAPI 仕様を直接的に意識・理解する必要があり、リクエスト形式にあわせて事前にリクエストフォーマットにフィットするテンプレートを準備する必要もあります。API エンドポイントへの設定もAPI 仕様を利用して適切に設定する必要があり、難易度は高めと言えるかも知れません。これらの多くの部分はCData Drivers を利用すればDriver への分かりやすい設定で実現できることですので、この記事では図らずも「CData Drivers の便利さ」も感じて頂けたかも知れません。
UPSERT モードが正式にリリースされた後は、CData Drivers でも一早くそれに対応したアップデートをお届けできると思います。もちろんDrivers を内部的に利用しているArc のkintone コネクタでもそれに続いて利用できるようになる見込みです。ぜひご期待ください。
CData Arc はシンプルで拡張性の高いコアフレームワークに、豊富なMFT・EDI・エンタープライズコネクタを備えたパワフルな製品です。CData Drivers との組み合わせで270を超えるアプリケーションへの連携を実現できます。
皆さんのつなぎたいシナリオでぜひ CData Arc を試してみてください。
CData Arc - セキュアなデータ連携とマネージドファイル転送（MFT）
製品を試していただく中で何かご不明な点があれば、テクニカルサポートへお気軽にお問い合わせください。
CData Software Japan - Support Form
この記事では CData Arc™ 2024 - 24.3.9118.0 を利用しています。
