こんにちは！primeNumberの杉之原です。
今回も、前回に引き続き TROCCO の「カスタムコネクタ」でのAI活用をテーマにしています。
前回の記事では、API の仕様を AI に読ませて、TROCCO のカスタムコネクタ機能での対応可否を判定するまでをご紹介しました。
今回は、前回の判定の結果、対応可能とわかった API を、AIを使ってカスタムコネクタとして実装していきます。
この記事を読む前に、ぜひこちらもご覧ください。
TROCCOのカスタムコネクタ実装を楽にするAI活用 〜実装前の仕様調査編〜
カスタムコネクタ機能はアップデートしました
これまでの TROCCO のカスタムコネクタ機能は、APIリファレンスを見ながらユーザー自身が画面入力してカスタムコネクタ定義を作成するものでしたが、最近のアップデートで YAML の定義ファイルとしてインポート・エクスポート機能が実装されました。
このアップデートによって、AI にカスタムコネクタ定義を作らせて取り込むということもできるようになりました！
この記事で書くこと
この記事は2部になっています。
前半（実装編） では、データ転送で「やりたいこと」をAIに伝えて、ベースとなるカスタムコネクタ定義を生成する流れをご紹介します。
定義作成のプロンプトもこの記事に添付していますので、ご自身でもお試しいただけます。
後半（運用編） では、よくある運用パターンから、カスタムコネクタの重要な設定をご紹介します。
カスタムコネクタは Advanced プラン以上の機能です。詳しくは カスタムコネクタについて をご覧ください。
【実装編】 AI をつかってカスタムコネクタ定義を作成する
さっそくですが、AIを使いながらカスタムコネクタ定義を作っていきます。
この記事では、TROCCOの各種設定やジョブの実行履歴などが取得できる 「TROCCO API」 を、転送元カスタムコネクタとして実装する実例でご紹介します。
実装までの流れを下記4ステップでご説明します。
- プロンプトと雛形を AI に投げる
- AI の回答を確認する
- インポートして定義を作成する
- 期待どおりの転送になるか確認する
Step 1 : プロンプトと雛形を AI に投げる
プロンプトをコピペして投げるだけ…と言いたいところですが、AIに投げる前に、まずは準備が必要です。
前回の記事のカスタムコネクタ対応可否の判定で 「着手可」 となっている前提です。
また、生成AIは前回と同じセッションで引き続き実行することをオススメします。（セッションを分ける場合は、前回の実行結果をコピーして今回のプロンプトと一緒に投げればよいです。）
- 前回の記事のプロンプト①②の結果 : 同じセッションならそのまま参照可
- カスタムコネクタ定義の雛形 : TROCCO の画面からダウンロード
- 定義作成のプロンプト : この記事のプロンプト③（転送先は後半のプロンプト④）
- プロンプトに書くインプット : データを使って「やりたいこと」を記載
ちなみに、今回作成するTROCCO APIは「着手可」と判定済みです。
雛形のダウンロード
TROCCO にログインし、カスタムコネクタ画面右上の「⋯」からカスタムコネクタ定義の雛形をエクスポートできます。今回は転送元コネクタの雛形を使いました。
雛形は「転送元用」と「転送先用」で分かれています。
お使いの生成AIに、雛形を添付して下記の転送元用プロンプトを貼ります。
プロンプト③：カスタムコネクタ定義の作成（転送元）
# 役割
あなたは TROCCO のカスタムコネクタ定義（転送元）を作る担当です。**接続確認が通る最小限の定義**を作ってください。
1レコードの単位・返ってくる項目・ページングの終端の挙動は、**推測で埋めるより接続確認で実際のレスポンスを見たほうが速くて確実**です。細かい設定はそのあと画面で足せます。最初から完璧を目指さないでください。
# 重要なルール
- **添付された雛形にあるキーだけを使ってください。** 新しいキーを足さないでください
- 分からない項目を、それらしい値で埋めないでください。**推測した箇所は「推測」と明示し、出力Dに入れてください**
- **APIキーやトークンを定義ファイルに書かないでください。** 認証情報は TROCCO の接続情報に登録します
- **利用者は API の知識を持っていない前提**で書いてください
- プロンプト①②の出力がこの会話にすでにある場合は、貼り直しを求めず**そのまま参照してください**
# インプット
- **雛形ファイル：この会話に添付されているファイルを使ってください**（TROCCO の画面からエクスポートした、転送元の空の雛形）
- APIの仕様：[プロンプト①の出力。同じ会話で続けている場合は「①を参照」でよい]
- 対応可否の判定結果：[プロンプト②の出力。同じ会話で続けている場合は「②を参照」でよい]
- やりたいこと：[どのくらいの頻度で、どこまでのデータが必要かまで書く。例：TROCCOのジョブ実行履歴を毎日DWHに貯めて、失敗を可視化したい]
# まず決めること
**足りない情報は質問してください。勝手に決めないでください。**
**使うエンドポイントの数や種類など、定義の骨格に関わることが決められない場合は、A〜D を出す前に質問してください。** 骨格が決まらないまま出すと、作り直しになります。細部（項目名や値の形式など）は、推測して置いたうえで**出力Aの直後に質問の形で**挙げてください。
| 決めること | 補足 |
|---|---|
| 何のデータが欲しいか | |
| **どの頻度で取るか。増分にするか** | **増分にするなら、APIが期間や更新日時で絞り込めることが前提です。** 絞り込めないAPIでは毎回すべて取り直すことになります |
| **必要な項目** | これが無いと目的を達しない、という項目 |
| どのエンドポイントを使うか | **上の3つから決まります。** 同じAPIでも、エンドポイントによって絞り込みの可否が違います。候補が複数あるなら選んだ理由も書いてください |
| **対象ごとにデータが分かれているか** | URL に対象のID（店舗ID・プロジェクトIDなど）を入れる API かどうか |
レスポンスの構造やページングの終端の挙動は、ここでは決めません。接続確認で確かめます。
**決めた内容は出力Aに反映してください。「決めたこと」の一覧を別のブロックとして出力しないでください。**
# 定義に含めるもの
## 認証
①の仕様から決まります。
- APIキーやトークンを HTTPヘッダに載せる場合は `auth_type: api_key`
- `auth_header_name` … ヘッダ名（多くは `Authorization`）
- `auth_header_scheme` … 値の先頭に付く語（`Bearer` / `Token` など。何も付かないなら空）
- OAuth2.0 の場合は `auth_type: oauth2`
- `grant_type` は `authorization_code` または `client_credentials`
- `authorization_code` なら `auth_uri`（認可URL）と `access_token_uri` の両方が必要です
- 認可URLに固定の追加パラメータが要る場合（`access_type=offline` など）は `auth_uri` に書き足し、**末尾を `&` で終えてください**
## エンドポイント
- **ベースURL（`url`）と認証方式が同じエンドポイントは、1つの定義にまとめてください**（分けると、コネクタも接続情報も別々に登録することになります）。**ベースURLが違うエンドポイントが必要な場合は、定義を分けます。** 1つの定義に違うホストは入れられません。その場合は、どちらの定義にどのエンドポイントを入れたかを出力Aに書いてください
- **やりたいことに必要なエンドポイントは一式入れてください。** URL に対象のIDが入る API なら、**対象の一覧を取るエンドポイントも含めます**（例：`/accounts/{account_id}/locations` で店舗一覧、`/locations/{location_id}/metrics` で明細）。使わなければ転送設定を作らなければよいだけで、足りずにあとから定義を編集するより安く済みます
- ただし**APIの全エンドポイントを網羅しないでください。** 目的に関係ないものは入れません
- `method` は**大文字**（`GET` / `POST`）
- **`POST` でリクエストボディを送るAPIでは `request_body` も書いてください。** ボディが無いと接続確認が成立しません（レポート取得系に多い）
- パスに `{}` がある場合は `path_parameters` に定義します。**`value` にはパスの `{}` の中の名前**を書きます（実際の値ではありません）。`/jobs/{job_id}` なら `value: job_id`、`name` は画面に出るラベル
- **認証以外に必須のヘッダがある API では `headers` に書いてください**（APIバージョンの指定など）。無いと接続確認が通りません。固定値で持たせるなら `default_value` に値を入れ、`is_editable: false` / **`is_required: false`** にします
- `is_required` は「**APIが必須とするか**」ではなく「**転送設定の画面で利用者に入力させるか**」です。**`is_editable: false` と `is_required: true` は組み合わせられません**（入力できない項目を必須にはできず、保存できなくなります）
## データの取り出し方
`jsonpath_root` には**データの配列そのもの**を指すパスを書きます。`{"items": [...]}` のように包まれていれば `$.items`、配列が直接返るなら `$`。**`$.items[*]` のように `[*]` を付けないでください。**
サンプルレスポンスが無くて確定できない場合は、**推測して置いてください。** 接続確認で直せるので、ここで止まる必要はありません。
## 保存できなくなる書き方
- **`success_codes` と `not_retryable_codes` は必須です。削除しないでください。** リファレンスに記載が無ければ `success_codes: "200"` / `not_retryable_codes: "400,401,403,404"` を既定にします（**`429` は含めないでください**。レート制限はリトライで回復します）
- どちらも**クォートした文字列**で書く。YAMLの配列で書くと保存できません
- **使わないブロックやキーは削除してください**（上記2つは必須なので残します）
- `transfer_type` は変更しない
# 定義に含めないもの
**パラメータ（絞り込み・取得項目・期間）とページングは、いま書かないでください。** 接続確認では動かないため、実際のレスポンスを見てから画面で足します。
**例外：無いとリクエストが成立しない必須のパラメータだけは書いてください。** 無いと接続確認が 400 で失敗します。**`is_editable: true` / `is_required: true` にし、`default_value` に接続確認用の値を入れます**（接続確認は `is_required: false` のパラメータを送りません）。任意の絞り込みは、必須でない限り書かないでください。
# 出力フォーマット
## A. この定義でできること
エンドポイントごとに、**何が取れて、何のために使うのか**を書いてください。利用者はここで、やりたいこととのずれを判断します。
| エンドポイント | 何が取れるか | 何のために使うか |
|---|---|---|
- 「何のために使うか」は**目的だけ**（例：日次で店舗ごとの指標を貯める）。**入力値や手順はCに書きます**
- 対象ごとに分かれている API なら、**エンドポイント同士の関係**も書いてください（一覧で取ったIDを明細のパスに使う、など）
決められなかったことがあれば、**この直後に質問の形で**挙げてください。
## B. 定義ファイル
雛形のキーの順番を保ったまま YAML で出力し、なぜその値にしたかをコメントで残してください。
## C. TROCCOで入力する値
**この定義に関係する入力値と、データソース側の事前準備だけ**を書いてください。画面の操作手順や、転送先の書き込みモード・スケジュールなど**定義と関係のない設定は書かないでください**。
| 場所 | 項目 | 入れる値 |
|---|---|---|
- 対象ごとに分かれている場合は、**転送設定が対象ごとに分かれること**
- OAuth2 の認可コードフローなら、**データソース側のアプリにコールバックURL `https://trocco.io/connections/custom_connector/callback` を登録する必要があること**
## D. 取り込んだあとに確かめること
接続確認やプレビュー、転送ジョブの実行で実物を見られます。**そこで確かめることを3〜5個**挙げてください。**同じことを重複させないでください。**
**次の3つは必ず含めます。**
1. **1レコードの単位が意図どおりか** — 実データが入れ子で、まとめて1つの列に入っていないか
2. **必要な項目が返っているか** — Aの「何が取れるか」に挙げた項目。**返っていなければ、取得項目を指定するパラメータを足す必要があります**
3. **ページングを設定する必要があるか** — **取れた件数が API の1ページあたりの上限ちょうどなら、まだ続きがあります。** 上限がリファレンスから分かる場合は、その値を書いてください。分からない場合は「100 や 1000 などキリのよい数でちょうど止まっていないか」を見るよう書いてください。**件数は転送ジョブのログで確認できます**（接続確認はページングを実行せず、レスポンスが大きいと途中で省略されます）
---
**定義ファイルの再インポートはできません。** このあと修正が必要になったときは、YAML 全体を作り直さず、**画面で変更する項目とその値**を挙げてください。
項目名は**画面に表示される名前**で書いてください。エンドポイントの編集画面にある項目は下記のとおりです。
- 名前 / パス（＋パスパラメータ）/ HTTPメソッド
- **パラメータ** … パラメータ名 / 表示名 / デフォルト値 / 編集可能 / 必須
- **HTTPヘッダ** … ヘッダ名 / 表示名 / デフォルト値 / 編集可能 / 必須
- **JSONPathルート**
- **ページング設定**（無効 / ページベース / オフセットベース / カーソルベース）
- 詳細設定 … 転送データ取得時に正常系と判定するステータスコード / 失敗時にリトライしないステータスコード / リクエストタイムアウト(秒)
**この一覧にない項目名を作らないでください。** 詳細は下記にあります。
https://documents.trocco.io/docs/create-source-custom-connector
プロンプトの「インプット」は、下記のようにしました。APIの仕様と対応可否の判定はAIとの会話の履歴を参照させています。
# インプット
- 雛形ファイル：添付したYAMLファイル
- APIの仕様：①の結果を参照
- 対応可否の判定結果：②の結果を参照
- やりたいこと：TROCCOの転送設定の一覧を毎日取得して、DWHに転送し、ジョブの実行時間やエラー率を可視化したい
「やりたいこと」について
TROCCOでのデータ転送の運用イメージをAIに伝えることで、適切なAPIのエンドポイントをAIに特定させ、カスタムコネクタ定義として実装させます。
データ転送の要件や転送の頻度、必要な項目などを具体的に記載することで、出力される定義の精度も上がります。
Step 2 : AI の回答を確認する
プロンプトを実行すると、AI は結果として下記を返します。
A : この定義で何ができるか
カスタムコネクタ定義に実装したエンドポイントごとに「何が取れて、何に使えるか」が表で出力されます。ここで 「やりたいこと」を満たせそうか を確認できます。
B : カスタムコネクタ定義のYAML
作成されたカスタムコネクタ定義です。ファイルとしてダウンロードできなければ、ダウンロードできる形式で出力してもらうよう AI に依頼すると楽です。
C : 画面で入力する値と、データソース側の事前準備
TROCCOでの実装時に必要となる接続情報の入力項目やその入手方法、APIのリクエストで使用するIDなどのパラメータといった情報です。
D : レスポンスで確かめること
この後の手順でおこなう動作確認時のポイントを挙げてくれます。
これら4つの他に、AI が判断に迷った部分についての確認依頼が返ってくる場合があります。ここで仕様を詰めることで、よりユーザーの目的に沿ったカスタムコネクタ定義を出力してくれます。
Step 3 : インポートして定義を作成する
AIが作成したYAMLファイルをダウンロードし、TROCCOにインポートします。
カスタムコネクタの新規作成画面の右上「⋯」から「定義ファイルから作成」を選択し、インポートするYAMLファイルを選択するだけです。
詳しくはこちらをご覧ください。
インポートできたら、保存ボタンを押して作成完了です。
Step 4 : 期待どおりの転送になるか確認する
転送設定のプレビューや転送ジョブを実行して、転送されるカラムやデータを確認します。
通常のコネクタと同様に、転送設定を作るには接続情報の作成が必要です。
AIの出力結果 C には、接続情報に必要なトークンなどの取得手順が出力されています。不明点もAIに追加確認しながら、接続情報の作成ができます。
APIのレスポンス（JSON）を確認することもできます
カスタムコネクタ定義の各エンドポイント編集画面にある「接続確認」から、APIを実行してレスポンスのJSONデータを確認できます。APIのレスポンスをAIに貼り付けて相談したいときに便利です。
確認ポイント
AIの出力結果 D で挙がったポイントを中心に見ていきます。不明点はAIに質問しながら、「やりたいこと」を満たすデータ転送になっているかを確かめましょう。
カスタムコネクタ定義の編集について
カスタムコネクタ定義のインポートは定義の新規作成時のみに対応しており、インポート後の編集は、画面操作する必要があります。
AIにカスタムコネクタ定義を修正させて再インポートはできませんので、ご注意ください。
ここまででカスタムコネクタの基本的な実装は完了です
無事に転送データの確認ができたら、カスタムコネクタ定義としては使用可能なものになっているはずです。
ただ、転送ジョブが成功しただけでは、そのまま運用を始められるとは限りません。
日々のデータ転送を安定して回すには、APIで過不足なくデータを転送できるようにしたり、TROCCOのデータ転送やワークフロー側の設定と組み合わせたりする必要があります。
この考え方はTROCCOの標準コネクタでの実装する場合も同じですが、カスタムコネクタ特有の設定を詰めていくことが、安定かつ効率的な運用には欠かせません。
【運用編】 カスタムコネクタ運用のための設定
ここからは、 カスタムコネクタの運用でよく使われる重要な設定をご紹介していきます。
やりたいことに合わせて実装の参考にしてみてください。
- ページングの設定 : 件数の多いデータを一括取得したいとき
- 取得範囲の絞り込み設定 : スケジュール実行で増分データだけ取得したいとき
- データの取得粒度（ルート）の設定 : 取りたいデータが1カラムにまとまってしまうとき
- ID一覧取得 → 詳細取得 : ID単位で1件ずつ取得するエンドポイントを使うとき
- データの書き込み（転送先カスタムコネクタ） : APIでデータを書き込みたいとき
1. ページングの設定
APIでは、件数の多いデータを扱うとき、1回のリクエストで返す件数に上限を設けてデータを区切り、続きのデータを繰り返しリクエストして取得する「ページング」という仕様を採用しているケースが多いです。
顧客情報やユーザー一覧などのマスタをDWHに同期したい、日々大量に登録される履歴データをひたすら貯めたい、といったいちどに多くの件数を扱う転送ではページングの設定が必要になります。
ページングを設定しないと、1ページ目だけ転送してジョブが終了してしまい、転送対象を全て取得することができなくなるため、APIのデータ取得においては重要な設定です。
カスタムコネクタ定義での設定
カスタムコネクタ編集画面の各エンドポイントの編集に「ページング設定」という項目があります。
この項目をAPIのページング仕様に合わせて設定していきます。
ページング設定の追加をAIにアシストさせる追加のプロンプトを用意しました。
前半から続けて、同じセッションで実行する前提です。 調査済みのAPI仕様をもとに、カスタムコネクタ編集画面でのページング設定案を回答してくれます。
追加プロンプト：ページングを足す
これからページングを設定します。下記のルールに従ってください。
- `page` / `per_page` を渡す → `page_increment` ／ `offset` / `limit` を渡す → `offset_increment` ／ カーソルを渡す → `cursor_based`
- **`cursor_based` を使ってよいのは、終端でカーソルが「返ってこなくなる」か「null になる」場合だけです。** 終端で空文字列 `""` を返すAPIでは、空のカーソルをそのまま送って1ページ目に戻り、**同じデータを取り続けてジョブが終わりません**。終端の挙動が確認できていない場合は、確認するよう促してください
- `*_option.field_name` には**リクエストに載せるパラメータ名**を書きます（`cursor` など）。JSONPath を書くのは `cursor_value` / `last_page_size` / `total_*` だけです
- **`page_size_option` / `page_token_option` に指定した名前を、`parameters` に重複して定義しないでください**（保存できません）
- `page_size` は**APIの上限以下**にしてください。上限より大きい値を書くと、1ページ目で終了と判定されてデータが欠けます
変更する項目と、その値だけを挙げてください。定義ファイル全体は作り直さないでください。
**項目名は、TROCCOの画面に表示される名前で書いてください。** インポート後の修正は画面で行うため、定義ファイルのキー名では利用者が探せません。画面の項目名は下記のとおりです。
- **JSONPathルート**
- **ページング設定**（無効 / ページベース / オフセットベース / カーソルベース）
- **ページングパラメータの挿入先**（クエリパラメータ / リクエストボディ）
- **1リクエストの取得件数** … パラメータ名 / 値
- **取得位置** … パラメータ名（カーソルベースのみ）
- **レスポンスデータに含まれるカーソルへのパス（JSONPath記法）**（カーソルベースのみ）
- **開始ページ(開始位置)** … パラメータ名 / 値（ページ・オフセットベースのみ）
- **終了ページ(終了位置)** … 終了判定方法 / 最大リクエスト数（ページ・オフセットベースのみ）
**この一覧にない項目名を作らないでください。** 詳細は下記にあります。
https://documents.trocco.io/docs/create-source-custom-connector
なお、**カーソルベースには「最大リクエスト数」の欄がありません。** 終端の判定を誤ると止める仕組みが無いので、上の終端の確認がとくに重要です。
確認方法
転送ジョブの転送件数を確認します。転送対象の件数が分かるなら、それと一致していれば確実です。
分からない場合も、転送件数がAPIの1ページ上限件数を超えていれば、ページングは効いています。
2. 取得範囲の絞り込み設定
日次のレポートを貯めたり、更新された顧客データだけ同期するといった場面では、増分データのみを取得して効率的に転送することが有効です。
カスタムコネクタでも、利用するAPIに、取得期間や更新日時といったデータを絞り込むパラメータがあれば、増分データの転送を実現することができます。
それには、利用するAPIのリクエストに「パラメータ」の指定ができるように、カスタムコネクタ定義に設定を追加する必要があります。
また、この「パラメータ」はデータを絞り込むだけでなく、取得する項目を指定・追加する際にも使います。
パラメータとして指定しないと既定の項目しか返さないようなAPIもあるため、APIの仕様によっては細かい設定が必要になることもあります。
カスタムコネクタ定義での設定
カスタムコネクタ編集画面の各エンドポイントの編集に「パラメータ」という項目があります。
ここに、絞り込みに使うパラメータを追加していきます。
パラメータの追加をAIにアシストさせる追加のプロンプトです。
追加プロンプト：パラメータを足す
これからパラメータ（絞り込み・取得項目・期間）を設定します。
**まず、APIリファレンスを見て、目的に使えるパラメータを挙げてください。** ①で挙げていなくても、リファレンスには載っていることがあります。
**リファレンスは、エンドポイントごとの個別ページまで開いて確認してください。** パラメータの一覧は、目次や概要のページには載っていないことがほとんどです。個別ページを開けない場合は、**「無い」と判断せず、開けなかったことを伝えてください。**
**記載が無ければ「無い」と書いてください。推測でパラメータ名を作らないでください。**
そのうえで、下記のルールに従ってください。
- 転送設定ごとに値を変えたいものは `is_editable: true`
- **`is_required: true` にできるのは `is_editable: true` の項目だけです。** 固定値にしたい項目は `is_editable: false` + `default_value` + `is_required: false` にしてください
- `is_editable` / `is_required` は省略できません
- **増分取得に使う日時のパラメータは、必ず `is_editable: true`** にしてください。固定値だと増分にできません
- **`POST` の場合、`request_body` と `parameters`（クエリパラメータ）は併用できません。** 両方書くと `request_body` が無視されます。POST でパラメータを可変にしたい場合は、`request_body` の中に埋め込む形にします
- **HTTPヘッダは、APIが必須とするものがある場合だけ追加してください。** 無くてもリクエストが通るヘッダは追加しないでください
変更する項目と、その値だけを挙げてください。定義ファイル全体は作り直さないでください。
**項目名は、TROCCOの画面に表示される名前で書いてください。** 画面の項目名は下記のとおりです。
- **パラメータ** … パラメータ名 / 表示名 / デフォルト値 / 編集可能 / 必須
- **HTTPヘッダ** … ヘッダ名 / 表示名 / デフォルト値 / 編集可能 / 必須
**この一覧にない項目名を作らないでください。** 詳細は下記にあります。
https://documents.trocco.io/docs/create-source-custom-connector
絞り込み条件として指定するパラメータは、「編集可能」にチェックを入れてください。 編集可能にすることで、転送設定側で値を入力・設定できるようになります。
データ転送での設定
パラメータに渡す値は、転送設定の 「カスタム変数」 を使うことで、ジョブを実行した日時の「前日1日分」といったように、取得期間を動的に指定することができます。
カスタム変数の使い方については、こちら をご覧ください。
また増分データの転送では、転送先の「転送モード」に 追記 か UPSERT を指定するのが一般的です。
確認方法
プレビューや転送ジョブの結果など、実際に出力されたデータで確認します。
データがパラメータとして指定した期間の範囲内のみであれば、絞り込みの設定はできています。
3. データの取得粒度（ルート）の設定
APIのレスポンスは形式が様々で、データの配列がそのまま返ってくるとは限りません。
データがひとつのキー配下に並んでいるのであれば単純ですが、HubSpotのコンタクト一覧のように1件ごとの中身がさらに下の階層にまとまっているものもあれば、Googleビジネスプロフィールの店舗別インサイトのように 「指標 → 日付 → 数値」と何段にも分かれているものもあります。
これはAPIの設計の違いによるもので、こうしたAPIでは、レスポンスのどの階層をデータのルートにするかで、TROCCOで転送するデータの粒度も変わります。
ルートが浅すぎるとデータがJSON文字列のまま1つのカラムに入り、転送したあとに展開する加工が必要になります。逆に深すぎると、ルートより浅い階層のデータが取得できなくなります。
カスタムコネクタ定義での設定
カスタムコネクタ編集画面の各エンドポイントの編集に 「JSONPathルート」 という項目があります。ここに、データとして取り出したい階層へのパスを指定します。
どこをルートとして設定するかは、下記のようなAPIのレスポンスデータを例に説明します。
{
"results": [
{
"id": "12345",
"updatedAt": "2026-09-09T12:00:00.000Z",
"properties": { "email": "taro@example.com", "firstname": "太郎" }
}
]
}
カスタムコネクタ定義のJSONPathルートに $.results を指定すると、転送設定では下記のようなカラム構成でプレビューを生成します。properties はひとつのカラムにJSON文字列として取得されています。
| id | updatedAt | properties |
|---|---|---|
| 12345 | 2026-09-09T12:00:00.000Z | {"email":"taro@example.com","firstname":"太郎"} |
JSONPathルートに1段深い階層の $.results[*].properties を指定すると、properties の中身のみのカラム構成となります。
| firstname | |
|---|---|
| taro@example.com | 太郎 |
properties は項目ごとに取得できましたが、properties と同じ階層の id と updatedAt は取得できなくなりました。これでは、レコードを一意に特定する id や、updatedAt で差分を取りたい場合は困ります。
このような場合は、JSONPathルートに $.results を指定するほうがデータ構造的に望ましいです。カスタムコネクタ定義では、まず必要なデータが不足なく取得できるように設計しましょう。
データ転送での設定
転送設定のカラム定義でも、JSON文字列を展開できます。
上記の例にある properties は転送設定でJSON文字列展開することで、id や updatedAtと同じ階層のカラムとして設定できます。
JSONカラムの展開方法はこちらをご覧ください。
確認方法
プレビューや転送ジョブの実行結果でカラムの構造を確認します。
必要な項目がカラムとして取得できるように、カスタムコネクタ定義のJSONPathルートや、JSONカラム展開の設定を使い分けるのがよいです。
4. ID一覧取得 → 詳細取得
店舗やユーザーの詳細なデータを取得するエンドポイントでは、APIのリクエストに店舗IDやユーザーIDといった値が必要になるものがあります。
こういったデータの取得は、まずIDの一覧を取得し、そのIDリストを使って各詳細を1件ずつ取得するという2段構えのデータ転送で実現できます。
特に、IDのリストが日々更新される場合にはこのような実装が有効です。
TROCCOの仕様上、ID一覧取得のデータ転送は転送先にDWH製品（BigQuery、Snowflake、Redshift、Databricks）を利用する必要があります。
カスタムコネクタ定義での設定
カスタムコネクタ定義には「一覧取得」と「詳細取得」のふたつのエンドポイントを作成します。
パスに {} が含まれる詳細取得のエンドポイントでは、カスタムコネクタ編集画面の「パスパラメータ」に、その名前を登録します。
例：TROCCO API 実行ジョブ取得エンドポイント（転送設定IDをパスパラメータに指定）
path: /api/job_definitions/{job_definition_id}/jobs
値として登録するのはパスの {} の中の名前（この例では job_definition_id）です。
ここで設定した項目は、転送設定の作成時にパラメータとして入力できるようになります。
データ転送での設定
一覧取得と詳細取得の転送設定をそれぞれ作成します。
詳細取得の転送設定では、IDごとにパスパラメータの値を変えられるようにパラメータに「カスタム変数」を使用します。
次に、ワークフローでID一覧取得 → 詳細取得の順にジョブを実行する設定を作成します。
TROCCOにはワークフローに カスタム変数ループ実行 という機能があります。
これを利用して、DWHから前段のジョブで転送したIDのリストを取得し、このリストを使ってパスパラメータ(ID)を変えながら詳細取得のデータ転送を繰り返し実行できます。
カスタム変数ループ実行の設定についてはこちらをご覧ください。
確認方法
ワークフローを実行し、ループ実行した詳細取得のジョブ実行件数を確認します。
一覧で取得したレコード数と詳細取得のジョブ実行件数が一致していれば、すべての対象から取得できています。
5. データの書き込み（転送先カスタムコネクタ）
ここまでは「APIからデータを取得する」転送元のケースでした。
最後は TROCCOからAPIにデータを書き込む 転送先カスタムコネクタ を紹介します。
集計結果をSharePointのリストに書き出して業務で使えるようにする、セグメントをMAツールのオーディエンスとして投入する。転送先カスタムコネクタはこうした使われ方をしています。
カスタムコネクタ定義作成の流れは前半でご紹介した転送元とほぼ同じです。
雛形をダウンロードし、プロンプトと一緒にAIへ投げ、出てきた定義をインポートして、動かして確認します。
ただ、転送元とは異なる部分ももちろんあるので、この違いを中心にご説明します。
雛形とプロンプト
雛形は転送元と転送先で異なります。 カスタムコネクタの画面から、転送先用の雛形をダウンロードします。
プロンプトも転送先用のものを用意しました。
プロンプト④：カスタムコネクタ定義の作成（転送先）
# 役割
あなたは TROCCO のカスタムコネクタ定義（転送先）を作る担当です。**接続確認が通る最小限の定義**を作ってください。
送るデータの形やカラム名は、**推測で埋めるより接続確認で実際の展開結果を見たほうが速くて確実**です。細かい設定はそのあと画面で足せます。最初から完璧を目指さないでください。
# 重要なルール
- **添付された雛形にあるキーだけを使ってください。** 新しいキーを足さないでください
- 分からない項目を、それらしい値で埋めないでください。**推測した箇所は「推測」と明示し、出力Dに入れてください**
- **APIキーやトークンを定義ファイルに書かないでください。** 認証情報は TROCCO の接続情報に登録します
- **利用者は API の知識を持っていない前提**で書いてください
- プロンプト①②の出力がこの会話にすでにある場合は、貼り直しを求めず**そのまま参照してください**
# インプット
- **雛形ファイル：この会話に添付されているファイルを使ってください**（TROCCO の画面からエクスポートした、転送先の空の雛形）
- APIの仕様：[プロンプト①の出力。同じ会話で続けている場合は「①を参照」でよい]
- 対応可否の判定結果：[プロンプト②の出力。同じ会話で続けている場合は「②を参照」でよい]
- やりたいこと：[何を、どこに、どう書き込みたいかまで書く。例：DWHで作った対応漏れ一覧を、タスク管理SaaSにタスクとして起票したい]
# まず決めること
**足りない情報は質問してください。勝手に決めないでください。**
**使うエンドポイントの数や種類など、定義の骨格に関わることが決められない場合は、A〜D を出す前に質問してください。** 骨格が決まらないまま出すと、作り直しになります。細部（項目名や値の形式など）は、推測して置いたうえで**出力Aの直後に質問の形で**挙げてください。
| 決めること | 補足 |
|---|---|
| 何を書き込むか | どのリソース（タスク／連絡先／行など） |
| **追記だけか、更新もするか** | **更新もするなら、作成用と更新用の両方のエンドポイントが要ります**（TROCCOのUPSERTは両方を使います） |
| **更新のとき、対象をどう特定するか** | URLにIDを入れるのか、リクエストボディのキーで指定するのか |
| **作成・更新に必須の項目** | これが無いとAPIがエラーを返す、という項目 |
| **やりたいことで書き込みたい項目** | 目的を達するために値を入れたい項目 |
| どのエンドポイントを使うか | **上から決まります。** 候補が複数あるなら選んだ理由も書いてください |
**転送するデータのカラム名は聞かないでください。** APIの仕様から必要な項目を割り出し、**あなたが提案してください**（出力Aに一覧で出します）。利用者は提案されたカラムを見て、手元のデータを用意します。
**決めた内容は出力Aに反映してください。「決めたこと」の一覧を別のブロックとして出力しないでください。**
# 定義に含めるもの
## 認証
①の仕様から決まります。
- APIキーやトークンを HTTPヘッダに載せる場合は `auth_type: api_key`
- `auth_header_name` … ヘッダ名（多くは `Authorization`）
- `auth_header_scheme` … 値の先頭に付く語（`Bearer` / `Token` など。何も付かないなら空）
- OAuth2.0 の場合は `auth_type: oauth2`
- `grant_type` は `authorization_code` または `client_credentials`
- `authorization_code` なら `auth_uri`（認可URL）と `access_token_uri` の両方が必要です
- 認可URLに固定の追加パラメータが要る場合は `auth_uri` に書き足し、**末尾を `&` で終えてください**
## エンドポイント
- **ベースURL（`url`）と認証方式が同じエンドポイントは、1つの定義にまとめてください。** ベースURLが違うエンドポイントが必要な場合は、定義を分けます
- **更新もするなら、同じリソースについて作成用と更新用を対で入れてください。** 追記は作成エンドポイントだけを使い、UPSERT は両方を使います。つまり**作成用しか無ければ追記のみ、更新用しか無ければどちらのモードにも当てはまりません。**
- **更新用だけの定義は作らないでください。** リファレンスに作成用が見当たらない場合は、**定義を出す前に**、作成用のエンドポイントがあるかを確認してください
- **`method` は小文字で書いてください**（`post` / `put` / `patch` のいずれか）。**転送元は大文字なので、方向によって逆になります。** 大文字で書くと保存時に原因の分からないエラーになります
- `operation` は作成用が `create`、更新用が `update`
- **`request_type` は `single`**（1レコードにつき1リクエスト）
- **パスに値を入れる方法は2つあり、併用できません。** どちらか一方だけを書いてください
- **行ごとに値が変わるなら、`path` に Liquid を直接書きます**（例：`/api/labels/{{ row.id }}`）。**更新用のエンドポイントは必ずこちらです。** 更新する対象は行ごとに違うからです。この場合 `path_parameters` は書きません
- 転送設定ごとに固定の値なら `path_parameters` を使います。`path` は `/accounts/{account_id}` のように書き、`value` には**その `{}` の中の名前**を書きます
- **`path_parameters` の `value` に Liquid を書かないでください。** 保存できません
- 日本語のカラム名はドットで参照できないので `{{ row["氏名"] }}` の形にします
- 認証以外に必須のヘッダがある API では `headers` に書いてください。固定値なら `default_value` に値を入れ、`is_editable: false` / **`is_required: false`** にします
- `is_required` は「APIが必須とするか」ではなく「**転送設定の画面で利用者に入力させるか**」です。**`is_editable: false` と `is_required: true` は組み合わせられません**
## リクエストボディ（`template`）
転送先の中核です。Liquid で書き、`request_type: single` なら転送データのカラムを `{{ row.カラム名 }}` で参照します。
**含める項目は2種類だけです。**
1. **作成・更新に必須の項目**（無いとAPIがエラーを返すもの）
2. **やりたいことで書き込みたい項目**
任意の項目を網羅しないでください。
**参照するカラム名は、あなたが決めてください。** APIの項目名に揃えるのが基本です（APIが `email` を受け取るなら `{{ row.email }}`）。決めたカラム名は**出力Aに一覧で出します**。
- **すべての値を引用符で囲んでください。** 数値でも真偽値でもです。`{"age": {{ row.age }}}` のように囲まないと、**値が空の行で JSON が壊れて失敗します**
- **値は自動でエスケープされません。** `"` を含む値が入ると JSON が壊れます。自由記述の項目を含める場合は、そのことを出力Dに挙げてください
## 保存できなくなる書き方
- **`success_codes` と `not_retryable_codes` は必須です。削除しないでください。** リファレンスに記載が無ければ `success_codes: "200,201,204"` / `not_retryable_codes: "400,401,403,404"` を既定にします（**`429` は含めないでください**。レート制限はリトライで回復します）
- どちらも**クォートした文字列**で書く。YAMLの配列で書くと保存できません
- **使わないブロックやキーは削除してください**（上記2つは必須なので残します）
- `transfer_type` は変更しない
# 定義に含めないもの
**一括送信（`request_type: multiple` と `batch_size`）は、いま書かないでください。** まとめて送るテンプレートは区切りのカンマの制御を間違えやすく、**1件のときは通って複数件で壊れます**。1件ずつ送る形で動かしてから、画面で切り替えます。
# 出力フォーマット
## A. この定義でできること
エンドポイントごとに、**何を書き込めて、何のために使うのか**を書いてください。利用者はここで、やりたいこととのずれを判断します。
| エンドポイント | 何を書き込むか | 何のために使うか |
|---|---|---|
- 「何のために使うか」は**目的だけ**（例：対応漏れの案件をタスクとして起票する）。**入力値や手順はCに書きます**
- **作成用と更新用をどう対にしたか**を書いてください。対になっていないエンドポイントがある場合は、そのことを明示します
続けて、**転送データに必要なカラム**を出してください。
| カラム名 | 必須 | 何に使われるか |
|---|---|---|
- **必須**は、無いとAPIがエラーを返すものに「必須」、目的のために入れたものに「任意」と書きます
- 利用者はこの表を見て、転送するデータを用意します。**手元のデータで名前が違う場合は、転送設定でカラム名を合わせるか、定義の `template` を直せばよい**ことも添えてください
決められなかったことがあれば、**この直後に質問の形で**挙げてください。
## B. 定義ファイル
雛形のキーの順番を保ったまま YAML で出力し、なぜその値にしたかをコメントで残してください。
## C. TROCCOで入力する値
**この定義に関係する入力値と、書き込み先サービス側の事前準備だけ**を書いてください。画面の操作手順など**定義と関係のない設定は書かないでください**。
| 場所 | 項目 | 入れる値 |
|---|---|---|
- **転送設定のモード**（追記／UPSERT）と、**UPSERTなら更新キーに指定するカラム**。ここは定義ではなく転送設定側の設定です
- 作成用・更新用のエンドポイントを転送設定でそれぞれ選ぶこと
- OAuth2 の認可コードフローなら、**書き込み先サービス側のアプリにコールバックURL `https://trocco.io/connections/custom_connector/callback` を登録する必要があること**
## D. 接続確認で見ること
**接続確認を実行すると、書き込み先に実際にデータが登録されます。** 本番環境を避けたい場合は、検証環境に接続できる接続情報を使うよう、最初に注意してください。
そのうえで、**確かめることを3〜5個**挙げてください。**同じことを重複させないでください。**
**次の3つは必ず含めます。**
1. **展開後のリクエストボディが意図どおりか** — 接続確認はテンプレートの展開結果を表示します。カラム名が違っていれば、その項目が空文字列で送られます
2. **値が空の行があるとどうなるか** — 空でも JSON が壊れないこと。引用符で囲めていれば壊れません
3. **書き込み先の画面で実際のレコードを確認する** — ステータスコードが正常でも、意図した値が入っているとは限りません
---
**定義ファイルの再インポートはできません。** このあと修正が必要になったときは、YAML 全体を作り直さず、**画面で変更する項目とその値**を挙げてください。
項目名は**画面に表示される名前**で書いてください。エンドポイントの編集画面にある項目は下記のとおりです。
- 名前 / パス（＋パスパラメータ）/ HTTPメソッド / 操作種別（作成API / 更新API）
- **リクエストタイプ**（単一 / 一括）/ バッチサイズ
- **リクエストテンプレート**
- **クエリパラメータ** … パラメータ名 / 表示名 / デフォルト値 / 編集可能 / 必須
- **HTTPヘッダ** … ヘッダ名 / 表示名 / デフォルト値 / 編集可能 / 必須
- ペイロード種別 / 正常系ステータスコード / リトライしないコード / リクエストタイムアウト(秒)
**この一覧にない項目名を作らないでください。** 詳細は下記にあります。
https://documents.trocco.io/docs/create-destination-custom-connector
転送先用のデータの用意
転送先カスタムコネクタでは、実行するAPIのフォーマットに合わせたデータを、転送元データとして用意する必要があります。
上記プロンプト④を実行すると、「転送データに必要なカラム」の表が出力されます。これを確認しながら、転送元にデータを用意しましょう。
例：TROCCO API ラベル作成・更新
カスタムコネクタ定義での設定
APIの仕様にもよりますが、カスタムコネクタ定義にはレコードを作成するエンドポイントと、更新するエンドポイントが設定されます。これらのエンドポイントは、後述する転送設定で使い分けます。
また、転送元では取得条件となるパラメータを設定しますが、転送先では登録するデータをAPIで送るリクエストボディのテンプレートを組み立てる設定になっています。
（書き方など詳細については こちら をご覧ください。）
編集画面の「接続確認」について
転送先のカスタムコネクタ定義編集で接続確認を実行すると、実際にAPIが実行され、データが登録・更新されます。
接続確認時は、検証環境や検証データを用意することをおすすめします。
転送設定での設定
転送設定の転送先の設定で、作成用と更新用のエンドポイントをそれぞれ選びます。
既存のデータを更新する場合は、モードで UPSERT を選び、更新キーにするカラムを指定します。
転送ジョブ実行時に、更新キーを持つレコードは更新エンドポイントへ、持たないレコードは作成エンドポイントへ振り分けられます。
確認方法
書き込み先で、意図したレコードが作成・更新されているかを確認します。
転送先カスタムコネクタの転送ジョブは、APIのレスポンスが「成功」であれば正常終了します。ジョブのステータスだけで判断しないように注意してください。
また、転送ジョブのログには create / update / errors の内訳が出力されるので、作成・更新された内訳の確認に利用できます。
おわりに
2本の記事にわたってかなり長くなってしまいましたが、AIを活用しつつカスタムコネクタを使い始めるまでのポイントはひと通りご紹介できたかなと思います。
正直なところ、AI活用という点においては、定義の反映や検証までコード化して自動化するほうが速くて精度の高いものができるだろうなと思っていたりします。
ただ、これからカスタムコネクタを導入しようという方に向けて、AIに頼りつつも「何を実装しているのか」を自分で理解しながら進められることは重要だと思い、TROCCOは今まで通り使いつつ、必要な知識の収集や作業時間をAIによって効率化する、という内容にしました。
普段TROCCOを使っているユーザーなら試しやすい内容になっていると思うので、これからカスタムコネクタの導入を検討される皆さんの参考になれば幸いです！