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.

Classi e funzioni di libreria di Node.js che si applicano a tutti i canary

Le seguenti funzioni di libreria CloudWatch Synthetics per Node.js sono utili per tutti i Canary.

Classe Synthetics

Le seguenti funzioni per tutti i canary sono nella classe Synthetics.

addExecutionError(errorMessage, ex);

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:

Esempio:

let logLevel = synthetics.getLogLevel();

setLogLevel();

Imposta il livello di log per la libreria Synthetics. I valori possibili sono i seguenti:

Esempio:

synthetics.setLogLevel(0);

Classe SyntheticsConfiguration

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.

Puoi impostare configurazioni CloudWatch Synthetics a livello globale, che vengono applicate a tutte le fasi dei canary. 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, functionToExecute, [stepConfig]); e executeHttpStep(stepName, requestOptions, [callback], [stepConfig])

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 canary che utilizzano syn-nodejs-puppeteer-3.2 o versione successiva, (options) per setConfig può includere i seguenti parametri:

setConfig(options) per quanto riguarda i parametri CloudWatch

Per i canary che utilizzano syn-nodejs-puppeteer-3.1 o versione successiva, (options) per setConfig può includere i seguenti parametri booleani che determinano quali parametri vengono pubblicati dal canary. 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.

Metodi per abilitare o disabilitare i parametri

disableAggregatedRequestMetrics()

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.

enableAggregatedRequestMetrics()

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.

getFailedCanaryMetric()

Indica se il canary emette un parametro Failed con dimensione CanaryName.

getFailedRequestsMetric()

Indica se il canary emette un parametro Failed requests con dimensione CanaryName.

getStepDurationMetric()

Indica se il canary emette un parametro Duration con dimensione CanaryName per questo canary.

getStepSuccessMetric()

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(aggregatedFailedCanaryMetric)

Accetta un argomento booleano, che specifica se emettere un parametro Failed senza alcuna dimensione per questo canary.

withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetric)

Accetta un argomento booleano, che specifica se emettere un parametro Failed requests senza alcuna dimensione per questo canary.

withFailedCanaryMetric(failedCanaryMetric)

Accetta un argomento booleano, che specifica se emettere un parametro Failed con dimensione CanaryName per questo canary.

withFailedRequestsMetric(failedRequestsMetric)

Accetta un argomento booleano, che specifica se emettere un parametro Failed requests con dimensione CanaryName per questo canary.

withStepDurationMetric(stepDurationMetric)

Accetta un argomento booleano, che specifica se emettere un parametro Duration con dimensione CanaryName per questo canary.

withStepSuccessMetric(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 visualizzate negli URL nei log e nei report.

withRestrictedUrlParameters()

Accetta una matrice di parametri del percorso dell'URL o della query da oscurare. Si applica agli URL visualizzati 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.

withLogRequestBody()

Accetta un argomento booleano, che specifica se registrare ogni corpo della richiesta nei log del canary.

withLogResponseBody()

Accetta un argomento booleano, che specifica se registrare ogni corpo della risposta nei log del canary.

withLogRequestHeaders()

Accetta un argomento booleano, che specifica se registrare ogni intestazione della richiesta nei log del canary.

withLogResponseHeaders()

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()

Restituisce se il canary include password visualizzate negli URL nei log e nei report.

getRestrictedUrlParameters()

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.

getLogRequestBody()

Restituisce se il canary registra ogni corpo della richiesta nei log del canary.

getLogResponseBody()

Restituisce se il canary registra ogni corpo della risposta nei log del canary.

getLogRequestHeaders()

Restituisce se il canary registra ogni intestazione della richiesta nei log del canary.

getLogResponseHeaders()

Restituisce se il canary registra ogni intestazione della risposta nei log del canary.

Funzioni per tutti i canary

setConfig(options) per canary dell'interfaccia utente

Per i canary dell'interfaccia utente, setConfig può includere i seguenti parametri booleani:

Metodi per abilitare o disabilitare gli screenshot

disableStepScreenshots()

Disabilita tutte le opzioni di screenshot (screenshotOnStepStart, screenshotOnStepSuccess e screenshotOnStepFailure).

enableStepScreenshots()

Abilita tutte le opzioni di screenshot (screenshotOnStepStart, screenshotOnStepSuccess e screenshotOnStepFailure). 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(screenshotOnStepStart)

Accetta un argomento booleano, che indica se eseguire uno screenshot prima di iniziare una fase.

withScreenshotOnStepSuccess(screenshotOnStepSuccess)

Accetta un argomento booleano, che indica se acquisire uno screenshot dopo aver completato correttamente una fase.

withScreenshotOnStepFailure(screenshotOnStepFailure)

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('Synthetics');

// 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:

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 canary che eseguono syn-puppeteer-node-3.2 e versione successiva. 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 Classe 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 canary, puoi utilizzare la console CloudWatch per modificare il canary in modo da eseguire una delle seguenti operazioni:

Per ulteriori informazioni sull'utilizzo della console CloudWatch per modificare un canary, consulta Modifica o eliminazione di un canary.

Altre opzioni per il monitoraggio visivo

syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)

