メインコンテンツへスキップ

レポートAPI - Google Sheetsカスタムインテグレーション

Eva Ferreira
  • 更新

このチュートリアルでは、実行後のWebhook、JavaScript、mablレポートAPIを使用して、mablテストの結果をGoogle Sheetに追加するカスタムインテグレーションの作成方法について説明します。

開始する前に

このカスタムレポートワークフローをセットアップするには、あなた、またはチームの誰かが以下のことに精通している必要があります。

  • Webhookの作成
  • カスタムJavaScriptコードの作成とメンテナンス
  • APIの操作

APIのセットアップ

このワークフローを実装するには、Google Sheets APIおよびmablレポートAPIへのアクセスが必要です。

Google Sheets API

Google Sheets APIを使ってGoogle Sheetをプログラムで編集するには、Google Cloudのプロジェクトを使用する必要があります。このチュートリアルに関しては、無料枠のGoogle Cloudプロジェクトで十分です。以下の手順に沿って、Google CloudのプロジェクトとWebhookからアクセスするGoogle Sheetを用意します。

  1. まだ作成していない場合は、Google Cloudのプロジェクトを作成します (無料枠が利用できます)。
  2. 作成したプロジェクトでSheets APIを有効にします。
  3. WebhookがSheets APIとの認証に使用するサービスアカウントを作成します。 このサービスアカウントには、役割や権限を付与する必要はありません。
  4. ステップ (3) のサービスアカウント用のキーを作成します。このキーはお使いのコンピューターに安全にダウンロードされます。 Webhookコードでこのキーを使用して、Sheets APIとの認証を行います。
  5. 新しいGoogle Sheetを作成するか、データを書き込む既存のGoogle Sheetを開きます。
  6. [共有] ボタンをクリックして、ステップ (3) で作成したサービスアカウントのメールアドレスと、編集者としてGoogle Sheetを共有します。

mablレポートAPI

ワークスペースの所有者にmabl Viewer APIキーを作成してもらうか、既存のmabl Viewer APIキーを使用します。Webhookコードでこのキーを使用して、mablレポートAPIとの認証を行います。

Webhookコード

クラウド実行後にmablから呼び出すことができる実行後のWebhookの作成を行います。 たとえば、Google Cloud FunctionやAWS Lambdaとして、このWebhookを作成することができます。
大まかに言うと、このWebhookコードは、mablのプラン実行が完了したときに以下を実行します。

  1. 実行後のペイロードからプラン実行IDを抽出します。 plan_execution.id
  2. mablレポートAPIを使用して抽出されたプラン実行IDのプラン実行結果を取得します。
  3. プラン実行結果を行と列から成るフラットなスプレッドシート形式に変換します。
  4. このフラットなスプレッドシート形式の結果を、Google Sheets APIのセットアップ時に共有したGoogle Sheetに追加します。

ライブラリのインポート

まず、このWebhookコードには、GoogleおよびmablのAPIとやり取りするためのgoogleapisおよびaxiosライブラリが必要です。 次のように、NPMを使用して、NodeJSプロジェクトにこれらをインストールします。

npm install googleapis@111 axios@1.3.3 --save

これらのライブラリをインポートし、mablレポートAPIおよびGoogle Sheetsとやり取りするための情報を設定して、Webhookコードを開始します。

API情報の設定

MABL_API_KEY、SPREADSHEET_ID、SPREADSHEET_PAGE、GOOGLE_SA_CREDENTIALS_FILEの値を適切な値に置き換えます。

const {google} = require('googleapis');
const axios = require('axios');

// mabl API info
const MABL_API_KEY = '<API-KEY>';
const MABL_ENDPOINT_URL = 'https://api.mabl.com/results/planRun';

// Spreadsheet that has been shared with Google Service Account email address.
// Spreadsheet ID can be found in the URL for the spreadsheet like https://docs.google.com/spreadsheets/d/SPREADSHEET-ID-IS-HERE
const SPREADSHEET_ID = '<SPREADSHEET-ID>';
const SPREADSHEET_PAGE = 'Sheet1';

