Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Fonctions de bibliothèque disponibles pour Node.js Canary

Cette section décrit les fonctions de bibliothèque disponibles pour les scripts Canary à l'aide du moteur d'exécution Node.js.

addExecutionError(Message d'erreur, par exemple) ;

errorMessage décrit l'erreur et ex est l'exception rencontrée.

Vous pouvez utiliser addExecutionError pour définir les erreurs d'exécution pour votre script Canary. Ce code fait échouer le script Canary sans interrompre l'exécution du script. Cela n'a pas non plus d'impact sur vos métriques successPercent.

Vous ne devriez suivre les erreurs comme des erreurs d'exécution que si elles ne sont pas importantes pour indiquer le succès ou l'échec de votre script Canary.

L'exemple suivant illustre l'utilisation de addExecutionError. Vous surveillez la disponibilité de votre point de terminaison et vous prenez des captures d'écran après le chargement de la page. Étant donné que l'échec de la prise d'une capture d'écran ne détermine pas la disponibilité du point de terminaison, vous pouvez détecter toutes les erreurs rencontrées lors de la prise de captures d'écran et les ajouter en tant qu'erreurs d'exécution. Vos métriques de disponibilité indiqueront toujours que le point de terminaison est opérationnel, mais le statut de votre script Canary indiquera qu'il a échoué. L'exemple de bloc de code suivant détecte une telle erreur et l'ajoute en tant qu'erreur d'exécution.

try {await synthetics.executeStep(stepName, callbackFunc);} catch(ex) {synthetics.addExecutionError('Unable to take screenshot ', ex);}

getCanaryName();

Renvoie le nom du script Canary.

getCanaryArn();

Renvoie l'ARN du script canary.

getCanaryUserAgentString();

Renvoie l'agent utilisateur personnalisé du script canary.

getRuntimeVersion();

Cette fonction est disponible sur les versions d'exécution syn-nodejs-3.0 et ultérieures. Elle renvoie la version d'exécution Synthetics du script Canary. Par exemple, la valeur renvoyée peut être syn-nodejs-3.0.

getLogLevel();

Récupère le niveau de journalisation actuel pour la bibliothèque Synthetics. Les valeurs possibles sont les suivantes :

Exemple :

let logLevel = synthetics.getLogLevel();

setLogLevel();

Définit le niveau de journalisation pour la bibliothèque Synthetics. Les valeurs possibles sont les suivantes :

Exemple :

synthetics.setLogLevel(0);

ExecuteStep (StepName, [StepConfig] functionToExecute)

Exécute l'étape fournie, en l'enveloppant avec start/pass/fail logging and pass/fail des métriques de durée.

La fonction executeStep effectue également les opérations suivantes :

Exemple

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, [rappel], [StepConfig])

Exécute la requête HTTP fournie en tant qu'étape et publie les métriques SuccessPercent (réussite/échec) et Duration.

executeHttpSteputilise des fonctions natives HTTP ou HTTPS sous le capot, selon le protocole spécifié dans la demande.

Cette fonction ajoute également un résumé de l'exécution des étapes au rapport du script Canary. Le résumé inclut des détails sur chaque requête HTTP, tels que les suivants :

Parameters

StepName () String

Spécifie le nom de l'étape. Ce nom est également utilisé pour publier CloudWatch les statistiques de cette étape.

Options de demande () Object or String

La valeur de ce paramètre peut être une URL, une chaîne d'URL ou un objet. S'il s'agit d'un objet, il doit s'agir d'un ensemble d'options configurables pour effectuer une requête HTTP. Il prend en charge toutes les options dans http.request(options[, callback]) dans la documentation de Node.js.

En plus de ces options Node.js, requestOptions prend en charge le paramètre supplémentaire body. Vous pouvez utiliser le paramètre body pour transmettre des données en tant que corps de requête.

rappel () response

(Facultatif) Il s'agit d'une fonction utilisateur qui est appelée avec la réponse HTTP. La réponse est du type Class : http. IncomingMessage.

Configuration de l'étape () object

(Facultatif) Utilisez ce paramètre pour remplacer les configurations Synthetics globales par une configuration différente pour cette étape.

Exemples d'utilisation executeHttpStep

Les exemples suivants s'inspirent les uns des autres pour illustrer les différentes utilisations de cette option.

Ce premier exemple configure les paramètres de requête. Vous pouvez transmettre une URL en tant que requestOptions :

let requestOptions = 'https://www.amazon.com';

Vous pouvez également transmettre un ensemble d'options :

let requestOptions = {
        'hostname': 'myproductsEndpoint.com',
        'method': 'GET',
        'path': '/test/product/validProductName',
        'port': 443,
        'protocol': 'https:'
    };

L'exemple suivant crée une fonction de rappel qui accepte une réponse. Par défaut, si vous ne spécifiez pas de rappel, CloudWatch Synthetics vérifie que le statut est compris entre 200 et 299 inclus.

// 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'exemple suivant crée une configuration pour cette étape qui remplace la configuration globale de CloudWatch Synthetics. La configuration d'étape dans cet exemple autorise les en-têtes de requête, les en-têtes de réponse, le corps de requête (données de publication) et le corps de réponse dans votre rapport et restreint les valeurs d'en-tête 'X-Amz-Security-Token' et 'Authorization'. Par défaut, ces valeurs ne sont pas incluses dans le rapport pour des raisons de sécurité. Si vous choisissez de les inclure, les données sont stockées uniquement dans votre compartiment 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
};

Ce dernier exemple transmet votre demande à l'étape executeHttpStepet lui donne un nom.

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

Avec cet ensemble d'exemples, CloudWatch Synthetics ajoute les détails de chaque étape de votre rapport et produit des métriques pour chaque étape à l'aide de StepName.

Vous verrez les métriques successPercent et duration pour l'étape Verify GET products API. Vous pouvez contrôler les performances de vos API en contrôlant les métriques des étapes d'appel de vos API.

Pour obtenir un exemple de script complet qui utilise ces fonctions, consultez Script Canary d'API à plusieurs étapes.