TROCCO #04｜TROCCO APIで柔軟なジョブの定期実行・ステータス確認

この記事を読んでる方へ

▼データマーケティングの教科書 下

初心者の方から、より詳しくなりたいという方へ。
本書ではデータマーケティングの基礎から学び、データを通じて顧客の行動や感情を理解し、 より確かな意思決定を目指します。

詳しく知りたい

みなさん、こんにちは！

これまでのTROCCOの記事では、データ転送やデータマート、ワークフローの作成・設定方法をご紹介しました。

今回はそれらをより柔軟に自動化・制御する方法として、TROCCO APIを使ったジョブの定期実行やステータス確認の手法を紹介します。

TROCCOにもスケジュール設定機能はありますが、営業日実行のような細かな指定や、ステータスに応じた後続処理の分岐を行いたい場合には、APIの活用が特に有効です。

APIトークンの発行から実際のコードまで解説していきますので、ぜひ最後までご覧ください！

TROCCO #01｜初心者でもできる！データ転送手順と設定ポイントを解説！

TROCCO #02｜データマート定義の設定方法とSQL活用例

TROCCO #03｜ワークフロー定義設定・カスタム変数を使ったループ処理の方法

TROCCO APIとは

TROCCO APIは、TROCCOの各種操作（ジョブ実行・ステータス確認・設定取得など）を外部からプログラムで実行できる機能です。
通常は管理画面（GUI）上で行う作業を、API経由で自動化・連携することができます。

TROCCO APIで実行できる主な操作は以下の通りです。

• データ転送実行／実行結果取得
• データマート実行
• ワークフロージョブ実行／実行結果取得
• データマート定義作成／更新／削除／取得
• ユーザー作成／更新／削除／取得
• 接続情報作成／更新／削除／取得

プラン上の制約としてFreeプランまたはAdvancedプラン以上の契約アカウントでのみ利用できます。

💡TROCCO APIには以下のコール数制限があります。
・Freeプラン：最大100コール/10分
・Advancedプラン以上：最大3,500コール/10分
コール数制限を超えたリクエストがあった際には429( too many requests) がステータスコードとして返却されます。コール数制限を考慮しながら実装しましょう。

TROCCO API KEYの発行

管理画面にログイン

ユーザー権限として「管理者（Admin）」以上のアクセス権があるアカウントでログインします。

TROCCO API KEY画面へ

左のサイドバー「外部連携」から「TROCCO API KEY」を選択します。

APIキーの一覧を確認できる画面が表示されます。

新規作成・設定

右上の「新規作成」ボタンをクリックし、APIキーの「名前」と「メモ（用途の補足など）」を入力して「保存」をクリックします。

API KEYの保存

発行後に表示されるAPIトークンを必ず控えておきます。
このトークンは発行時にしか表示されないため、再確認することはできません。安全な場所に保管してください。

ジョブ実行の自動化

発行したAPIキーを使って、実際にGoogle Apps Script(以下GAS)からデータ転送ジョブを実行する方法をご紹介します。

APIエンドポイント

今回実行するAPIは次の形式です。

POST https://api.trocco.io/api/v1/jobs/{job_id}/executions

ここで {job_id} は、trocco上のジョブID（URLなどから確認可能）を指定します。

GASのコード

const TROCCO_API_TOKEN = 'YOUR_API_TOKEN'; // 取得したAPIキー
const JOB_ID = '123456'; // 実行したいジョブID

function runTroccoJob() {
　const url = `https://api.trocco.io/api/v1/jobs/${JOB_ID}/executions`;

　const options = {
　　method: 'post',
　　headers: {
　　　'Authorization': `Token ${TROCCO_API_TOKEN}`,
　　　'Content-Type': 'application/json'
　　},
　　muteHttpExceptions: true
　};

　const response = UrlFetchApp.fetch(url, options);
　const result = JSON.parse(response.getContentText());

　Logger.log('ジョブ実行リクエストを送信しました');
　Logger.log(result);
}

ステータス確認の自動化（実行後のチェック）

ジョブを実行したあと、ステータスを監視することも可能です。
以下のエンドポイントを使います。

GET https://api.trocco.io/api/v1/jobs/{job_id}/executions/latest

GASのコード

function checkTroccoJobStatus() {
  const url = `https://api.trocco.io/api/v1/jobs/${JOB_ID}/executions/latest`;
  const options = {
    method: 'get',
    headers: { 'Authorization': `Token ${TROCCO_API_TOKEN}` },
  };
  const response = UrlFetchApp.fetch(url, options);
  const result = JSON.parse(response.getContentText());

  Logger.log(`最新実行ステータス: ${result.status}`);
}

