はじめに

こんにちは！primeNumberの杉之原です。

普段お客様と接するなかで、TROCCOではコネクタ未対応のサービスへのデータ転送のご要件も伺うことがあります。
その際、TROCCOの「カスタムコネクタ」という機能を提案することが多いのですが、この機能を使いこなすことがなかなか難しく、残念ながら導入に至らないケースも度々ありました。

そんなカスタムコネクタですが、ここ最近のアップデートで、AIを活用することでかなり導入のハードルを下げることができるようになったので、今回はTROCCOのカスタムコネクタでのAI活用術をシェアしたいと思います！

TROCCOの「カスタムコネクタ」について知りたい方はこちらをご参照ください。

※カスタムコネクタはTROCCOのAdvancedプラン以上で利用可能な機能です。

カスタムコネクタを導入するハードル

カスタムコネクタはとても便利な機能ではあるのですが、APIに関する知識がないと、実装までのハードルがかなり高くなってしまうのも事実です。
実際にご相談をいただく中では、大きく2つのハードルがあると感じています。

1つ目のハードルは 「提供元APIの仕様がカスタムコネクタで対応可能なものか判断すること」 です。
提供元のAPIの仕様によっては、カスタムコネクタで対応できるものとそうでないものがあります。
APIを理解しないままカスタムコネクタを使い始めると、時間をかけて色々試したが結局ダメだった、という結果になりかねません。

2つ目のハードルは 「転送したいデータのエンドポイントを特定して、適切な設定を組むこと」 です。
APIリファレンスから自分が利用したいエンドポイントを探して、TROCCOのカスタムコネクタとして設定しないといけません。
APIの扱い方を理解していることはもちろん、APIリファレンスを読み解く時間や、TROCCOのカスタムコネクタの仕様理解も必要です。

これらをひとつの記事にまとめるとかなりのボリュームになってしまいそうなので、今回はまず1つ目のハードルをAIを使って楽にクリアする方法をお伝えします。
2つ目のハードルは続編として、後日公開したいと思っています。

カスタムコネクタの対応可否を判定する方法

1つ目のハードルを超えるために、雑にAIに「このAPIはカスタムコネクタで使えますか？」と質問したくなるのですが、これでは的を射た回答をもらえない可能性が高いです。
AIはTROCCOの公開情報だけではカスタムコネクタの細かい仕様までは把握できず、「できる可能性が高い、ただ確認が必要」という回答になりがちです。

そこで、確認すべき観点と判定の基準をあらかじめ決めておき、AIにはそれに沿って情報を集めて比較してもらう、という方法を考えてみました。

確認すべきAPIの仕様

カスタムコネクタでの対応可否を左右するAPIの仕様には、主にこういった要素があります。

認証方式：認証情報をどうやって渡すか、トークンに有効期限があるか
接続要件：クライアント証明書や、接続元IPの制限が必要か
リクエスト：どのHTTPメソッドで呼ぶか、1回のリクエストでデータを取得できるか
データの形式：レスポンスやリクエストボディがどの形式か
ページングの方式：大量のデータをどう分割して取得するか
レート制限：どのくらいの頻度でリクエストできるか
絞り込みのパラメータ：更新日時などで取得範囲を限定できるか

これらの要素には、カスタムコネクタでの対応可否がはっきりしているものと、カスタムコネクタとデータ転送の設計次第で対応可否が決まるものがあります。
この中で認証方式・接続要件・リクエスト・データの形式は主に前者であり、APIとカスタムコネクタの技術仕様を比較すればほぼ機械的に判定することができるので、今回はこれらの項目に絞って判定していきます。

判定の流れ

前置きが長くなりましたが、この記事でやることがはっきりしたところで、具体的な判定の流れを見ていきます。
今回は下記2つのステップです。

ステップ1 : APIリファレンスからカスタムコネクタ利用に関わる仕様を抽出
ステップ2 : 抽出した仕様を判定表と比較して利用可否を判定

ステップ1：APIリファレンスからカスタムコネクタ利用に関わる仕様を抽出

まずは、APIリファレンスから判定に必要な仕様を抜き出します。
APIリファレンスは分厚いことが多いですが、今回の判定に必要な情報は下記の4種類です。

