# Node.js Canary 用のライブラリ関数 このセクションでは、Node.js ランタイムを使用して Canary スクリプトで使用できるライブラリ関数について説明します。 **Topics** + [addExecutionError(errorMessage, ex);](#Library_function_Nodejs_addExecutionError_Nodecanary) + [getCanaryName();](#Library_function_Nodejs_getCanaryName) + [getCanaryArn();](#Library_function_Nodejs_Nodecanary) + [getCanaryUserAgentString();](#Library_function_Nodejs_getCanaryUserAgentString_Nodecanary) + [getRuntimeVersion();](#Library_function_Nodejs_getRuntimeVersion_Nodecanary) + [getLogLevel ();](#Library_function_Nodejs_getLogLevel_Nodecanary) + [setLogLevel();](#Library_function_Nodejs_setLogLevel_Nodecanary) + [executeStep(stepName, functionToExecute, [stepConfig])](#Library_function_Nodejs_executestep_Nodecanary) + [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#Library_function_Nodejs_executeHttpStep) ## addExecutionError(errorMessage, ex); `errorMessage` はエラーの詳細を示し、`ex` は発生した例外を示します `addExecutionError` を使用すると、Canary の実行エラーを設定できます。これにより、スクリプトの実行を中断することなく Canary を失敗させることができます。また、`successPercent` メトリクスにも影響を与えません。 Canary スクリプトの成功または失敗を確認するために重要でない場合にのみ、エラーを実行エラーとして追跡するようにします。 `addExecutionError` の使用例を次に示します。ここでは、エンドポイントの可用性をモニターリングしながら、ページが読み込まれた後にスクリーンショットを取得しています。スクリーンショットの作成に失敗したとしても、エンドポイントの可用性が判断されるわけではないため、スクリーンショットの作成中に発生したすべてのエラーは、キャッチした上で実行エラーとして追加します。可用性に関するメトリックスには、依然としてエンドポイントが起動し実行中であることが示されていますが、Canary のステータスは失敗としてマークされています。次に示すコードブロックのサンプルでは、このようなエラーをキャッチし、実行エラーとして追加します。 ``` try {await synthetics.executeStep(stepName, callbackFunc);} catch(ex) {synthetics.addExecutionError('Unable to take screenshot ', ex);} ``` ## getCanaryName(); Canary の名前を返します。 ## getCanaryArn(); Canary の ARN を返します。 ## getCanaryUserAgentString(); canary のカスタムユーザーエージェントを返します。 ## getRuntimeVersion(); この関数は、ランタイムバージョン `syn-nodejs-3.0` 以降で使用できます。これは、Canary の Synthetics ランタイムバージョンを返します。例えば、戻り値は `syn-nodejs-3.0` になる可能性があります。 ## getLogLevel (); Synthetics ライブラリの現在のログレベルを取得します。取り得る値には以下のものがあります。 + `0` – デバッグ + `1` – 情報 + `2` – 警告 + `3` – エラー 例: ``` let logLevel = synthetics.getLogLevel(); ``` ## setLogLevel(); Synthetics ライブラリのログレベルを設定します。取り得る値には以下のものがあります。 + `0` – デバッグ + `1` – 情報 + `2` – 警告 + `3` – エラー 例: ``` synthetics.setLogLevel(0); ``` ## executeStep(stepName, functionToExecute, [stepConfig]) 指定されたステップを実行します。ステップは、開始/成功/失敗のログ記録、成功/失敗と所要時間のメトリクスでラップされます。 `executeStep` 関数は、次のことも行います。 + ステップの開始をログに記録 + タイマーを開始 + 指定された関数を実行 + 関数が正常に戻ると、成功としてカウント。関数がスローされると、失敗としてカウント + タイマーを終了 + ステップが合格したか失敗したかをログに記録します。 + `stepName SuccessPercent` メトリクスを出力。合格の場合は 100、不合格の場合は 0 + `stepName Duration metric` メトリクスを出力。値は、ステップの開始時刻と終了時刻に基づきます + functionToExecute が返した内容を返すか、` functionToExecute` がスローした内容を再スロー + Canary のレポートにステップ実行の概要を追加 **例** ``` await synthetics.executeStep(stepName, async function () { return new Promise((resolve, reject) => { const req = https.request(url, (res) => { console.log(`Status: ${res.statusCode}`); if (res.statusCode >= 400) { reject(new Error(`Request failed with status ${res.statusCode} for ${url}`)); } else { resolve(); } }); req.on('error', (err) => { reject(new Error(`Request failed for ${url}: ${err.message}`)); }); req.end(); }); }); ``` ## executeHttpStep(stepName, requestOptions, [callback], [stepConfig]) 提供された HTTP リクエストをステップとして実行し、`SuccessPercent` (pass/fail) および `Duration` メトリクスを発行します。 **executeHttpStep** は、リクエストで指定されたプロトコルに応じて、HTTP または HTTPS ネイティブ関数のいずれかを内部で使用します。 この関数は、Canary のレポートにステップ実行の概要も追加します。概要には、次のような各 HTTP リクエストの詳細が含まれます。 + 開始時間 + 終了時間 + ステータス (PASSED/FAILED) + 失敗の理由 (失敗した場合) + リクエスト/レスポンスヘッダー、本文、ステータスコード、ステータスメッセージ、パフォーマンスタイミングなどの HTTP 呼び出しの詳細。 **Topics** + [パラメータ](#Library_function_Nodejs_executeHttpStep_parameters_Nodecanary) + [executeHttpStep の使用例](#Library_function_Nodejs_executeHttpStep_examples_Nodecanary) ### パラメータ **stepName({{文字列}})** ステップの名前を指定します。この名前は、このステップの CloudWatch メトリクスを発行する場合にも使用されます。 **requestOptions({{オブジェクトまたは文字列}})** このパラメータの値には、URL、URL 文字列、またはオブジェクトを指定できます。オブジェクトの場合、HTTP リクエストを行うために設定可能なオプションのセットである必要があります。Node.js ドキュメントの [http.request(options[, callback])](https://nodejs.org/api/http.html#http_http_request_options_callback) のすべてのオプションをサポートしています。 これらの Node.js オプションに加えて、**requestOptions** では、追加のパラメータ `body` がサポートされます。`body` パラメータを使用して、データをリクエスト本文として渡すことができます。 **callback({{レスポンス}})** (オプション) これは HTTP レスポンスで呼び出されるユーザー関数です。レスポンスは、[Class: http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage) のタイプです。 **stepConfig({{オブジェクト}})** (オプション) このパラメータを使用して、このステップについて、異なる設定でグローバル Synthetics 設定を上書きします。 ### executeHttpStep の使用例 次の一連の例は、このオプションのさまざまな用途を説明するために、相互に関連しています。 この最初の例では、リクエストパラメータを設定します。**requestOptions** として URL を渡すことができます: ``` let requestOptions = 'https://www.amazon.com'; ``` または、一連のオプションを渡すことができます: ``` let requestOptions = { 'hostname': 'myproductsEndpoint.com', 'method': 'GET', 'path': '/test/product/validProductName', 'port': 443, 'protocol': 'https:' }; ``` 次の例では、レスポンスを受け入れるコールバック関数を作成します。デフォルトでは、**コールバック**を指定しない場合、CloudWatch Synthetics はステータスが 200 から 299 の範囲であることを検証します。 ``` // Handle validation for positive scenario const callback = async function(res) { return new Promise((resolve, reject) => { if (res.statusCode < 200 || res.statusCode > 299) { throw res.statusCode + ' ' + res.statusMessage; } let responseBody = ''; res.on('data', (d) => { responseBody += d; }); res.on('end', () => { // Add validation on 'responseBody' here if required. For ex, your status code is 200 but data might be empty resolve(); }); }); }; ``` 次の例では、グローバル CloudWatch Synthetics の設定を上書きするこのステップの設定を作成します。この例のステップ設定では、レポートでリクエストヘッダー、レスポンスヘッダー、リクエスト本文 (投稿データ)、およびレスポンス本文を許可し、「X-Amz-Security-Token」および「Authorization」ヘッダーの値を制限します。デフォルトでは、セキュリティ上の理由から、これらの値はレポートに含まれません。それらを含めるように選択した場合、データは S3 バケットにのみ保存されます。 ``` // By default headers, post data, and response body are not included in the report for security reasons. // Change the configuration at global level or add as step configuration for individual steps let stepConfig = { includeRequestHeaders: true, includeResponseHeaders: true, restrictedHeaders: ['X-Amz-Security-Token', 'Authorization'], // Restricted header values do not appear in report generated. includeRequestBody: true, includeResponseBody: true }; ``` この最後の例では、リクエストを **executeHttpStep** に渡し、ステップに名前を付けます。 ``` await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig); ``` この一連の例では、CloudWatch Synthetics はレポートの各ステップの詳細を追加し、**stepName** を使用して各ステップのメトリクスを生成します。 `Verify GET products API` ステップの `successPercent` および `duration` メトリクスが表示されます。API 呼び出しステップのメトリクスをモニターリングすることで、API のパフォーマンスをモニターリングできます。 これらの関数を使用する完全なスクリプトのサンプルについては、「[マルチステップ API Canary](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps)」を参照してください。