転送ジョブのステータス一覧

• queued – 実行待機
• setting_up – 実行準備
• executing – 実行中
• interrupting – 実行中断
• succeeded – 実行完了（成功）
• error – 実行完了（エラー）
• canceled – 実行完了（キャンセル）
• skipped – 実行完了（スキップ）
• timeout – 実行完了（タイムアウト）

カスタム変数を指定する場合

APIでもジョブ実行時にカスタム変数を指定して動的に値を渡すことができます。

今回の例では、ジョブ定義側で設定されているカスタム変数 $id$ に、対象のアカウントID を代入して実行しています。

GASのコード

function customID(){
  var id = '1234567890'; // ←ここに実際に渡したいアカウントIDを代入します
  var url = 'https://trocco.io/api/jobs?job_definition_id=' + trocco_id;
  var headers = {
    'Authorization': 'Token ' + ${TROCCO_API_TOKEN},
    'accept': 'application/json'
  };
  var payload = 'custom_variables[][name]=$id$' + '&custom_variables[][value]=' + encodeURIComponent(id);


  var options = {
    "headers": headers,
    "method": "POST",
    "payload": payload,
    "muteHttpExceptions": true
  };
  var response = UrlFetchApp.fetch(url, options);
  var job_id = JSON.parse(response.getContentText()).id;
}

このコードでは、custom_variables[][name] にジョブ定義側で設定済みの変数名をセットし、
custom_variables[][value] に実際に渡す値を指定しています。

今回の例では、対象アカウントの id を文字列として代入し、encodeURIComponent() でURLエンコードして送信することで、文字化けや特殊文字によるエラーを防止しています。

var payload = 'custom_variables[][name]=$id$' +'&custom_variables[][value]=' + encodeURIComponent(id);

活用事例

月末3営業日の13:00にデータ転送を実行

GASのトリガーを「日付ベースのタイマー」で毎日午前9:00～10:00に設定し、今日が月末3営業日かどうかを判別します。
実行日だった場合のみ、TROCCO APIを午後1時に実行するためのトリガーを作成します。

TROCCOにはスケジュール設定機能もあり、毎日10時や毎月1日の実行などは管理画面から設定可能です。
しかし、営業日や祝日を考慮した条件付きの実行を行いたい場合は、スクリプトから任意のタイミングで制御する方法がおすすめです。

また、不要な日の実行をなくすことで、無駄な処理時間の削減にもつながります。

アカウント設定依頼があったタイミングでデータ転送の実行

GASのトリガーを「スプレッドシート」「編集時」に設定することで、アカウント設定の依頼があったタイミングで自動的に処理が開始されます。

依頼内容に含まれるアカウントIDをカスタム変数としてTROCCO APIに渡し、データ転送を実行します。

転送後に結果のステータスを確認し、問題がなければアカウントを任意のDB・DWHに登録します。

これにより、手作業でアカウントIDの実行権限を確認したり登録したりする負荷を削減できます。

まとめ

本記事では、TROCCO API の基本的な設定方法から、実際の活用事例までをご紹介しました。

API を利用することで、カスタム変数を使った柔軟なデータ転送や、転送結果に応じた自動化ワークフローの構築が可能になります。今回の事例を参考に、データ運用もぜひ効率化してみてください。

さらに、TROCCO で整備したデータは Looker Studio のダッシュボードと連携することで、可視化まで一気通貫で活用できます。日々のデータ更新を API で自動化し、Looker  Studio上で最新の指標をいつでも確認できる仕組みを整えることで、よりスムーズで再現性の高いデータ活用が実現します。

他にもTROCCOについては、TROCCO(トロッコ)とは？主要機能・特徴・料金・類似サービスとの違いを解説で、主要機能や導入支援についてご紹介していますので、あわせてご覧ください。

またD2CではTROCCOによるデータ処理基盤の整備から、Looker Studioを用いた可視化・レポーティングの設計・構築まで一貫した支援を行っています。

詳しくはこちらよりお気軽にお問い合わせください。

この記事を読んでる方へ

▼データマーケティングの教科書 下

初心者の方から、より詳しくなりたいという方へ。
本書ではデータマーケティングの基礎から学び、データを通じて顧客の行動や感情を理解し、 より確かな意思決定を目指します。

詳しく知りたい