# Canary 設計図の使用 このセクションでは、Canary の各設計図と、各設計図に最も適合するタスクについて詳しく説明します。設計図は、以下の Canary タイプのために提供されています: **Topics** + [ハートビートのモニターリング](#CloudWatch_Synthetics_Canaries_Blueprints_Heartbeat) + [API Canary](#CloudWatch_Synthetics_Canaries_Blueprints_API) + [リンク切れチェッカー](#CloudWatch_Synthetics_Canaries_Blueprints_Broken_Links) + [ビジュアルモニターリングの設計図](#CloudWatch_Synthetics_Canaries_Blueprints_VisualTesting) + [Canary Recorder](#CloudWatch_Synthetics_Canaries_Blueprints_Recorder) + [GUI ワークフロービルダー](#CloudWatch_Synthetics_Canaries_Blueprints_GUI_Workflow) + [マルチチェックのブループリント](#CloudWatch_Synthetics_Canaries_Blueprints_Multichecks_Blueprint) + [マルチチェックブループリント Canary の作成](CloudWatch_Synthetics_Canaries_MultiCheck_Blueprint.md) 設計図を使用して Canary を作成する場合、CloudWatch コンソールの各フィールドに入力するに従って、作成中の Canary がページの [**スクリプトエディタ**] 領域に Node.js スクリプトとして表示されます。この領域で Canary を編集し、さらにカスタマイズすることもできます。 ## ハートビートのモニターリング ハートビートスクリプトは、指定した URL をロードし、ページのスクリーンショットと HTTP アーカイブファイル (HAR ファイル) を保存します。また、アクセスした URL のログも保存します。 HAR ファイルを使用して、ウェブページに関する詳細なパフォーマンスデータを表示できます。ウェブリクエストのリストを分析し、項目の読み込み時間などのパフォーマンス問題を検出できます。 Canary が `syn-nodejs-puppeteer-3.1` 以降のランタイムバージョンを使用している場合、ハートビートモニターリングブループリントを使用して複数の URL をモニターリングし、Canary 実行レポートのステップの概要で各 URL のステータス、期間、関連付けられたスクリーンショット、失敗の理由を確認できます。 ## API Canary API Canary は、REST API の基本的な読み取り関数と書き込み関数をテストできます。RESTは *Representational State Transfer* の略であり、開発者が API を作成するときに従う一連のルールです。これらのルールの 1 つでは、特定の URL へのリンクがデータを返す必要があることを指定しています。 Canary は任意の API で動作し、すべてのタイプの機能をテストできます。各 Canary は複数の API 呼び出しを行うことができます。 ランタイムバージョン `syn-nodejs-2.2` 以降を使用する Canary では、API Canary ブループリントは、API を HTTP ステップとしてモニターリングする複数ステップの Canary をサポートします。1 つの Canary で複数の API をテストできます。各ステップは、異なる URL にアクセスしたり、異なるヘッダーを使用したり、ヘッダーとレスポンス本文を取得するかどうかについて異なるルールを使用したりできる個別のリクエストです。ヘッダーとレスポンス本文を取得しないことで、機密データが記録されないようにできます。 API Canary 内の各リクエストは、次の情報で構成されます。 + *エンドポイント*。リクエストする URL です。 + *メソッド*。サーバーに送信されるリクエストのタイプです。REST API は、GET (読み取り)、POST (書き込み)、PUT (更新)、PATCH (更新)、DELETE (削除) の各オペレーションをサポートしています。 + *ヘッダー*。クライアントとサーバーの両方に情報を提供します。これらは認証に使用され、本文の内容に関する情報を提供します。有効なヘッダーのリストについては、「[HTTPヘッダー](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)」をご参照ください。 + *データ* (または*本文*)。サーバーに送信される情報を含みます。これは、POST、PUT、PATCH、または DELETE の各リクエストでのみ使用されます。 **注記** API Canary ブループリントは、Playwright ランタイムではサポートされていません。 API Canary ブループリントは、GET メソッドと POST メソッドをサポートしています。この設計図を使用する場合は、ヘッダーを指定する必要があります。例えば、**Authorization** を **[キー]** として指定し、必要な認可データを **[値]** として指定できます。 POST リクエストをテストする場合は、**[データ]** フィールドに書き込むコンテンツも指定します。 **API Gateway との統合** API ブループリントは Amazon API Gateway と統合されています。これにより、API Gateway API やステージを Canary と同じ AWS アカウントやリージョンから選択したり、API Gateway から Swagger テンプレートをアップロードして、クロスアカウントとクロスリージョン API のモニターリングを行ったりすることができます。その後、最初から入力するのではなく、コンソールで残りの詳細を選択して Canary を作成できます。API Gateway の詳細については、「[Amazon API Gateway とは](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html)」を参照してください。 **プライベート API の使用** Amazon API Gateway でプライベート API を使用する Canary を作成できます。詳細については、「[Amazon API Gateway でのプライベート API の作成](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html)」を参照してください。 ## リンク切れチェッカー リンク切れチェッカーは、`document.getElementsByTagName('a')` を使用して、テスト対象である URL 内のすべてのリンクを収集します。この際、ユーザーが指定したリンク数までがテストされ、また、URL 自体も最初のリンクとしてカウントされます。例えば、5 つのリンクが含まれているページのすべてのリンクをチェックする場合は、Canary が 6 つのリンクをたどるように指定する必要があります。 `syn-nodejs-2.0-beta` ランタイム以降を使用して作成されたリンク切れチェッカー Canary は、次の追加機能をサポートしています。 + チェックされたリンク、ステータスコード、エラーの理由 (存在する場合)、およびソースページとターゲットページのスクリーンショットを含むレポートを生成する。 + Canary の結果を表示するとき、フィルタリングしてリンク切れのみを表示し、エラーの理由に基づいてリンクを修正できます。 + このバージョンでは、各リンクの注釈付きソースページのスクリーンショットがキャプチャされ、リンクが見つかったアンカーが強調表示されます。非表示のコンポーネントには注釈が付けられません。 + キャプチャするスクリーンショットは、ソースおよびターゲットページの両方、ソースページのみ、またはターゲットページのみに設定できます。 + 最初のページから多くのリンクがスクレイプされた場合でも最初のリンク切れの後に Canary スクリプトが停止するという、以前のバージョンの問題は、このバージョンで修正されています。 **注記** 壊れたリンクチェッカーのブループリントは、Playwright ランタイムではサポートされていません。 新しいランタイムを導入するために、`syn-1.0` を使用している既存の Canary を更新する場合は、一度 Canary を削除した上で再作成する必要があります。既存の Canary を新しいランタイムに更新しても、これらの機能は利用可能になりません。 リンク切れチェッカー Canary は、次の種類のリンクエラーを検出します。 + 404 ページが見つからない。 + ホスト名が無効である。 + URL が正しくない。この例としては、URL から角括弧が抜けている、スラッシュが余分についている、プロトコルが間違っているなどが挙げられます。 + HTTP レスポンスコードが無効である。 + ホストサーバーが、コンテンツもなく、レスポンスコードもない、空のレスポンスを返す。 + HTTPリクエストが Canary の実行中に常にタイムアウトする。 + ホストが正しく設定されていないか、ビジーすぎるために接続が常に切断される。 ## ビジュアルモニターリングの設計図 ビジュアルモニターリングの設計図には、Canary 実行中に撮影されたスクリーンショットと、ベースライン Canary 実行中に撮影されたスクリーンショットを比較するコードが含まれています。2 つのスクリーンショット間の不一致がしきい値のパーセンテージを超えている場合、Canary は失敗します。ビジュアルモニターリングは、**syn-puppeteer-node-3.2** 以降で実行中の Canary でサポートされています。Python と Selenium を実行している Canary、または Playwright ランタイムを使用している Canary では現在サポートされていません。 ビジュアルモニターリングのブループリントには、デフォルトの Canary ブループリントスクリプトに次のコード行が含まれており、ビジュアルモニターリングが有効になります。 ``` syntheticsConfiguration.withVisualCompareWithBaseRun(true); ``` この行がスクリプトに追加された後に初めて Canary が正常に実行されると、その実行中に撮影されたスクリーンショットが比較のベースラインとして使用されます。最初に Canary を実行した後、CloudWatch コンソールを使用して Canary を編集して、次のいずれかの操作を行うことができます。 + Canary の次の実行を新しいベースラインとして設定する。 + 現在のベースラインスクリーンショットに境界を描画し、ビジュアル比較時に無視するスクリーンショットの領域を指定する。 + スクリーンショットをビジュアルモニターリングに使用しないようにする。 CloudWatch コンソールを使用して Canary を編集する方法の詳細については、 「[Canary を編集または削除する](synthetics_canaries_deletion.md)」を参照してください。 また、` nextrun` または `lastrun` パラメーターを指定するか、Canary 実行 ID を [UpdateCanary](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_UpdateCanary.html) API で指定することにより、ベースラインとして使用される Canary 実行を変更することもできます。 ビジュアルモニターリングの設計図を使用する場合は、スクリーンショットを撮影する URL を入力し、差分しきい値をパーセンテージで指定します。ベースライン実行後、そのしきい値よりも大きい視覚差を検出する Canary を今後実行すると、Canary 障害がトリガーされます。ベースライン実行後、Canary を編集して、ビジュアルモニターリング中に無視するベースラインスクリーンショットに境界線を「描画」することもできます。 ビジュアルモニターリング機能は、ImageMagick オープンソースソフトウェアツールキットによって機能します。詳細については、「[ImageMagick](https://imagemagick.org/index.php)」を参照してください。 ## Canary Recorder Canary レコーダーの設計図を使用すると、CloudWatch Synthetics Recorder を使用してウェブサイトでクリックおよび入力のアクションを記録し、同じステップに従う Canary を作成するために使用できる Node.js スクリプトを自動的に生成できます。CloudWatch Synthetics Recorder は、Amazon が提供する Google Chrome 拡張機能です。Canary レコーダーは、Playwright ランタイムを使用する Canary ではサポートされていません。 **クレジット**: CloudWatch Synthetics Recorder は、[Headless レコーダー](https://github.com/checkly/headless-recorder)に基づいています。 詳細については、「[Google Chrome の CloudWatch Synthetics Recorder を使用する](CloudWatch_Synthetics_Canaries_Recorder.md)」を参照してください。 ## GUI ワークフロービルダー GUI ワークフロービルダー設計図は、ウェブページに対してアクションを実行できることを検証します。例えば、ウェブページにログインフォームがある場合、Canary はユーザーフィールドとパスワードフィールドに入力し、このフォームを送信してウェブページが正しく動作していることを検証できます。 このタイプの Canary を設計図を従って作成する場合は、Canary がウェブページに対して実行するアクションを指定します。使用できるアクションは次のとおりです。 + **クリック** – 指定した要素を選択し、ユーザーによる要素のクリックまたは選択をシミュレートします。 Node.js スクリプトで要素を指定するには、`[id=]` または ` a[class=]` を使用します。 Python スクリプトで要素を指定するには、`xpath //*[@id=]` または ` //*[@class=]` を使用します。 + **セレクタの検証** – 指定した要素がウェブページに存在することを検証します。このテストは、以前のアクションによって正しい要素がページに入力されていることを検証するのに役立ちます。 Node.js スクリプトで検証する要素を指定するには、`[id=]` または ` a[class=]` を使用します。 Python スクリプトで検証する要素を指定するには、`xpath //*[@id=]` または `//*[class=]` を使用します。 + **テキストの検証** – 指定した文字列がターゲット要素内に含まれていることを検証します。このテストは、事前のアクションが正しいテキストを表示したかどうかを確認するのに役立ちます。 このアクションでは Puppeteer の ` div[@id=]//h1` 関数を使用するため、Node.js スクリプト内の要素を指定するには `waitForXPath` などの形式を使用します。 Python スクリプトで要素を指定するには、このアクションは Selenium で ` //*[@id=] ` 関数を使用するため、`implicitly_wait` または //\*[@class=] などの xpath 形式を使用します。 + **テキストの入力** – 指定したテキストをターゲット要素に書き込みます。 Node.js スクリプトで検証する要素を指定するには、`[id=]` または ` a[class=]` を使用します。 Python スクリプトで検証する要素を指定するには、`xpath //*[@id=]` または `//*[@class=]` を使用します。 + **クリックして移動** – 指定した要素を選択した後で、ページ全体が読み込まれるまで待ちます。これは、ページを再度読み込む必要がある場合に最も役立ちます。 Node.js スクリプトで要素を指定するには、`[id=]` または ` a[class=]` を使用します。 Python スクリプトで要素を指定するには、`xpath //*[@id=]` または ` //*[@class=]` を使用します。 例えば、次のブループリントでは Node.js を使用しています。このスクリプトは指定した URL の **[firstButton]** をクリックし、想定したセレクタで想定されたテキストが表示されることを検証します。さらに、名前 `Test_Customer` を **[名前]** フィールドに入力して **[ログイン]** ボタンをクリックし、次のページに **[ようこそ]** テキストが表示されることを確認し、そのログインが成功したことを検証します。 ![コンソールの Canary の作成ページ。GUI ワークフロー設計図のフィールドが入力されています。](http://docs.aws.amazon.com/ja_jp/AmazonCloudWatch/latest/monitoring/images/canary_create_gui_workflow.PNG) 次のランタイムを使用する GUI ワークフロー Canary は、各 Canary 実行に対して実行されたステップの概要も提供します。各ステップに関連付けられたスクリーンショットおよびエラーメッセージを使用して、エラーの根本原因を見つけることができます。 + `syn-nodejs-2.0` 以降 + `syn-python-selenium-1.0` 以降 ## マルチチェックのブループリント マルチチェックブループリントで、Canary の作成が簡単になります。HTTP、DNS、SSL、TCP チェックを実行する、すぐに使用できる機能を提供するシンプルな JSON 設定を使用することで、コストを削減できます。最大 10 個のチェックを設定できます。各チェックを順番に実行される数値ステップとして設定し、Canary フローを明確に理解できるようにします。 マルチチェックブループリントは以下をサポートします。 + 基本的な HTTP リクエスト、TCP リクエスト、DNS レコードの検証、SSL 証明書のモニタリング + Secrets Manager と統合された Basic、API Key、OAuth、Sigv4 などの HTTP 認証方法 + 各チェックのアサーション 詳細については、「[Canary を作成する](CloudWatch_Synthetics_Canaries_Create.md)」を参照してください。