① 認証方式

カスタムコネクタが対応している認証方式は、大きく2種類です。
ひとつは発行済みのAPIキーやトークンをHTTPヘッダに載せて送る方式。もうひとつはOAuth2.0です。
認証方式そのものに加えて、認証情報をどこに載せるかやトークンの有効期限、そしてアクセストークンとは別のトークンの取得が必要かどうかもあわせて確認します。

② 接続要件

認証が通る形式であっても、その手前で弾かれることがあります。
クライアント証明書を求めるAPIや、VPN経由でしかアクセスできないAPI、接続元IPを制限しているAPIなどが該当します。

③ リクエスト

カスタムコネクタで使えるHTTPメソッドは決まっているので、利用したいエンドポイントがその範囲に収まるかを確認します。
あわせて、目的のデータが何回のリクエストで手に入るかも確認します。「ジョブを実行して、完了を待って、結果を取得する」といった手順を踏むAPIがあるためです。

④ データの形式

カスタムコネクタで扱えるレスポンス形式はJSONが前提になっているので、扱う形式を確認します。
また、レスポンスがデータ本体なのか、ダウンロード用のURLを返すだけなのかによって対応可否が異なるため確認します。

APIの仕様抽出用プロンプトを投げる

APIリファレンスから上記の4種類の仕様のみを抜き出してもらうプロンプトを用意しました。
プロンプト内の「インプット」の3項目を埋めて、ClaudeやGeminiなどの生成AIに投げます。
ちなみにAPIリファレンスは、内容を貼り付けるよりURLで渡すほうが、AIが関連ページまで読みにいけるのでおすすめです。

# インプット
- APIリファレンス：[ここにURLを貼るか、ページの内容を貼り付ける]
- やりたいこと：[例：顧客の一覧を取得したい]
- 方向：[転送元（APIからデータを取得）／転送先（APIにデータを書き込み） のどちらか]

プロンプト①：APIの仕様をまとめる（クリックして開く）

# 役割
あなたはAPIリファレンスを読んで仕様を抜き出す担当です。
以下のAPIリファレンスを読み、後述の4項目をまとめてください。

# 重要なルール
- リファレンスに書かれていないことは推測せず、必ず「記載なし」と書いてください
- 認証方式やエンドポイントの詳細が別のページにまとまっている場合は、
  同じリファレンスサイト内のそのページも読んでください
  （推測してよいという意味ではありません。読む範囲だけを広げてください）
- 各項目に、リファレンスのどこに書いてあったか（見出し名・URL・原文の引用）を必ず添えてください
- 「このAPIが特定のツールで使えるか」の判断はしないでください。仕様を読み取ることに徹してください

# インプット
- APIリファレンス：[ここにURLを貼るか、ページの内容を貼り付ける]
- やりたいこと：[例：顧客の一覧を取得したい]
- 方向：[転送元（APIからデータを取得）／転送先（APIにデータを書き込み） のどちらか]

# まとめてほしい4項目

## ① 認証方式
- 認証方式（APIキー / Bearerトークン / OAuth2.0 / Basic認証 / その他）
- 認証情報をどこに載せるか（HTTPヘッダ / URLのクエリパラメータ / その他）
- ヘッダに載せる場合、ヘッダ名と、値の先頭に付く語（Bearer / Token / 何も付かない など）
- OAuth2.0の場合、使えるグラントタイプ
  （authorization_code / client_credentials / それ以外）と、認可URL・アクセストークンURL
- OAuth2.0で authorization_code が使える場合は、あわせて下記も調べてください
  - リダイレクトURLとして、任意のHTTPSのURL（例：https://example.com/callback）を登録できるか。localhost やカスタムURIスキームに限定されていないか
  - 認可URLに追加のパラメータの指定が必要かどうか
    （PKCE の code_challenge、リフレッシュトークンを返させる access_type=offline など）
    必要な場合は、固定値で足りるのか、リクエストごとに計算が必要な値なのかも書いてください
  - クライアントの種別（ウェブアプリ / デスクトップアプリ など）によってリダイレクトURLの制約や追加パラメータの要否が変わる場合は、種別ごとに書いてください