// Google scopes needed to append to spreadsheet
const SCOPES = ['https://www.googleapis.com/auth/spreadsheets'];

// File containing Google Service Account key created and downloaded in Setup step (4)
const GOOGLE_SA_CREDENTIALS_FILE = 'path/to/google-service-account-key.json';

テスト結果フィールドの定義

次に、順に抽出してスプレッドシートにプッシュするフィールドを定義します。 特定のフィールドが存在しないか、フィールドに実行結果の値がない場合、生成されるスプレッドシートのこの行のセルは空欄になります。 以下に示すフィールドは、ここに示された順序で、Google Sheetで定義される列に対応している必要があります。ただし、Google Sheetの列見出しでは、列を表すのにこれとまったく同じフィールド名を使用する必要はありません。

// Ordered fields on individual test runs
const TEST_RUN_FIELDS = [
  "initial_url",
  "browser",
  "browser_version",
  "execution_runner_type",
  "scenario_name",
  "test_id",
  "test_version",
  "test_name",
  "test_type",
  "branch",
  "test_run_id",
  "test_run_app_url",
  "is_ad_hoc_run",
  "start_time",
  "end_time",
  "run_time",
  "status",
  "success",
  "failure_category",
  "emulation_mode"
];

// Ordered fields on plan runs, to be appended after the test run fields.
const PLAN_RUN_FIELDS = [
  "workspace_name",
  "plan_id",
  "plan_run_id",
  "plan_name",
  "trigger_type",
  "triggering_deployment_event_id",
  "application_name",
  "environment_name",
  "status",
  "success"
];

Webhook関数の作成

Webhookでジョブを実行するのに必要な関数を作成します。 最初に、特定のプラン実行IDで、詳細なテスト実行結果を取得し、上記のフィールドに対応するフラットな値のリストに変換するステップ (2) および (3) の関数を作成します。

async function getPlanRunResults(id) {
  const response = await axios.get(`${MABL_ENDPOINT_URL}/${id}`, {
    auth: {
      username: 'key',
      password: MABL_API_KEY,
    }
  });
  return response.data.test_results.map(result => {
    const testRunFields = TEST_RUN_FIELDS.map(field => result[field]);
    const planRunFields = PLAN_RUN_FIELDS.map(field => response.data[field]);
    return [...testRunFields, ...planRunFields];
  });
}

次に、Googleとの認証を行うためのサービスアカウントのクレデンシャルを読み込み、これらを使ってフラットな実行結果をスプレッドシートにプッシュする関数を作成します。

async function loadGoogleCredentials(filename) {
  return new google.auth.GoogleAuth({
    keyFile: filename,
    scopes: SCOPES,
  });
}

async function appendToSheet(googleAuth, data) {
  const sheets = google.sheets({version: 'v4', auth: googleAuth});
  return await sheets.spreadsheets.values.append({
    spreadsheetId: SPREADSHEET_ID,
    range: SPREADSHEET_PAGE,
    valueInputOption: 'RAW',
    insertDataOption: 'INSERT_ROWS',
    resource: {
      values: data
    }
  });
}

最後に、トップレベル関数でこれらの関数を使用して、Webhookのペイロードを受け取り、詳細な実行結果をGoogle Sheetにプッシュします。

async function handlePlanRunWebhook(webhookPayload) {
  const planRunId = webhookPayload.plan_execution.id;
  const planRunResult = await getPlanRunResults(planRunId);
  const googleAuth = await loadGoogleCredentials(GOOGLE_SA_CREDENTIALS_FILE);
  await appendToSheet(googleAuth, planRunResult);
  console.log(`Successfully processed plan run ID [${planRunId}]`);
}

実行後のWebhookの作成

このWebhookが機能する状態になったら、各実行後に呼び出される実行後のWebhookとしてURLを指定します。

関連記事