みなさん、こんにちは。
TROCCOを使ってデータ連携をしていると、「社内 API と連携したいけど方法がない」「HTTPコネクタだと設定がちょっとつらい」といった場面に出会うことは意外と多いのではないでしょうか。
そんなときに活躍するのがTROCCOのカスタムコネクタです！
カスタムコネクタを使うと、TROCCOが標準でサポートしていない APIでも、自分で定義して連携できるようになります。
この記事では、カスタムコネクタの概要や設定手順など詳しく解説しますので、最後までご覧ください！
過去記事はこちらから↓
TROCCO #01｜初心者でもできる！データ転送手順と設定ポイントを解説！
TROCCO #02｜データマート定義の設定方法とSQL活用例
TROCCO #03｜ワークフロー定義設定・カスタム変数を使ったループ処理の方法
TROCCO #04｜TROCCO APIで柔軟なジョブの定期実行・ステータス確認
TROCCOのカスタムコネクタとは
多くのサービス API は世の中に存在するものの、TROCCOの標準コネクタとして対応されていないケースも少なくありません。
- 自社内 API / SaaS（非公開）
- 新興サービスの API
- 社内運用ツールへの通知/データ送信
- 従来 TROCCOでは HTTP/HTTPS コネクタを使わないと対応できなかった API
こうしたケースでも API の仕様に合わせた接続処理 + 転送処理ができる のがカスタムコネクタです。つまり「TROCCOの連携対象を自分で増やせる」という点が最大のメリットになります。
また、1 回カスタムコネクタを定義すると 複数のプロジェクトで再利用可能 であり、運用負担も大幅に軽減できます。
カスタムコネクタの設定方法
事前準備
カスタムコネクタを作る前に、データ取得／送信対象の API の仕様や認証方法を整理しておきましょう。API 側での準備は次のようになります。
API 認証が必要な場合
- API キー認証 を使う API は事前に API キーを発行しておく必要があります。
- OAuth2 認証 を使う API は、クライアントアプリ登録とリダイレクト URL の設定が必要です。
リダイレクトURL：https://trocco.io/connections/custom_connector/callback
転送元用カスタムコネクタの作成（データ取得）
今回は例として、graph APIのAd Account Ad Imagesをカスタムコネクタを使って取得します。
https://developers.facebook.com/docs/marketing-api/reference/ad-account/adimages?locale=ja_JP
GET /v24.0/{ad-account-id}/adimages HTTP/1.1 Host: graph.facebook.com
データ転送でFacebook Ad Insightsを取得することは可能ですが、adImagesを選択することができないため、カスタムコネクタを使用します。
「カスタムコネクタ」から「新規作成」をクリック
「転送元として作成」を選択
基本情報（名前／説明） を入力
APIドキュメントURL
カスタムコネクタで利用するREST APIのドキュメントを入力することで、認証情報や各種設定を自動的に定義できます。
自動生成に対応している項目は以下のとおりです。
- コネクタ情報・認証情報
- ベースURL
- 認証種別
- 認証ヘッダー名
- 認証スキーム
- エンドポイント
- パス
- HTTPメソッド
- パラメータ
- HTTPヘッダ
- JSONPathルート
- ページング設定
ベースURL
カスタムコネクタで取得対象とするREST APIのベースURLを入力します。
ベースURLは、すべてのAPIエンドポイントの共通となる基本URLです。
https://graph.facebook.com/v17.0
認証情報
認証種別を選択します。
APIキーまたはOAuth2に対応しており、選択した認証種別に応じて入力する認証情報が異なります。
API エンドポイントを追加
名前
エンドポイントのわかりやすい名前をつけます。
パス
ベースURLを除いたAPIエンドポイントのパスを入力します。
パスを動的に指定する場合は、パスパラメータを中括弧（{}）で囲んで記述します。
今回はアカウントIDを動的に変更したいので、act_{account}と指定します。
例：/act_{account}/adimages?fields=id,name,hash,url,permalink_url,width,height
HTTPメソッド
HTTPメソッドを選択します。GETのみサポートしています。
JSONPathルート
レスポンスからデータを抽出する際のルートとするパスをJSONPath記法（新しいタブで開く）で指定します。
今回のadImagesは以下のJSONフォーマットの結果が返されるため、$.data.*とdata配下を指定します。
{
"data": [],
"paging": {},
"summary": {}
}
必要な設定が完了したら「保存」をクリックしてください。
転送設定の作成
カスタムコネクタを作成し接続情報を設定したら、通常のコネクタと同じように 転送設定 を作成します。
これはどのデータソースからどのデータを取得／送信するかを指定するものです。
今回はスプレッドシートに全件洗い出しで転記させます。
転送設定の新規作成
サイドバー「転送設定」から新規作成します。
転送元には「カスタムコネクタ」、転送先には「Google Spreadsheets」を選択します。
転送元 カスタムコネクタの基本設定の入力
カスタムコネクタ
先ほど設定したカスタムコネクタを選択します。
取得対象
取得対象には、プルダウンからカスタムコネクタ内のエンドポイントを選択します。
Path Parameterでは、カスタムコネクタで設定した act_{account} の {account} の値を入力します。
転送先 Google Spreadsheetsの設定
転送先としてスプレッドシートを選択し、IDやシート名を入力します。
必要な設定が完了したら「保存」をクリックしてください。
これで必要な設定は完了です。
データ転送を実行すると、adImageカラムをスプレッドシートへ転記できます。
まとめ
TROCCOのカスタムコネクタは、API 連携の自由度を大幅に高め、標準コネクタでは実現できない連携を可能にします。
API の仕様に合わせて動的にリクエストを変えられるため、DWH を中心としたデータパイプライン構築にも最適です。
これを機にぜひ活用してみてください！