- 認証情報の入手方法（管理画面で発行 / 署名やJWTの生成が必要 / リクエストごとに計算 など）
- トークンやAPIキーに有効期限があるか（無期限 / N時間 / N日）。
  期限がある場合、更新に何が必要か（OAuth2.0のトークンエンドポイントで再取得できるか、それとも独自の手順が必要か）
- 目的のエンドポイントを叩く前に、アクセストークンとは別のトークンの取得が必要かどうか。
  必要な場合は、そのトークンの名称・取得用エンドポイント・有効期限・どのエンドポイントで必要になるかを書いてください
  （例：PII を含むデータを取得する際に、別途トークン発行APIを叩く必要がある など）

## ② 接続要件
- 接続元IPの制限があるかどうか。ある場合、許可リストに登録できるか
- インターネットから直接アクセスできるか
  （クライアント証明書、VPN、PrivateLink、専用線などが必要ないか）
- いずれもリファレンスに記述が見つからない場合は「制限の記載なし」と書いてください

## ③ リクエスト
- 使うエンドポイントのHTTPメソッドとパス
- 成功したときのステータスコード
- 目的のデータを手に入れるまでに、何回のリクエストが必要か。
  1回のリクエストで完結するか、複数回にまたがるかを書いてください
  （ページングのための繰り返しリクエストは、ここでの「複数回」に含めません）
- 複数回にまたがる場合は、その順序を、各ステップのHTTPメソッド・パス・成功ステータスコードとあわせて列挙してください
  （例：ジョブ発行 → 完了までポーリング → 結果の取得 など）
- 複数回にまたがる場合、**前のレスポンスで返った値（ジョブIDなど）を次のリクエストで使う必要があるか**を必ず書いてください
- 完了を待つポーリングが必要な場合、完了・失敗を判定するレスポンスのフィールド名と、取り得る値を書いてください

## ④ データの形式
- （転送元）レスポンスの形式（JSON / XML / CSV / JSON Lines など）
- （転送元）レスポンスの本文がデータ本体かどうか。
  データ本体ではなく、ダウンロード用のURLを返すだけの場合は、その旨を書いてください
- （転送元）ダウンロード用のURLを返す場合は、あわせて下記も調べてください
  - そのURLの先にある実体の形式（TSV / CSV / JSON / JSON Lines / XML など）
  - 圧縮されているかどうか、されている場合は圧縮形式（gzip / zip など）
  - 形式や圧縮の有無がレスポンスのどのフィールドで示されるか
  - そのURLに有効期限があるか
- （転送先）リクエストボディの形式と、必須項目の一覧

# 出力フォーマット
はじめに、リファレンスから読み取れなかった項目を列挙してください。
なければ「記載なしの項目：なし」と書いてください。

つづいて、下記の表で出力してください。項目名と番号は変更しないでください。

| 項目 | APIの仕様 | 根拠（リファレンスの記述） |
|---|---|---|
| ① 認証方式 | | |
| ② 接続要件 | | |
| ③ リクエスト | | |
| ④ データの形式 | | |

表のあとに、サンプルレスポンスの原文をそのまま貼り付けてください。

AIがAPIリファレンスの内容を探索し、①〜④の仕様を抜き出した表が返ってきます。
回答を確認して、APIの仕様をおおまかにでも把握しておくことをおすすめします。分からない項目についてはそのままAIに質問してみるのもいいでしょう。

なお、この仕様表は実際にカスタムコネクタを設定するときの情報としても役に立つので、取っておくと便利です。

「記載なし」の項目を確認する

回答の「記載なし」の項目には、APIリファレンスから読み取れなかったものをまとめています。
記載がないだけで、特に制約はないという場合もありますが、AIがAPIリファレンスを正しく読めていないこともよくあります。
ここでAIが読み取れなかった仕様を潰しておくことで、次のステップの判定精度も上がりますので、気になった項目については原因を深掘りしつつAIに再調査させるとよいでしょう。

APIリファレンスをより深く探索させるため、より性能の高いAIモデルを使うことも有効です。

