Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Für Node.js-Canary-Skripte verfügbare Bibliotheksfunktionen, die Puppeteer verwenden In diesem Abschnitt werden die Bibliotheksfunktionen beschrieben, die für Canary-Skripts von Node.js verfügbar sind. **Topics** + [Node.js-Bibliotheksfunktionen, die für alle Canarys gelten](#CloudWatch_Synthetics_Library_allcanaries) + [Node.js-Bibliotheksklassen und -funktionen, die nur für UI-Canaries gelten](#CloudWatch_Synthetics_Library_UIcanaries) + [Node.js-Bibliotheksklassen und -funktionen, die nur für API-Canaries gelten](#CloudWatch_Synthetics_Library_APIcanaries) ## Node.js-Bibliotheksfunktionen, die für alle Canarys gelten Die folgenden CloudWatch Synthetics-Bibliotheksfunktionen für Node.js sind für alle Kanarienvögel nützlich. **Topics** + [Synthetics-Klasse](#CloudWatch_Synthetics_Library_Synthetics_Class_all) + [SyntheticsConfiguration Klasse](#CloudWatch_Synthetics_Library_SyntheticsConfiguration) + [Synthetics Logger](#CloudWatch_Synthetics_Library_SyntheticsLogger) + [SyntheticsLogHelper Klasse](#CloudWatch_Synthetics_Library_SyntheticsLogHelper) ### Synthetics-Klasse Die folgenden Funktionen für alle Canarys befinden sich in der Klasse Synthetics. **Topics** + [addExecutionError(errorMessage, ex);](#CloudWatch_Synthetics_Library_addExecutionError) + [getCanaryName();](#CloudWatch_Synthetics_Library_getCanaryName) + [getCanaryArn();](#CloudWatch_Synthetics_Library_getCanaryARN) + [getCanaryUserAgentString();](#CloudWatch_Synthetics_Library_getCanaryUserAgentString) + [getRuntimeVersion();](#CloudWatch_Synthetics_Library_getRuntimeVersion) + [getLogLevel();](#CloudWatch_Synthetics_Library_getLogLevel) + [setLogLevel();](#CloudWatch_Synthetics_Library_setLogLevel) #### addExecutionError(errorMessage, ex); `errorMessage` beschreibt den Fehler und `ex` ist die aufgetretene Ausnahme Sie können Folgendes verwenden:`addExecutionError`, um Ausführungsfehler für Ihren Canary festzulegen. Es lässt den Canary fehlschlagen, ohne die Skriptausführung zu unterbrechen. Es wirkt sich auch nicht auf Ihre `successPercent`-Metriken aus. Sie sollten Fehler nur dann als Ausführungsfehler verfolgen, wenn sie nicht wichtig sind, um den Erfolg oder Misserfolg Ihres Canary-Skripts anzuzeigen. Ein Beispiel für die Verwendung von `addExecutionError` ist das folgende. Sie überwachen die Verfügbarkeit Ihres Endpunkts und machen Screenshots, nachdem die Seite geladen wurde. Da der Fehler beim Erstellen eines Screenshots die Verfügbarkeit des Endpunkts nicht bestimmt, können Sie beim Erstellen von Screenshots aufgetretene Fehler abfangen und sie als Ausführungsfehler hinzufügen. Ihre Verfügbarkeitsmetriken zeigen weiterhin an, dass der Endpunkt aktiv ist und ausgeführt wird, aber Ihr Canary-Status wird als fehlgeschlagen markiert. Der folgende Codeblock fängt einen solchen Fehler ab und fügt ihn als Ausführungsfehler hinzu. ``` try { await synthetics.takeScreenshot(stepName, "loaded"); } catch(ex) { synthetics.addExecutionError('Unable to take screenshot ', ex); } ``` #### getCanaryName(); Gibt den Namen des Canarys zurück. #### getCanaryArn(); Gibt den ARN des Canarys aus. #### getCanaryUserAgentString(); Gibt den benutzerdefinierten Benutzeragenten des Canary zurück. #### getRuntimeVersion(); Diese Funktion ist in Laufzeitversion `syn-nodejs-puppeteer-3.0` und höher verfügbar. Es gibt die Synthetics Laufzeitversion des Canarys zurück. Der Rückgabewert könnte beispielsweise `syn-nodejs-puppeteer-3.0` sein. #### getLogLevel(); Ruft die aktuelle Protokollebene für die Synthetics-Bibliothek ab. Folgende Werte sind möglich: + `0` – Debug + `1` – Info + `2` – Warnen + `3` – Fehler Beispiel: ``` let logLevel = synthetics.getLogLevel(); ``` #### setLogLevel(); Legt die Protokollebene für die Synthetics-Bibliothek fest. Folgende Werte sind möglich: + `0` – Debug + `1` – Info + `2` – Warnen + `3` – Fehler Beispiel: ``` synthetics.setLogLevel(0); ``` ### SyntheticsConfiguration Klasse Diese Klasse ist nur in der `syn-nodejs-2.1`-Laufzeitversion oder höher verfügbar. Sie können die `SyntheticsConfiguration`-Klasse verwenden, um das Verhalten von Synthetics-Bibliotheksfunktionen zu konfigurieren. Sie können diese Klasse beispielsweise verwenden, um die `executeStep()`-Funktion so zu konfigurieren, dass keine Screenshots erfasst werden. Sie können CloudWatch Synthetics-Konfigurationen auf globaler Ebene festlegen, die auf alle Stufen der Kanaren angewendet werden. Sie können diese Konfigurationen auch auf Schrittebene überschreiben, indem Sie Konfigurationsschlüssel-Wert-Paare übergeben. Sie können Optionen auf Schrittebene übergeben. Beispiele finden Sie unter [asynchron executeStep (stepName, functionToExecute, [StepConfig]);](#CloudWatch_Synthetics_Library_executeStep) und [executeHttpStep(stepName, RequestOptions, [Rückruf], [StepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep). **Topics** + [setConfig (Optionen)](#CloudWatch_Synthetics_Library_setConfig) + [Visuelle Überwachung](#CloudWatch_Synthetics_Library_SyntheticsLogger_VisualTesting) #### setConfig (Optionen) ` {{options}} ` ist ein Objekt, bei dem es sich um eine Reihe konfigurierbarer Optionen für Ihren Canary handelt. In den folgenden Abschnitten werden die möglichen Felder in ` {{options}} ` erläutert. ##### setConfig (Optionen) für alle Canary Für Benutzer, die Canaries `syn-nodejs-puppeteer-3.2` oder später verwenden, können die **(Optionen)** für **SetConfig die folgenden** Parameter enthalten: + `includeRequestHeaders` (boolean) – Gibt an, ob Anforderungs-Header in den Bericht aufgenommen werden sollen. Der Standardwert ist `false`. + `includeResponseHeaders` (boolean) – Gibt an, ob Antwort-Header in den Bericht aufgenommen werden sollen. Der Standardwert ist `false`. + `restrictedHeaders` (array) – Eine Liste von Header-Werten, die ignoriert werden sollen, wenn Header enthalten sind. Dies gilt sowohl für Anforderungs- als auch für Antwort-Header. Sie können Ihre Anmeldeinformationen beispielsweise verbergen, indem Sie ** includeRequestHeaders**as `true` und **RestrictedHeaders** als übergeben. `['Authorization']` + `includeRequestBody` (boolean) – Gibt an, ob der Anforderungstext in den Bericht aufgenommen werden soll. Der Standardwert ist `false`. + `includeResponseBody` (boolean) – Gibt an, ob der Antworttext in den Bericht aufgenommen werden soll. Der Standardwert ist `false`. **Wichtig** Wenn Sie entweder `includeResponseBody` oder aktivieren` logResponseBody`, wird das Datenobjekt in der Antwort einiger Clients nicht zurückgegeben APIs, z. B. von aws-sdk v3-Clients. Dies liegt an einer Beschränkung von Node.js und des Typs des verwendeten Antwortobjekts. **setConfig (Optionen) in Bezug auf Metriken CloudWatch ** Für Kanarienvögel, die das Programm verwenden `syn-nodejs-puppeteer-3.1` oder später verwenden, können die **(Optionen)** für **SetConfig** die folgenden booleschen Parameter enthalten, die bestimmen, welche Metriken vom Kanarienvogel veröffentlicht werden. Der Standardwert für jede dieser Optionen ist `true`. Die Optionen, die mit `aggregated` beginnen, bestimmen, ob die Metrik ohne die ` CanaryName`-Dimension ausgegeben wird. Sie können diese Metriken verwenden, um die aggregierten Ergebnisse für alle Canarys anzuzeigen. Die anderen Optionen bestimmen, ob die Metrik mit der `CanaryName` Dimension ausgegeben wird. Sie können diese Metriken verwenden, um die Ergebnisse für jeden einzelnen Canary anzuzeigen. Eine Liste der von Canaries ausgegebenen CloudWatch Messwerte finden Sie unter. [CloudWatch von Canaries veröffentlichte Metriken](CloudWatch_Synthetics_Canaries_metrics.md) + `failedCanaryMetric` (boolean) – Gibt an, ob die ` Failed`-Metrik (mit der `CanaryName`-Dimension) für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `failedRequestsMetric` (boolean) – Gibt an, ob die `Failed requests`-Metrik (mit der `CanaryName`-Dimension) für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `_2xxMetric` (boolean) – Gibt an, ob die `2xx`-Metrik (mit der `CanaryName`-Dimension) für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `_4xxMetric` (boolean) – Gibt an, ob die `4xx`-Metrik (mit der `CanaryName`-Dimension) für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `_5xxMetric` (boolean) – Gibt an, ob die `5xx`-Metrik (mit der `CanaryName`-Dimension) für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `stepDurationMetric` (boolean) – Gibt an, ob die `Step duration`-Metrik (mit der `CanaryName`-Dimension `StepName`) für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `stepSuccessMetric` (boolean) – Gibt an, ob die `Step success`-Metrik (mit der `CanaryName`-Dimension `StepName`) für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `aggregatedFailedCanaryMetric` (boolean) – Gibt an, ob die `Failed`-Metrik (ohne die `CanaryName`-Dimension) für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `aggregatedFailedRequestsMetric` (boolean) – Gibt an, ob die `Failed Requests`-Metrik (ohne die `CanaryName`-Dimension) für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `aggregated2xxMetric` (boolean) – Gibt an, ob die ` 2xx`-Metrik (ohne die `CanaryName`-Dimension) für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `aggregated4xxMetric` (boolean) – Gibt an, ob die ` 4xx`-Metrik (ohne die `CanaryName`-Dimension) für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `aggregated5xxMetric` (boolean) – Gibt an, ob die ` 5xx`-Metrik (ohne die `CanaryName`-Dimension) für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `visualMonitoringSuccessPercentMetric` (boolean) – Gibt an, ob die `visualMonitoringSuccessPercent`-Metrik für diesen Canary emittiert werden soll. Der Standardwert ist `true`. + `visualMonitoringTotalComparisonsMetric` (boolean) – Gibt an, ob die `visualMonitoringTotalComparisons`-Metrik für diesen Canary emittiert werden soll. Der Standardwert ist `false`. + `includeUrlPassword` (boolean) – Gibt an, ob ein Passwort eingefügt werden soll, das in der URL angezeigt wird. Standardmäßig URLs werden Passwörter, die in erscheinen, aus Protokollen und Berichten entfernt, um zu verhindern, dass sensible Daten preisgegeben werden. Der Standardwert ist `false`. + `restrictedUrlParameters` (array) – Eine Liste von URL-Pfad- oder Abfrageparametern, die geschwärzt werden sollen. Dies gilt für das URLs Erscheinen in Protokollen, Berichten und Fehlern. Bei dem Parameter wird die Groß-/Kleinschreibung nicht beachtet. Sie können ein Sternchen (\*) als Wert übergeben, um alle URL-Pfad- und Abfrageparameterwerte zu überarbeiten. Der Standardwert ist ein leeres Array. + `logRequest` (boolean) – Gibt an, ob jede Anforderung in Canary-Protokollen protokolliert werden soll. Bei UI-Canarys protokolliert dies jede Anforderung, die vom Browser gesendet wird. Der Standardwert ist `true`. + `logResponse` (boolean) – Gibt an, ob jede Antwort in Canary-Protokollen protokolliert werden soll. Bei UI-Canarys protokolliert dies jede vom Browser empfangene Antwort. Der Standardwert ist `true`. + `logRequestBody` (boolean) – Gibt an, ob Anforderungstexte zusammen mit den Anforderungen in Canary- Protokollen protokolliert werden sollen. Diese Konfiguration gilt nur, wenn `logRequest` `true` ist. Der Standardwert ist `false`. + `logResponseBody` (boolean) – Gibt an, ob Antworttexte zusammen mit den Antworten in Canary-Logs protokolliert werden sollen. Diese Konfiguration gilt nur, wenn `logResponse` `true` ist. Der Standardwert ist ` false`. **Wichtig** Wenn Sie entweder `includeResponseBody` oder aktivieren` logResponseBody`, wird das Datenobjekt in der Antwort einiger Clients nicht zurückgegeben APIs, z. B. von aws-sdk v3-Clients. Dies liegt an einer Beschränkung von Node.js und des Typs des verwendeten Antwortobjekts. + `logRequestHeaders` (boolean) – Gibt an, ob Anforderungsheader zusammen mit den Anforderungen in Canary-Protokollen protokolliert werden sollen. Diese Konfiguration gilt nur, wenn `logRequest` `true` ist. Der Standardwert ist ` false`. Beachten Sie, dass `includeRequestHeaders` Header in Artefakten aktiviert. + `logResponseHeaders` (boolean) – Gibt an, ob Antwortheader zusammen mit den Antworten in Canary-Protokollen protokolliert werden sollen. Diese Konfiguration gilt nur, wenn `logResponse` `true` ist. Der Standardwert ist ` false`. Beachten Sie, dass `includeResponseHeaders` Header in Artefakten aktiviert. **Anmerkung** Die `Duration`- und `SuccessPercent`-Metriken werden immer für jeden Canary ausgegeben, sowohl mit als auch ohne die `CanaryName`-Metrik ##### Methoden zum Aktivieren oder Deaktivieren von Metriken **disableAggregatedRequestMetriken ()** Verhindert, dass der Canary alle Anforderungsmesswerte ausgibt, die ohne `CanaryName`-Dimension ausgegeben werden. **disableRequestMetrics()** Deaktiviert alle Anforderungsmetriken, einschließlich aller Canary-Metriken und Metriken, die über alle Canarys aggregiert werden. **disableStepMetrics()** Deaktiviert alle Schrittmetriken, einschließlich Metriken für den Schritterfolg und für die Schrittdauer. **enableAggregatedRequestMetriken ()** Ermöglicht dem Canary, alle Anforderungsmesswerte auszugeben, die ohne ` CanaryName`-Dimension ausgegeben werden. **enableRequestMetrics()** Aktiviert alle Anforderungsmetriken, einschließlich aller Canary-Metriken und Metriken, die über alle Canarys aggregiert werden. **enableStepMetrics()** Aktiviert alle Schrittmetriken, einschließlich Metriken für den Schritterfolg und für die Schrittdauer. **get2xxMetric()** Gibt zurück, ob der Canary eine `2xx`-Metrik mit der ` CanaryName`-Dimension ausgibt. **get4xxMetric()** Gibt zurück, ob der Canary eine `4xx`-Metrik mit der ` CanaryName`-Dimension ausgibt. **get5xxMetric()** Gibt zurück, ob der Canary eine `5xx`-Metrik mit der ` CanaryName`-Dimension ausgibt. **getAggregated2xxMetric()** Gibt zurück, ob der Canary eine `2xx`-Metrik ohne Dimension ausgibt. **getAggregated4xxMetric()** Gibt zurück, ob der Canary eine `4xx`-Metrik ohne Dimension ausgibt. **getAggregatedFailedCanaryMetric()** Gibt zurück, ob der Canary eine `Failed`-Metrik ohne Dimension ausgibt. **getAggregatedFailedRequestsMetric()** Gibt zurück, ob der Canary eine `Failed requests`-Metrik ohne Dimension ausgibt. **getAggregated5xxMetric()** Gibt zurück, ob der Canary eine `5xx`-Metrik ohne Dimension ausgibt. **getFailedCanaryMetrisch ()** Gibt zurück, ob der Canary eine `Failed`-Metrik mit der ` CanaryName`-Dimension ausgibt. **getFailedRequestsMetrisch ()** Gibt zurück, ob der Canary eine `Failed requests`-Metrik mit der `CanaryName`-Dimension ausgibt. **getStepDurationMetrisch ()** Gibt zurück, ob der Canary eine `Duration`-Metrik mit der ` CanaryName`-Dimension für dieses Canary ausgibt. **getStepSuccessMetrisch ()** Gibt zurück, ob der Canary eine `StepSuccess`-Metrik mit der ` CanaryName`-Dimension für dieses Canary ausgibt. **with2xxMetric(\_2xxMetric)** Akzeptiert ein boolesches Argument, das angibt, ob eine `2xx`-Metrik mit der `CanaryName`-Dimension für diesen Canary emittiert werden soll. **with4xxMetric(\_4xxMetric)** Akzeptiert ein boolesches Argument, das angibt, ob eine `4xx`-Metrik mit der `CanaryName`-Dimension für diesen Canary emittiert werden soll. **with5xxMetric(\_5xxMetric)** Akzeptiert ein boolesches Argument, das angibt, ob eine `5xx`-Metrik mit der `CanaryName`-Dimension für diesen Canary emittiert werden soll. **withAggregated2xxMetric(aggregated2xxMetric)** Akzeptiert ein boolesches Argument, das angibt, ob eine `2xx`-Metrik mit keiner Dimension für diesen Canary emittiert werden soll. **withAggregated4xxMetric(aggregated4xxMetric)** Akzeptiert ein boolesches Argument, das angibt, ob eine `4xx`-Metrik mit keiner Dimension für diesen Canary emittiert werden soll. **withAggregated5xxMetric(aggregated5xxMetric)** Akzeptiert ein boolesches Argument, das angibt, ob eine `5xx`-Metrik mit keiner Dimension für diesen Canary emittiert werden soll. ** withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetrisch)** Akzeptiert ein boolesches Argument, das angibt, ob eine `Failed`-Metrik mit keiner Dimension für diesen Canary emittiert werden soll. ** withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetrisch)** Akzeptiert ein boolesches Argument, das angibt, ob eine `Failed requests`-Metrik mit keiner Dimension für diesen Canary emittiert werden soll. **withFailedCanaryMetrisch (failedCanaryMetric)** Akzeptiert ein boolesches Argument, das angibt, ob eine `Failed`-Metrik mit der `CanaryName`-Dimension für diesen Canary emittiert werden soll. **withFailedRequestsMetrisch (failedRequestsMetric)** Akzeptiert ein boolesches Argument, das angibt, ob eine `Failed requests`-Metrik mit der `CanaryName`-Dimension für diesen Canary emittiert werden soll. **withStepDurationMetrisch (stepDurationMetric)** Akzeptiert ein boolesches Argument, das angibt, ob eine `Duration`-Metrik mit der `CanaryName`-Dimension für diesen Canary emittiert werden soll. **withStepSuccessMetrisch (stepSuccessMetric)** Akzeptiert ein boolesches Argument, das angibt, ob eine ` StepSuccess`-Metrik mit der `CanaryName`-Dimension für diesen Canary emittiert werden soll. ##### Methoden zum Aktivieren oder Deaktivieren anderer Features **withHarFile()** Akzeptiert ein boolesches Argument, das angibt, ob eine HAR-Datei für diesen Canary erstellt werden soll. **withStepsReport()** Akzeptiert ein boolesches Argument, das angibt, ob eine Zusammenfassung der Schrittausführung für diesen Canary gemeldet werden soll. **withIncludeUrlPasswort ()** Akzeptiert ein boolesches Argument, das angibt, ob Passwörter, die URLs in Protokollen und Berichten vorkommen, eingeschlossen werden sollen. **withRestrictedUrlParameter ()** Akzeptiert ein Array von URL-Pfad- oder Abfrageparametern zum Schwärzen. Dies gilt für das URLs Erscheinen in Protokollen, Berichten und Fehlern. Sie können ein Sternchen (\*) als Wert übergeben, um alle URL-Pfad- und Abfrageparameterwerte zu verkleinern **withLogRequest()** Akzeptiert ein boolesches Argument, das angibt, ob jede Anforderung in den Protokollen des Canarys protokolliert werden soll. **withLogResponse()** Akzeptiert ein boolesches Argument, das angibt, ob jede Antwort in den Protokollen des Canarys protokolliert werden soll. **withLogRequestKörper ()** Akzeptiert ein boolesches Argument, das angibt, ob jeder Anforderungstext in den Protokollen des Canarys protokolliert werden soll. **withLogResponseKörper ()** Akzeptiert ein boolesches Argument, das angibt, ob jeder Antworttext in den Protokollen des Canarys protokolliert werden soll. **withLogRequestÜberschriften ()** Akzeptiert ein boolesches Argument, das angibt, ob jeder Anforderungs-Header in den Protokollen des Canarys protokolliert werden soll. **withLogResponseÜberschriften ()** Akzeptiert ein boolesches Argument, das angibt, ob jeder Antwort-Header in den Protokollen des Canarys protokolliert werden soll. **getHarFile()** Gibt zurück, ob der Canary eine HAR-Datei erstellt. **getStepsReport()** Gibt zurück, ob der Canary eine Zusammenfassung der Schrittausführung meldet **getIncludeUrlPasswort ()** Gibt zurück, ob der Canary Passwörter enthält, die URLs in Protokollen und Berichten vorkommen. **getRestrictedUrlParameter ()** Gibt zurück, ob der Canary den URL-Pfad oder die Abfrageparameter entfernt. **getLogRequest()** Gibt zurück, ob der Canary jede Anforderung in den Canaryprotokollen protokolliert. **getLogResponse()** Gibt zurück, ob der Canary jede Antwort in den Canaryprotokollen protokolliert. **getLogRequestKörper ()** Gibt zurück, ob der Canary jeden Anforderungstext in den Canaryprotokollen protokolliert. **getLogResponseKörper ()** Gibt zurück, ob der Canary jeden Antworttext in den Canaryprotokollen protokolliert. **getLogRequestÜberschriften ()** Gibt zurück, ob der Canary jeden Anforderungsheader in den Protokollen des Canarys. **getLogResponseÜberschriften ()** Gibt zurück, ob der Canary alle Antwort-Header in den Canaryprotokollen protokolliert. **Funktionen für alle Canarys** + `withIncludeRequestHeaders`(includeRequestHeaders) + `withIncludeResponseHeaders`(includeResponseHeaders) + `withRestrictedHeaders`(RestrictedHeader) + `withIncludeRequestBody`(includeRequestBody) + `withIncludeResponseBody`(includeResponseBody) + `enableReportingOptions`() — Aktiviert alle Berichtsoptionen-- **includeRequestHeaders**, ** includeResponseHeaders**includeRequestBody****, und **includeResponseBody**,. + `disableReportingOptions`() — Deaktiviert alle Berichtsoptionen-- **includeRequestHeaders**, ** includeResponseHeaders**includeRequestBody****, und **includeResponseBody**,. ##### setConfig (Optionen) für UI-Canarys Für UI-Canarys kann **SetConfig** folgende boolesche Parameter enthalten: + `continueOnStepFailure`(boolean) — Ob mit der Ausführung des Canary-Skripts fortgefahren werden soll, nachdem ein Schritt fehlgeschlagen ist (dies bezieht sich auf die **ExecuteStep-Funktion**). Wenn Schritte fehlschlagen, wird der Canary-Lauf weiterhin als fehlgeschlagen markiert. Der Standardwert ist `false`. + `harFile` (boolean) – Gibt an, ob eine HAR-Datei erstellt werden soll. Der Standardwert ist `True`. + `screenshotOnStepStart` (boolean) – Gibt an, ob ein Screenshot erstellt werden soll, bevor ein Schritt gestartet wird. + `screenshotOnStepSuccess` (boolean) – Gibt an, ob nach einem erfolgreichen Schritt ein Screenshot erstellt werden soll. + `screenshotOnStepFailure` (boolean) - Ob ein Screenshot erstellt werden soll, nachdem ein Schritt fehlgeschlagen ist. ##### Methoden zum Aktivieren oder Deaktivieren von Screenshots **disableStepScreenshots()** Deaktiviert alle Screenshot-Optionen (screenshotOnStepStart, screenshotOnStep Erfolg und Fehler). screenshotOnStep **enableStepScreenshots()** Aktiviert alle Screenshot-Optionen (screenshotOnStepStart, screenshotOnStep Erfolg und screenshotOnStep Fehler). Standardmäßig sind alle diese Methoden aktiviert. **getScreenshotOnStepFailure()** Gibt zurück, ob der Canary einen Screenshot macht, nachdem ein Schritt fehlschlägt. **getScreenshotOnStepStart()** Gibt zurück, ob der Canary einen Screenshot erstellt, bevor er einen Schritt startet. **getScreenshotOnStepSuccess()** Gibt zurück, ob der Canary nach erfolgreichem Abschluss eines Schritts einen Screenshot erstellt. **withScreenshotOnStepStart(screenshotOnStepStart)** Akzeptiert ein boolesches Argument, das angibt, ob ein Screenshot erstellt werden soll, bevor ein Schritt gestartet wird. **withScreenshotOnStepSuccess(screenshotOnStepErfolg)** Akzeptiert ein boolesches Argument, das angibt, ob nach erfolgreichem Abschluss eines Schritts ein Screenshot erstellt werden soll. **withScreenshotOnStepFailure(screenshotOnStepMisserfolg)** Akzeptiert ein boolesches Argument, das angibt, ob nach einem Schritt ein Screenshot erstellt werden soll. **Verwendung in UI-Canarys** Importieren Sie zuerst die Synthetics-Abhängigkeit und holen Sie die Konfiguration ab. ``` // Import Synthetics dependency const synthetics = require('@aws/synthetics-puppeteer'); // Get Synthetics configuration const synConfig = synthetics.getConfiguration(); ``` Legen Sie dann die Konfiguration für jede Option fest, indem Sie die setConfig-Methode mit einer der folgenden Optionen aufrufen. ``` // Set configuration values synConfig.setConfig({ screenshotOnStepStart: true, screenshotOnStepSuccess: false, screenshotOnStepFailure: false }); ``` Oder ``` synConfig.withScreenshotOnStepStart(false).withScreenshotOnStepSuccess(true).withScreenshotOnStepFailure(true) ``` Um alle Screenshots zu deaktivieren, verwenden Sie die `disableStepScreenshots()`-Funktion wie in diesem Beispiel. ``` synConfig.disableStepScreenshots(); ``` Sie können Screenshots jederzeit im Code aktivieren oder deaktivieren. Wenn Sie beispielsweise Screenshots nur für einen Schritt deaktivieren möchten, deaktivieren Sie sie, bevor Sie diesen Schritt ausführen, und aktivieren Sie sie dann nach dem Schritt. ##### setConfig (Optionen) für API-Canarys Für API-Canarys kann **SetConfig** folgende boolesche Parameter enthalten: + `continueOnHttpStepFailure`(boolean) — Ob mit der Ausführung des Canary-Skripts fortgefahren werden soll, nachdem ein HTTP-Schritt fehlgeschlagen ist (dies bezieht sich auf die **executeHttpStep**Funktion). Wenn Schritte fehlschlagen, wird der Canary-Lauf weiterhin als fehlgeschlagen markiert. Der Standardwert ist `true`. #### Visuelle Überwachung Die visuelle Überwachung vergleicht Screenshots, die während eines Canary-Laufs aufgenommen wurden, mit Screenshots, die während eines Baseline-Canary-Laufs aufgenommen wurden. Wenn die Diskrepanz zwischen den beiden Screenshots einen Schwellenwert überschreitet, schlägt der Canary fehl, und Sie können die Bereiche mit Unterschieden in der Farbe im Canarylauf-Bericht sehen. Die visuelle Überwachung wird auf Kanaren unterstützt, auf denen die Version **syn-puppeteer-node-3.2** und höher ausgeführt wird. Es wird derzeit nicht in Canarys unterstützt, die Python und Selenium ausführen. Um die visuelle Überwachung zu aktivieren, fügen Sie dem Canary-Skript die folgende Codezeile hinzu. Weitere Details finden Sie unter [SyntheticsConfiguration Klasse](#CloudWatch_Synthetics_Library_SyntheticsConfiguration). ``` syntheticsConfiguration.withVisualCompareWithBaseRun(true); ``` Wenn der Canary zum ersten Mal erfolgreich ausgeführt wird, nachdem diese Zeile zum Skript hinzugefügt wurde, verwendet er die während dieser Ausführung erstellten Screenshots als Vergleichsbasis. Nach dem ersten Canary-Run kannst du die CloudWatch Konsole verwenden, um den Canary zu bearbeiten, um einen der folgenden Schritte auszuführen: + Legen Sie den nächsten Lauf des Canarys als neue Basislinie fest. + Zeichnen Sie Grenzen auf dem aktuellen Baseline-Screenshot, um Bereiche des Screenshots festzulegen, die bei visuellen Vergleichen ignoriert werden sollen. + Entfernen Sie einen Screenshot, der für die visuelle Überwachung verwendet wird. Weitere Informationen zur Verwendung der CloudWatch Konsole zum Bearbeiten eines Canary finden Sie unter[Einen Canary bearbeiten oder löschen](synthetics_canaries_deletion.md). **Weitere Optionen für die visuelle Überwachung** **Synthetics-Konfiguration. withVisualVarianceThresholdPercentage(Gewünschter Prozentsatz)** Legen Sie den akzeptablen Prozentsatz für die Screenshot-Varianz in visuellen Vergleichen fest. **Konfiguration „Synthetik“. withVisualVarianceHighlightHexColor(“ \#fafa00 „)** Legen Sie die Hervorhebungsfarbe fest, die Varianzbereiche angibt, wenn Sie Canary-Lauf-Berichte betrachten, die visuelle Überwachung verwenden. **Synthetische Konfiguration. withFailCanaryRunOnVisualVariance(Canary scheitern)** Legen Sie fest, ob der Canary fehlschlägt, wenn ein visueller Unterschied größer als der Schwellenwert ist. Die Standardeinstellung ist, dass der Canary fehlschlägt. ### Synthetics Logger SyntheticsLogger schreibt Logs sowohl in die Konsole als auch in eine lokale Protokolldatei auf derselben Protokollebene. Diese Protokolldatei wird nur dann an beide Speicherorte geschrieben, wenn die Protokollebene auf oder unter der gewünschten Protokollierungsebene der aufgerufenen Protokollfunktion liegt. Den Protokollierungsanweisungen in der lokalen Protokolldatei werden je nach der Protokollebene der aufgerufenen Funktion „DEBUG“ „INFO“ usw. vorangestellt. Sie können das verwenden SyntheticsLogger, vorausgesetzt, Sie möchten die Synthetics Library auf derselben Protokollebene wie Ihr Synthetics Canary-Logging ausführen. Die Verwendung von SyntheticsLogger ist nicht erforderlich, um eine Protokolldatei zu erstellen, die an Ihren S3-Ergebnisspeicherort hochgeladen wird. Sie können stattdessen eine andere Protokolldatei im ` /tmp`-Ordner erstellen. Alle Dateien, die unter dem `/tmp`-Ordner erstellt wurden, werden als Artefakte an den Ergebnisspeicherort in S3 hochgeladen. So verwenden Sie den Synthetics Library Logger: ``` const log = require('@aws/synthetics-logger'); ``` Nützliche Funktionsdefinitionen: **log.debug ({{message}},); {{ex}}** Parameter: {{message}} ist die zu protokollierende Nachricht. {{ ex}}ist die Ausnahme, falls vorhanden, für die Protokollierung. Beispiel: ``` log.debug("Starting step - login."); ``` **log.error ({{message}},); {{ex}}** Parameter: {{message}} ist die zu protokollierende Nachricht. {{ ex}}ist die Ausnahme, falls vorhanden, für die Protokollierung. Beispiel: ``` try { await login(); catch (ex) { log.error("Error encountered in step - login.", ex); } ``` **log.info ({{message}},{{ex}});** Parameter: {{message}} ist die zu protokollierende Nachricht. {{ ex}}ist die Ausnahme, falls vorhanden, für die Protokollierung. Beispiel: ``` log.info("Successfully completed step - login."); ``` **log.log ({{message}},{{ex}});** Dies ist ein Alias für `log.info`. Parameter: {{message}} ist die zu protokollierende Nachricht. {{ ex}}ist die Ausnahme, falls vorhanden, für die Protokollierung. Beispiel: ``` log.log("Successfully completed step - login."); ``` **log.warn ({{message}},); {{ex}}** Parameter: {{message}} ist die zu protokollierende Nachricht. {{ ex}}ist die Ausnahme, falls vorhanden, für die Protokollierung. Beispiel: ``` log.warn("Exception encountered trying to publish CloudWatch Metric.", ex); ``` ### SyntheticsLogHelper Klasse Die Klasse `SyntheticsLogHelper` ist in der Laufzeit ` syn-nodejs-puppeteer-3.2` und späteren Laufzeiten verfügbar. Es ist bereits in der CloudWatch Synthetics-Bibliothek initialisiert und mit der Synthetics-Konfiguration konfiguriert. Sie können dies in Ihrem Skript als Abhängigkeit hinzufügen. Mit dieser Klasse können Sie Header und Fehlermeldungen bereinigen URLs, um vertrauliche Informationen zu redigieren. **Anmerkung** Synthetics bereinigt alle URLs protokollierten Fehlermeldungen, bevor sie auf der Grundlage der Synthetics-Konfigurationseinstellung in Protokolle, Berichte, HAR-Dateien und Canary-Run-Fehler aufgenommen werden. `restrictedUrlParameters` Sie müssen ` getSanitizedUrl` oder `getSanitizedErrorMessage` nur verwenden, wenn Sie Fehler in Ihrem Skript protokollieren URLs . Synthetics speichert keine Canaryartefakte mit Ausnahme von Canaryfehlern, die vom Skript ausgelöst werden. Canary-Lauf-Artefakte werden in Ihrem Kundenkonto gespeichert. Weitere Informationen finden Sie unter [Sicherheitsüberlegungen für Synthetics-Canaries](servicelens_canaries_security.md). **Topics** + [getSanitizedUrl(url, stepConfig = null)](#CloudWatch_Synthetics_Library_getSanitizedUrl) + [getSanitizedErrorNachricht](#CloudWatch_Synthetics_Library_getSanitizedErrorMessage) + [getSanitizedHeaders(Header, StepConfig=Null)](#CloudWatch_Synthetics_Library_getSanitizedHeaders) #### getSanitizedUrl(url, stepConfig = null) Diese Funktion ist in `syn-nodejs-puppeteer-3.2` und höher verfügbar. Es gibt bereinigt URL-Zeichenfolgen basierend auf der Konfiguration. Sie können sich dafür entscheiden, sensible URL-Parameter wie password und access\_token zu schwärzen, indem Sie die Eigenschaft `restrictedUrlParameters` festlegen. Standardmäßig werden Passwörter in URLs geschwärzt. Sie können bei Bedarf URL-Passwörter aktivieren, indem Sie `includeUrlPassword` auf true setzen. Diese Funktion löst einen Fehler aus, wenn die übergebene URL keine gültige URL ist. **Parameter** + {{url}}ist eine Zeichenfolge und die URL, die bereinigt werden soll. + {{stepConfig}}(Optional) überschreibt die globale Synthetics-Konfiguration für diese Funktion. Wenn `stepConfig` nicht übergeben wird, wird die globale Konfiguration verwendet, um die URL zu bereinigen. **Beispiel** In diesem Beispiel wird die folgende Beispiel-URL verwendet :` https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200`. In diesem Beispiel enthält `access_token` Ihre vertraulichen Informationen, die nicht protokolliert werden sollten. Beachten Sie, dass die Synthetics-Services keine Canary-Artefakte speichern. Artefakte wie Protokolle, Screenshots und Berichte werden in einem Amazon-S3-Bucket in Ihrem Kundenkonto gespeichert. Der erste Schritt besteht darin, die Synthetics-Konfiguration festzulegen. ``` // Import Synthetics dependency const synthetics = require('@aws/synthetics-puppeteer'); // Import Synthetics logger for logging url const log = require('@aws/synthetics-logger'); // Get Synthetics configuration const synConfig = synthetics.getConfiguration(); // Set restricted parameters synConfig.setConfig({ restrictedUrlParameters: ['access_token']; }); // Import SyntheticsLogHelper dependency const syntheticsLogHelper = require('@aws/synthetics-log-helper'); const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('{{URL}}'); const urlConfig = { restrictedUrlParameters = ['*'] }; const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('{{URL}}', urlConfig); logger.info('My example url is: ' + sanitizedUrl); ``` Als nächstes bereinigen und protokollieren Sie die URL ``` // Import SyntheticsLogHelper dependency const syntheticsLogHelper = require('@aws/synthetics-log-helper'); const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200'); ``` Dies protokolliert Folgendes in Ihrem Canaryprotokoll. ``` My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200 ``` Sie können die Synthetics-Konfiguration für eine URL überschreiben, indem Sie einen optionalen Parameter mit Synthetics-Konfigurationsoptionen übergeben, wie im folgenden Beispiel gezeigt. ``` const urlConfig = { restrictedUrlParameters = ['*'] }; const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200', urlConfig); logger.info('My example url is: ' + sanitizedUrl); ``` Im obigen Beispiel werden alle Abfrageparameter geschwärzt und wie folgt protokolliert: ``` My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=REDACTED&expires_in=REDACTED ``` #### getSanitizedErrorNachricht Diese Funktion ist in `syn-nodejs-puppeteer-3.2` und höher verfügbar. Es gibt bereinigte Fehlerzeichenfolgen zurück, indem alle URLs vorhandenen Zeichenketten basierend auf der Synthetics-Konfiguration bereinigt werden. Sie können die globale Synthetics-Konfiguration überschreiben, wenn Sie diese Funktion aufrufen, indem Sie einen optionalen `stepConfig`-Parameter übergeben. **Parameter** + {{error}}ist der Fehler bei der Bereinigung. Es kann ein Fehler-Objekt oder eine Zeichenfolge sein. + {{stepConfig}}(Optional) überschreibt die globale Synthetics-Konfiguration für diese Funktion. Wenn `stepConfig` nicht übergeben wird, wird die globale Konfiguration verwendet, um die URL zu bereinigen. **Beispiel** In diesem Beispiel wird der folgende Fehler verwendet: ` Failed to load url: https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200` Der erste Schritt besteht darin, die Synthetics-Konfiguration festzulegen. ``` // Import Synthetics dependency const synthetics = require('@aws/synthetics-puppeteer'); // Import Synthetics logger for logging url const log = require('@aws/synthetics-logger'); // Get Synthetics configuration const synConfig = synthetics.getConfiguration(); // Set restricted parameters synConfig.setConfig({ restrictedUrlParameters: ['access_token']; }); ``` Als nächstes bereinigen und protokollieren Sie die Fehlermeldung ``` // Import SyntheticsLogHelper dependency const syntheticsLogHelper = require('@aws/synthetics-log-helper'); try { // Your code which can throw an error containing url which your script logs } catch (error) { const sanitizedErrorMessage = syntheticsLogHelper.getSanitizedErrorMessage(errorMessage); logger.info(sanitizedErrorMessage); } ``` Dies protokolliert Folgendes in Ihrem Canaryprotokoll. ``` Failed to load url: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200 ``` #### getSanitizedHeaders(Header, StepConfig=Null) Diese Funktion ist in `syn-nodejs-puppeteer-3.2` und höher verfügbar. Es gibt bereinigte Header basierend auf der `restrictedHeaders`-Eigenschaft von ` syntheticsConfiguration` zurück. Die in der Eigenschaft `restrictedHeaders` angegebenen Header werden aus Protokollen, HAR-Dateien und Berichten entfernt. **Parameter** + {{headers}}ist ein Objekt, das die zu bereinigenden Header enthält. + {{stepConfig}}(Optional) überschreibt die globale Synthetics-Konfiguration für diese Funktion. Wenn `stepConfig` nicht übergeben wird, wird die globale Konfiguration verwendet, um die Header zu bereinigen. ## Node.js-Bibliotheksklassen und -funktionen, die nur für UI-Canaries gelten Die folgenden CloudWatch Synthetics-Bibliotheksfunktionen für Node.js sind nur für UI Canaries nützlich. **Topics** + [Synthetics-Klasse](#CloudWatch_Synthetics_Library_Synthetics_Class) + [BrokenLinkCheckerReport Klasse](#CloudWatch_Synthetics_Library_BrokenLinkCheckerReport) + [SyntheticsLink Klasse](#CloudWatch_Synthetics_Library_SyntheticsLink) ### Synthetics-Klasse Die folgenden Funktionen befinden sich in der Klasse Synthetics. **Topics** + [asynchron addUserAgent (Seite,); userAgentString](#CloudWatch_Synthetics_Library_addUserAgent) + [asynchron executeStep (stepName, functionToExecute, [StepConfig]);](#CloudWatch_Synthetics_Library_executeStep) + [getDefaultLaunchOptionen ();](#CloudWatch_Synthetics_Library_getDefaultLaunchOptions) + [getPage();](#CloudWatch_Synthetics_Library_getPage) + [getRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_getRequestResponseLogHelper) + [Start (Optionen)](#CloudWatch_Synthetics_Library_LaunchOptions) + [RequestResponseLogHelper Klasse](#CloudWatch_Synthetics_Library_RequestResponseLogHelper) + [setRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_setRequestResponseLogHelper) + [async takeScreenshot(name, suffix);](#CloudWatch_Synthetics_Library_takeScreenshot) #### asynchron addUserAgent (Seite,); userAgentString Diese Funktion hängt {{userAgentString}} an den User-Agent-Header der angegebenen Seite an. Beispiel: ``` await synthetics.addUserAgent(page, "MyApp-1.0"); ``` Bewirkt, dass der User-Agent-Header der Seite auf `{{ browsers-user-agent-header-value}}MyApp-1.0` gesetzt wird. #### asynchron executeStep (stepName, functionToExecute, [StepConfig]); Führt den angegebenen Schritt aus und umschließt ihn mit Metriken und deren Dauer. start/pass/fail logging, start/pass/fail screenshots, and pass/fail **Anmerkung** Wenn Sie die Laufzeit `syn-nodejs-2.1` oder höher verwenden, können Sie konfigurieren, ob und wann Screenshots erstellt werden. Weitere Informationen finden Sie unter [SyntheticsConfiguration Klasse](#CloudWatch_Synthetics_Library_SyntheticsConfiguration). Die `executeStep`-Funktion tut Folgendes: + Protokolliert, dass der Schritt gestartet wurde. + Erfasst einen Screenshot mit dem Namen `-starting`. + Startet einen Timer. + Führt die bereitgestellte Funktion aus. + Wenn die Funktion normal zurückgegeben wird, gilt sie als „bestanden“. Wenn die Funktion scheitert, gilt sie als fehlgeschlagen. + Beendet den Timer. + Protokolliert, ob der Schritt bestanden oder fehlgeschlagen ist + Erfasst einen Screenshot mit dem Namen `-succeeded` oder ` -failed`. + Gibt die Metrik `stepName` `SuccessPercent` aus, wobei „100“ für erfolgreich bzw. „0“ für nicht erfolgreich steht. + Gibt die Metrik `stepName` `Duration` aus, mit einem Wert basierend auf der Start- und der Endzeit des Schrittes. + Gibt schließlich zurück, was die `functionToExecute` zurückgegeben hat, oder wiederholt einen Throw-Vorgang von `functionToExecute`. Wenn der Canary die Laufzeit `syn-nodejs-2.0` oder höher verwendet, fügt diese Funktion dem Bericht des Canary auch eine Zusammenfassung der Schrittausführung hinzu. Die Zusammenfassung enthält Details zu jedem Schritt, wie Startzeit, Endzeit, Status (PASSED/FAILED), Fehlergrund (falls fehlgeschlagen) und Screenshots, die während der Ausführung jedes Schritts erfasst wurden. Beispiel: ``` await synthetics.executeStep('navigateToUrl', async function (timeoutInMillis = 30000) { await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});}); ``` Antwort: Gibt zurück, was `functionToExecute` zurückgibt. **Updates mit syn-nodejs-2.2** Zunächst können Sie optional Schrittkonfigurationen übergeben`syn-nodejs-2.2`, um CloudWatch Synthetics-Konfigurationen auf Schrittebene zu überschreiben. Eine Liste der Optionen, die Sie an `executeStep` übergeben können, finden Sie unter [SyntheticsConfiguration Klasse](#CloudWatch_Synthetics_Library_SyntheticsConfiguration). Das folgende Beispiel überschreibt die `false`-Standardkonfiguration für ` continueOnStepFailure` bis `true` und gibt an, wann Screenshots erstellt werden sollen. ``` var stepConfig = { 'continueOnStepFailure': true, 'screenshotOnStepStart': false, 'screenshotOnStepSuccess': true, 'screenshotOnStepFailure': false } await executeStep('Navigate to amazon', async function (timeoutInMillis = 30000) { await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis}); }, stepConfig); ``` #### getDefaultLaunchOptionen (); Die `getDefaultLaunchOptions()` Funktion gibt die Browser-Startoptionen zurück, die von CloudWatch Synthetics verwendet werden. Weitere Informationen finden Sie unter [Startoptionen-Typ](https://pptr.dev/browsers-api/browsers.launchoptions/) ``` // This function returns default launch options used by Synthetics. const defaultOptions = await synthetics.getDefaultLaunchOptions(); ``` #### getPage(); Gibt die aktuell geöffnete Seite als Puppeteer-Objekt zurück. Weitere Informationen finden Sie unter [Puppeteer API v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md). Beispiel: ``` let page = await synthetics.getPage(); ``` Antwort: Die Seite (Puppeteer-Objekt), die derzeit in der aktuellen Browsersitzung geöffnet ist. #### getRequestResponseLogHelper(); **Wichtig** In Canaries, die die Laufzeit `syn-nodejs-puppeteer-3.2` oder höher verwenden, ist diese Funktion zusammen mit der `RequestResponseLogHelper`-Klasse veraltet. Jede Verwendung dieser Funktion bewirkt, dass eine Warnung in Ihren Canaryprotokollen angezeigt wird. Diese Funktion wird in zukünftigen Laufzeitversionen entfernt. Wenn Sie diese Funktion verwenden, verwenden Sie stattdessen [RequestResponseLogHelper Klasse](#CloudWatch_Synthetics_Library_RequestResponseLogHelper). Verwenden Sie diese Funktion als Builder-Muster zum Optimieren der Anforderungs- und Antwortprotokollierungsmarkierungen. Beispiel: ``` synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));; ``` Antwort: ``` {RequestResponseLogHelper} ``` #### Start (Optionen) Die Optionen für diese Funktion sind erst ab der Laufzeit-Version `syn-nodejs-2.1` verfügbar. Diese Funktion wird nur für UI-Canarys verwendet. Es schließt den vorhandenen Browser und startet einen neuen. **Anmerkung** CloudWatch Synthetics startet immer einen Browser, bevor Sie mit der Ausführung Ihres Skripts beginnen. Sie müssen launch() nicht aufrufen, es sei denn, Sie möchten einen neuen Browser mit benutzerdefinierten Optionen starten. (Optionen) ist ein konfigurierbarer Satz von Optionen, die im Browser festgelegt werden sollen. Weitere Informationen finden Sie unter [Startoptionen-Typ](https://pptr.dev/browsers-api/browsers.launchoptions/). Wenn Sie diese Funktion ohne Optionen aufrufen, startet Synthetics einen Browser mit Standardargumenten `executablePath` und `defaultViewport`. Das Standardansichtsfenster in CloudWatch Synthetics ist 1920 mal 1080. Sie können die von CloudWatch Synthetics verwendeten Startparameter überschreiben und beim Starten des Browsers zusätzliche Parameter übergeben. Mit dem folgenden Codeausschnitt wird beispielsweise ein Browser mit Standardargumenten und einem standardmäßigen ausführbaren Pfad gestartet, jedoch mit einem Ansichtsfenster von 800 x 600. ``` await synthetics.launch({ defaultViewport: { "deviceScaleFactor": 1, "width": 800, "height": 600 }}); ``` Der folgende Beispielcode fügt den `ignoreHTTPSErrors` CloudWatch Synthetics-Startparametern einen neuen Parameter hinzu: ``` await synthetics.launch({ ignoreHTTPSErrors: true }); ``` Sie können die Websicherheit deaktivieren, indem Sie args in den CloudWatch Synthetics-Startparametern ein `--disable-web-security` Flag hinzufügen: ``` // This function adds the --disable-web-security flag to the launch parameters const defaultOptions = await synthetics.getDefaultLaunchOptions(); const launchArgs = [...defaultOptions.args, '--disable-web-security']; await synthetics.launch({ args: launchArgs }); ``` #### RequestResponseLogHelper Klasse **Wichtig** In Canaries, die die Laufzeit `syn-nodejs-puppeteer-3.2` oder höher verwenden, ist diese Klasse veraltet. Jede Verwendung dieser Klasse bewirkt, dass eine Warnung in Ihren Canaryprotokollen angezeigt wird. Diese Funktion wird in zukünftigen Laufzeitversionen entfernt. Wenn Sie diese Funktion verwenden, verwenden Sie stattdessen [RequestResponseLogHelper Klasse](#CloudWatch_Synthetics_Library_RequestResponseLogHelper). Behandelt die präzise Konfiguration und Erstellung von Zeichenfolgendarstellungen von Anforderungs- und Antwort-Nutzlasten. ``` class RequestResponseLogHelper { constructor () { this.request = {url: true, resourceType: false, method: false, headers: false, postData: false}; this.response = {status: true, statusText: true, url: true, remoteAddress: false, headers: false}; } withLogRequestUrl(logRequestUrl); withLogRequestResourceType(logRequestResourceType); withLogRequestMethod(logRequestMethod); withLogRequestHeaders(logRequestHeaders); withLogRequestPostData(logRequestPostData); withLogResponseStatus(logResponseStatus); withLogResponseStatusText(logResponseStatusText); withLogResponseUrl(logResponseUrl); withLogResponseRemoteAddress(logResponseRemoteAddress); withLogResponseHeaders(logResponseHeaders); ``` Beispiel: ``` synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper() .withLogRequestPostData(true) .withLogRequestHeaders(true) .withLogResponseHeaders(true)); ``` Antwort: ``` {RequestResponseLogHelper} ``` #### setRequestResponseLogHelper(); **Wichtig** In Canaries, die die Laufzeit `syn-nodejs-puppeteer-3.2` oder höher verwenden, ist diese Funktion zusammen mit der `RequestResponseLogHelper`-Klasse veraltet. Jede Verwendung dieser Funktion bewirkt, dass eine Warnung in Ihren Canaryprotokollen angezeigt wird. Diese Funktion wird in zukünftigen Laufzeitversionen entfernt. Wenn Sie diese Funktion verwenden, verwenden Sie stattdessen [RequestResponseLogHelper Klasse](#CloudWatch_Synthetics_Library_RequestResponseLogHelper). Verwenden Sie diese Funktion als Builder-Muster zum Einstellen der Anforderungs- und Antwortprotokollierungsmarkierungen. Beispiel: ``` synthetics.setRequestResponseLogHelper().withLogRequestHeaders(true).withLogResponseHeaders(true); ``` Antwort: ``` {RequestResponseLogHelper} ``` #### async takeScreenshot(name, suffix); Erstelle einen Screenshot (.PNG) der aktuellen Seite mit Name und Suffix (Optional). Beispiel: ``` await synthetics.takeScreenshot("navigateToUrl", "loaded") ``` In diesem Beispiel wird ein Screenshot mit dem Namen ` 01-navigateToUrl-loaded.png` aufgenommen und in den S3 Bucket des Canary hochgeladen. Sie können einen Screenshot für einen bestimmten Canary-Schritt erstellen, indem Sie das ` stepName` als ersten Parameter übergeben. Screenshots sind mit dem Canaryschritt in Ihren Berichten verknüpft, damit Sie jeden Schritt beim Debuggen verfolgen können. CloudWatch Synthetics Canaries macht automatisch Screenshots vor dem Starten eines Schritts (die `executeStep` Funktion) und nach Abschluss des Schritts (es sei denn, Sie konfigurieren den Canary so, dass Screenshots deaktiviert werden). Sie können weitere Screenshots erstellen, indem Sie den Schrittnamen in der `takeScreenshot`-Funktion übergeben. Im folgenden Beispiel wird ein Screenshot mit dem `signupForm` als Wert von `stepName` erstellt. Der Screenshot erhält den Namen ` 02-signupForm-address` und wird mit dem Schritt namens ` signupForm` im Canary-Bericht verknüpft. ``` await synthetics.takeScreenshot('signupForm', 'address') ``` ### BrokenLinkCheckerReport Klasse Diese Klasse bietet Methoden, um eine Synthetics-Verknüpfung hinzuzufügen. Es wird nur auf Canarysn unterstützt, die die `syn-nodejs-2.0-beta`-Version der Laufzeitumgebung oder höher verwenden. Um `BrokenLinkCheckerReport` zu verwenden, fügen Sie die folgenden Zeilen in das Skript ein: ``` const BrokenLinkCheckerReport = require('@aws/synthetics-broken-link-checker-report'); const brokenLinkCheckerReport = new BrokenLinkCheckerReport(); ``` Nützliche Funktionsdefinitionen: **Link hinzufügen ({{syntheticsLink}}, ist kaputt)** ` {{syntheticsLink}} ` ist ein ` SyntheticsLink`-Objekt, das eine Verknüpfung darstellt. Diese Funktion fügt den Link entsprechend dem Statuscode hinzu. Standardmäßig betrachtet es einen Link als unterbrochen, wenn der Statuscode nicht verfügbar ist oder der Statuscode 400 oder höher ist. Sie können dieses Standardverhalten überschreiben, indem Sie den optionalen Parameter `isBrokenLink` mit einem Wert von`true` oder `false` übergeben. Diese Funktion hat keinen Rückgabewert. **getLinks()** Diese Funktion gibt ein Array von `SyntheticsLink`-Objekten zurück, die im Bericht zur Überprüfung von defekten Links enthalten sind. **getTotalBrokenVerknüpfungen ()** Diese Funktion gibt eine Zahl zurück, die die Gesamtzahl der defekten Links darstellt. **getTotalLinksGeprüft ()** Diese Funktion gibt eine Zahl zurück, die die Gesamtzahl der im Bericht enthaltenen Links darstellt. **Wie benutzt man BrokenLinkCheckerReport** Das folgende Code-Snippet aus einem Canary-Skript veranschaulicht anhand eines Beispiels die Navigation zu einem Link und das Hinzufügen zum Bericht zur Überprüfung eines fehlerhaften Links. 1. Importieren von `SyntheticsLink`, `BrokenLinkCheckerReport` und ` Synthetics`. ``` const BrokenLinkCheckerReport = require('@aws/synthetics-broken-link-checker-report'); const SyntheticsLink = require('@aws/synthetics-link'); // Synthetics dependency const synthetics = require('@aws/synthetics-puppeteer'); ``` 1. Um einen Link zum Bericht hinzuzufügen, erstellen Sie eine Instance von ` BrokenLinkCheckerReport`. ``` let brokenLinkCheckerReport = new BrokenLinkCheckerReport(); ``` 1. Navigieren Sie zu der URL, und fügen Sie sie dem Bericht zur Überprüfung fehlerhafter Links hinzu. ``` let url = "https://amazon.com"; let syntheticsLink = new SyntheticsLink(url); // Navigate to the url. let page = await synthetics.getPage(); // Create a new instance of Synthetics Link let link = new SyntheticsLink(url) try { const response = await page.goto(url, {waitUntil: 'domcontentloaded', timeout: 30000}); } catch (ex) { // Add failure reason if navigation fails. link.withFailureReason(ex); } if (response) { // Capture screenshot of destination page let screenshotResult = await synthetics.takeScreenshot('amazon-home', 'loaded'); // Add screenshot result to synthetics link link.addScreenshotResult(screenshotResult); // Add status code and status description to the link link.withStatusCode(response.status()).withStatusText(response.statusText()) } // Add link to broken link checker report. brokenLinkCheckerReport.addLink(link); ``` 1. Fügen Sie den Bericht zu Synthetics hinzu. Dadurch wird für jeden Canary-Lauf eine JSON-Datei mit dem Namen ` BrokenLinkCheckerReport.json` in Ihrem S3 Bucket erstellt. Sie können einen Link-Bericht in der Konsole für jeden Canary-Lauf zusammen mit Screenshots, Protokollen und HAR-Dateien sehen. ``` await synthetics.addReport(brokenLinkCheckerReport); ``` ### SyntheticsLink Klasse Diese Klasse bietet Methoden zum Umschließen von Informationen. Es wird nur auf Canaries unterstützt, die die `syn-nodejs-2.0-beta`-Version der Laufzeit oder höher verwenden. Um `SyntheticsLink` zu verwenden, fügen Sie die folgenden Zeilen in das Skript ein: ``` const SyntheticsLink = require('@aws/synthetics-link'); const syntheticsLink = new SyntheticsLink("https://www.amazon.com"); ``` Diese Funktion gibt `syntheticsLink{{Object}}` zurück Nützliche Funktionsdefinitionen: **mit URL () {{url}}** ` {{url}} ` ist eine URL-Zeichenfolge. Diese Funktion gibt `syntheticsLink{{Object}}` zurück **mit Text () {{text}}** ` {{text}} ` ist eine Zeichenfolge, die Ankertext darstellt. Diese Funktion gibt `syntheticsLink{{Object}}` zurück. Es fügt Ankertext hinzu, der dem Link entspricht. **withParentUrl({{parentUrl}})** ` {{parentUrl}} ` ist eine Zeichenfolge, die die übergeordnete URL (Quellseite) darstellt. Diese Funktion gibt `syntheticsLink{{ Object}}` zurück **withStatusCode({{statusCode}})** ` {{statusCode}} ` ist eine Zeichenfolge, die den Statuscode darstellt. Diese Funktion gibt `syntheticsLink{{Object}}` zurück **withFailureReason({{failureReason}})** ` {{failureReason}} ` ist eine Zeichenfolge, die den Grund für den Fehler darstellt. Diese Funktion gibt `syntheticsLink{{ Object}}` zurück **addScreenshotResult({{screenshotResult}})** ` {{screenshotResult}} ` ist ein Objekt. Es ist eine Instance von `ScreenshotResult`, die von der Synthetics-Funktion `takeScreenshot` zurückgegeben wurde. Das Objekt umfasst Folgendes: + `fileName` – Eine Zeichenfolge, die ` screenshotFileName` darstellt + `pageUrl` (optional) + `error` (optional) ## Node.js-Bibliotheksklassen und -funktionen, die nur für API-Canaries gelten Die folgenden CloudWatch Synthetics-Bibliotheksfunktionen für Node.js sind nur für API Canaries nützlich. **Topics** + [executeHttpStep(stepName, RequestOptions, [Rückruf], [StepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep) ### executeHttpStep(stepName, RequestOptions, [Rückruf], [StepConfig]) Führt die bereitgestellte HTTP-Anforderung als Schritt aus und veröffentlicht `SuccessPercent`- (pass/fail) und `Duration`-Metriken. **executeHttpStep**verwendet entweder native HTTP- oder HTTPS-Funktionen unter der Haube, abhängig vom in der Anfrage angegebenen Protokoll. Diese Funktion fügt dem Bericht des Canarys außerdem eine Zusammenfassung der Schrittausführung hinzu. Die Zusammenfassung enthält Details zu jeder HTTP-Anforderung, wie zum Beispiel die folgenden: + Startzeit + Endzeit + Status (PASSED/FAILED) + Fehlergrund, wenn fehlgeschlagen + HTTP-Aufrufdetails wie request/response Header, Hauptteil, Statuscode, Statusmeldung und Leistungszeiten. **Topics** + [Parameters](#CloudWatch_Synthetics_Library_executeHttpStep_parameters) + [Beispiele für die Verwendung executeHttpStep](#CloudWatch_Synthetics_Library_executeHttpStep_examples) #### Parameters **stepName () {{String}}** Legt den Namen des Schrittes fest. Dieser Name wird auch für die Veröffentlichung von CloudWatch Metriken für diesen Schritt verwendet. **RequestOptions () {{Object or String}}** Der Wert dieses Parameters kann eine URL, eine URL-Zeichenfolge oder ein Objekt sein. Wenn es sich um ein Objekt handelt, muss es sich um eine Gruppe konfigurierbarer Optionen handeln, um eine HTTP-Anforderung zu stellen. Es unterstützt alle Optionen in [ http.request(options[, callback])](https://nodejs.org/api/http.html#http_http_request_options_callback) in der Node.js-Dokumentation. Zusätzlich zu diesen Node.js-Optionen unterstützt **requestOptions** den zusätzlichen Parameter `body`. Sie können den Parameter `body` verwenden, um Daten als Anforderungstext zu übergeben. **Rückruf () {{response}}** (Optional) Dies ist eine Benutzerfunktion, die mit der HTTP-Antwort aufgerufen wird. Die Antwort ist vom Typ [Class: http. IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage). **SchrittKonfiguration () {{object}}** (Optional) Verwenden Sie diesen Parameter, um globale Synthetics-Konfigurationen mit einer anderen Konfiguration für diesen Schritt zu überschreiben. #### Beispiele für die Verwendung executeHttpStep Die folgende Reihe von Beispielen baut aufeinander auf, um die verschiedenen Verwendungsmöglichkeiten dieser Option zu veranschaulichen. In diesem ersten Beispiel werden Anforderungsparameter konfiguriert. Sie können eine URL als **RequestOptions** übergeben: ``` let requestOptions = 'https://www.amazon.com'; ``` Oder Sie können eine Reihe von Optionen übergeben: ``` let requestOptions = { 'hostname': 'myproductsEndpoint.com', 'method': 'GET', 'path': '/test/product/validProductName', 'port': 443, 'protocol': 'https:' }; ``` Das nächste Beispiel erstellt eine Callback-Funktion, die eine Antwort akzeptiert. Wenn Sie keinen **Callback** angeben, überprüft CloudWatch Synthetics standardmäßig, ob der Status zwischen 200 und 299 (einschließlich) liegt. ``` // 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(); }); }); }; ``` Das nächste Beispiel erstellt eine Konfiguration für diesen Schritt, die die globale CloudWatch Synthetics-Konfiguration überschreibt. Die Schrittkonfiguration in diesem Beispiel ermöglicht Anforderungskopfzeilen, Antwort-Header, Anforderungstext (Postdaten) und Antworttext in Ihrem Bericht und schränkt die Header-Werte „X-AMZ-Security-Token“ und „Authorization“ ein. Standardmäßig sind diese Werte aus Sicherheitsgründen nicht im Bericht enthalten. Wenn Sie sie einbeziehen, werden die Daten nur in Ihrem S3 Bucket gespeichert. ``` // 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 }; ``` Dieses letzte Beispiel leitet Ihre Anfrage an den Schritt weiter **executeHttpStep**und benennt ihn. ``` await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig); ``` Mit diesen Beispielen fügt CloudWatch Synthetics die Details aus jedem Schritt in Ihrem Bericht hinzu und erstellt mithilfe von **stepName** Metriken für jeden Schritt. Sie sehen `successPercent`- und `duration`-Metriken für den Schritt `Verify GET products API`. Sie können Ihre API-Leistung überwachen, indem Sie die Metriken für Ihre API-Aufrufschritte überwachen. Ein vollständiges Beispielskript, das diese Funktionen verwendet, finden Sie unter [Mehrstufiger API-Canary](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps).