Puppeteer ランタイムを使用した Node.js Canary スクリプトの記述

CloudWatch Synthetics Canary を最初から作成する

次の例は、Synthetics の最小の Canary スクリプトを示しています。このスクリプトは、合格して正常な実行となり、文字列を返します。不合格となる Canary の例を確認するには、let fail = false; を let fail = true; に変更します。

Canary スクリプトのエントリポイント関数を定義する必要があります。Canary の ArtifactS3Location として指定した先の Amazon S3 にファイルがアップロードされる方法を確認するには、これらのファイルを /tmp フォルダに作成します。Canary アーティファクトは書き込み可能な唯一のディレクトリであるため、すべて /tmp に保存する必要があります。スクリプトによって作成されたスクリーンショットやその他のファイルについては、スクリーンショットパスが /tmp に設定されていることを確認してください。Synthetics は、 /tmp のファイルを S3 バケットに自動的にアップロードします。

/tmp/<name>

スクリプトを実行すると、合格/不合格のステータスと所要時間のメトリクスが CloudWatch に発行され、/tmp の下のファイルが S3 にアップロードされます。

const basicCustomEntryPoint = async function () {

    // Insert your code here

    // Perform multi-step pass/fail check

    // Log decisions made and results to /tmp

    // Be sure to wait for all your code paths to complete
    // before returning control back to Synthetics.
    // In that way, your canary will not finish and report success
    // before your code has finished executing

    // Throw to fail, return to succeed
    let fail = false;
    if (fail) {
        throw "Failed basicCanary check.";
    }

    return "Successfully completed basicCanary checks.";
};

exports.handler = async () => {
    return await basicCustomEntryPoint();
};

次に、AWS SDK を使用して、Synthetics のログ記録を使用して呼び出しを行うようにスクリプトが拡張されます。デモのために、このスクリプトは Amazon DynamoDB クライアントを作成し、DynamoDB listTables API を呼び出します。リクエストに対するレスポンスを記録し、リクエストが成功したかどうかに応じて合格または不合格を記録します。

const log = require('@aws/synthetics-logger');
const AWS = require('aws-sdk');
// Require any dependencies that your script needs
// Bundle additional files and dependencies into a .zip file with folder structure
// nodejs/node_modules/additional files and folders

const basicCustomEntryPoint = async function () {

    log.info("Starting DynamoDB:listTables canary.");

    let dynamodb = new AWS.DynamoDB();
    var params = {};
    let request = await dynamodb.listTables(params);
    try {
        let response = await request.promise();
        log.info("listTables response: " + JSON.stringify(response));
    } catch (err) {
        log.error("listTables error: " + JSON.stringify(err), err.stack);
        throw err;
    }

    return "Successfully completed DynamoDB:listTables canary.";
};

exports.handler = async () => {
    return await basicCustomEntryPoint();
};

Node.js Canary ファイルのパッケージング

syn-nodejs-puppeteer-11.0 以降の場合

古いパッケージング構造 (syn-nodejs-puppeteer-10.0 以前) は、新しいバージョンでも引き続きサポートされています。

以下のいずれかのオプションを使用してスクリプトを作成します。

• .js ファイル (CommonJS 構文)

• .mjs ファイル (ES モジュール構文)

ES モジュールの場合は、以下のいずれかのオプションを使用します。

• .js ファイル (CommonJS 構文)

• .mjs ファイル (ES モジュール構文)

パッケージ構造は以下のとおりです。

• ルートレベルのハンドラーファイル (index.js/index.mjs)

• オプションの設定ファイル (synthetics.json)

• node_modules の追加依存関係 (必要な場合)

パッケージング構造の例:

  my_function/
├── index.mjs
├── synthetics.json
├── helper-utils.mjs
└── node_modules/
    └── dependencies

パッケージ化するには、以下のステップに従います。

1. 依存関係 (存在する場合) をインストールします。

   npm install

2. .zip パッケージを作成します。

   zip -r my_deployment_package.zip

syn-nodejs-puppeteer-11.0 以下の場合

Amazon S3 を使用する場合は、以下の構造が必要です。

  nodejs/
└── node_modules/
    └── myCanaryFilename.js

syn-nodejs-puppeteer-3.4+ でオプションのサブフォルダサポートを追加するには:

nodejs/
└── node_modules/
    └── myFolder/
        └── myCanaryFilename.js

注記

設定のハンドラーパスは、ファイルの場所と一致する必要があります。

ハンドラー名

スクリプトのエントリポイントのファイル名に一致するように、Canary のスクリプトのエントリポイント (ハンドラー) を myCanaryFilename.functionName として設定します。syn-nodejs-puppeteer-3.4 より前のランタイムを使用している場合は、functionName は handler である必要があります。 syn-nodejs-puppeteer-3.4 以降を使用している場合、ハンドラーとして任意の関数名を選択できます。syn-nodejs-puppeteer-3.4 以降を使用している場合、オプションで Canary を nodejs/node_modules/myFolder/my_canary_filename などの別のフォルダに保存することもできます。別のフォルダに保存する場合は、スクリプトエントリポイントでそのパスを指定します ( myFolder/my_canary_filename.functionName など)。

既存の Puppeteer スクリプトを変更して Synthetics の Canary として使用する

このセクションでは、Puppeteer スクリプトを変更して Synthetics の Canary スクリプトとして実行する方法について説明します。Puppeteer の詳細については、「Puppeteer API v1.14.0」を参照してください。

まず、次の Puppeteer スクリプトの例から始めます。

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({path: 'example.png'});

  await browser.close();
})();

変更の手順は次のとおりです。

• handler 関数を作成してエクスポートします。このハンドラーは、スクリプトのエントリポイント関数です。 syn-nodejs-puppeteer-3.4 より前のランタイムを使用している場合、ハンドラー関数には handler という名前を付ける必要があります。syn-nodejs-puppeteer-3.4 以降を使用している場合、関数には任意の名前を付けることができますが、スクリプトで使用されている名前と同じである必要があります。また、syn-nodejs-puppeteer-3.4 以降を使用している場合は、スクリプトを任意のフォルダに保存し、そのフォルダをハンドラー名の一部として指定できます。

  const basicPuppeteerExample = async function () {};
  
  exports.handler = async () => {
      return await basicPuppeteerExample();
  };

• Synthetics 依存関係を使用します。

  var synthetics = require('@aws/synthetics-puppeteer');

• Puppeteer の Page オブジェクトを取得するには、Synthetics.getPage 関数を使用します。

  const page = await synthetics.getPage();

  Synthetics.getPage 関数から返されるページオブジェクトには、ログ記録用にインストルメント化された page.on、request、response、および requestfailed の各イベントがあります。また、Synthetics は、ページのリクエストおよびレスポンス用の HAR ファイルの生成を設定し、ページの送信リクエストのユーザーエージェントヘッダーに Canary ARN を追加します。

これで、スクリプトを Synthetics の Canary として実行できるようになりました。更新されたスクリプトは次のとおりです。

var synthetics = require('@aws/synthetics-puppeteer');  // Synthetics dependency

const basicPuppeteerExample = async function () {
    const page = await synthetics.getPage(); // Get instrumented page from Synthetics
    await page.goto('https://example.com');
    await page.screenshot({path: '/tmp/example.png'}); // Write screenshot to /tmp folder
};

exports.handler = async () => {  // Exported handler function
    return await basicPuppeteerExample();
};

関連トピック

• 環境変数

• カスタマーマネージド型キーを使用した環境変数の保存時の暗号化

• 転送中の環境変数の暗号化

• Canary に静的 IP アドレスの使用を強制する