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
CloudWatch Synthetics include diverse classi e funzioni integrate che è possibile chiamare durante la scrittura di script Node.js da utilizzare come canarini.
Alcune si applicano sia ai canary UI che alle API. Altri si applicano solo ai canary dell'interfaccia utente. Un canary dell'interfaccia utente è un canary che utilizza la funzione `getPage()` e utilizza Puppeteer come driver Web per navigare e interagire con le pagine Web.
**Nota**
Ogni volta che aggiorni un canary per utilizzare una nuova versione del runtime Synthetics, tutte le funzioni della libreria Synthetics utilizzate dal canary vengono aggiornate automaticamente alla stessa versione di NodeJS supportata dal runtime Synthetics.
**Topics**
+ [
# Funzioni di libreria disponibili per Node.js canary
](Library_function_Nodejs.md)
+ [
# Funzioni di libreria disponibili per canary Java
](CloudWatch_Synthetics_Canaries_Java.md)
+ [
# Funzioni di libreria disponibili per gli script canary Node.js che utilizzano Playwright
](CloudWatch_Synthetics_Canaries_Nodejs_Playwright.md)
+ [
# Funzioni di libreria disponibili per gli script canary Node.js utilizzando Puppeteer
](CloudWatch_Synthetics_Canaries_Library_Nodejs.md)
+ [
# Funzioni di libreria disponibili per gli script canary Python che usano Selenium
](CloudWatch_Synthetics_Canaries_Library_Python.md)
# Funzioni di libreria disponibili per Node.js canary
Questa sezione descrive le funzioni di libreria disponibili per gli script Canary che utilizzano il runtime Node.js.
**Topics**
+ [
## addExecutionError(ErrorMessage, es.);
](#Library_function_Nodejs_addExecutionError_Nodecanary)
+ [
## getCanaryName();
](#Library_function_Nodejs_getCanaryName)
+ [
## getCanaryArn();
](#Library_function_Nodejs_Nodecanary)
+ [
## getCanaryUserAgentString();
](#Library_function_Nodejs_getCanaryUserAgentString_Nodecanary)
+ [
## getRuntimeVersion();
](#Library_function_Nodejs_getRuntimeVersion_Nodecanary)
+ [
## getLogLevel();
](#Library_function_Nodejs_getLogLevel_Nodecanary)
+ [
## setLogLevel();
](#Library_function_Nodejs_setLogLevel_Nodecanary)
+ [
## ExecuteStep (StepName, [ functionToExecuteStepConfig])
](#Library_function_Nodejs_executestep_Nodecanary)
+ [
## executeHttpStep(StepName, RequestOptions, [callback], [StepConfig])
](#Library_function_Nodejs_executeHttpStep)
## 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.executeStep(stepName, callbackFunc);} 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 runtime `syn-nodejs-3.0` e successive. Restituisce la versione di runtime di Synthetics del canary. Ad esempio, il valore restituito potrebbe essere `syn-nodejs-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);
```
## ExecuteStep (StepName, [ functionToExecuteStepConfig])
Esegue il passaggio fornito, avvolgendolo con le metriche di durata. start/pass/fail logging and pass/fail
La funzione `executeStep` svolge anche le operazioni seguenti:
+ Registra l'inizio del passaggio
+ Avvia un timer
+ Esegue la funzione fornita
+ Quando la funzione ritorna normalmente, conta come passaggio. Se la funzione viene generata, viene considerata fallita
+ Termina il timer
+ Registra se il passaggio è riuscito o non è riuscito
+ Emette la `stepName SuccessPercent` metrica, 100 per il passaggio o 0 per l'errore
+ Emette il`stepName Duration metric`, con un valore basato sull'ora di inizio e di fine del passo
+ Restituisce ciò che ha functionToExecute restituito o rigetta ciò che ha lanciato ` functionToExecute`
+ Aggiunge un riepilogo dell'esecuzione delle fasi al rapporto di Canary
**Esempio**
```
await synthetics.executeStep(stepName, async function () {
return new Promise((resolve, reject) => {
const req = https.request(url, (res) => {
console.log(`Status: ${res.statusCode}`);
if (res.statusCode >= 400) {
reject(new Error(`Request failed with status ${res.statusCode} for ${url}`));
} else {
resolve();
}
});
req.on('error', (err) => {
reject(new Error(`Request failed for ${url}: ${err.message}`));
});
req.end();
});
});
```
## executeHttpStep(StepName, RequestOptions, [callback], [StepConfig])
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
](#Library_function_Nodejs_executeHttpStep_parameters_Nodecanary)
+ [
### Esempi di utilizzo executeHttpStep
](#Library_function_Nodejs_executeHttpStep_examples_Nodecanary)
### 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).
# Funzioni di libreria disponibili per canary Java
La funzione `executeStep` viene utilizzata per suddividere in moduli il codice del canary ed eseguirlo in più fasi. In CloudWatch Synthetics, una fase di Synthetics è un modo per suddividere lo script canary in una serie di azioni chiaramente definite, che consentono di monitorare separatamente diverse parti del percorso applicativo. Per ogni passaggio, CloudWatch Synthetics esegue le seguenti operazioni:
+ Per ogni esecuzione canary viene creato un report che include un riepilogo dei dettagli relativi all'esecuzione di un passaggio, ad esempio la durata, lo stato *riuscito* o *non riuscito* e così via. **Quando scegli un'esecuzione nella console CloudWatch Synthetics, puoi visualizzare i dettagli di esecuzione di ogni passaggio nella scheda Step.**
+ *SuccessPercent*e le CloudWatch metriche di *durata* vengono emesse per ogni passaggio, consentendo agli utenti di monitorare la disponibilità e la latenza di ogni passaggio.
**Utilizzo**
```
synthetics.executeStep(stepName,()->{
try {
//step code to be executed
return null;
} catch (Exception e) {
throw e;
}
}).get();
```
**Parametri**
+ *stepName*, String (obbligatorio): un nome descrittivo del passaggio di Synthetics
+ *function to execute*, Callable (obbligatorio): rappresenta le attività da eseguire
+ *StePoptions*, `com.amazonaws.synthetics.StepOptions (optional)` — StepOptions oggetto che può essere utilizzato per configurare l'esecuzione della fase.
*stepConfiguration*, ` com.amazonaws.synthetics.StepConfiguration` (richiesto come parte di StepOptions)
**Valori restituiti**
Il valore restituito è. *CompletableFuture*
**Nota**
Synthetics supporta solo passaggi sequenziali. Assicurati di chiamare il metodo `.get()` come mostrato nell'esempio per assicurarti che il passaggio venga completato prima di procedere a quello successivo.
# Funzioni di libreria disponibili per gli script canary Node.js che utilizzano Playwright
Questa sezione descrive le funzioni di libreria disponibili per gli script Canary che utilizzano il runtime Node.js Playwright.
**Topics**
+ [
## avvio
](#Synthetics_Library_Nodejs_Playwright_functions)
+ [
## newPage
](#Synthetics_Library_Nodejs_Playwright_function_newPage)
+ [
## close
](#Synthetics_Library_Nodejs_Playwright_function_close)
+ [
## getDefaultLaunchOpzioni
](#Synthetics_Library_Nodejs_Playwright_function_getDefaultLaunchOptions)
+ [
## executeStep
](#Synthetics_Library_Nodejs_Playwright_function_executeStep)
## avvio
Questa funzione avvia un browser Chromium utilizzando una funzione di avvio Playwright e restituisce l'oggetto browser. Decomprime i file binari del browser e avvia il browser Chromium utilizzando le opzioni predefinite adatte per un browser headless. Per ulteriori informazioni sulla funzione `launch`, consulta [https://playwright.dev/docs/api/class-browsertype#browser-type-launch](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) nella documentazione di Playwright.
**Utilizzo**
```
const browser = await synthetics.launch();
```
**Arguments (Argomenti)**
`options` [options](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) (facoltativo) è un insieme configurabile di opzioni da impostare sul browser.
**Valori restituiti**
Promise `` dove [Browser](https://playwright.dev/docs/api/class-browser) è un'istanza del browser Playwright.
Se questa funzione viene chiamata nuovamente, un browser aperto in precedenza viene chiuso prima di avviare un nuovo browser. È 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 pixel. Per ulteriori informazioni, consulta le [opzioni di avvio di Playwright](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) nella documentazione di Playwright.
```
const browser = await synthetics.launch({
defaultViewport: {
"deviceScaleFactor": 1,
"width": 800,
"height": 600
}});
```
Puoi anche aggiungere o sostituire i flag Chromium trasmessi per impostazione predefinita al browser. Ad esempio, puoi disabilitare la sicurezza web aggiungendo un `--disable-web-security` flag agli argomenti 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'];
const browser = await synthetics.launch({
args: launchArgs
});
```
## newPage
La funzione `newPage()` crea e restituisce una nuova pagina Playwright. Synthetics configura automaticamente una connessione DevTools Chrome Protocol (CDP) per abilitare le acquisizioni di rete per la generazione di archivi HTTP (HAR).
**Utilizzo**
Usa `newPage()` in una delle seguenti modalità:
**1. Creazione di una nuova pagina in un nuovo contesto del browser:**
```
const page = await synthetics.newPage(browser);
```
**2. Creazione di una nuova pagina in un contesto del browser specificato:**
```
// Create a new browser context
const browserContext = await browser.newContext();
// Create a new page in the specified browser context
const page = await synthetics.newPage(browserContext)
```
**Arguments (Argomenti)**
Accetta l'istanza Playwright [Browser](https://playwright.dev/docs/api/class-browser) o l'istanza [ BrowserContext](https://playwright.dev/docs/api/class-browsercontext)Playwright.
**Valori restituiti**
Promise dove Page è un'istanza [Page](https://playwright.dev/docs/api/class-page) di Playwright.
## close
Chiude il browser attualmente aperto.
**Utilizzo**
```
await synthetics.close();
```
Si consiglia di chiudere il browser in un blocco `finally` dello script.
**Arguments (Argomenti)**
Nessuno
**Valori restituiti**
Restituisce una Promise utilizzata dalla funzione di avvio di Synthetics per avviare il browser.
## getDefaultLaunchOpzioni
La `getDefaultLaunchOptions()` funzione restituisce le opzioni di avvio del browser utilizzate da CloudWatch Synthetics.
**Utilizzo**
```
const defaultOptions = await synthetics.getDefaultLaunchOptions();
```
**Arguments (Argomenti)**
Nessuno
**Valori restituiti**
Restituisce le [opzioni di avvio](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) di Playwright utilizzate dalla funzione `launch` di Synthetics per avviare il browser.
## executeStep
La funzione `executeStep` viene utilizzata per eseguire un passaggio in uno script Synthetics. In CloudWatch Synthetics, una fase di Synthetics è un modo per suddividere lo script canary in una serie di azioni chiaramente definite, che consentono di monitorare separatamente diverse parti del percorso applicativo. Per ogni passaggio, CloudWatch Synthetics esegue le seguenti operazioni:
+ Cattura automaticamente uno screenshot prima dell'inizio del passaggio e dopo il completamento di un passaggio. Puoi anche catturare schermate all'interno di un passaggio. Le schermate vengono acquisite per impostazione predefinita, ma possono essere disattivate utilizzando le configurazioni Synthetics.
+ Per ogni esecuzione di Canary viene creato un rapporto, che include un riepilogo, dei dettagli relativi all'esecuzione delle fasi, come la durata di una fase `pass` o `fail` lo stato URLs, la pagina di origine e di destinazione, le schermate associate, ecc. **Quando scegli un'esecuzione nella console CloudWatch Synthetics, puoi visualizzare i dettagli di esecuzione di ogni passaggio nella scheda Step.**
+ `SuccessPercent`e le `Duration` CloudWatch metriche vengono emesse per ogni passaggio, consentendo agli utenti di monitorare la disponibilità e la latenza di ogni passaggio.
**Utilizzo**
```
await synthetics.executeStep("mystepname", async function () {
await page.goto(url, { waitUntil: 'load', timeout: 30000 });
}
```
**Nota**
I passaggi dovrebbero essere eseguiti in sequenza. Assicurati di usare `await` on-premises.
**Arguments (Argomenti)**
+ Stringa `stepName` (obbligatorio) (booleano): nome del passaggio di Synthetics.
+ Funzione asincrona `functionToExecute` (obbligatoria): la funzione che desideri che venga eseguita da Synthetics. Questa funzione dovrebbe contenere la logica per il passaggio.
+ Oggetto `stepConfig` (facoltativo): la configurazione del passaggio sovrascrive la configurazione globale di Synthetics per questo passaggio.
+ Booleano `continueOnStepFailure` (facoltativo): indica se continuare l'esecuzione dello script canary dopo che questo passaggio ha esito negativo.
+ Booleano `screenshotOnStepStart` (facoltativo): indica se fare uno screenshot all'inizio di questo passaggio.
+ Booleano `screenshotOnStepSuccess` (facoltativo): indica se fare uno screenshot dopo che questo passaggio ha esito positivo.
+ Booleano `screenshotOnStepFailure` (facoltativo): indica se fare uno screenshot dopo che questo passaggio ha esito negativo.
+ `page`: oggetto pagina di Playwright (facoltativo)
Un oggetto pagina di Playwright. Synthetics utilizza questo oggetto pagina per acquisire schermate e. URLs Per impostazione predefinita, Synthetics utilizza la pagina Playwright creata quando viene chiamata `synthetics.newPage()` la funzione per acquisire dettagli della pagina come schermate e. URLs
**Valori restituiti**
Restituisce una Promise che si risolve con il valore restituito dalla funzione ` functionToExecute`. Per uno script di esempio, consulta [Codice di esempio per gli script canary](CloudWatch_Synthetics_Canaries_Samples.md) in questa guida.
# 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 (\$1) 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(\$12xxMetric)**
Accetta un argomento booleano, che specifica se emettere un parametro `2xx` con dimensione `CanaryName` per questo canary.
**with4xxMetric(\$14xxMetric)**
Accetta un argomento booleano, che specifica se emettere un parametro `4xx` con dimensione `CanaryName` per questo canary.
**with5xxMetric(\$15xxMetric)**
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 (\$1) 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(» \$1fafa00 «)**
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\$1token 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-valueMyApp-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 `syntheticsLinkObject`
Definizioni utili delle funzioni:
**con URL () *url***
` url ` è una stringa URL. Questa funzione restituisce `syntheticsLinkObject`
**con testo () *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 `syntheticsLink Object`
**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 `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).
# Funzioni di libreria disponibili per gli script canary Python che usano Selenium
Questa sezione elenca le funzioni di libreria di Selenium disponibili per gli script canary Python.
**Topics**
+ [
## Classi e funzioni della libreria Python e Selenium che si applicano a tutti i canary
](#CloudWatch_Synthetics_Library_allcanaries_Python)
+ [
## Classi e funzioni della libreria Python e Selenium che si applicano solo ai canary dell'interfaccia utente
](#CloudWatch_Synthetics_Library_Python_UIcanaries)
## Classi e funzioni della libreria Python e Selenium che si applicano a tutti i canary
Le seguenti funzioni della libreria CloudWatch Synthetics Selenium per Python sono utili per tutti i canarini.
**Topics**
+ [
### SyntheticsConfiguration classe
](#CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python)
+ [
### SyntheticsLogger classe
](#CloudWatch_Synthetics_Library_SyntheticsLogger_Python)
### SyntheticsConfiguration classe
È possibile utilizzare la SyntheticsConfiguration classe 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 le configurazioni CloudWatch Synthetics a livello globale.
Definizioni della funzione:
#### set\$1config(options)
```
from aws_synthetics.common import synthetics_configuration
```
` options ` è un oggetto, che è un insieme di opzioni configurabili per il tuo canary. Le seguenti sezioni spiegano i campi possibili in ` options `.
+ `screenshot_on_step_start` (booleano): indica se fare uno screenshot prima di iniziare una fase.
+ `screenshot_on_step_success` (booleano): indica se acquisire uno screenshot dopo aver completato una fase riuscita.
+ `screenshot_on_step_failure` (booleano): indica se acquisire uno screenshot dopo il fallimento di una fase.
**with\$1screenshot\$1on\$1step\$1start(screenshot\$1on\$1step\$1start)**
Accetta un argomento booleano, che indica se eseguire uno screenshot prima di iniziare una fase.
**with\$1screenshot\$1on\$1step\$1success(screenshot\$1on\$1step\$1success)**
Accetta un argomento booleano, che indica se acquisire uno screenshot dopo aver completato correttamente una fase.
**with\$1screenshot\$1on\$1step\$1failure(screenshot\$1on\$1step\$1failure)**
Accetta un argomento booleano, che indica se acquisire uno screenshot dopo il fallimento di una fase.
**get\$1screenshot\$1on\$1step\$1start()**
Restituisce se acquisire uno screenshot prima di iniziare una fase.
**get\$1screenshot\$1on\$1step\$1success()**
Restituisce se acquisire uno screenshot dopo aver completato correttamente una fase.
**get\$1screenshot\$1on\$1step\$1failure()**
Restituisce se acquisire uno screenshot dopo che una fase fallisce.
**disable\$1step\$1screenshots()**
Disabilita tutte le opzioni di screenshot (get\$1screenshot\$1on\$1step\$1start, get\$1screenshot\$1on\$1step\$1success e get\$1screenshot\$1on\$1step\$1failure).
**enable\$1step\$1screenshots()**
Abilita tutte le opzioni di screenshot (get\$1screenshot\$1on\$1step\$1start, get\$1screenshot\$1on\$1step\$1success e get\$1screenshot\$1on\$1step\$1failure). Per impostazione predefinita, tutti questi metodi sono abilitati.
**setConfig (opzioni) relative alle metriche CloudWatch **
Per i canarini che utilizzano `syn-python-selenium-1.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)
+ `failed_canary_metric` (booleano): indica se emettere il parametro ` Failed` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`.
+ `failed_requests_metric` (booleano): indica se emettere il parametro `Failed requests` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`.
+ `2xx_metric` (booleano): indica se emettere il parametro `2xx` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`.
+ `4xx_metric` (booleano): indica se emettere il parametro `4xx` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`.
+ `5xx_metric` (booleano): indica se emettere il parametro `5xx` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`.
+ `step_duration_metric` (booleano): indica se emettere il parametro `Step duration` (con le dimensioni `CanaryName` `StepName`) per questo canary. Il valore predefinito è `true`.
+ `step_success_metric` (booleano): indica se emettere il parametro `Step success` (con le dimensioni `CanaryName` `StepName`) per questo canary. Il valore predefinito è `true`.
+ `aggregated_failed_canary_metric` (booleano): indica se emettere il parametro `Failed` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`.
+ `aggregated_failed_requests_metric` (booleano): indica se emettere il parametro `Failed Requests` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`.
+ `aggregated_2xx_metric` (booleano): indica se emettere il parametro ` 2xx` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`.
+ `aggregated_4xx_metric` (booleano): indica se emettere il parametro ` 4xx` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`.
+ `aggregated_5xx_metric` (booleano): indica se emettere il parametro ` 5xx` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`.
**with\$12xx\$1metric(2xx\$1metric)**
Accetta un argomento booleano, che specifica se emettere un parametro `2xx` con dimensione `CanaryName` per questo canary.
**with\$14xx\$1metric(4xx\$1metric)**
Accetta un argomento booleano, che specifica se emettere un parametro `4xx` con dimensione `CanaryName` per questo canary.
**with\$15xx\$1metric(5xx\$1metric)**
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.
**with\$1aggregated\$15xx\$1metric(aggregated\$15xx\$1metric)**
Accetta un argomento booleano, che specifica se emettere un parametro `5xx` senza alcuna dimensione per questo canary.
**with\$1aggregated\$1failed\$1canary\$1metric (aggregated\$1failed\$1canary\$1metric)**
Accetta un argomento booleano, che specifica se emettere un parametro `Failed` senza alcuna dimensione per questo canary.
**con \$1aggregated\$1failed\$1requests\$1metric (aggregated\$1failed\$1requests\$1metric)**
Accetta un argomento booleano, che specifica se emettere un parametro `Failed requests` senza alcuna dimensione per questo canary.
**with\$1failed\$1canary\$1metric(failed\$1canary\$1metric)**
Accetta un argomento booleano, che specifica se emettere un parametro `Failed` con dimensione `CanaryName` per questo canary.
**with\$1failed\$1requests\$1metric(failed\$1requests\$1metric)**
Accetta un argomento booleano, che specifica se emettere un parametro `Failed requests` con dimensione `CanaryName` per questo canary.
**with\$1step\$1duration\$1metric(step\$1duration\$1metric)**
Accetta un argomento booleano, che specifica se emettere un parametro `Duration` con dimensione `CanaryName` per questo canary.
**with\$1step\$1success\$1metric(step\$1success\$1metric)**
Accetta un argomento booleano, che specifica se emettere un parametro `StepSuccess` con dimensione `CanaryName` per questo canary.
##### Metodi per abilitare o disabilitare i parametri
**disable\$1aggregated\$1request\$1metrics()**
Disabilita il canary dall'emettere tutti i parametri delle richieste emessi senza dimensione ` CanaryName`.
**disable\$1request\$1metrics()**
Disabilita tutti i parametri delle richieste, inclusi i parametri dei canary e i parametri aggregati in tutti i canary.
**disable\$1step\$1metrics()**
Disabilita tutti i parametri dei passaggi, inclusi sia quelli di riuscita che di durata.
**enable\$1aggregated\$1request\$1metrics()**
Consente al canary di emettere tutti i parametri della richiesta emessi senza la dimensione ` CanaryName`.
**enable\$1request\$1metrics()**
Abilita tutti i parametri delle richieste, inclusi i parametri dei canary e i parametri aggregati in tutti i canary.
**enable\$1step\$1metrics()**
Abilita tutti i parametri dei passaggi, inclusi sia quelli di riuscita che di durata.
**Utilizzo in canary dell'interfaccia utente**
Innanzitutto, importa la dipendenza di Synthetics e recupera la configurazione. Quindi, imposta la configurazione per ogni opzione chiamando il metodo setConfig utilizzando una delle opzioni seguenti.
```
from aws_synthetics.common import synthetics_configuration
synthetics_configuration.set_config(
{
"screenshot_on_step_start": False,
"screenshot_on_step_success": False,
"screenshot_on_step_failure": True
}
)
or
```
Oppure
```
synthetics_configuration.with_screenshot_on_step_start(False).with_screenshot_on_step_success(False).with_screenshot_on_step_failure(True)
```
Per disabilitare tutti gli screenshot, usa la funzione () come in questo esempio. disableStepScreenshots
```
synthetics_configuration.disable_step_screenshots()
```
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.
##### set\$1config(options) per canary dell'interfaccia utente
A partire da `syn-python-selenium-1.1`, per i canary dell'interfaccia utente, ` set_config` può includere i seguenti parametri booleani:
+ `continue_on_step_failure`**(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`.
### SyntheticsLogger classe
`synthetics_logger` 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.
L'utilizzo di `synthetics_logger` non è necessario per creare un file di log che viene caricato nel percorso dei risultati di Amazon 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 nel bucket S3 come artefatti.
Per utilizzare `synthetics_logger`:
```
from aws_synthetics.common import synthetics_logger
```
****Definizioni utili delle funzioni:
Ottenere il livello di log:
```
log_level = synthetics_logger.get_level()
```
Impostare il livello di log:
```
synthetics_logger.set_level()
```
Registrare un messaggio con un livello specificato. Il livello può essere `DEBUG`, ` INFO`, `WARN` oppure `ERROR`, come negli esempi di sintassi seguenti:
```
synthetics_logger.debug(message, *args, **kwargs)
```
```
synthetics_logger.info(message, *args, **kwargs)
```
```
synthetics_logger.log(message, *args, **kwargs)
```
```
synthetics_logger.warning(message, *args, **kwargs)
```
```
synthetics_logger.error(message, *args, **kwargs)
```
Per informazioni sui parametri di debug, consulta la documentazione standard di Python all'indirizzo [logging.debug](https://docs.python.org/3/library/logging.html#logging.debug)
In queste funzioni di registrazione, `message` è la stringa di formato del messaggio. `args` sono gli argomenti che vengono uniti in `msg` utilizzando l'operatore di formattazione delle stringhe.
Ci sono tre argomenti della parola chiave in `kwargs`:
+ `exc_info`: se non viene valutato come false (falso), aggiunge informazioni sulle eccezioni al messaggio di log.
+ `stack_info`: imposta il valore predefinito su false (falso). Se true (vero), aggiunge le informazioni sullo stack al messaggio di log, inclusa la chiamata di registrazione effettiva.
+ `extra`: il terzo argomento della parola chiave facoltativo, che puoi utilizzare per il passaggio a un dizionario utilizzato per popolare il `__dict__` di `LogRecord` creato per l'evento di log con attributi definiti dall'utente.
Esempi:
Registrare un messaggio con il livello `DEBUG`:
```
synthetics_logger.debug('Starting step - login.')
```
Registrare un messaggio con il livello `INFO`. `logger.log` è sinonimo di `logger.info`:
```
synthetics_logger.info('Successfully completed step - login.')
```
or
```
synthetics_logger.log('Successfully completed step - login.')
```
Registrare un messaggio con il livello `WARN`:
```
synthetics_logger.warning('Warning encountered trying to publish %s', 'CloudWatch Metric')
```
Registrare un messaggio con il livello `ERROR`:
```
synthetics_logger.error('Error encountered trying to publish %s', 'CloudWatch Metric')
```
Registrare un'eccezione:
```
synthetics_logger.exception(message, *args, **kwargs)
```
Registra un messaggio con il livello `ERROR`. Le informazioni sulle eccezioni vengono aggiunte al messaggio di log. Dovresti chiamare questa funzione solo da un gestore di eccezioni.
[Per informazioni sui parametri di eccezione, consulta la documentazione standard di Python all'indirizzo logging.exception](https://docs.python.org/3/library/logging.html#logging.exception)
`message` è la stringa di formato del messaggio. `args` sono gli argomenti che vengono uniti in `msg` utilizzando l'operatore di formattazione delle stringhe.
Ci sono tre argomenti della parola chiave in `kwargs`:
+ `exc_info`: se non viene valutato come false (falso), aggiunge informazioni sulle eccezioni al messaggio di log.
+ `stack_info`: imposta il valore predefinito su false (falso). Se true (vero), aggiunge le informazioni sullo stack al messaggio di log, inclusa la chiamata di registrazione effettiva.
+ `extra`: il terzo argomento della parola chiave facoltativo, che puoi utilizzare per il passaggio a un dizionario utilizzato per popolare il `__dict__` di `LogRecord` creato per l'evento di registrazione con attributi definiti dall'utente.
Esempio:
```
synthetics_logger.exception('Error encountered trying to publish %s', 'CloudWatch Metric')
```
## Classi e funzioni della libreria Python e Selenium che si applicano solo ai canary dell'interfaccia utente
Le seguenti funzioni della libreria CloudWatch Synthetics Selenium per Python sono utili solo per i canari dell'interfaccia utente.
**Topics**
+ [
### SyntheticsBrowser classe
](#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser)
+ [
### SyntheticsWebDriver classe
](#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver)
### SyntheticsBrowser classe
**Nota**
`SyntheticsBrowser` è supportato solo nel browser Chrome.
Quando crei un'istanza del browser chiamando `synthetics_webdriver.Chrome()`, l'istanza del browser restituita è del tipo `SyntheticsBrowser`. La ` SyntheticsBrowser` classe eredita la WebDriver classe e fornisce l'accesso a tutti i metodi esposti da. [WebDriver](https://www.selenium.dev/documentation/webdriver/) Controlla e abilita lo script canary per guidare il browser, permettendo a Selenium di funzionare con WebDriver Synthetics. ChromeDriver
**Nota**
Synthetics sovrascrive il metodo quit per non intraprendere WebDriver [alcuna](https://www.selenium.dev/selenium/docs/api/py/selenium_webdriver_firefox/selenium.webdriver.firefox.webdriver.html) azione. Non è necessario chiudere il browser manualmente, poiché Synthetics se ne occupa automaticamente.
Oltre ai metodi standard di Selenium, offre anche i seguenti metodi.
**Topics**
+ [
#### set\$1viewport\$1size(width, height)
](#CloudWatch_Synthetics_Library_set_viewport_size)
+ [
#### save\$1screenshot(filename, suffix)
](#CloudWatch_Synthetics_Library_save_screenshot)
#### set\$1viewport\$1size(width, height)
Imposta l'area di visualizzazione del browser. Esempio:
```
browser.set_viewport_size(1920, 1080)
```
#### save\$1screenshot(filename, suffix)
Salva gli screenshot nella directory `/tmp`. Gli screenshot vengono caricati da lì nella cartella degli artefatti del canary nel bucket S3.
*filename* è il nome del file per lo screenshot e *suffix* è una stringa opzionale da utilizzare per denominare lo screenshot.
Esempio:
```
browser.save_screenshot('loaded.png', 'page1')
```
### SyntheticsWebDriver classe
Per utilizzare questa classe, utilizza i seguenti elementi nello script:
```
from aws_synthetics.selenium import synthetics_webdriver
```
**Topics**
+ [
#### addExecutionError(errorMessage, ex);
](#CloudWatch_Synthetics_Library_Python_addExecutionError)
+ [
#### add\$1user\$1agent(user\$1agent\$1str)
](#CloudWatch_Synthetics_Library_add_user_agent)
+ [
#### execute\$1step(step\$1name, function\$1to\$1execute)
](#CloudWatch_Synthetics_Library_Python_execute_step)
+ [
#### get\$1http\$1response(url)
](#CloudWatch_Synthetics_Library_Python_get_http_response)
+ [
#### Chrome()
](#CloudWatch_Synthetics_Library_Python_Chrome)
#### addExecutionError(errorMessage, ex);
`errorMessage` descrive l'errore e `ex` è l'eccezione che si verifica
Puoi utilizzare `add_execution_error` 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 `add_execution_error`. 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:
browser.save_screenshot("loaded.png")
except Exception as ex:
self.add_execution_error("Unable to take screenshot", ex)
```
#### add\$1user\$1agent(user\$1agent\$1str)
Aggiunge il valore di `user_agent_str` all'intestazione dell'agente utente del browser. È necessario assegnare `user_agent_str` prima di creare l'istanza del browser.
Esempio:
```
await synthetics_webdriver.add_user_agent('MyApp-1.0')
```
`add_user_agent` deve essere usato all'interno di una funzione `async`.
#### execute\$1step(step\$1name, function\$1to\$1execute)
Elabora una funzione. Inoltre esegue le seguenti operazioni:
+ 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.
Esempio:
```
from selenium.webdriver.common.by import By
def custom_actions():
#verify contains
browser.find_element(By.XPATH, "//*[@id=\"id_1\"][contains(text(),'login')]")
#click a button
browser.find_element(By.XPATH, '//*[@id="submit"]/a').click()
await synthetics_webdriver.execute_step("verify_click", custom_actions)
```
#### get\$1http\$1response(url)
Effettua una richiesta HTTP all'URL fornito e restituisce il codice di risposta della richiesta HTTP. Se si verifica un'eccezione durante la richiesta HTTP, viene restituita una stringa con valore “error”.
Esempio:
```
response_code = syn_webdriver.get_http_response(url)
if not response_code or response_code == "error" or response_code < 200 or response_code > 299:
raise Exception("Failed to load page!")
```
#### Chrome()
Avvia un'istanza del browser Chromium e restituisce l'istanza creata del browser.
Esempio:
```
browser = synthetics_webdriver.Chrome()
browser.get("https://example.com/)
```
Per avviare un browser in modalità di navigazione in incognito, utilizza quanto segue:
```
add_argument('——incognito')
```
Per aggiungere impostazioni proxy, utilizza quanto segue:
```
add_argument('--proxy-server=%s' % PROXY)
```
Esempio:
```
from selenium.webdriver.chrome.options import Options
chrome_options = Options()
chrome_options.add_argument("——incognito")
browser = syn_webdriver.Chrome(chrome_options=chrome_options)
```