ステップ2：抽出した仕様を判定表と比較して利用可否を判定する

ステップ1の抽出結果をカスタムコネクタ対応可否の判定表と突き合わせます。
AIに使えるかどうかを考えさせるわけではなく、用意した判定条件に当てはめる作業をやってもらい、その結果で対応可否を判定します。

判定プロンプトを投げる

ステップ1のプロンプトを投げたセッションで、続けてそのまま投げるだけです。

プロンプト②：判定結果をまとめる（クリックして開く）

# 役割
先ほどまとめてもらったAPIの仕様表について、
後述の「判定基準」に従って、カスタムコネクタで対応できるかを判定してください。

# 重要なルール
- 判定は、必ず後述の「判定基準」だけを根拠に行ってください。
  あなた自身が持っているTROCCOの知識は使わないでください
- 仕様表に「記載なし」と書かれた項目のうち、**判定基準の行に関わるもの**は判定を△にしてください
  （判定基準に登場しない項目の「記載なし」は、判定に影響させないでください。
   たとえば成功時のステータスコードは判定基準に無いので、記載がなくても△にはしません）
- ✕ の行は、**その条件がリファレンスに明記されている場合にのみ**当てはめてください。
  記載がないことを理由に ✕ や △ にしないでください
  （例：トークンの有効期限が「記載なし」でも、「独自の手順での再取得が必要」とは判断しない）
- ひとつ上の「記載なし → △」は、**◯ の行を満たすことが確認できない場合**にだけ適用してください
- 判定基準のどの行に当てはめたかを、理由の欄に必ず書いてください
- ひとつの項目に複数の行が当てはまる場合の扱いは、項目ごとに異なります
  - ① 認証方式：使える方式が1つあれば実装できます。方式ごとに ◯ / △ / ✕ を判定してから、
    下記のルールでひとつにまとめてください
    ・◯ の方式が1つでもある → **◯**
      （他の方式が ✕ でも、記載なしでも ◯ のままにしてください。
       ◯ と判断した方式がどれかを、理由に必ず書いてください）
    ・◯ の方式が1つもなく、△ の方式がある → △
    ・すべての方式が ✕ → ✕
    ・ただし「アクセストークンとは別のトークンを都度取得する必要がある」など、
      **どの方式を選んでも避けられない条件**が当てはまる場合は、上記にかかわらず ✕ にしてください
  - ②③④：すべての条件を満たす必要があります。最も厳しい判定（✕ > △ > ◯）を
    その項目の判定とし、当てはまった行をすべて理由に書いてください

# 判定基準

## ① 認証方式
- ◯ APIキーやトークンをHTTPヘッダに載せる（先頭の語はBearer / Token / 独自の語どれでもよい）
- ◯ OAuth2.0の client_credentials フローが使える
- ◯ OAuth2.0の authorization_code フローが使え、かつ下記2条件を満たす
  1. リダイレクトURLとして任意のURL（TROCCOのコールバックURL）を登録できる
  2. 認可URLに、リクエストごとに計算した値を渡す必要がない
     （PKCEの code_challenge が必須なら満たしません。
      access_type=offline のような固定値の追加パラメータは、あっても問題ありません）
- △ Basic認証
- ✕ 認証情報をURLのクエリパラメータで渡す
- ✕ OAuth2.0の authorization_code フローだが、上記2条件のいずれかを満たさない
  （満たさない条件がどれかを理由に書いてください）
- ✕ 発行済みのキーやトークンを設定するだけでは認証できない
  （リクエストごとの署名計算、独自の手順でのトークン再取得、ログインしてCookieを保持 など）
- ✕ 目的のエンドポイントを叩く前に、アクセストークンとは別のトークンを都度取得する必要がある
  （そのトークンの名称と、どのエンドポイントで必要になるかを理由に書いてください）

## ② 接続要件
- ◯ 接続元IPの制限がない、または制限についての記載がない
  （公開APIでは接続元IPの制限が明記されないのが通常です。
   制限があると明記されていない場合は「制限なし」とみなして ◯ にしてください）
- △ 接続元IPの制限があり、許可リストに登録できる
- ✕ インターネットから直接アクセスできない
  （クライアント証明書、VPN、PrivateLink などが必要）

## ③ リクエスト
- ◯（転送元）GET または POST
- ◯（転送先）GET / POST / PUT / PATCH
- ✕（転送元）GET・POST以外のメソッドが必須
- ✕（転送先）DELETEが必須
- △ 目的のデータの取得に複数回のリクエストが必要だが、前のレスポンスで返った値を使わずに取得できる
  （「最新の結果を取得する」エンドポイントがある場合など）
- ✕ 前のレスポンスで返った値（ジョブIDなど）を使って次のリクエストを叩く必要がある
  （ジョブ発行 → 完了までポーリング → 結果の取得 など。何ステップ必要かを理由に書いてください）
- ※ページングのための繰り返しリクエストは、ここでの「複数回」に含めません

## ④ データの形式
- ◯（転送元）レスポンスの本文がJSONで、それがデータ本体である
- ✕（転送元）レスポンスがXML / CSV / JSON Lines / その他
- ✕（転送元）レスポンスの本文がデータ本体ではなく、ダウンロード用のURLを返すだけ
  （URLの先の実体形式と、圧縮の有無を理由に書いてください）
- ◯（転送先）リクエストボディがJSON
- ✕（転送先）リクエストボディがJSON以外（フォーム形式 / XML / CSV / ファイル添付 など）
- ※転送先の場合、APIが返すレスポンスの形式は判定に影響しない

# 出力フォーマット

## 判定結果
| 項目 | 判定 | 当てはめた判定基準 | 理由 |
|---|---|---|---|
| ① 認証方式 | | | |
| ② 接続要件 | | | |
| ③ リクエスト | | | |
| ④ データの形式 | | | |

## 総合判定
次の2つから選び、理由を1〜2行で書いてください。
- 着手可（✕が無い）→ △があればその内容を書く
- 非対応（✕がある）→ どの項目が原因かを書く

ステップ1で抽出した仕様①〜④それぞれについての判定と、総合判定が返ってきます。

各項目の「判定」は下記のようになっています。

◯：対応可能
△：条件付きで対応可能
✕：非対応

また、「総合判定」の基準は下記のようになっています。

着手可：各項目の ✕ 判定が1つも無く、技術仕様的に対応可能と判定
非対応：各項目の ✕ が1つ以上あり、対応不可と判定

判定結果の確認

判定結果が「着手可」となったのであれば、 技術仕様的にはカスタムコネクタで対応可能 です。実際にカスタムコネクタを作成しての検証に進みましょう！
ただし、「着手可」であっても判定結果に △ が含まれる場合は、API提供元に仕様を確認する必要があったり、実装に考慮が必要な場合があります。理由も確認してご自身の環境で対応可能かどうかを判断してください。

カスタムコネクタを触り始める前に、まずこの判定を実施して技術仕様がマッチしていることを確認することで、次のステップでの確認ポイントも絞られ、よりスムーズに検証や実装に進むことができるかと思います。

※このプロンプトの判定基準は、記事執筆時点（2026年9月）での仕様を元に作成しています。
最新の情報は公式ドキュメントもあわせてご確認ください。

また、判定基準の表を記事の最後に付録としてまとめています。
判定結果を自分で確認したいときや「なぜこれは対応できないのか」を詳しく知りたいときの参考にしてみてください。

おわりに

今回はカスタムコネクタに焦点を当てて、AIを活用した実装前の仕様調査と対応可否判定をご紹介しました。
TROCCOのカスタムコネクタを検討されるかたのお役に立てれば幸いです。

ただ繰り返しになりますが、今回ご紹介した内容だけでは目的のデータ転送を実現できるとは限りません。
次のステップとして、実際にTROCCOで設定を作って動かしながら必要なデータが取れるか、ページングやレート制限は問題ないか、といった点を確認していくことになります。

次回は、2つ目のハードルであるカスタムコネクタ定義の実装部分を記事にしようと思います。それでは！

付録：判定基準の一覧

ステップ2のプロンプトでAIに渡している判定基準です。
AIの判定結果を自分で確認するときや、「なぜこれは対応できないのか」を詳しく知りたいときにご活用ください。