Imposta la percentuale accettabile per la varianza dello screenshot nei confronti visivi.

syntheticsConfiguration.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.

syntheticsConfiguration.withFailCanaryRunOnVisualVariance(failCanary)

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 sia nella console che in un file di log locale allo stesso livello di log. 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 utilizzare SyntheticsLogger se vuoi eseguire la libreria Synthetics allo stesso livello di log della registrazione dei Canary Synthetics.

L'utilizzo di SyntheticsLogger non è necessario per creare un file di log che viene caricato nel percorso 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('SyntheticsLogger');

Definizioni utili delle funzioni:

log.debug(message, ex);

Parametri: message è il messaggio da registrare, ed ex è l'eccezione, se presente, da registrare

Esempio:

log.debug("Starting step - login.");

log.error(message, ex);

Parametri: message è il messaggio da registrare, ed ex è l'eccezione, se presente, 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, ed ex è l'eccezione, se presente, 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, ed ex è l'eccezione, se presente, da registrare

Esempio:

 log.log("Successfully completed step - login.");

log.warn(message, ex);

Parametri: message è il messaggio da registrare, ed ex è l'eccezione, se presente, da registrare

Esempio:

log.warn("Exception encountered trying to publish CloudWatch Metric.", ex);

Classe SyntheticsLogHelper

La classe SyntheticsLogHelper è disponibile nel runtime syn-nodejs-puppeteer-3.2 e nei runtime successivi. È già inizializzata nella libreria Synthetics CloudWatch ed è configurata con la configurazione Synthetics. È possibile aggiungerla come dipendenza nello script. Questa classe consente di sanificare URL, intestazioni e messaggi di errore per oscurare informazioni sensibili.

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 negli URL vengono oscurate. 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

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('Synthetics');

// Import Synthetics logger for logging url
const log = require('SyntheticsLogger');

// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();

// Set restricted parameters
synConfig.setConfig({
   restrictedUrlParameters: ['access_token'];
});
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('SyntheticsLogHelper');

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('SyntheticsLogHelper');

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

getSanitizedErrorMessage

Questa funzione è disponibile nella versione syn-nodejs-puppeteer-3.2 e versione successiva. Restituisce stringhe di errore sanificate sanificando qualsiasi URL presente in base alla configurazione Synthetics. Puoi scegliere di sovrascrivere la configurazione Synthetics globale quando chiami questa funzione passando un parametro stepConfig.

Parametri

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('Synthetics');

// Import Synthetics logger for logging url
const log = require('SyntheticsLogger');

// 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('SyntheticsLogHelper');

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(headers, 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

Classi e funzioni della libreria di Node.js che si applicano solo ai canary dell'interfaccia utente

Le seguenti funzioni di libreria CloudWatch Synthetics per Node.js sono utili solo per i canary dell'interfaccia utente.

Classe Synthetics

Le seguenti funzioni sono nella classe Synthetics.

async addUserAgent(page, userAgentString);

Questa funzione 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-valueMyApp-1.0

async executeStep(stepName, functionToExecute, [stepConfig]);

Esegue il passaggio fornito, con registrazione avviata/riuscita/non riuscita, screenshot avviato/riuscito/non riuscito e parametro riuscito/non riuscito e durata.

La funzione executeStep svolge anche le operazioni seguenti:

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

Iniziando con syn-nodejs-2.2, puoi facoltativamente trasferire le configurazioni delle fasi per sovrascrivere le configurazioni CloudWatch Synthetics a livello di fase. Per un elenco di opzioni che puoi trasferire a executeStep, consulta Classe 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);

getDefaultLaunchOptions();

La funzione getDefaultLaunchOptions() restituisce le opzioni di avvio del browser utilizzate da CloudWatch Synthetics. Per ulteriori informazioni, consulta Tipo di opzioni di avvio.

// 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.

Esempio:

let page = await synthetics.getPage();

Risposta:

La pagina (oggetto Puppeteer) attualmente aperta nella sessione corrente del browser.

getRequestResponseLogHelper();

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.

(options) è un insieme configurabile di opzioni da impostare sul browser. Per ulteriori informazioni, consulta Tipi di opzioni di avvio.

Se chiami questa funzione senza “options”, Synthetics avvia un browser con argomenti predefiniti, executablePath e defaultViewport. L'area di visualizzazione di default in CloudWatch Synthetics è 1920 per 1080.

Puoi sovrascrivere i parametri di avvio utilizzati da CloudWatch Synthetics e trasferire 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 codice di esempio riportato di seguito aggiunge un nuovo parametro ignoreHTTPSErrors ai parametri di avvio di CloudWatch Synthetics:

await synthetics.launch({
        ignoreHTTPSErrors: true
 });

Puoi disabilitare la sicurezza Web aggiungendo un flag --disable-web-security per gli argomenti nei parametri di lancio 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
  });

Classe 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();

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.

I canary CloudWatch Synthetics acquisiscono automaticamente screenshot prima di iniziare una fase (la funzione executeStep) e dopo il completamento della fase (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')

Classe BrokenLinkCheckerReport

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('BrokenLinkCheckerReport');
            
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.

getTotalBrokenLinks()

Questa funzione restituisce un numero che rappresenta il numero totale di collegamenti interrotti.

getTotalLinksChecked()

Questa funzione restituisce un numero che rappresenta il numero totale di collegamenti inclusi nel report.

Come utilizzare 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.

Classe SyntheticsLink

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('SyntheticsLink');

const syntheticsLink = new SyntheticsLink("https://www.amazon.com");

Questa funzione restituisce syntheticsLinkObject

Definizioni utili delle funzioni:

withUrl(url)

url è una stringa URL. Questa funzione restituisce syntheticsLinkObject

withText(text)

text è una stringa che rappresenta il testo di ancoraggio. Questa funzione restituisce syntheticsLinkObject. Aggiunge il testo di ancoraggio corrispondente al collegamento.

withParentUrl(parentUrl)

parentUrl è una stringa che rappresenta l'URL principale (pagina di origine). Questa funzione restituisce syntheticsLinkObject

withStatusCode(statusCode)

statusCode è una stringa che rappresenta il codice di stato. Questa funzione restituisce syntheticsLinkObject

withFailureReason(failureReason)

failureReason è una stringa che rappresenta il motivo dell'errore. Questa funzione restituisce syntheticsLinkObject

addScreenshotResult(screenshotResult)

screenshotResult è un oggetto. Si tratta di un'istanza di ScreenshotResult restituita dalla funzione takeScreenshot di Synthetics. L'oggetto include i seguenti elementi:

Classi e funzioni della libreria di Node.js che si applicano solo ai canary dell'API

Le seguenti funzioni di libreria CloudWatch Synthetics per Node.js sono utili solo per i canary dell'API.

executeHttpStep(stepName, requestOptions, [callback], [stepConfig])

Esegue la richiesta HTTP fornita come fase e pubblica SuccessPercent (pass/fail) e parametri Duration.

executeHttpStep utilizza funzioni native HTTP o HTTPS dietro le quinte, 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:

Parametri

stepName(String)

Specifica il nome della fase. Questo nome viene utilizzato anche per pubblicare i parametri CloudWatch per questa fase.

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]) 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.

callback(response)

(Facoltativo) Questa è una funzione utente che viene richiamata con la risposta HTTP. La risposta è del tipo 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 di 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 trasferire 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 specifichi callback, CloudWatch Synthetics convalida che lo stato è 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();
            });
        });
    };

Nell'esempio seguente viene creata una configurazione per questa fase che sovrascrive la configurazione globale CloudWatch Synthetics. 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 tua richiesta a executeHttpStep e assegna un nome alla fase.

await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig);

Con questa serie di esempi, CloudWatch Synthetics aggiunge i dettagli di ogni fase del report e produce parametri per ogni fase 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.