Funciones de biblioteca disponibles para el canario de Node.js

En esta sección, se describen las funciones de biblioteca disponibles para los scripts de canarios que utilizan el tiempo de ejecución de Node.js.

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.executeStep(stepName, callbackFunc);} 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-3.0 y 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-3.0.

getLogLevel();

Recupera el nivel de registro actual para la biblioteca de Synthetics. Los valores posibles son los siguientes:

Ejemplo:

let logLevel = synthetics.getLogLevel();

setLogLevel();

Establece el nivel de registro de la biblioteca de Synthetics. Los valores posibles son los siguientes:

Ejemplo:

synthetics.setLogLevel(0);

executeStep(stepName, functionToExecute, [stepConfig])

Ejecuta el paso proporcionado y lo integra con iniciar/superar/fallar el registro, superar/fallar y métricas de duración.

La función executeStep también hace lo siguiente:

Ejemplo

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

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:

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

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.