① 認証方式

APIの仕様	判定	理由
APIキーやトークンをHTTPヘッダに載せる	◯	先頭の語（Bearer / Token など）は自由に設定できます。URLのクエリパラメータでしか渡せないAPIは ✕ です
OAuth2.0のクライアントクレデンシャルフロー	◯	対応しています。アクセストークンURLを設定します
Basic認証	△	IDとパスワードをbase64形式に変換した文字列を自分で用意します
発行済みのキーやトークンを設定するだけでは認証できない（リクエストごとの署名計算、独自の手順でのトークン再取得、ログインしてCookieを保持など）	✕	設定できるのは固定の値だけで、実行時に値を計算したり取り直したりする仕組みがありません
目的のエンドポイントを叩く前に、アクセストークンとは別のトークンを都度取得する必要がある	✕	同上です。個人情報を含むデータの取得時に、別途トークン発行APIを叩く必要があるAPIなどが該当します
OAuth2.0の認可コードフロー（ブラウザで許可操作をするタイプ）	◯	対応しています。ただし下の2行に当てはまる場合は使えません
↳ TROCCOのリダイレクトURLを登録できない（localhost などに限定されている場合を含む）	✕	リダイレクトURLは `https://trocco.io/connections/custom_connector/callback` に固定されています
↳ 認可URLに、リクエストごとに計算した値を渡す必要がある（PKCEの `code_challenge` など）	✕	認可URLは固定の文字列として設定するため、リクエストごとに計算した値を差し込めません

APIが複数の認証方式に対応している場合は、そのうち1つでも ◯ があれば対応可（使えない方式が併存していても、◯ の方式で実装すればよい）

認可コードフローは対応条件あり（PKCE が必須のAPIは非対応）

クライアントの種別（ウェブアプリ / デスクトップアプリなど）によって、リダイレクトURLの制約や追加パラメータの要否が変わるAPIもあるため、種別ごとに確認が必要

② 接続要件

APIの仕様	判定	理由
接続元IPの制限がない	◯	リファレンスに制限の記載がない場合も、制限なしとみなします
接続元IPの制限があり、TROCCOのジョブ実行元IPを許可リストに登録できる	△	登録の運用がまわるかは利用者側での判断になります
インターネットから直接アクセスできない（クライアント証明書、VPN、PrivateLink などが必要）	✕	これらを設定する手段がありません

③ リクエスト

APIの仕様	判定	理由
転送元で使うメソッドが `GET` または `POST`	◯	転送元はこの2つのみ対応しています。これ以外のメソッドが必須なら ✕ です
転送先で使うメソッドが `GET` `POST` `PUT` `PATCH` のいずれか	◯	転送先はこの4つのみ対応しています。`DELETE` が必須なら ✕ です
目的のデータの取得に複数回のリクエストが必要だが、前のレスポンスで返った値を使わずに取得できる	△	ワークフローでタスクを並べれば組めますが、ひと手間かかります
前のレスポンスで返った値（ジョブIDなど）を使って次のリクエストを叩く必要がある	✕	ワークフローの「HTTPリクエスト」タスクは、レスポンスの内容を後続のタスクに引き継げません（残るのはステータスコードだけです）

前のレスポンスの値を次のリクエストに使う必要がある場合は、カスタムコネクタでは対応不可

ページングのための繰り返しリクエストは「複数回」には含まない

④ データの形式

APIの仕様	判定	理由
転送元でレスポンスがJSONで、それがデータ本体	◯	データの取り出しがJSON前提です。XML / CSV / JSON Lines などなら ✕ です
転送元でレスポンスがデータ本体ではなく、ダウンロード用のURLを返すだけ	✕	返ってきたURLの先を取得する手段がありません。URLの先がTSVや圧縮ファイルの場合も同様です
転送先でリクエストボディがJSON	◯	JSON前提の設計になっています。フォーム形式 / XML / CSV などは動作保証外、ファイル添付（multipart）は非対応なので ✕ です

転送先ではレスポンスのステータスコードのみ参照するため、レスポンス形式に制限はない