# Funciones de la biblioteca disponibles para los scripts de canarios de Node.js mediante Puppeteer En esta sección se describen las funciones de biblioteca disponibles para los scripts de canarios de Node.js. **Topics** + [Funciones y clases de biblioteca aplicables a todos los canaries](#CloudWatch_Synthetics_Library_allcanaries) + [Funciones y clases de biblioteca Node.js que solo se aplican a los canaries de la UI](#CloudWatch_Synthetics_Library_UIcanaries) + [Clases y funciones de biblioteca Node.js que se aplican sólo a los canaries de la API](#CloudWatch_Synthetics_Library_APIcanaries) ## Funciones y clases de biblioteca aplicables a todos los canaries Las siguientes funciones de biblioteca de CloudWatch Synthetics para Node.js son útiles para todos los canaries. **Topics** + [Clase de Synthetics](#CloudWatch_Synthetics_Library_Synthetics_Class_all) + [Clase SyntheticsConfiguration](#CloudWatch_Synthetics_Library_SyntheticsConfiguration) + [Registrador de Synthetics](#CloudWatch_Synthetics_Library_SyntheticsLogger) + [Clase de SyntheticSloghelper](#CloudWatch_Synthetics_Library_SyntheticsLogHelper) ### Clase de Synthetics Las siguientes funciones para todos los canaries están en la clase de Synthetics. **Topics** + [addExecutionError(errorMessage, ex);](#CloudWatch_Synthetics_Library_addExecutionError) + [getCanaryName();](#CloudWatch_Synthetics_Library_getCanaryName) + [getCanaryArn();](#CloudWatch_Synthetics_Library_getCanaryARN) + [getCanaryUserAgentString();](#CloudWatch_Synthetics_Library_getCanaryUserAgentString) + [getRuntimeVersion();](#CloudWatch_Synthetics_Library_getRuntimeVersion) + [getLogLevel();](#CloudWatch_Synthetics_Library_getLogLevel) + [setLogLevel();](#CloudWatch_Synthetics_Library_setLogLevel) #### addExecutionError(errorMessage, ex); `errorMessage` describe el error y `ex` es la excepción que se ha encontrado `addExecutionError` puede usarse para establecer errores de ejecución para el valor controlado. Se produce un error en el valor controlado sin interrumpir la ejecución del script. Tampoco afecta a las métricas de `successPercent`. Debe realizar un seguimiento de los errores como errores de ejecución sólo si no son importantes para indicar el éxito o el error del script valor controlado. A continuación, se muestra un ejemplo del uso de un `addExecutionError`. Está supervisando la disponibilidad de su punto de conexión y tomando capturas de pantalla después de que la página se haya cargado. Debido a que el hecho de no tomar una captura de pantalla no determina la disponibilidad del punto de enlace, puede detectar cualquier error que encuentre al tomar capturas de pantalla y agregarlos como errores de ejecución. Las métricas de disponibilidad seguirán indicando que el punto de conexión está activo y en ejecución, pero el estado del valor controlado se marcará como fallido. El siguiente bloque de código de muestra detecta dicho error y lo agrega como un error de ejecución. ``` try { await synthetics.takeScreenshot(stepName, "loaded"); } catch(ex) { synthetics.addExecutionError('Unable to take screenshot ', ex); } ``` #### getCanaryName(); Devuelve el nombre del valor controlado. #### getCanaryArn(); Devuelve el ARN del valor controlado. #### getCanaryUserAgentString(); Devuelve el agente de usuario personalizado del valor controlado. #### getRuntimeVersion(); Esta función está disponible en la versión de tiempo de ejecución `syn-nodejs-puppeteer-3.0` y en posteriores. Devuelve la versión de tiempo de ejecución de Synthetics del valor controlado. Por ejemplo, el valor de devuelto podría ser `syn-nodejs-puppeteer-3.0`. #### getLogLevel(); Recupera el nivel de registro actual para la biblioteca de Synthetics. Los valores posibles son los siguientes: + `0`: depuración + `1`: información + `2`: advertencia + `3`: error Ejemplo: ``` let logLevel = synthetics.getLogLevel(); ``` #### setLogLevel(); Establece el nivel de registro de la biblioteca de Synthetics. Los valores posibles son los siguientes: + `0`: depuración + `1`: información + `2`: advertencia + `3`: error Ejemplo: ``` synthetics.setLogLevel(0); ``` ### Clase SyntheticsConfiguration Esta clase solo está disponible en la versión de tiempo de ejecución de `syn-nodejs-2.1` o en posteriores. La clase `SyntheticsConfiguration` se puede utilizar para configurar el comportamiento de las funciones de biblioteca de Synthetics. Por ejemplo, puede utilizar esta clase para configurar la función `executeStep()` para no tomar capturas de pantalla. Pueden establecerse configuraciones de CloudWatch Synthetics a nivel global, que se aplican a todos los pasos de canaries. También se pueden anular estas configuraciones en el nivel de paso al pasar los pares clave y valor de configuración. Se pueden pasar opciones en el nivel de paso. Para ver ejemplos, consulte [async executeStep(stepName, functionToExecute, [stepConfig]);](#CloudWatch_Synthetics_Library_executeStep) y [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep). **Topics** + [setConfig(options)](#CloudWatch_Synthetics_Library_setConfig) + [Supervisión visual](#CloudWatch_Synthetics_Library_SyntheticsLogger_VisualTesting) #### setConfig(options) ` {{options}} ` es un objeto, que es un conjunto de opciones configurables para el valor controlado. En las siguientes secciones se explican los posibles campos en ` {{options}} `. ##### setConfig(options) para todos los canaries Para los canarios que utilizan `syn-nodejs-puppeteer-3.2` o versiones posteriores, las **(opciones)** para **setConfig** pueden incluir los siguientes parámetros: + `includeRequestHeaders` (booleano): si se deben incluir cabeceras de solicitud en el informe. El valor predeterminado es `false`. + `includeResponseHeaders` (booleano): si se deben incluir cabeceras de respuesta en el informe. El valor predeterminado es `false`. + `restrictedHeaders` (matriz): lista de valores de cabecera que se deben ignorar si se incluyen cabeceras. Esto aplica a las cabeceras de solicitud y respuesta. Por ejemplo, puede ocultar las credenciales al pasar **includeRequestHeaders** como `true` y **restrictedHeaders** como `['Authorization']`. + `includeRequestBody` (booleano): si se debe incluir el cuerpo de la solicitud en el informe. El valor predeterminado es `false`. + `includeResponseBody` (booleano): si se debe incluir el cuerpo de respuesta en el informe. El valor predeterminado es `false`. **importante** Si habilita `includeResponseBody` o ` logResponseBody`, el objeto de datos no se devuelve en la respuesta de algunas API, como los clientes de la versión 3 de aws-sdk. Esto se debe a una limitación de Node.js y al tipo de objeto de respuesta utilizado. **setConfig(options) con respecto a las métricas de CloudWatch** Para los canarios que utilizan `syn-nodejs-puppeteer-3.1` o versiones posteriores, las **(opciones)** para **setConfig** pueden incluir los siguientes parámetros booleanos que determinan qué métricas publica el canario. El valor predeterminado para cada una de estas opciones es `true`. Las opciones que comienzan con `aggregated` determinan si la métrica se emite sin la dimensión ` CanaryName`. Se pueden utilizar estas métricas para ver los resultados agregados de todos los canaries. Las otras opciones determinan si la métrica se emite con la dimensión `CanaryName`. Se pueden usar estas métricas para ver los resultados de cada valor controlado individualmente. Para obtener una lista de las métricas de CloudWatch que los canaries emiten, consulte [Métricas de CloudWatch que los canaries publican](CloudWatch_Synthetics_Canaries_metrics.md). + `failedCanaryMetric` (booleano): si se debe emitir la métrica ` Failed` (con la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`. + `failedRequestsMetric` (booleano): si se debe emitir la métrica `Failed requests` (con la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`. + `_2xxMetric` (booleano): si se debe emitir la métrica `2xx` (con la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`. + `_4xxMetric` (booleano): si se debe emitir la métrica `4xx` (con la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`. + `_5xxMetric` (booleano): si se debe emitir la métrica `5xx` (con la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`. + `stepDurationMetric` (booleano): si se debe emitir la métrica `Step duration` (con las dimensiones `CanaryName` y `StepName`) para este valor controlado. El valor predeterminado es `true`. + `stepSuccessMetric` (booleano): si se debe emitir la métrica `Step success` (con las dimensiones `CanaryName` y `StepName`) para este valor controlado. El valor predeterminado es `true`. + `aggregatedFailedCanaryMetric` (booleano): si se debe emitir la métrica `Failed` (sin la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`. + `aggregatedFailedRequestsMetric` (booleano): si se debe emitir la métrica `Failed Requests` (sin la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`. + `aggregated2xxMetric` (booleano): si se debe emitir la métrica ` 2xx` (sin la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`. + `aggregated4xxMetric` (booleano): si se debe emitir la métrica ` 4xx` (sin la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`. + `aggregated5xxMetric` (booleano): si se debe emitir la métrica ` 5xx` (sin la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`. + `visualMonitoringSuccessPercentMetric` (booleano): si se debe emitir la métrica `visualMonitoringSuccessPercent` para este valor controlado. El valor predeterminado es `true`. + `visualMonitoringTotalComparisonsMetric` (booleano): si se debe emitir la métrica `visualMonitoringTotalComparisons` para este valor controlado. El valor predeterminado es `false`. + `includeUrlPassword` (booleano): si se debe incluir una contraseña que aparezca en la dirección URL. De forma predeterminada, las contraseñas que aparecen en las direcciones URL se eliminan de los registros e informes para evitar que se divulgue información confidencial. El valor predeterminado es `false`. + `restrictedUrlParameters` (matriz): lista de la ruta URL o los parámetros de consulta que se van a editar. Esto aplica a las URL que aparecen en registros, informes y en errores. El parámetro no distingue entre mayúsculas y minúsculas. Puede pasar un asterisco (\*) como un valor para editar todos los valores de ruta de URL y los parámetros de consulta. El valor predeterminado es una matriz vacía. + `logRequest` (booleano): si se debe registrar cada solicitud en los registros de valores controlados. Para canaries de UI, esto registra cada solicitud que el navegador envía. El valor predeterminado es `true`. + `logResponse` (booleano): si se debe registrar cada respuesta en los registros de valores controlados. Para canaries de UI, esto registra todas las respuestas que el navegador recibe. El valor predeterminado es `true`. + `logRequestBody` (booleano): si se deben registrar los cuerpos de la solicitud junto con las solicitudes en los registros de valores controlados. Esta configuración sólo aplica si `logRequest` es `true`. El valor predeterminado es `false` . + `logResponseBody` (booleano): si se deben registrar los cuerpos de respuesta junto con las respuestas en los registros de valores controlados. Esta configuración sólo aplica si `logResponse` es `true`. El valor predeterminado es ` false`. **importante** Si habilita `includeResponseBody` o ` logResponseBody`, el objeto de datos no se devuelve en la respuesta de algunas API, como los clientes de la versión 3 de aws-sdk. Esto se debe a una limitación de Node.js y al tipo de objeto de respuesta utilizado. + `logRequestHeaders` (booleano): si se deben registrar cabeceras de solicitud junto con las solicitudes en registros de valores controlados. Esta configuración sólo aplica si `logRequest` es `true`. El valor predeterminado es ` false`. Debe tener en cuenta que `includeRequestHeaders` habilita cabeceras en artefactos. + `logResponseHeaders` (booleano): si se deben registrar cabeceras de respuesta junto con las respuestas en los registros de valores controlados. Esta configuración sólo aplica si `logResponse` es `true`. El valor predeterminado es ` false`. Debe tener en cuenta que `includeResponseHeaders` habilita cabeceras en artefactos. **nota** Las métricas de `Duration` y de `SuccessPercent` se emiten siempre para cada valor controlado con la métrica `CanaryName` y sin ella. ##### Métodos para habilitar o desactivar métricas **disableAggregatedRequestMetrics()** Desactiva que el valor controlado emita todas las métricas de solicitud que se emiten sin dimensión `CanaryName`. **disableRequestMetrics()** Deshabilita todas las métricas de solicitud, incluidas las métricas por valor controlado y las métricas agregadas en todos los valores controlados. **disableStepMetrics()** Desactiva todas las métricas de pasos, incluidas las métricas de éxito y de duración de los pasos. **enableAggregatedRequestMetrics()** Permite que el valor controlado emita todas las métricas de solicitud que se emiten sin dimensión ` CanaryName`. **enableRequestMetrics()** Habilita todas las métricas de solicitud, incluidas las métricas por valor controlado y las métricas agregadas en todos los valores controlados. **enableStepMetrics()** Habilita todas las métricas de pasos, incluidas las métricas de éxito y de duración de los pasos. **get2xxMetric()** Muestra si el valor controlado emite una métrica `2xx` con la dimensión ` CanaryName`. **get4xxMetric()** Muestra si el valor controlado emite una métrica `4xx` con la dimensión ` CanaryName`. **get5xxMetric()** Muestra si el valor controlado emite una métrica `5xx` con la dimensión ` CanaryName`. **getAggregated2xxMetric()** Muestra si el valor controlado emite una métrica `2xx` sin dimensión. **getAggregated4xxMetric()** Muestra si el valor controlado emite una métrica `4xx` sin dimensión. **getAggregatedFailedCanaryMetric()** Muestra si el valor controlado emite una métrica `Failed` sin dimensión. **getAggregatedFailedRequestsMetric()** Muestra si el valor controlado emite una métrica `Failed requests` sin dimensión. **getAggregated5xxMetric()** Muestra si el valor controlado emite una métrica `5xx` sin dimensión. **getFailedCanaryMetric()** Muestra si el valor controlado emite una métrica `Failed` con la dimensión ` CanaryName`. **getFailedRequestsMetric()** Muestra si el valor controlado emite una métrica `Failed requests` con la dimensión `CanaryName`. **getStepDurationMetric()** Muestra si el valor controlado emite una métrica `Duration` con la dimensión ` CanaryName` para este valor controlado. **getStepSuccessMetric()** Muestra si el valor controlado emite una métrica `StepSuccess` con la dimensión ` CanaryName` para este valor controlado. **with2xxMetric(\_2xxMetric)** Acepta un argumento booleano, que especifica si se emitirá una métrica `2xx` con la dimensión `CanaryName` para este valor controlado. **with4xxMetric(\_4xxMetric)** Acepta un argumento booleano, que especifica si se emitirá una métrica `4xx` con la dimensión `CanaryName` para este valor controlado. **with5xxMetric(\_5xxMetric)** Acepta un argumento booleano, que especifica si se emitirá una métrica `5xx` con la dimensión `CanaryName` para este valor controlado. **withAggregated2xxMetric(aggregated2xxMetric)** Acepta un argumento booleano, que especifica si se emitirá una métrica `2xx` sin dimensión para este valor controlado. **withAggregated4xxMetric(aggregated4xxMetric)** Acepta un argumento booleano, que especifica si se emitirá una métrica `4xx` sin dimensión para este valor controlado. **withAggregated5xxMetric(aggregated5xxMetric)** Acepta un argumento booleano, que especifica si se emitirá una métrica `5xx` sin dimensión para este valor controlado. ** withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetric)** Acepta un argumento booleano, que especifica si se emitirá una métrica `Failed` sin dimensión para este valor controlado. ** withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetric)** Acepta un argumento booleano, que especifica si se emitirá una métrica `Failed requests` sin dimensión para este valor controlado. **withFailedCanaryMetric(failedCanaryMetric)** Acepta un argumento booleano, que especifica si se emitirá una métrica `Failed` con la dimensión `CanaryName` para este valor controlado. **withFailedRequestsMetric(failedRequestsMetric)** Acepta un argumento booleano, que especifica si se emitirá una métrica `Failed requests` con la dimensión `CanaryName` para este valor controlado. **withStepDurationMetric(stepDurationMetric)** Acepta un argumento booleano, que especifica si se emitirá una métrica `Duration` con la dimensión `CanaryName` para este valor controlado. **withStepSuccessMetric(stepSuccessMetric)** Acepta un argumento booleano, que especifica si se emitirá una métrica ` StepSuccess` con la dimensión `CanaryName` para este valor controlado. ##### Métodos para habilitar o desactivar otras características **withHarFile()** Acepta un argumento booleano, que especifica si se debe crear un archivo HAR para este valor controlado. **withStepsReport()** Acepta un argumento booleano, que especifica si se debe informar de un resumen de ejecución de pasos para este valor controlado. **withIncludeUrlPassword()** Acepta un argumento booleano, que especifica si se deben incluir las contraseñas que aparecen en las URL de los registros e informes. **withRestrictedUrlParameters()** Acepta una matriz de ruta de URL o parámetros de consulta para editar. Esto aplica a las URL que aparecen en registros, informes y en errores. Se puede pasar un asterisco (\*) como un valor para redactar todos los valores de ruta de URL y los parámetros de consulta **withLogRequest()** Acepta un argumento booleano, que especifica si se debe registrar cada solicitud en los registros del valor controlado. **withLogResponse()** Acepta un argumento booleano, que especifica si se debe registrar cada respuesta en los registros del valor controlado. **withLogRequestBody()** Acepta un argumento booleano, que especifica si se debe registrar cada cuerpo de la solicitud en los registros del valor controlado. **withLogResponseBody()** Acepta un argumento booleano, que especifica si se debe registrar cada cuerpo de respuesta en los registros del valor controlado. **withLogRequestHeaders()** Acepta un argumento booleano, que especifica si se debe registrar cada cabecera de solicitud en los registros del valor controlado. **withLogResponseHeaders()** Acepta un argumento booleano, que especifica si se debe registrar cada cabecera de respuesta en los registros del valor controlado. **getHarFile()** Muestra si el valor controlado crea un archivo HAR. **getStepsReport()** Muestra si el valor controlado informa un resumen de ejecución de pasos. **getIncludeUrlPassword()** Muestra si el valor controlado incluye contraseñas que aparecen en las URL en los registros e informes. **getRestrictedUrlParameters()** Muestra si el valor controlado redacta la ruta de URL o los parámetros de consulta. **getLogRequest()** Muestra si el valor controlado registra cada solicitud en los registros del valor controlado. **getLogResponse()** Muestra si el valor controlado registra cada respuesta en los registros del valor controlado. **getLogRequestBody()** Muestra si el valor controlado registra cada cuerpo de la solicitud en los registros del valor controlado. **getLogResponseBody()** Muestra si el valor controlado registra cada cuerpo de respuesta en los registros del valor controlado. **getLogRequestHeaders()** Muestra si el valor controlado registra cada cabecera de solicitud en los registros del valor controlado. **getLogResponseHeaders()** Muestra si el valor controlado registra cada cabecera de respuesta en los registros del valor controlado. **Funciones para todos los valores controlados** + `withIncludeRequestHeaders`(includeRequestHeaders) + `withIncludeResponseHeaders`(includeResponseHeaders) + `withRestrictedHeaders`(restrictedHeaders) + `withIncludeRequestBody`(includeRequestBody) + `withIncludeResponseBody`(includeResponseBody) + `enableReportingOptions`(): activa todas las opciones de informes-- **includeRequestHeaders**, **includeResponseHeaders**, **includeRequestBody** e **includeResponseBody**. + `disableReportingOptions`(): desactiva todas las opciones de informes-- **includeRequestHeaders**, **includeResponseHeaders**, **includeRequestBody** e **includeResponseBody**. ##### setConfig(options) para canaries de la UI Para canaries de la UI, **setConfig** puede incluir los siguientes parámetros booleanos: + `continueOnStepFailure` (booleano): si se debe continuar con la ejecución del script canario después de que un paso falle (este parámetro hace referencia a la función **executeStep**). Si algún paso falla, la ejecución del valor controlado seguirá marcándose como fallida. El valor predeterminado es `false`. + `harFile` (booleano): si se crea un archivo HAR. El valor predeterminado es `True`. + `screenshotOnStepStart` (booleano): si se debe tomar una captura de pantalla antes de comenzar un paso. + `screenshotOnStepSuccess` (booleano): si se debe tomar una captura de pantalla después de completar un paso correctamente. + `screenshotOnStepFailure` (booleano): si se debe tomar una captura de pantalla después de que un paso falla. ##### Métodos para habilitar o desactivar las capturas de pantalla **disableStepScreenshots()** Deshabilita todas las opciones de captura de pantalla (screenshotOnStepStart, screenshotOnStepSuccess, y screenshotOnStepFailure). **enableStepScreenshots()** Habilita todas las opciones de captura de pantalla (screenshotOnStepStart, screenshotOnStepSuccess, y screenshotOnStepFailure). Estos métodos no están habilitados de forma predeterminada. **getScreenshotOnStepFailure()** Muestra si el valor controlado toma una captura de pantalla después de que un paso falla. **getScreenshotOnStepStart()** Muestra si el valor controlado toma una captura de pantalla antes de iniciar un paso. **getScreenshotOnStepSuccess()** Muestra si el valor controlado toma una captura de pantalla después de completar un paso correctamente. **withScreenshotOnStepStart(screenshotOnStepStart)** Acepta un argumento booleano, que indica si se debe tomar una captura de pantalla antes de iniciar un paso. **withScreenshotOnStepSuccess(screenshotOnStepSuccess)** Acepta un argumento booleano, que indica si se debe tomar una captura de pantalla después de completar un paso correctamente. **withScreenshotOnStepFailure(screenshotOnStepFailure)** Acepta un argumento booleano, que indica si se debe tomar una captura de pantalla después de que un paso falla. **Uso en valores controlados de la IU** Primero, importe la relación de Synthetics y obtenga la configuración. ``` // Import Synthetics dependency const synthetics = require('@aws/synthetics-puppeteer'); // Get Synthetics configuration const synConfig = synthetics.getConfiguration(); ``` A continuación, establezca la configuración para cada opción mediante llamadas al método SetConfig con una de las siguientes opciones. ``` // Set configuration values synConfig.setConfig({ screenshotOnStepStart: true, screenshotOnStepSuccess: false, screenshotOnStepFailure: false }); ``` O ``` synConfig.withScreenshotOnStepStart(false).withScreenshotOnStepSuccess(true).withScreenshotOnStepFailure(true) ``` Para deshabilitar todas las capturas de pantalla, utilice la función `disableStepScreenshots()` como en este ejemplo. ``` synConfig.disableStepScreenshots(); ``` Puede habilitar y desactivar las capturas de pantalla en cualquier punto del código. Por ejemplo, para desactivar las capturas de pantalla solo para un paso, se deben desactivar antes de ejecutar ese paso y habilitarlas después del paso. ##### setConfig(options) para canaries de la API Para los canaries de la API, **setConfig** puede incluir los siguientes parámetros booleanos: + `continueOnHttpStepFailure` (booleano): si se continúa con la ejecución del script valor controlado después de que se produce un error en un paso HTTP (esto se refiere a la función **executeHttpStep**). Si algún paso falla, la ejecución del valor controlado seguirá marcándose como fallida. El valor predeterminado es `true`. #### Supervisión visual La supervisión visual compara las capturas de pantalla que se toman durante una ejecución de un valor controlado con las capturas de pantalla que se toman durante una ejecución de un valor controlado de línea de base. Si la discrepancia entre las dos capturas de pantalla está más allá de un porcentaje umbral, el valor controlado falla y se podrán ver las áreas con diferencias resaltadas en color en el informe de ejecución del valor controlado. La supervisión visual es compatible con canaries que ejecutan **syn-puppeteer-node-3.2** y versiones posteriores. Por el momento no es compatible con canaries que ejecutan Python y Selenium. Para habilitar la supervisión visual, agregue la siguiente línea de código al script valor controlado. Para obtener más información, consulte [Clase SyntheticsConfiguration](#CloudWatch_Synthetics_Library_SyntheticsConfiguration). ``` syntheticsConfiguration.withVisualCompareWithBaseRun(true); ``` La primera vez que el valor controlado se ejecuta correctamente después de agregar esta línea al script, utiliza las capturas de pantalla que se toman durante esa ejecución como línea de base para la comparación. Después de la primera ejecución del valor controlado, se puede usar la consola de CloudWatch para editar el valor controlado para realizar cualquiera de las siguientes acciones: + Establecer la siguiente ejecución del valor controlado como la nueva línea de base. + Establecer límites en la captura de pantalla de línea de base actual para designar áreas de la captura de pantalla que se ignorarán durante las comparaciones visuales. + Eliminar una captura de pantalla de ser utilizada para la supervisión visual. Para obtener más información sobre cómo usar la consola de CloudWatch para editar un valor controlado, consulte [Edición o eliminación de un valor controlado](synthetics_canaries_deletion.md). **Otras opciones para la supervisión visual** ** syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)** Establezca el porcentaje aceptable para la desviación de captura de pantalla en las comparaciones visuales. ** syntheticsConfiguration.withVisualVarianceHighlightHexColor(“\#fafa00")** Establezca el color de resaltado que designa las áreas de desviación cuando vea los informes de ejecución del valor controlado que utilizan supervisión visual. ** syntheticsConfiguration.withFailCanaryRunOnVisualVariance(failCanary)** Establezca si el valor controlado falla o no cuando hay una diferencia visual superior al umbral. El valor predeterminado es que el valor controlado falle. ### Registrador de Synthetics SyntheticsLogger escribe registros tanto en la consola como en un archivo de registro local, en el mismo nivel de registro. Este archivo de registro se escribe en ambas ubicaciones solo si el nivel de registro coincide con el deseado para la función de registro a la que se llamó o está por debajo de este. Los valores “DEBUG:“, “INFO:“, etc. se anteponen a las instrucciones de registro del archivo de registro local para que coincidan con el nivel de registro de la función a la que se llamó. Puede utilizar SyntheticsLogger si desea ejecutar la biblioteca de Synthetics en el mismo nivel de registro que el registro de valores controlados de Synthetics. No es necesario que se utilice SyntheticsLogger para crear un archivo de registros que se carga en la ubicación de resultados de S3. En su lugar, puede crear un archivo de registro distinto en la carpeta ` /tmp`. Los archivos creados en la carpeta `/tmp` se cargan en la ubicación de resultados de S3 como artefactos. Para utilizar el registrador de la biblioteca de Synthetics: ``` const log = require('@aws/synthetics-logger'); ``` Definiciones de funciones útiles: **log.debug({{message}}, {{ex}} );** Parámetros: {{message}} es el mensaje que se va a registrar. {{ex}} es la excepción que se registra, si la hay Ejemplo: ``` log.debug("Starting step - login."); ``` **log.error({{message}}, {{ex}} );** Parámetros: {{message}} es el mensaje que se va a registrar. {{ex}} es la excepción que se registra, si la hay Ejemplo: ``` try { await login(); catch (ex) { log.error("Error encountered in step - login.", ex); } ``` **log.info({{message}}, {{ex}} );** Parámetros: {{message}} es el mensaje que se va a registrar. {{ex}} es la excepción que se registra, si la hay Ejemplo: ``` log.info("Successfully completed step - login."); ``` **log.log({{message}}, {{ex}} );** Este es un alias para `log.info`. Parámetros: {{message}} es el mensaje que se va a registrar. {{ex}} es la excepción que se registra, si la hay Ejemplo: ``` log.log("Successfully completed step - login."); ``` **log.warn({{message}}, {{ex}} );** Parámetros: {{message}} es el mensaje que se va a registrar. {{ex}} es la excepción que se registra, si la hay Ejemplo: ``` log.warn("Exception encountered trying to publish CloudWatch Metric.", ex); ``` ### Clase de SyntheticSloghelper La clase `SyntheticsLogHelper` está disponible en el tiempo de ejecución ` syn-nodejs-puppeteer-3.2` y en tiempos de ejecución posteriores. Ya está inicializado en la biblioteca CloudWatch Synthetics y está configurado con la configuración de Synthetics. Puede agregar esto como una relación en el script. Esta clase le permite borrar las URL, encabezados y mensajes de error para redactar información confidencial. **nota** Synthetics sanitiza todas las URL y los mensajes de error que registra antes de incluirlos en los registros, informes, archivos HAR y errores de ejecución de los valores controlados basados en la configuración `restrictedUrlParameters` de Synthetics. Tiene que usar ` getSanitizedUrl` o `getSanitizedErrorMessage` solo si está registrando direcciones URL o errores en el script. Synthetics no almacena ningún artefacto de valores controlados excepto los errores de valores controlados que el script lanza. Los artefactos de ejecución de valores controlados se almacenan en la cuenta del cliente. Para obtener más información, consulte [Consideraciones de seguridad para los canaries de Synthetics](servicelens_canaries_security.md). **Topics** + [getSanitizedUrl(url, stepConfig = null)](#CloudWatch_Synthetics_Library_getSanitizedUrl) + [getSanitizedErrorMessage](#CloudWatch_Synthetics_Library_getSanitizedErrorMessage) + [getSanitizedHeaders(headers, stepConfig=null)](#CloudWatch_Synthetics_Library_getSanitizedHeaders) #### getSanitizedUrl(url, stepConfig = null) Esta función está disponible en `syn-nodejs-puppeteer-3.2` y en posteriores. Devuelve cadenas de url sanitizadas basadas en la configuración. Puede optar por eliminar los parámetros de las URL confidenciales como la contraseña y el access\_token al establecer la propiedad `restrictedUrlParameters`. De forma predeterminada, las contraseñas de las URL se eliminan. Si es necesario, puede habilitar las contraseñas de las URL si configura `includeUrlPassword` a verdadero. Esta función arroja un error si la URL pasada no es una URL válida. **Parámetros ** + Una {{url}} es una cadena y es la URL para sanitizar. + {{stepConfig}} (Opcional) anula la configuración global de Synthetics para esta función. Si `stepConfig` no se especifica, la configuración global se utiliza para sanitizar la URL. **Ejemplo ** En este ejemplo se usa la siguiente URL de ejemplo: ` https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200`. En este ejemplo, `access_token` contiene su información confidencial que no debe registrarse. Debe tener en cuenta que los servicios de Synthetics no almacenan ningún artefacto de ejecución de valores controlados. Los artefactos como registros, capturas de pantalla e informes se almacenan en un bucket de Amazon S3 de la cuenta de cliente. El primer paso es configurar la configuración de 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); ``` A continuación, sanitice y registre la 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'); ``` Esto registra lo siguiente en el registro del valor controlado. ``` My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200 ``` Puede anular la configuración de Synthetics para una URL si especifica un parámetro opcional que contenga las opciones de configuración de Synthetics, como en el siguiente ejemplo . ``` 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); ``` El ejemplo anterior elimina todos los parámetros de consulta y se registra de la siguiente manera: ``` My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=REDACTED&expires_in=REDACTED ``` #### getSanitizedErrorMessage Esta función está disponible en `syn-nodejs-puppeteer-3.2` y en posteriores. Devuelve cadenas de error sanitizadas al sanitizar cualquier URL presente en función de la configuración de Synthetics. Puede optar por anular la configuración global de Synthetics cuando llame a esta función mediante la especificación de un parámetro `stepConfig`. **Parámetros ** + {{error}} es el error para sanitizar. Puede ser un objeto Error o una cadena. + {{stepConfig}} (Opcional) anula la configuración global de Synthetics para esta función. Si `stepConfig` no se especifica, la configuración global se utiliza para sanitizar la URL. **Ejemplo ** En este ejemplo se utiliza el siguiente error: ` Failed to load url: https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200` El primer paso es configurar la configuración de 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']; }); ``` A continuación, sanitice y registre el mensaje de error ``` // 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); } ``` Esto registra lo siguiente en el registro del valor controlado. ``` Failed to load url: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200 ``` #### getSanitizedHeaders(headers, stepConfig=null) Esta función está disponible en `syn-nodejs-puppeteer-3.2` y en posteriores. Devuelve encabezados sanitizados basados en la propiedad `restrictedHeaders` de ` syntheticsConfiguration`. Los encabezados especificados en la propiedad `restrictedHeaders` se editan a partir de registros, archivos HAR e informes. **Parámetros ** + {{headers}} (cabeceras) es un objeto que contiene las cabeceras para desinfectar. + {{stepConfig}} (Opcional) anula la configuración global de Synthetics para esta función. Si `stepConfig` no se especifica, la configuración global se utiliza para desinfectar las cabeceras. ## Funciones y clases de biblioteca Node.js que solo se aplican a los canaries de la UI Las siguientes funciones de la biblioteca de CloudWatch Synthetics solo son útiles para los canaries de la UI. **Topics** + [Clase de Synthetics](#CloudWatch_Synthetics_Library_Synthetics_Class) + [Clase BrokenLinkCheckerReport](#CloudWatch_Synthetics_Library_BrokenLinkCheckerReport) + [Clase SyntheticsLink](#CloudWatch_Synthetics_Library_SyntheticsLink) ### Clase de Synthetics Las siguientes funciones están en la clase de Synthetics. **Topics** + [async addUserAgent(page, userAgentString);](#CloudWatch_Synthetics_Library_addUserAgent) + [async executeStep(stepName, functionToExecute, [stepConfig]);](#CloudWatch_Synthetics_Library_executeStep) + [getDefaultLaunchOptions();](#CloudWatch_Synthetics_Library_getDefaultLaunchOptions) + [getPage();](#CloudWatch_Synthetics_Library_getPage) + [getRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_getRequestResponseLogHelper) + [Lanzamiento (opciones)](#CloudWatch_Synthetics_Library_LaunchOptions) + [RequestResponseLogHelper class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper) + [setRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_setRequestResponseLogHelper) + [async takeScreenshot(name, suffix);](#CloudWatch_Synthetics_Library_takeScreenshot) #### async addUserAgent(page, userAgentString); Esta función añade {{userAgentString}} al encabezado de agente de usuario de la página especificada. Ejemplo: ``` await synthetics.addUserAgent(page, "MyApp-1.0"); ``` Los resultados del encabezado del agente de usuario de la página se establecen en `{{ browsers-user-agent-header-value}}MyApp-1.0` #### async executeStep(stepName, functionToExecute, [stepConfig]); Ejecuta el paso proporcionado y lo integra con iniciar/superar/fallar el registro, iniciar/superar/fallar capturas de pantalla, superar/fallar y métricas de duración. **nota** Si utiliza el `syn-nodejs-2.1` o una versión posterior de tiempo de ejecución, puede configurar si se toman capturas de pantalla y cuándo. Para obtener más información, consulte [Clase SyntheticsConfiguration](#CloudWatch_Synthetics_Library_SyntheticsConfiguration). La función `executeStep` también hace lo siguiente: + Registra que el paso se ha iniciado. + Toma una captura de pantalla denominada `-starting`. + Inicia un temporizador. + Ejecuta la función proporcionada. + Si la función devuelve resultados normalmente, cuenta como superada. Si la función falla, cuenta como error. + Finaliza el temporizador. + Registra si el paso se ha superado o no. + Toma una captura de pantalla denominada `-succeeded` o ` -failed`. + Emite la métrica `stepName` `SuccessPercent`, 100 para superado o 0 para no superado. + Emite la métrica `stepName` `Duration`, con un valor basado en las horas de inicio y de finalización del paso. + Por último, devuelve el mismo resultado que `functionToExecute` o vuelve a arrojar el mismo error que `functionToExecute`. Si el valor controlado utiliza el tiempo de ejecución `syn-nodejs-2.0` o uno posterior, esta función también agrega un resumen de ejecución de pasos al informe del valor controlado. El resumen incluye detalles acerca de cada paso, como la hora de inicio, la hora de finalización, el estado (SUPERADO o NO SUPERADO), el motivo del error (si hubo) y las capturas de pantalla que se tomaron durante la ejecución de cada paso. Ejemplo: ``` await synthetics.executeStep('navigateToUrl', async function (timeoutInMillis = 30000) { await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});}); ``` Respuesta: Devuelve el mismo resultado que `functionToExecute`. **Actualizaciones con syn-nodejs-2.2** A partir de `syn-nodejs-2.2`, se pueden pasar opcionalmente configuraciones de pasos para anular las configuraciones de CloudWatch Synthetics en el nivel de pasos. Para obtener una lista de opciones que puede pasar a `executeStep`, consulte [Clase SyntheticsConfiguration](#CloudWatch_Synthetics_Library_SyntheticsConfiguration). En el siguiente ejemplo se anula la configuración predeterminada `false` para ` continueOnStepFailure` a `true` y se especifica cuándo tomar capturas de pantalla. ``` var stepConfig = { 'continueOnStepFailure': true, 'screenshotOnStepStart': false, 'screenshotOnStepSuccess': true, 'screenshotOnStepFailure': false } await executeStep('Navigate to amazon', async function (timeoutInMillis = 30000) { await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis}); }, stepConfig); ``` #### getDefaultLaunchOptions(); La función `getDefaultLaunchOptions()` muestra los resultados de las opciones de lanzamiento del navegador que CloudWatch Synthetics utiliza. Para más información, consulte [Tipo de opciones de lanzamiento](https://pptr.dev/browsers-api/browsers.launchoptions/) ``` // This function returns default launch options used by Synthetics. const defaultOptions = await synthetics.getDefaultLaunchOptions(); ``` #### getPage(); Devuelve la página abierta actual como objeto de Puppeteer. Para obtener más información, consulte [Puppeteer API v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md). Ejemplo: ``` let page = await synthetics.getPage(); ``` Respuesta: La página (objeto de Puppeteer) que está abierta en la sesión del explorador actual. #### getRequestResponseLogHelper(); **importante** En los canaries que utilizan el tiempo de ejecución `syn-nodejs-puppeteer-3.2` o posteriores, esta función está obsoleta junto con la clase `RequestResponseLogHelper`. El uso de esta función hace que aparezca una advertencia en los registros de los valores controlados. Esta función se eliminará en versiones futuras de tiempo de ejecución. Si está utilizando esta función, utilice en su lugar [RequestResponseLogHelper class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper). Utilice esta función como patrón generador para modificar las marcas de registro de solicitudes y respuestas. Ejemplo: ``` synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));; ``` Respuesta: ``` {RequestResponseLogHelper} ``` #### Lanzamiento (opciones) Las opciones para esta función sólo están disponibles en la versión de tiempo de ejecución `syn-nodejs-2.1` o en posteriores. Esta función solo se usa para los canaries de la UI. Cierra el navegador existente y lanza uno nuevo. **nota** CloudWatch Synthetics siempre lanza un navegador antes de comenzar a ejecutar el script. No es necesario que llame un lanzamiento() a menos que desee lanzar un navegador nuevo con opciones personalizadas. (opciones) es un conjunto configurable de opciones para configurar en el navegador. Para obtener más información, consulte [Tipo de opciones de lanzamiento](https://pptr.dev/browsers-api/browsers.launchoptions/). Si llama a esta función sin opciones, Synthetics lanza un navegador con argumentos predeterminados, `executablePath` y `defaultViewport`. La ventana gráfica predeterminada en CloudWatch Synthetics es 1920 x 1080. Se pueden anular los parámetros de lanzamiento que CloudWatch Synthetics utiliza y pasar parámetros adicionales al lanzar el navegador. Por ejemplo, el siguiente fragmento de código inicia un navegador con argumentos predeterminados y una ruta ejecutable predeterminada, pero con una ventana gráfica de 800 x 600. ``` await synthetics.launch({ defaultViewport: { "deviceScaleFactor": 1, "width": 800, "height": 600 }}); ``` En el siguiente código de muestra se agrega un nuevo parámetro `ignoreHTTPSErrors` a los parámetros de lanzamiento de CloudWatch Synthetics: ``` await synthetics.launch({ ignoreHTTPSErrors: true }); ``` Puede desactivar la seguridad web si agrega un indicador `--disable-web-security` a los argumentos en los parámetros de lanzamiento de 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 class **importante** En los canaries que utilizan el tiempo de ejecución `syn-nodejs-puppeteer-3.2` o posteriores, esta clase está obsoleta. El uso de esta clase hace que aparezca una advertencia en los registros de los valores controlados. Esta función se eliminará en versiones futuras de tiempo de ejecución. Si está utilizando esta función, utilice en su lugar [RequestResponseLogHelper class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper). Controla la configuración y la creación en detalle de las representaciones de cadena de cargas de solicitud y respuesta. ``` 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); ``` Ejemplo: ``` synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper() .withLogRequestPostData(true) .withLogRequestHeaders(true) .withLogResponseHeaders(true)); ``` Respuesta: ``` {RequestResponseLogHelper} ``` #### setRequestResponseLogHelper(); **importante** En los canaries que utilizan el tiempo de ejecución `syn-nodejs-puppeteer-3.2` o posteriores, esta función está obsoleta junto con la clase `RequestResponseLogHelper`. El uso de esta función hace que aparezca una advertencia en los registros de los valores controlados. Esta función se eliminará en versiones futuras de tiempo de ejecución. Si está utilizando esta función, utilice en su lugar [RequestResponseLogHelper class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper). Utilice esta función como patrón generador para establecer las marcas de registro de solicitudes y respuestas. Ejemplo: ``` synthetics.setRequestResponseLogHelper().withLogRequestHeaders(true).withLogResponseHeaders(true); ``` Respuesta: ``` {RequestResponseLogHelper} ``` #### async takeScreenshot(name, suffix); Toma una captura de pantalla (.PNG) de la página actual con nombre y un sufijo (opcional). Ejemplo: ``` await synthetics.takeScreenshot("navigateToUrl", "loaded") ``` Este ejemplo captura y carga una captura de pantalla denominada ` 01-navigateToUrl-loaded.png` al bucket de S3 del valor controlado. Puede tomar una captura de pantalla para un paso del valor controlado en particular al pasar ` stepName` como primer parámetro. Las capturas de pantalla están vinculadas al paso del valor controlado en los informes, para ayudarlo a realizar un rastreo de cada paso durante la depuración. Los valores controlados de CloudWatch Synthetics toman capturas de pantalla automáticamente antes de comenzar un paso (la función `executeStep`) y después de la finalización del paso (a menos que configure el valor controlado para desactivar las capturas de pantalla). Puede tomar más capturas de pantalla si pasa el nombre del paso en la función `takeScreenshot`. El siguiente ejemplo toma una captura de pantalla con `signupForm` como el valor de `stepName`. La captura de pantalla se denominará ` 02-signupForm-address` y se vinculará al paso denominado ` signupForm` en el informe del valor controlado. ``` await synthetics.takeScreenshot('signupForm', 'address') ``` ### Clase BrokenLinkCheckerReport Esta clase proporciona métodos para agregar un enlace Synthetics. Solo se admite en canaries que utilizan la versión `syn-nodejs-2.0-beta` de tiempo de ejecución o posteriores. Para utilizar `BrokenLinkCheckerReport`, incluya las siguientes líneas en el script: ``` const BrokenLinkCheckerReport = require('@aws/synthetics-broken-link-checker-report'); const brokenLinkCheckerReport = new BrokenLinkCheckerReport(); ``` Definiciones de funciones útiles: **addLink({{syntheticsLink}}, isBroken)** ` {{syntheticsLink}} ` es un objeto ` SyntheticsLink` que representa un enlace. Esta función agrega el enlace de acuerdo con el código de estado. De forma predeterminada, considera que un enlace se rompe si el código de estado no está disponible o si el código de estado es 400 o superior. Puede anular este comportamiento predeterminado si pasa el parámetro opcional `isBrokenLink` con un valor de `true` o `false`. Esta función no tiene un valor de retorno. **getLinks()** Esta función muestra los resultados de una matriz de los objetos `SyntheticsLink` que se incluyen en el informe del verificador de enlaces que no funcionan. **getTotalBrokenLinks()** Esta función muestra los resultados de un número que representa el número total de enlaces que no funcionan. **getTotalLinksChecked()** Esta función muestra los resultados de un número que representa el número total de enlaces incluidos en el informe. **Cómo utilizar BrokenLinkCheckerReport** El siguiente fragmento de código de script valor controlado muestra un ejemplo de navegación a un enlace que se agrega al informe del verificador de enlaces que no funcionan. 1. Importe `SyntheticsLink`, `BrokenLinkCheckerReport`, y ` 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. Para agregar un enlace al informe, cree una instancia de ` BrokenLinkCheckerReport`. ``` let brokenLinkCheckerReport = new BrokenLinkCheckerReport(); ``` 1. Desplácese hasta la URL y agréguela al informe del verificador de vínculos que no funcionan. ``` 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. Agregue el informe a Synthetics. Esto crea un archivo JSON llamado ` BrokenLinkCheckerReport.json` en el bucket de S3 para cada ejecución del valor controlado. Se puede ver un informe de enlaces en la consola para cada ejecución de valores controlados junto con capturas de pantalla, registros y archivos HAR. ``` await synthetics.addReport(brokenLinkCheckerReport); ``` ### Clase SyntheticsLink Esta clase proporciona métodos para ajustar la información. Solo se admite en canaries que utilizan la versión `syn-nodejs-2.0-beta` de tiempo de ejecución o posteriores. Para utilizar `SyntheticsLink`, incluya las siguientes líneas en el script: ``` const SyntheticsLink = require('@aws/synthetics-link'); const syntheticsLink = new SyntheticsLink("https://www.amazon.com"); ``` La función muestra los resultados de . `syntheticsLink{{Object}}` Definiciones de funciones útiles: **withUrl({{url}})** ` {{url}} ` es una cadena de URL. La función muestra los resultados de `syntheticsLink{{Object}}`. **withText({{text}})** ` {{text}} ` es una cadena que representa el texto de anclaje. La función muestra los resultados de `syntheticsLink{{Object}}`. Añade texto de anclaje correspondiente al enlace. **withParentUrl({{parentUrl}})** ` {{parentUrl}} ` es una cadena que representa la URL principal (página fuente). La función muestra los resultados de . `syntheticsLink{{ Object}}` **withStatusCode({{statusCode}})** ` {{statusCode}} ` es una cadena que representa el código de estado. La función muestra los resultados de . `syntheticsLink{{Object}}` **withFailureReason({{failureReason}})** ` {{failureReason}} ` es una cadena que representa la causa del error. La función muestra los resultados de . `syntheticsLink{{ Object}}` **addScreenshotResult({{screenshotResult}})** ` {{screenshotResult}} ` es un objeto. Es una instancia de `ScreenshotResult` que la función de Synthetics `takeScreenshot` ha mostrado. El objeto incluye lo siguiente: + `fileName`— Una cadena que representa el ` screenshotFileName` + `pageUrl` (opcional) + `error` (opcional) ## Clases y funciones de biblioteca Node.js que se aplican sólo a los canaries de la API Las siguientes funciones de biblioteca de CloudWatch Synthetics para Node.js solo son útiles para los API canaries de la UI. **Topics** + [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep) ### executeHttpStep(stepName, requestOptions, [callback], [stepConfig]) Ejecuta la solicitud HTTP proporcionada como un paso y publica `SuccessPercent` (aprobar o no aprobar) y las métricas `Duration`. **executeHttpStep** utiliza funciones nativas HTTP o HTTPS que no son visibles a simple vista de acuerdo al protocolo que se ha especificado en la solicitud. Esta función también agrega un resumen de ejecución de pasos al informe del valor controlado. El resumen incluye detalles sobre cada solicitud HTTP, como los siguientes: + Hora de inicio + Hora de finalización + Estado (APROBADO o NO APROBADO) + Razón del error, si hubo + Detalles de llamada HTTP como cabeceras de solicitud o respuesta, cuerpo, código de estado, mensaje de estado y tiempos de rendimiento. **Topics** + [Parameters](#CloudWatch_Synthetics_Library_executeHttpStep_parameters) + [Ejemplos de uso de executeHttpStep](#CloudWatch_Synthetics_Library_executeHttpStep_examples) #### Parameters **stepName({{String}})** Especifica el nombre del paso. Este nombre también se utiliza para publicar métricas de CloudWatch para este paso. **requestOptions({{Object or String}})** El valor de este parámetro puede ser una URL, una cadena URL o un objeto. Si es un objeto, entonces debe ser un conjunto de opciones configurables para realizar una solicitud HTTP. Es compatible con todas las opciones en [http.request(options[, callback])](https://nodejs.org/api/http.html#http_http_request_options_callback) en el documento de Node.js. Además de estas opciones de Node.js, **requestOptions** admite el parámetro adicional `body`. Puede utilizar el parámetro `body` para pasar datos como un cuerpo de la solicitud. **callback({{response}})** (Opcional) Esta es una función de usuario que se invoca con la respuesta HTTP. La respuesta es del tipo [Clase: http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage). **stepConfig({{object}})** (Opcional) Utilice este parámetro para anular configuraciones globales de Synthetics con una configuración diferente para este paso. #### Ejemplos de uso de executeHttpStep La siguiente serie de ejemplos se crean entre sí para ilustrar los diversos usos de esta opción. Este primer ejemplo configura los parámetros de solicitud. Puede pasar una URL como **requestOptions**: ``` let requestOptions = 'https://www.amazon.com'; ``` O puede pasar un conjunto de opciones: ``` let requestOptions = { 'hostname': 'myproductsEndpoint.com', 'method': 'GET', 'path': '/test/product/validProductName', 'port': 443, 'protocol': 'https:' }; ``` El siguiente ejemplo crea una función de devolución de llamada que acepta una respuesta. De forma predeterminada, si no se especifica **callback** (devolución de llamada), CloudWatch Synthetics valida que el estado esté entre 200 y 299 inclusive. ``` // 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(); }); }); }; ``` El siguiente ejemplo crea una configuración para este paso que reemplaza la configuración global de CloudWatch Synthetics. La configuración de pasos de este ejemplo permite las cabeceras de solicitud, las cabeceras de respuesta, el cuerpo de la solicitud (datos posteriores) y el cuerpo de la respuesta en el informe y restringe los valores de las cabeceras de ‘X-Amz-Security-Token’ y de ‘Autorización’. De forma predeterminada, estos valores no se incluyen en el informe por motivos de seguridad. Si elige incluirlos, los datos solo se almacenan en su bucket de 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 }; ``` Este último ejemplo pasa su solicitud a **executeHttpStep** y nombra el paso. ``` await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig); ``` Con este conjunto de ejemplos, CloudWatch Synthetics agrega los detalles de cada paso al informe y genera métricas para cada paso mediante **stepName**. Se podrán ver `successPercent` y métricas `duration` para el paso `Verify GET products API`. Puede supervisar el rendimiento de la API si supervisa las métricas de los pasos de llamadas a la API. Para obtener un script completo de ejemplo que utilice estas funciones, consulte [Valor controlado de la API de varios pasos](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps).