Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Funzioni di libreria disponibili per gli script canary Node.js utilizzando Puppeteer Questa sezione descrive le funzioni di libreria disponibili per gli script canary Node.js. **Topics** + [Classi e funzioni di libreria di Node.js che si applicano a tutti i canary](#CloudWatch_Synthetics_Library_allcanaries) + [Classi e funzioni della libreria di Node.js che si applicano solo ai canary dell'interfaccia utente](#CloudWatch_Synthetics_Library_UIcanaries) + [Classi e funzioni della libreria di Node.js che si applicano solo ai canary dell'API](#CloudWatch_Synthetics_Library_APIcanaries) ## Classi e funzioni di libreria di Node.js che si applicano a tutti i canary Le seguenti funzioni della libreria CloudWatch Synthetics per Node.js sono utili per tutti i canarini. **Topics** + [Classe Synthetics](#CloudWatch_Synthetics_Library_Synthetics_Class_all) + [SyntheticsConfiguration classe](#CloudWatch_Synthetics_Library_SyntheticsConfiguration) + [Synthetics logger](#CloudWatch_Synthetics_Library_SyntheticsLogger) + [SyntheticsLogHelper classe](#CloudWatch_Synthetics_Library_SyntheticsLogHelper) ### Classe Synthetics Le seguenti funzioni per tutti i canary sono nella classe Synthetics. **Topics** + [addExecutionError(ErrorMessage, es.);](#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, es.); `errorMessage` descrive l'errore e `ex` è l'eccezione che si verifica Puoi utilizzare `addExecutionError` per impostare gli errori di esecuzione per il tuo canary. Fa fallire il canary senza interrompere l'esecuzione dello script. Inoltre, non influisce sui tuoi parametri `successPercent`. È necessario tenere traccia degli errori come errori di esecuzione solo se non sono importanti per indicare il successo o il fallimento dello script canary. Di seguito è illustrato un esempio dell'uso dell'elemento `addExecutionError`. Stai monitorando la disponibilità del tuo endpoint e acquisendo screenshot dopo che la pagina è stata caricata. Poiché l'errore di acquisizione di uno screenshot non determina la disponibilità dell'endpoint, puoi rilevare eventuali errori riscontrati durante l'acquisizione di screenshot e aggiungerli come errori di esecuzione. I parametri di disponibilità indicheranno comunque che l'endpoint è attivo e funzionante, ma lo stato del canary verrà contrassegnato come non riuscito. Il seguente blocco di codice di esempio rileva tale errore e lo aggiunge come errore di esecuzione. ``` try { await synthetics.takeScreenshot(stepName, "loaded"); } catch(ex) { synthetics.addExecutionError('Unable to take screenshot ', ex); } ``` #### getCanaryName(); Restituisce il nome del canary. #### getCanaryArn(); Restituisce l'ARN del canary. #### getCanaryUserAgentString(); Restituisce l'agente utente personalizzato del canary. #### getRuntimeVersion(); Questa funzione è disponibile nella versione di runtime `syn-nodejs-puppeteer-3.0` e versione successiva. Restituisce la versione di runtime di Synthetics del canary. Ad esempio, il valore restituito potrebbe essere `syn-nodejs-puppeteer-3.0`. #### getLogLevel(); Recupera il livello di log corrente per la libreria Synthetics. I valori possibili sono i seguenti: + `0`: Debug + `1`: Info + `2`: Warn + `3`: Error Esempio: ``` let logLevel = synthetics.getLogLevel(); ``` #### setLogLevel(); Imposta il livello di log per la libreria Synthetics. I valori possibili sono i seguenti: + `0`: Debug + `1`: Info + `2`: Warn + `3`: Error Esempio: ``` synthetics.setLogLevel(0); ``` ### SyntheticsConfiguration classe Questa classe è disponibile solo nella versione di runtime `syn-nodejs-2.1` o versioni successive. Puoi utilizzare la classe `SyntheticsConfiguration` per configurare il comportamento delle funzioni della libreria Synthetics. Ad esempio, puoi utilizzare questa classe per configurare la funzione `executeStep()` per non acquisire screenshot. È possibile impostare configurazioni CloudWatch Synthetics a livello globale, che vengono applicate a tutti i passaggi di Canaries. Puoi anche sovrascrivere queste configurazioni a livello di passaggio passando coppie chiave e valore di configurazione. Puoi passare le opzioni a livello di fase. Per alcuni esempi, consulta [async executeStep (StepName,, [StepConfig]); functionToExecute](#CloudWatch_Synthetics_Library_executeStep) e [executeHttpStep(StepName, RequestOptions, [callback], [StepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep) **Topics** + [setConfig(options)](#CloudWatch_Synthetics_Library_setConfig) + [Monitoraggio visivo](#CloudWatch_Synthetics_Library_SyntheticsLogger_VisualTesting) #### setConfig(options) ` {{options}} ` è un oggetto, che è un insieme di opzioni configurabili per il tuo canary. Le seguenti sezioni spiegano i campi possibili in ` {{options}} `. ##### setConfig(options) per tutti i canary Per i canarini che utilizzano `syn-nodejs-puppeteer-3.2` o versioni successive, le **(opzioni)** di **setConfig possono includere i seguenti parametri**: + `includeRequestHeaders` (booleano): indica se includere le intestazioni della richiesta nel report. Il valore predefinito è `false`. + `includeResponseHeaders` (booleano): indica se includere le intestazioni della risposta nel report. Il valore predefinito è `false`. + `restrictedHeaders` (array): un elenco di valori di intestazione da ignorare, se le intestazioni sono incluse. Questo vale sia per le intestazioni della richiesta che della risposta. **Ad esempio, puoi nascondere le tue credenziali passando ** includeRequestHeaders**as e RestrictedHeaders as`true`.** `['Authorization']` + `includeRequestBody` (booleano): indica se includere il corpo della richiesta nel report. Il valore predefinito è `false`. + `includeResponseBody` (booleano): indica se includere il corpo della risposta nel report. Il valore predefinito è `false`. **Importante** Se abiliti uno dei due `includeResponseBody` o` logResponseBody`, l'oggetto dati non viene restituito nella risposta da alcuni APIs, come i client aws-sdk v3. Ciò è dovuto a una limitazione di Node.js e al tipo di oggetto di risposta utilizzato. **setConfig (opzioni) relative alle metriche CloudWatch ** Per i canarini che utilizzano `syn-nodejs-puppeteer-3.1` o versioni successive, le **(options)** di **setConfig** possono includere i seguenti parametri booleani che determinano quali metriche vengono pubblicate dal canarino. Il valore predefinito per ciascuna di queste opzioni è `true`. Le opzioni che iniziano con `aggregated` determinano se il parametro viene emesso senza destinazione ` CanaryName`. Puoi usare questi parametri per visualizzare i risultati aggregati per tutti i canary. Le altre opzioni determinano se il parametro viene emesso con la dimensione `CanaryName`. Puoi usare questi parametri per visualizzare i risultati per ogni singolo canary. Per un elenco delle metriche emesse dai canarini, vedi CloudWatch . [CloudWatch metriche pubblicate da canaries](CloudWatch_Synthetics_Canaries_metrics.md) + `failedCanaryMetric` (booleano): indica se emettere il parametro ` Failed` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `failedRequestsMetric` (booleano): indica se emettere il parametro `Failed requests` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `_2xxMetric` (booleano): indica se emettere il parametro `2xx` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `_4xxMetric` (booleano): indica se emettere il parametro `4xx` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `_5xxMetric` (booleano): indica se emettere il parametro `5xx` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `stepDurationMetric` (booleano): indica se emettere il parametro `Step duration` (con le dimensioni `CanaryName` `StepName`) per questo canary. Il valore predefinito è `true`. + `stepSuccessMetric` (booleano): indica se emettere il parametro `Step success` (con le dimensioni `CanaryName` `StepName`) per questo canary. Il valore predefinito è `true`. + `aggregatedFailedCanaryMetric` (booleano): indica se emettere il parametro `Failed` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `aggregatedFailedRequestsMetric` (booleano): indica se emettere il parametro `Failed Requests` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `aggregated2xxMetric` (booleano): indica se emettere il parametro ` 2xx` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `aggregated4xxMetric` (booleano): indica se emettere il parametro ` 4xx` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `aggregated5xxMetric` (booleano): indica se emettere il parametro ` 5xx` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `visualMonitoringSuccessPercentMetric` (booleano): indica se emettere il parametro `visualMonitoringSuccessPercent` per questo canary. Il valore predefinito è `true`. + `visualMonitoringTotalComparisonsMetric` (booleano): indica se emettere il parametro `visualMonitoringTotalComparisons` per questo canary. Il valore predefinito è `false`. + `includeUrlPassword` (booleano): indica se includere una password visualizzata nell'URL. Per impostazione predefinita, le password che compaiono in URLs vengono cancellate dai registri e dai report, per evitare la divulgazione di dati sensibili. Il valore predefinito è `false`. + `restrictedUrlParameters` (array): un elenco di parametri del percorso dell'URL o della query da oscurare. Questo vale per la URLs visualizzazione nei log, nei report e negli errori. Il parametro prevede la distinzione tra lettere maiuscole e minuscole. Puoi passare un asterisco (\*) come valore per oscurare tutti i valori dei parametri del percorso dell'URL e delle query. L'impostazione predefinita è una matrice vuota. + `logRequest` (booleano): indica se registrare ogni richiesta nei log del canary. Per i canary dell'interfaccia utente, registra ogni richiesta inviata dal browser. Il valore predefinito è `true`. + `logResponse` (booleano): indica se registrare ogni risposta nei log del canary. Per i canary dell'interfaccia utente, registra ogni risposta ricevuta dal browser. Il valore predefinito è `true`. + `logRequestBody` (booleano): indica se registrare i corpi delle richieste insieme alle richieste nei log dei canary. Questa configurazione si applica solo se `logRequest` è `true`. Il valore predefinito è `false`. + `logResponseBody` (booleano): indica se registrare i corpi delle risposte insieme alle risposte nei log dei canary. Questa configurazione si applica solo se `logResponse` è `true`. Il valore predefinito è ` false`. **Importante** Se abiliti uno dei due `includeResponseBody` o` logResponseBody`, l'oggetto dati non viene restituito nella risposta da alcuni APIs, come i client aws-sdk v3. Ciò è dovuto a una limitazione di Node.js e al tipo di oggetto di risposta utilizzato. + `logRequestHeaders` (booleano): indica se registrare le intestazioni delle richieste insieme alle richieste nei log dei canary. Questa configurazione si applica solo se `logRequest` è `true`. Il valore predefinito è ` false`. Nota che `includeRequestHeaders` abilita le intestazioni negli artefatti. + `logResponseHeaders` (booleano): indica se registrare le intestazioni delle risposte insieme alle risposte nei log dei canary. Questa configurazione si applica solo se `logResponse` è `true`. Il valore predefinito è ` false`. Nota che `includeResponseHeaders` abilita le intestazioni negli artefatti. **Nota** I parametri `Duration` e `SuccessPercent` vengono sempre emessi per ogni canary, sia con che senza il parametro `CanaryName`. ##### Metodi per abilitare o disabilitare i parametri **disableAggregatedRequestMetriche ()** Disabilita il canary dall'emettere tutti i parametri delle richieste emessi senza dimensione `CanaryName`. **disableRequestMetrics()** Disabilita tutti i parametri delle richieste, inclusi i parametri dei canary e i parametri aggregati in tutti i canary. **disableStepMetrics()** Disabilita tutti i parametri dei passaggi, inclusi sia quelli di riuscita che di durata. **enableAggregatedRequestMetriche ()** Consente al canary di emettere tutti i parametri della richiesta emessi senza la dimensione ` CanaryName`. **enableRequestMetrics()** Abilita tutti i parametri delle richieste, inclusi i parametri dei canary e i parametri aggregati in tutti i canary. **enableStepMetrics()** Abilita tutti i parametri dei passaggi, inclusi sia quelli di riuscita che di durata. **get2xxMetric()** Indica se il canary emette un parametro `2xx` con dimensione ` CanaryName`. **get4xxMetric()** Indica se il canary emette un parametro `4xx` con dimensione ` CanaryName`. **get5xxMetric()** Indica se il canary emette un parametro `5xx` con dimensione ` CanaryName`. **getAggregated2xxMetric()** Indica se il canary emette un parametro `2xx` senza dimensione. **getAggregated4xxMetric()** Indica se il canary emette un parametro `4xx` senza dimensione. **getAggregatedFailedCanaryMetric()** Indica se il canary emette un parametro `Failed` senza dimensione. **getAggregatedFailedRequestsMetric()** Indica se il canary emette un parametro `Failed requests` senza dimensione. **getAggregated5xxMetric()** Indica se il canary emette un parametro `5xx` senza dimensione. **getFailedCanaryMetrica ()** Indica se il canary emette un parametro `Failed` con dimensione ` CanaryName`. **getFailedRequestsMetrico ()** Indica se il canary emette un parametro `Failed requests` con dimensione `CanaryName`. **getStepDurationMetrico ()** Indica se il canary emette un parametro `Duration` con dimensione ` CanaryName` per questo canary. **getStepSuccessMetrico ()** Indica se il canary emette un parametro `StepSuccess` con dimensione ` CanaryName` per questo canary. **with2xxMetric(\_2xxMetric)** Accetta un argomento booleano, che specifica se emettere un parametro `2xx` con dimensione `CanaryName` per questo canary. **with4xxMetric(\_4xxMetric)** Accetta un argomento booleano, che specifica se emettere un parametro `4xx` con dimensione `CanaryName` per questo canary. **with5xxMetric(\_5xxMetric)** Accetta un argomento booleano, che specifica se emettere un parametro `5xx` con dimensione `CanaryName` per questo canary. **withAggregated2xxMetric(aggregated2xxMetric)** Accetta un argomento booleano, che specifica se emettere un parametro `2xx` senza alcuna dimensione per questo canary. **withAggregated4xxMetric(aggregated4xxMetric)** Accetta un argomento booleano, che specifica se emettere un parametro `4xx` senza alcuna dimensione per questo canary. **withAggregated5xxMetric(aggregated5xxMetric)** Accetta un argomento booleano, che specifica se emettere un parametro `5xx` senza alcuna dimensione per questo canary. ** withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetrico)** Accetta un argomento booleano, che specifica se emettere un parametro `Failed` senza alcuna dimensione per questo canary. ** withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetrico)** Accetta un argomento booleano, che specifica se emettere un parametro `Failed requests` senza alcuna dimensione per questo canary. **withFailedCanaryMetrico () failedCanaryMetric** Accetta un argomento booleano, che specifica se emettere un parametro `Failed` con dimensione `CanaryName` per questo canary. **withFailedRequestsMetrico () failedRequestsMetric** Accetta un argomento booleano, che specifica se emettere un parametro `Failed requests` con dimensione `CanaryName` per questo canary. **withStepDurationMetrico () stepDurationMetric** Accetta un argomento booleano, che specifica se emettere un parametro `Duration` con dimensione `CanaryName` per questo canary. **withStepSuccessMetrico () stepSuccessMetric** Accetta un argomento booleano, che specifica se emettere un parametro ` StepSuccess` con dimensione `CanaryName` per questo canary. ##### Metodi per abilitare o disabilitare altre funzionalità **withHarFile()** Accetta un argomento booleano, che specifica se creare un file HAR per questo canary. **withStepsReport()** Accetta un argomento booleano, che specifica se segnalare un riepilogo dell'esecuzione delle fasi per questo canary. **withIncludeUrlPassword ()** Accetta un argomento booleano che specifica se includere le password che compaiono nei log e URLs nei report. **withRestrictedUrlParametri ()** Accetta una matrice di parametri del percorso dell'URL o della query da oscurare. Questo vale per la URLs visualizzazione nei log, nei report e negli errori. Puoi passare un asterisco (\*) come valore per oscurare tutti i valori dei parametri del percorso dell'URL e delle query **withLogRequest()** Accetta un argomento booleano, che specifica se registrare ogni richiesta nei log del canary. **withLogResponse()** Accetta un argomento booleano, che specifica se registrare ogni risposta nei log del canary. **withLogRequestCorpo ()** Accetta un argomento booleano, che specifica se registrare ogni corpo della richiesta nei log del canary. **withLogResponseCorpo ()** Accetta un argomento booleano, che specifica se registrare ogni corpo della risposta nei log del canary. **withLogRequestIntestazioni ()** Accetta un argomento booleano, che specifica se registrare ogni intestazione della richiesta nei log del canary. **withLogResponseIntestazioni ()** Accetta un argomento booleano, che specifica se registrare ogni intestazione della risposta nei log del canary. **getHarFile()** Restituisce se il canary crea un file HAR. **getStepsReport()** Restituisce se il canary segnala un riepilogo dell'esecuzione della fase. **getIncludeUrlPassword ()** Indica se il canarino include le password che compaiono nei registri e URLs nei rapporti. **getRestrictedUrlParametri ()** Restituisce se il canary oscura i parametri del percorso dell'URL o della query. **getLogRequest()** Restituisce se il canary registra ogni richiesta nei log del canary. **getLogResponse()** Restituisce se il canary registra ogni risposta nei log del canary. **getLogRequestCorpo ()** Restituisce se il canary registra ogni corpo della richiesta nei log del canary. **getLogResponseCorpo ()** Restituisce se il canary registra ogni corpo della risposta nei log del canary. **getLogRequestIntestazioni ()** Restituisce se il canary registra ogni intestazione della richiesta nei log del canary. **getLogResponseIntestazioni ()** Restituisce se il canary registra ogni intestazione della risposta nei log del canary. **Funzioni per tutti i canary** + `withIncludeRequestHeaders`(includeRequestHeaders) + `withIncludeResponseHeaders`(includeResponseHeaders) + `withRestrictedHeaders`(restrictedHeaders) + `withIncludeRequestBody`(includeRequestBody) + `withIncludeResponseBody`(includeResponseBody) + `enableReportingOptions`() — Abilita tutte le opzioni di reporting-- **includeRequestHeaders**, ** includeResponseHeaders**includeRequestBody****, e **includeResponseBody**,. + `disableReportingOptions`() — Disattiva tutte le opzioni di reporting-- **includeRequestHeaders**, ** includeResponseHeaders**includeRequestBody****, e **includeResponseBody**,. ##### setConfig(options) per canary dell'interfaccia utente Per i canary dell'interfaccia utente, **setConfig** può includere i seguenti parametri booleani: + `continueOnStepFailure`**(boolean) — Indica se continuare a eseguire lo script canary dopo un passaggio fallito (si riferisce alla funzione ExecuteStep).** Se le fasi hanno esito negativo, l'esecuzione del canary verrà comunque contrassegnata come fallita. Il valore predefinito è `false`. + `harFile` (booleano): indica se creare un file HAR. Il valore predefinito è `True`. + `screenshotOnStepStart` (booleano): indica se fare uno screenshot prima di iniziare una fase. + `screenshotOnStepSuccess` (booleano): indica se acquisire uno screenshot dopo aver completato una fase riuscita. + `screenshotOnStepFailure` (booleano): indica se acquisire uno screenshot dopo il fallimento di una fase. ##### Metodi per abilitare o disabilitare gli screenshot **disableStepScreenshots()** Disattiva tutte le opzioni relative agli screenshot (screenshotOnStepStart, Success e Failure). screenshotOnStep screenshotOnStep **enableStepScreenshots()** Abilita tutte le opzioni relative agli screenshot (screenshotOnStepStart, screenshotOnStep Success e screenshotOnStep Failure). Per impostazione predefinita, tutti questi metodi sono abilitati. **getScreenshotOnStepFailure()** Restituisce se il canary acquisisce uno screenshot dopo che una fase fallisce. **getScreenshotOnStepStart()** Restituisce se il canary acquisisce uno screenshot prima di iniziare una fase. **getScreenshotOnStepSuccess()** Restituisce se il canary acquisisce uno screenshot dopo aver completato correttamente una fase. **withScreenshotOnStepStart(screenshotOnStepInizio)** Accetta un argomento booleano, che indica se eseguire uno screenshot prima di iniziare una fase. **withScreenshotOnStepSuccess(screenshotOnStepSuccesso)** Accetta un argomento booleano, che indica se acquisire uno screenshot dopo aver completato correttamente una fase. **withScreenshotOnStepFailure(screenshotOnStepFallimento)** Accetta un argomento booleano, che indica se acquisire uno screenshot dopo il fallimento di una fase. **Utilizzo in canary dell'interfaccia utente** Innanzitutto, importa la dipendenza di Synthetics e recupera la configurazione. ``` // Import Synthetics dependency const synthetics = require('@aws/synthetics-puppeteer'); // Get Synthetics configuration const synConfig = synthetics.getConfiguration(); ``` Quindi, imposta la configurazione per ogni opzione chiamando il metodo setConfig utilizzando una delle opzioni seguenti. ``` // Set configuration values synConfig.setConfig({ screenshotOnStepStart: true, screenshotOnStepSuccess: false, screenshotOnStepFailure: false }); ``` Oppure ``` synConfig.withScreenshotOnStepStart(false).withScreenshotOnStepSuccess(true).withScreenshotOnStepFailure(true) ``` Per disabilitare tutti gli screenshot, utilizza la funzione `disableStepScreenshots()` come in questo esempio. ``` synConfig.disableStepScreenshots(); ``` Puoi abilitare e disabilitare gli screenshot in qualsiasi punto del codice. Ad esempio, per disabilitare gli screenshot solo per una fase, disattivali prima di eseguire tale fase e quindi attivali dopo la fase. ##### setConfig(options) per canary dell'iAPI Per i canary dell'API, **setConfig** può includere i seguenti parametri booleani: + `continueOnHttpStepFailure`(boolean) — Indica se continuare a eseguire lo script canary dopo un errore in un passaggio HTTP (si riferisce alla **executeHttpStep**funzione). Se le fasi hanno esito negativo, l'esecuzione del canary verrà comunque contrassegnata come fallita. Il valore predefinito è `true`. #### Monitoraggio visivo Il monitoraggio visivo confronta gli screenshot acquisiti durante un'esecuzione del canary con quelli acquisiti durante un'esecuzione del canary di riferimento. Se la discrepanza tra i due screenshot supera una percentuale di soglia, il canary fallisce e puoi vedere le aree con differenze di colore evidenziate nel report di esecuzione del canary. **Il monitoraggio visivo è supportato nei canaries che eseguono syn-puppeteer-node -3.2 e versioni successive.** Attualmente non è supportato nei canary che eseguono Python e Selenium. Per abilitare il monitoraggio visivo, aggiungi la seguente riga di codice allo script canary. Per ulteriori dettagli, consulta [SyntheticsConfiguration classe](#CloudWatch_Synthetics_Library_SyntheticsConfiguration). ``` syntheticsConfiguration.withVisualCompareWithBaseRun(true); ``` La prima volta che il canary viene eseguito correttamente dopo che questa riga è stata aggiunta allo script, utilizza gli screenshot acquisiti durante l'esecuzione come riferimento per il confronto. Dopo la prima esecuzione del canarino, puoi usare la CloudWatch console per modificare il canarino per eseguire una delle seguenti operazioni: + Imposta l'esecuzione successiva del canary come nuovo riferimento. + Disegna dei limiti sullo screenshot di riferimento corrente per designare le aree dello screenshot da ignorare durante i confronti visivi. + Rimuovi uno screenshot dall'utilizzo per il monitoraggio visivo. Per ulteriori informazioni sull'utilizzo della CloudWatch console per modificare un canarino, consulta. [Modifica o eliminazione di un canary](synthetics_canaries_deletion.md) **Altre opzioni per il monitoraggio visivo** Configurazione **sintetica. withVisualVarianceThresholdPercentage(Percentuale desiderata)** Imposta la percentuale accettabile per la varianza dello screenshot nei confronti visivi. **Configurazione sintetica. withVisualVarianceHighlightHexColor(» \#fafa00 «)** Imposta il colore di evidenziazione che designa le aree di varianza quando si esaminano i report di esecuzione del canary che utilizzano il monitoraggio visivo. Configurazione **sintetica. withFailCanaryRunOnVisualVariance(Fail Canary)** Imposta se il canary fallisce o meno quando vi è una differenza visiva superiore alla soglia. L'impostazione predefinita è far fallire il canary. ### Synthetics logger SyntheticsLogger scrive i log out sia sulla console che su un file di registro locale allo stesso livello di registro. Questo file di log viene scritto in entrambe le posizioni solo se il livello di log è pari o inferiore al livello di registrazione desiderato della funzione di log chiamata. Le istruzioni di registrazione nel file di log locale sono precedute da "DEBUG: ", "INFO: " e così via per corrispondere al livello di log della funzione che è stata chiamata. Puoi usare SyntheticsLogger, supponendo che tu voglia eseguire la Synthetics Library allo stesso livello di registro del tuo Synthetics Canary Logging. L'utilizzo di non SyntheticsLogger è necessario per creare un file di registro da caricare nella posizione dei risultati S3. Puoi invece creare un file di log diverso nella cartella ` /tmp`. Tutti i file creati nella cartella `/tmp` vengono caricati nella posizione dei risultati in S3 come artefatti. Per utilizzare il logger della libreria Synthetics: ``` const log = require('@aws/synthetics-logger'); ``` Definizioni utili delle funzioni: **log.debug (,); {{message}} {{ex}}** Parametri: {{message}} è il messaggio da registrare. {{ ex}}è l'eventuale eccezione da registrare. Esempio: ``` log.debug("Starting step - login."); ``` **log.error ({{message}},); {{ex}}** Parametri: {{message}} è il messaggio da registrare. {{ ex}}è l'eventuale eccezione da registrare. Esempio: ``` try { await login(); catch (ex) { log.error("Error encountered in step - login.", ex); } ``` **log.info ({{message}},{{ex}});** Parametri: {{message}} è il messaggio da registrare. {{ ex}}è l'eventuale eccezione da registrare. Esempio: ``` log.info("Successfully completed step - login."); ``` **log.log ({{message}},{{ex}});** Questo è un alias per `log.info`. Parametri: {{message}} è il messaggio da registrare. {{ ex}}è l'eventuale eccezione da registrare. Esempio: ``` log.log("Successfully completed step - login."); ``` **log.warn (,){{message}}; {{ex}}** Parametri: {{message}} è il messaggio da registrare. {{ ex}}è l'eventuale eccezione da registrare. Esempio: ``` log.warn("Exception encountered trying to publish CloudWatch Metric.", ex); ``` ### SyntheticsLogHelper classe La classe `SyntheticsLogHelper` è disponibile nel runtime ` syn-nodejs-puppeteer-3.2` e nei runtime successivi. È già inizializzato nella libreria CloudWatch Synthetics ed è configurato con la configurazione Synthetics. È possibile aggiungerla come dipendenza nello script. Questa classe consente di disinfettare le intestazioni e i messaggi di URLs errore per oscurare le informazioni sensibili. **Nota** Synthetics elimina URLs tutti i messaggi di errore che registra prima di includerli nei registri, nei report, nei file HAR e negli errori di esecuzione di Canary in base all'impostazione di configurazione Synthetics. `restrictedUrlParameters` È necessario utilizzarlo ` getSanitizedUrl` o `getSanitizedErrorMessage` solo se si registrano errori o si verificano errori nello script. URLs Synthetics non memorizza alcun artefatto canary tranne che per gli errori del canary generati dallo script. Gli artefatti di esecuzione del canary sono archiviati nel tuo account cliente. Per ulteriori informazioni, consulta [Considerazioni sulla sicurezza per Canary Synthetics](servicelens_canaries_security.md). **Topics** + [getSanitizedUrl(url, stepConfig = null)](#CloudWatch_Synthetics_Library_getSanitizedUrl) + [getSanitizedErrorMessaggio](#CloudWatch_Synthetics_Library_getSanitizedErrorMessage) + [getSanitizedHeaders(intestazioni, stepconfig=null)](#CloudWatch_Synthetics_Library_getSanitizedHeaders) #### getSanitizedUrl(url, stepConfig = null) Questa funzione è disponibile nella versione `syn-nodejs-puppeteer-3.2` e versione successiva. Restituisce stringhe di URL sanificate in base alla configurazione. Puoi scegliere di oscurare parametri di URL sensibili ad esempio password e access\_token impostando la proprietà `restrictedUrlParameters`. Per impostazione predefinita, le password inserite vengono oscurate. URLs Se necessario, puoi abilitare le password degli URL impostando `includeUrlPassword` su “true”. Questa funzione genera un errore se l'URL passato non è un URL valido. **Parametri** + {{url}}è una stringa ed è l'URL da disinfettare. + {{stepConfig}}(Facoltativo) sovrascrive la configurazione globale Synthetics per questa funzione. Se `stepConfig` non viene passato, la configurazione globale viene utilizzata per sanificare l'URL. **Esempio** In questo esempio viene utilizzato l'URL di esempio riportato di seguito: ` https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200`. In questo esempio, `access_token` contiene le tue informazioni sensibili che non devono essere registrate. Ricorda che i servizi Synthetics non memorizzano alcun artefatto di esecuzione del canary. Artefatti ad esempio log, screenshot e report sono tutti memorizzati in un bucket Amazon S3 nel tuo account cliente. La prima fase consiste nell'impostare la configurazione Synthetics. ``` // 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); ``` Quindi, sanifica e registra l'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'); ``` Questa procedura registra quanto segue nel log del canary. ``` My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200 ``` Puoi ignorare la configurazione Synthetics per un URL passando un parametro facoltativo contenente le opzioni di configurazione Synthetics, come nell'esempio seguente. ``` 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); ``` Nell'esempio precedente vengono oscurati tutti i parametri di query e vengono registrati come segue: ``` My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=REDACTED&expires_in=REDACTED ``` #### getSanitizedErrorMessaggio Questa funzione è disponibile nella versione `syn-nodejs-puppeteer-3.2` e versione successiva. Restituisce stringhe di errore sanificate disinfettando qualsiasi URLs regalo in base alla configurazione Synthetics. Puoi scegliere di sovrascrivere la configurazione Synthetics globale quando chiami questa funzione passando un parametro `stepConfig`. **Parametri** + {{error}}è l'errore da disinfettare. Può essere un oggetto Error o una stringa. + {{stepConfig}}(Facoltativo) sovrascrive la configurazione globale Synthetics per questa funzione. Se `stepConfig` non viene passato, la configurazione globale viene utilizzata per sanificare l'URL. **Esempio** In questo esempio viene utilizzato l'errore seguente: ` Failed to load url: https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200` La prima fase consiste nell'impostare la configurazione Synthetics. ``` // 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']; }); ``` Quindi, sanifica e registra il messaggio di errore ``` // 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); } ``` Questa procedura registra quanto segue nel log del canary. ``` Failed to load url: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200 ``` #### getSanitizedHeaders(intestazioni, stepconfig=null) Questa funzione è disponibile nella versione `syn-nodejs-puppeteer-3.2` e versione successiva. Restituisce intestazioni sanificate in base alla proprietà `restrictedHeaders` di ` syntheticsConfiguration`. Le intestazioni specificate nella proprietà `restrictedHeaders` vengono oscurate da log, file HAR e report. **Parametri** + {{headers}}è un oggetto contenente le intestazioni da disinfettare. + {{stepConfig}}(Facoltativo) sovrascrive la configurazione globale Synthetics per questa funzione. Se `stepConfig` non viene passato, la configurazione globale viene utilizzata per sanificare le intestazioni. ## Classi e funzioni della libreria di Node.js che si applicano solo ai canary dell'interfaccia utente Le seguenti funzioni della libreria CloudWatch Synthetics per Node.js sono utili solo per i canari dell'interfaccia utente. **Topics** + [Classe Synthetics](#CloudWatch_Synthetics_Library_Synthetics_Class) + [BrokenLinkCheckerReport classe](#CloudWatch_Synthetics_Library_BrokenLinkCheckerReport) + [SyntheticsLink classe](#CloudWatch_Synthetics_Library_SyntheticsLink) ### Classe Synthetics Le seguenti funzioni sono nella classe Synthetics. **Topics** + [async addUserAgent (pagina,); userAgentString](#CloudWatch_Synthetics_Library_addUserAgent) + [async executeStep (StepName,, [StepConfig]); functionToExecute](#CloudWatch_Synthetics_Library_executeStep) + [getDefaultLaunchOpzioni ();](#CloudWatch_Synthetics_Library_getDefaultLaunchOptions) + [getPage();](#CloudWatch_Synthetics_Library_getPage) + [getRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_getRequestResponseLogHelper) + [launch(options)](#CloudWatch_Synthetics_Library_LaunchOptions) + [RequestResponseLogHelper classe](#CloudWatch_Synthetics_Library_RequestResponseLogHelper) + [setRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_setRequestResponseLogHelper) + [async takeScreenshot(name, suffix);](#CloudWatch_Synthetics_Library_takeScreenshot) #### async addUserAgent (pagina,); userAgentString Questa funzione si aggiunge {{userAgentString}} all'intestazione user-agent della pagina specificata. Esempio: ``` await synthetics.addUserAgent(page, "MyApp-1.0"); ``` Risultati nell'intestazione user-agent della pagina impostata su `{{ browsers-user-agent-header-value}}MyApp-1.0` #### async executeStep (StepName,, [StepConfig]); functionToExecute Esegue il passaggio fornito, avvolgendolo con le metriche di durata. start/pass/fail logging, start/pass/fail screenshots, and pass/fail **Nota** Se utilizzi il runtime `syn-nodejs-2.1` o versione successiva, puoi configurare se e quando vengono acquisite le schermate. Per ulteriori informazioni, consulta [SyntheticsConfiguration classe](#CloudWatch_Synthetics_Library_SyntheticsConfiguration). La funzione `executeStep` svolge anche le operazioni seguenti: + Registra che il passaggio è iniziato. + Acquisisce uno screenshot denominato `-starting`. + Avvia un timer. + Esegue la funzione fornita. + Se la funzione viene restituita normalmente, conta come passaggio. Se la funzione genera, conta come errore. + Termina il timer. + Registra se il passaggio è riuscito o non è riuscito + Prende uno screenshot chiamato `-succeeded` o ` -failed`. + Emette la metrica `stepName` `SuccessPercent`, 100 per passato o 0 per errore. + Genera il parametro `stepName` `Duration` con un valore basato sull'ora di inizio e di fine del passaggio. + Infine, restituisce ciò che il `functionToExecute` ha restituito o rigenera ciò che `functionToExecute` ha generato. Se il canary usa il runtime `syn-nodejs-2.0` o versioni successive, questa funzione aggiunge anche un riepilogo dell'esecuzione delle fasi al report del canary. Il riepilogo include dettagli su ogni fase, ad esempio l'ora di inizio, l'ora di fine, lo stato (PASSED/FAILED), il motivo dell'errore (in caso di errore) e le schermate acquisite durante l'esecuzione di ogni fase. Esempio: ``` await synthetics.executeStep('navigateToUrl', async function (timeoutInMillis = 30000) { await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});}); ``` Risposta: Restituisce ciò che `functionToExecute` restituisce. **Aggiornamenti con syn-nodejs-2.2** A partire da`syn-nodejs-2.2`, puoi facoltativamente passare le configurazioni dei passaggi per sovrascrivere le configurazioni CloudWatch Synthetics a livello di passaggio. Per un elenco di opzioni che puoi trasferire a `executeStep`, consulta [SyntheticsConfiguration classe](#CloudWatch_Synthetics_Library_SyntheticsConfiguration). L'esempio riportato di seguito sostituisce la configurazione `false` di default per ` continueOnStepFailure` su `true` e specifica quando acquisire screenshot. ``` 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); ``` #### getDefaultLaunchOpzioni (); La `getDefaultLaunchOptions()` funzione restituisce le opzioni di avvio del browser utilizzate da CloudWatch Synthetics. Per ulteriori informazioni, consulta [Tipo di opzioni di avvio](https://pptr.dev/browsers-api/browsers.launchoptions/). ``` // This function returns default launch options used by Synthetics. const defaultOptions = await synthetics.getDefaultLaunchOptions(); ``` #### getPage(); Restituisce la pagina corrente aperta come oggetto Puppeteer. Per ulteriori informazioni, consulta l'[API Puppeteer v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md). Esempio: ``` let page = await synthetics.getPage(); ``` Risposta: La pagina (oggetto Puppeteer) attualmente aperta nella sessione corrente del browser. #### getRequestResponseLogHelper(); **Importante** Nei canary che usano il runtime `syn-nodejs-puppeteer-3.2` o versione successiva, questa funzione è resa obsoleta insieme alla classe `RequestResponseLogHelper`. Qualsiasi utilizzo di questa funzione fa apparire un avviso nei log del canary. Questa funzione verrà rimossa nelle future versioni di runtime. Se utilizzi questa funzione, utilizza invece [RequestResponseLogHelper classe](#CloudWatch_Synthetics_Library_RequestResponseLogHelper). Utilizza questa funzione come modello di builder per modificare i flag di registrazione della richiesta e della risposta. Esempio: ``` synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));; ``` Risposta: ``` {RequestResponseLogHelper} ``` #### launch(options) Le opzioni per questa funzione sono disponibili solo nella versione di runtime `syn-nodejs-2.1` o versioni successive. Questa funzione è utilizzata solo per i canary dell'interfaccia utente. Chiude il browser esistente e ne avvia uno nuovo. **Nota** CloudWatch Synthetics avvia sempre un browser prima di iniziare a eseguire lo script. Non è necessario chiamare “launch()” a meno che non desideri avviare un nuovo browser con opzioni personalizzate. (options) è un insieme configurabile di opzioni da impostare sul browser. Per ulteriori informazioni, consulta [Tipi di opzioni di avvio](https://pptr.dev/browsers-api/browsers.launchoptions/). Se chiami questa funzione senza “options”, Synthetics avvia un browser con argomenti predefiniti, `executablePath` e `defaultViewport`. La finestra di visualizzazione predefinita in CloudWatch Synthetics è 1920 x 1080. È possibile sovrascrivere i parametri di avvio utilizzati da CloudWatch Synthetics e passare parametri aggiuntivi all'avvio del browser. Ad esempio, il seguente frammento di codice avvia un browser con argomenti predefiniti e un percorso eseguibile predefinito, ma con un'area di visualizzazione di 800 x 600. ``` await synthetics.launch({ defaultViewport: { "deviceScaleFactor": 1, "width": 800, "height": 600 }}); ``` Il seguente codice di esempio aggiunge un nuovo `ignoreHTTPSErrors` parametro ai parametri di avvio di CloudWatch Synthetics: ``` await synthetics.launch({ ignoreHTTPSErrors: true }); ``` Puoi disabilitare la sicurezza web aggiungendo un `--disable-web-security` flag ad args nei parametri di avvio di CloudWatch Synthetics: ``` // 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 classe **Importante** Nei canary che usano il runtime `syn-nodejs-puppeteer-3.2` o versioni successive, questa classe è resa obsoleta. Qualsiasi uso di questa classe fa apparire un avviso nei log del canary. Questa funzione verrà rimossa nelle future versioni di runtime. Se utilizzi questa funzione, utilizza invece [RequestResponseLogHelper classe](#CloudWatch_Synthetics_Library_RequestResponseLogHelper). Gestisce la configurazione granulare e la creazione di rappresentazioni di stringa di payload di richiesta e risposta. ``` 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); ``` Esempio: ``` synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper() .withLogRequestPostData(true) .withLogRequestHeaders(true) .withLogResponseHeaders(true)); ``` Risposta: ``` {RequestResponseLogHelper} ``` #### setRequestResponseLogHelper(); **Importante** Nei canary che usano il runtime `syn-nodejs-puppeteer-3.2` o versione successiva, questa funzione è resa obsoleta insieme alla classe `RequestResponseLogHelper`. Qualsiasi utilizzo di questa funzione fa apparire un avviso nei log del canary. Questa funzione verrà rimossa nelle future versioni di runtime. Se utilizzi questa funzione, utilizza invece [RequestResponseLogHelper classe](#CloudWatch_Synthetics_Library_RequestResponseLogHelper). Utilizza questa funzione come modello di builder per impostare i flag di registrazione richiesta e risposta. Esempio: ``` synthetics.setRequestResponseLogHelper().withLogRequestHeaders(true).withLogResponseHeaders(true); ``` Risposta: ``` {RequestResponseLogHelper} ``` #### async takeScreenshot(name, suffix); Acquisisce uno screenshot (.PNG) della pagina corrente con nome e suffisso (opzionale). Esempio: ``` await synthetics.takeScreenshot("navigateToUrl", "loaded") ``` Questo esempio acquisisce e carica uno screenshot denominato ` 01-navigateToUrl-loaded.png` nel bucket S3 del canary. Puoi acquisire uno screenshot per una particolare fase del canary passando ` stepName` come primo parametro. Gli screenshot sono collegati alla fase del canary nei report, per aiutarti a tenere traccia di ogni fase durante il debug. CloudWatch Synthetics canaries acquisisce automaticamente gli screenshot prima di iniziare un passaggio (`executeStep`la funzione) e dopo il completamento del passaggio (a meno che non si configuri il canary per disabilitare gli screenshot). Puoi acquisire più screenshot passando il nome della fase nella funzione `takeScreenshot`. L'esempio seguente acquisisce screenshot con `signupForm` come valore di `stepName`. Lo screenshot sarà chiamato ` 02-signupForm-address` e sarà collegato alla fase denominata ` signupForm` nel report del canary. ``` await synthetics.takeScreenshot('signupForm', 'address') ``` ### BrokenLinkCheckerReport classe Questa classe offre metodi per aggiungere un collegamento Synthetics. È supportata solo sui canary che utilizzano la versione `syn-nodejs-2.0-beta` del runtime o versioni successive. Per utilizzare `BrokenLinkCheckerReport`, includi le seguenti righe nello script: ``` const BrokenLinkCheckerReport = require('@aws/synthetics-broken-link-checker-report'); const brokenLinkCheckerReport = new BrokenLinkCheckerReport(); ``` Definizioni utili delle funzioni: **addLink ({{syntheticsLink}}, isBroken)** ` {{syntheticsLink}} ` è un ` SyntheticsLink` che rappresenta un collegamento. Questa funzione aggiunge il collegamento in base al codice di stato. Per impostazione predefinita, considera un collegamento interrotto se il codice di stato non è disponibile o se il codice di stato è 400 o superiore. Puoi ignorare questo comportamento predefinito passando il parametro opzionale `isBrokenLink` con un valore di `true` o `false`. Questa funzione non ha un valore di restituzione. **getLinks()** Questa funzione restituisce una matrice di oggetti `SyntheticsLink` inclusi nel report di controllo del collegamento interrotto. **getTotalBrokenCollegamenti ()** Questa funzione restituisce un numero che rappresenta il numero totale di collegamenti interrotti. **getTotalLinksControllato ()** Questa funzione restituisce un numero che rappresenta il numero totale di collegamenti inclusi nel report. **Come usare BrokenLinkCheckerReport** Il seguente frammento di codice di script canary mostra un esempio di spostamento a un collegamento e aggiunta al report di controllo del collegamento interrotto. 1. Importa `SyntheticsLink`, `BrokenLinkCheckerReport` e ` 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. Per aggiungere un collegamento al report, crea un'istanza di ` BrokenLinkCheckerReport`. ``` let brokenLinkCheckerReport = new BrokenLinkCheckerReport(); ``` 1. Passa all'URL e aggiungilo al report di controllo del collegamento interrotto. ``` 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. Aggiungi il report a Synthetics. Questa procedura crea un file JSON denominato ` BrokenLinkCheckerReport.json` nel bucket S3 per ogni esecuzione del canary. Puoi visualizzare un report dei collegamenti nella console per ogni esecuzione del canary insieme a screenshot, log e file HAR. ``` await synthetics.addReport(brokenLinkCheckerReport); ``` ### SyntheticsLink classe Questa classe offre metodi per impacchettare le informazioni. È supportata solo sui canary che utilizzano la versione `syn-nodejs-2.0-beta` del runtime o versioni successive. Per utilizzare `SyntheticsLink`, includi le seguenti righe nello script: ``` const SyntheticsLink = require('@aws/synthetics-link'); const syntheticsLink = new SyntheticsLink("https://www.amazon.com"); ``` Questa funzione restituisce `syntheticsLink{{Object}}` Definizioni utili delle funzioni: **con URL () {{url}}** ` {{url}} ` è una stringa URL. Questa funzione restituisce `syntheticsLink{{Object}}` **con testo () {{text}}** ` {{text}} ` è una stringa che rappresenta il testo di ancoraggio. Questa funzione restituisce `syntheticsLink{{Object}}`. Aggiunge il testo di ancoraggio corrispondente al collegamento. **withParentUrl({{parentUrl}})** ` {{parentUrl}} ` è una stringa che rappresenta l'URL principale (pagina di origine). Questa funzione restituisce `syntheticsLink{{ Object}}` **withStatusCode({{statusCode}})** ` {{statusCode}} ` è una stringa che rappresenta il codice di stato. Questa funzione restituisce `syntheticsLink{{Object}}` **withFailureReason({{failureReason}})** ` {{failureReason}} ` è una stringa che rappresenta il motivo dell'errore. Questa funzione restituisce `syntheticsLink{{ Object}}` **addScreenshotResult({{screenshotResult}})** ` {{screenshotResult}} ` è un oggetto. Si tratta di un'istanza di `ScreenshotResult` restituita dalla funzione `takeScreenshot` di Synthetics. L'oggetto include i seguenti elementi: + `fileName`: una stringa che rappresenta ` screenshotFileName` + `pageUrl` (facoltativo) + `error` (facoltativo) ## Classi e funzioni della libreria di Node.js che si applicano solo ai canary dell'API Le seguenti CloudWatch funzioni della libreria Synthetics per Node.js sono utili solo per API canaries. **Topics** + [executeHttpStep(StepName, RequestOptions, [callback], [StepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep) ### executeHttpStep(StepName, RequestOptions, [callback], [StepConfig]) Esegue la richiesta HTTP fornita come fase e pubblica `SuccessPercent` (pass/fail) e parametri `Duration`. **executeHttpStep**utilizza automaticamente funzioni native HTTP o HTTPS, a seconda del protocollo specificato nella richiesta. Questa funzione aggiunge anche un riepilogo dell'esecuzione delle fasi al report del canary. Il riepilogo include dettagli su ogni richiesta HTTP, ad esempio: + Ora di inizio + Ora di fine + Stato (PASSED/FAILED) + Motivo dell'errore, se non è riuscita + dettagli della chiamata HTTP come request/response header, body, codice di stato, messaggio di stato e tempi delle prestazioni. **Topics** + [Parameters](#CloudWatch_Synthetics_Library_executeHttpStep_parameters) + [Esempi di utilizzo executeHttpStep](#CloudWatch_Synthetics_Library_executeHttpStep_examples) #### Parameters **StepName () {{String}}** Specifica il nome della fase. Questo nome viene utilizzato anche per pubblicare le CloudWatch metriche relative a questo passaggio. **requestOptions () {{Object or String}}** Il valore di questo parametro può essere un URL, una stringa URL o un oggetto. Se si tratta di un oggetto, deve essere un insieme di opzioni configurabili per effettuare una richiesta HTTP. Supporta tutte le opzioni in [ http.request(options[, callback])](https://nodejs.org/api/http.html#http_http_request_options_callback) nella documentazione di Node.js. Oltre a queste opzioni Node.js, **requestOptions** supporta il parametro aggiuntivo `body`. Puoi utilizzare il parametro `body` per trasferire i dati come corpo della richiesta. **richiamata () {{response}}** (Facoltativo) Questa è una funzione utente che viene richiamata con la risposta HTTP. La risposta è del tipo [Class: http. IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage). **StepConfig () {{object}}** (Facoltativo) Utilizza questo parametro per sostituire le configurazioni Synthetics globali con una configurazione diversa per questa fase. #### Esempi di utilizzo executeHttpStep La seguente serie di esempi si basa l'uno sull'altro per illustrare i vari usi di questa opzione. Questo primo esempio configura i parametri della richiesta. Puoi passare un URL come **RequestOptions:** ``` let requestOptions = 'https://www.amazon.com'; ``` Oppure puoi trasferire una serie di opzioni: ``` let requestOptions = { 'hostname': 'myproductsEndpoint.com', 'method': 'GET', 'path': '/test/product/validProductName', 'port': 443, 'protocol': 'https:' }; ``` L'esempio seguente crea una funzione di callback che accetta una risposta. Per impostazione predefinita, se non si specifica il **callback**, CloudWatch Synthetics verifica che lo stato sia compreso tra 200 e 299 inclusi. ``` // 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(); }); }); }; ``` L'esempio successivo crea una configurazione per questo passaggio che sovrascrive la configurazione globale di Synthetics CloudWatch . La configurazione della fase in questo esempio consente le intestazioni della richiesta, le intestazioni della risposta, il corpo della richiesta (dopo i dati) e il corpo della risposta nel report e di limitare i valori di intestazione “X-Amz-Security-Token” e “Authorization”. Per impostazione predefinita, questi valori non vengono inclusi nel report per motivi di sicurezza. Se scegli di includerli, i dati vengono archiviati solo nel bucket 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 }; ``` Questo ultimo esempio passa la richiesta a **executeHttpStep**e assegna un nome alla fase. ``` await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig); ``` **Con questo set di esempi, CloudWatch Synthetics aggiunge i dettagli di ogni passaggio del rapporto e produce metriche per ogni passaggio utilizzando StepName.** Vedrai i parametri `successPercent` e `duration` per la fase `Verify GET products API`. Puoi monitorare le prestazioni delle API monitorando i parametri per le fasi delle chiamate API. Per uno script completo di esempio che utilizza queste funzioni, consulta [Canary dell'API in più fasi](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps).