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.
# Écriture d'un script Canary
Les sections suivantes expliquent comment écrire un script Canary et comment intégrer un script Canary à d'autres AWS services ainsi qu'à des dépendances et bibliothèques externes.
**Topics**
+ [Écriture d’un script Canary en utilisant l’exécution Java](Synthetics_WritingCanary_Java.md)
+ [Écriture d’un script Canary Node.js en utilisant l’exécution Playwright](Synthetics_WritingCanary_Nodejs_Playwright.md)
+ [Écriture d’un script Canary Node.js utilisant l’exécution Puppeteer](CloudWatch_Synthetics_Canaries_WritingCanary_Nodejs_Pup.md)
+ [Écriture d'un script Canary Python](CloudWatch_Synthetics_Canaries_WritingCanary_Python.md)
+ [Écrire une configuration JSON pour le plan Node.js Multi Checks](CloudWatch_Synthetics_WritingCanary_Multichecks.md)
# Écriture d’un script Canary en utilisant l’exécution Java
**Topics**
+ [Structure d’un projet Java pour un script Canary](#Synthetics_canary_Java_package)
+ [Empaquetage du projet pour un script Canary](#Synthetics_canary_Java_package_canary)
+ [Nom du gestionnaire](#Synthetics_canary_Java_handler)
+ [CloudWatch Configurations Synthetics](#Synthetics_canary_Java_config)
+ [CloudWatch Variables d'environnement Synthetics](#Synthetics_canary_Java_variables)
## Structure d’un projet Java pour un script Canary
Pour créer un script Canary en Java, vous devez écrire votre code, le compiler et déployer les artefacts compilés dans Synthetics. Vous pouvez initialiser un projet Java Lambda de différentes manières. Par exemple, vous pouvez utiliser une configuration de projet Java standard dans votre IDE préféré, comme IntelliJ IDEA ou Visual Studio Code. Vous pouvez également créer manuellement la structure de fichiers requise.
Un projet Synthetics Java contient la structure générale suivante :
```
/project-root
└ src
└ main
└ java
└ canarypackage // name of package
| └ ExampleCanary.java // Canary code file
| └ other_supporting_classes
- resources
└ synthetics.json // Synthetics configuration file
└ build.gradle OR pom.xml
```
Vous pouvez utiliser Maven ou Gradle pour créer votre projet et gérer les dépendances.
Dans la structure ci-dessus, la classe `ExampleCanary` est le point d’entrée ou le gestionnaire du script Canary.
**Exemple de classe Java pour un script Canary**
Dans cet exemple, un canari envoie une requête get à une URL stockée dans la variable d'environnement Lambda *TESTING\$1URL*. Ce script Canary n’utilise pas les méthodes fournies par l’exécution Synthetics.
```
package canarypackage;
import java.net.HttpURLConnection;
import java.net.URL;
// Handler value: canary.ExampleCanary::canaryCode
public class ExampleCanary {
public void canaryCode() throws Exception{
URL url = new URL(System.getenv("TESTING_URL"));
HttpURLConnection con=(HttpURLConnection)url.openConnection();
con.setRequestMethod("GET");
con.setConnectTimeout(5000);
con.setReadTimeout(5000);
int status=con.getResponseCode();
if(status!=200){
throw new Exception("Failed to load " + url + ", status code: " + status);
}
}
}
```
Il est fortement recommandé de modulariser vos scripts Canary à l’aide de la fonction de bibliothèque `executeStep` fournie par Synthetics. Le canari fait `get` appel à deux variables d' URL2 environnement URL1 et d' URLs approvisionnement distinctes.
**Note**
Pour utiliser la fonctionnalité `executeStep`, la méthode de gestion du script Canary doit prendre en compte un paramètre de type Synthetics, comme indiqué ci-dessous.
```
package canarypackage;
import com.amazonaws.synthetics.Synthetics;
import java.net.HttpURLConnection;
import java.net.URL;
// Handler value: canary.ExampleCanary::canaryCode
public class ExampleCanary {
public void canaryCode(Synthetics synthetics) throws Exception {
createStep("Step1", synthetics, System.getenv("URL1"));
createStep("Step2", synthetics, System.getenv("URL2"));
return;
}
private void createStep(String stepName, Synthetics synthetics, String url) throws Exception{
synthetics.executeStep(stepName,()->{
URL obj=new URL(url);
HttpURLConnection con=(HttpURLConnection)obj.openConnection();
con.setRequestMethod("GET");
con.setConnectTimeout(5000);
con.setReadTimeout(5000);
int status=con.getResponseCode();
if(status!=200){
throw new Exception("Failed to load" + url + "status code:" + status);
}
return null;
}).get();
}
}
```
## Empaquetage du projet pour un script Canary
Synthetics accepte le code d’un Canary Java au format *zip*. Le fichier zip contient les fichiers de classes du code du script Canary, les fichiers JAR des dépendances tierces et le fichier de configuration Synthetics.
Un fichier zip Synthetics Java présente la structure générale suivante.
```
example-canary
└ lib
| └ //third party dependency jars
└ java-canary.jar
└ synthetics.json
```
Pour créer ce fichier zip à partir de la structure de projet ci-dessus, vous pouvez utiliser Gradle (build.gradle) ou Maven (pom.xml). Voici un exemple.
[Pour plus d'informations sur les interdépendances ou les interfaces liées au temps de compilation pour la bibliothèque Synthetics, consultez le fichier README sous -java. aws-cloudwatch-synthetics-sdk](https://github.com/aws/aws-cloudwatch-synthetics-sdk-java/tree/main)
```
plugins {
id 'java'
}
repositories {
mavenCentral()
}
dependencies {
// Third party dependencies
// example: implementation 'software.amazon.awssdk:s3:2.31.9'
// Declares dependency on Synthetics interfaces for compiling only
// Refer https://github.com/aws/aws-cloudwatch-synthetics-sdk-java for building from source.
compileOnly 'software.amazon.synthetics:aws-cloudwatch-synthetics-sdk-java:1.0.0'}
test {
useJUnitPlatform()
}
// Build the zip to be used as Canary code.
task buildZip(type: Zip) {
archiveFileName.set("example-canary.zip")
destinationDirectory.set(file("$buildDir"))
from processResources
into('lib') {
from configurations.runtimeClasspath
from(tasks.named("jar"))
}
from "src/main/java/resources/synthetics.json"
doLast {
println "Artifact written to: ${archiveFile.get().asFile.absolutePath}"
}
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
tasks.named("build") {
dependsOn "buildZip"
}
```
## Nom du gestionnaire
Le nom du gestionnaire correspond au point d’entrée du script Canary. Pour l’exécution Java, le gestionnaire est au format suivant.
```
<>::<>
// for above code: canarypackage.ExampleCanary::canaryCode
```
## CloudWatch Configurations Synthetics
Vous pouvez configurer le comportement de l’exécution Java Synthetics à l’aide d’un fichier de configuration JSON facultatif nommé `synthetics.json`. Ce fichier doit être empaqueté dans le répertoire racine du package zip. Bien qu'un fichier de configuration soit facultatif, il CloudWatch utilise les valeurs par défaut si vous ne fournissez pas de fichier de configuration ou s'il manque une clé de configuration.
Les valeurs de configuration prises en charge et leurs valeurs par défaut sont les suivantes.
```
{
"step": {
"stepSuccessMetric": true,
"stepDurationMetric": true,
"continueOnStepFailure": false,
"stepsReport": true
},
"logging": {
"logRequest": false,
"logResponse": false
},
"httpMetrics": {
"metric_2xx": true,
"metric_4xx": true,
"metric_5xx": true,
"aggregated2xxMetric": true,
"aggregated4xxMetric": true,
"aggregated5xxMetric": true
},
"canaryMetrics": {
"failedCanaryMetric": true,
"aggregatedFailedCanaryMetric": true
}
}
```
**Étapes de configuration**
+ *continueOnStepEchec* : détermine si un script doit continuer même après l'échec d'une étape. La valeur par défaut est false.
+ *stepSuccessMetric* : détermine si la métrique ` SuccessPercent` d’une étape est émise. La `SuccessPercent` métrique d'une étape est de *100* pour Canary Run si l'étape réussit, et de *0* si l'étape échoue. Par défaut, la valeur est *true*.
+ *stepDurationMetric*— Détermine si la métrique de *durée* d'une étape est émise. La métrique *Durée* est émise sous forme de durée, en millisecondes, de l’exécution de l’étape. La valeur par défaut est *true*.
**Configurations d'enregistrement**
S'applique aux journaux générés par CloudWatch Synthetics. Contrôle la verbosité des journaux de requêtes et de réponses.
+ *logRequest* : indique s’il faut journaliser chaque requête dans les journaux du script Canary. La valeur par défaut est false.
+ *logResponse* : indique s’il faut journaliser chaque réponse dans les journaux du script Canary. La valeur par défaut est false.
**Configurations des métriques HTTP**
Configurations pour les métriques liées au nombre de requêtes réseau avec différents codes d'état HTTP, émises par CloudWatch Synthetics pour ce canari.
+ *metric\$12xx* — Spécifie s'il faut émettre la métrique *2xx* (avec la CanaryName dimension) pour ce canari. Par défaut, la valeur est *true*.
+ *metric\$14xx* — Spécifie s'il faut émettre la métrique *4xx* (avec la CanaryName dimension) pour ce canari. Par défaut, la valeur est *true*.
+ *metric\$15xx* — Spécifie s'il faut émettre la métrique *5xx* (avec la CanaryName dimension) pour ce canari. Par défaut, la valeur est *true*.
+ *Aggregated2xxMetric* — Spécifie s'il faut émettre la métrique *2xx* (sans la CanaryName dimension) pour ce canari. Par défaut, la valeur est *true*.
+ *Aggregated4xxMetric* — Spécifie s'il faut émettre la métrique *4xx* (sans la CanaryName dimension) pour ce canari. Par défaut, la valeur est *true*.
+ *Aggregated5xxMetric* — Spécifie s'il faut émettre la métrique *5xx* (sans la CanaryName dimension) pour ce canari. Par défaut, la valeur est *true*.
**Configurations des métriques du script Canary**
Configurations pour les autres métriques émises par CloudWatch Synthetics.
+ *failedCanaryMetric*Network Access Analyzer indique s'il faut émettre la métrique *Failed* (avec la CanaryName dimension) pour ce canari. Par défaut, la valeur est *true*.
+ *aggregatedFailedCanaryMétrique* — Spécifie s'il faut émettre la métrique d'*échec* (sans la CanaryName dimension) pour ce canari. Par défaut, la valeur est *true*.
## CloudWatch Variables d'environnement Synthetics
Vous pouvez configurer le niveau de journalisation et le format des journaux à l’aide de variables d’environnement.
**Format du journal**
Le moteur d'exécution CloudWatch Synthetics Java CloudWatch crée des journaux pour chaque exécution de Canary. Les journaux sont écrits au format JSON pour faciliter les requêtes. Vous pouvez éventuellement modifier le format du journal en *TEXT*.
+ *Nom de la variable d’environnement* : CW\$1SYNTHETICS\$1LOG\$1FORMAT
+ *Valeurs prises en charge* : JSON, TEXT
+ *Par défaut* : JSON
**Niveaux de journalisation**
+ *Nom de la variable d’environnement* : CW\$1SYNTHETICS\$1LOG\$1LEVEL
+ *Valeurs prises en charge* : TRACE, DEBUG, INFO, WARN, ERROR, FATAL
+ *Valeur par défaut* : INFO
Outre les variables d’environnement ci-dessus, une variable d’environnement par défaut est ajoutée à l’exécution Java. Ajoutez la variable d’environnement `AWS_LAMBDA-EXEC_WRAPPER` à votre fonction et définissez sa valeur sur `/opt/synthetics-otel-instrument`. Cette variable modifie le comportement de démarrage de la fonction pour la télémétrie. Si cette variable existe déjà, assurez-vous qu’elle est configurée avec la valeur requise.
# Écriture d’un script Canary Node.js en utilisant l’exécution Playwright
**Topics**
+ [Empaquetage de vos fichiers Canary Node.js pour l’exécution Playwright](#Synthetics_canary_Nodejs_Playwright_package)
+ [Modification d'un script de dramaturge existant pour l'utiliser comme canari CloudWatch Synthetics](#CloudWatch_Synthetics_canary_edit_Playwright_script)
+ [CloudWatch Configurations Synthetics](#Synthetics_canary_configure_Playwright_script)
## Empaquetage de vos fichiers Canary Node.js pour l’exécution Playwright
Votre script Canary est constitué d’un fichier `.js` (syntaxe CommonJS) ou `.mjs` (syntaxe ES) contenant votre code de gestionnaire Synthetics,ainsi que de tout autre module ou package dont votre code dépend. Les scripts créés au format ES (ECMAScript) doivent utiliser .mjs comme extension ou inclure un fichier package.json avec le champ « type » : « module » défini. Contrairement à d’autres exécutions comme Node.js Puppeteer, il n’est pas nécessaire de respecter une structure de dossiers particulière pour enregistrer vos scripts. Vous pouvez empaqueter vos scripts directement. Utilisez votre utilitaire `zip` préféré pour créer un fichier `.zip` contenant votre fichier gestionnaire à la racine. Si votre script Canary dépend de packages supplémentaires qui ne sont pas inclus dans l’exécution Synthetics, vous pouvez les ajouter dans votre fichier `.zip`. Pour ce faire, vous pouvez installer les bibliothèques requises par votre fonction dans le répertoire `node_modules` à l’aide de la commande `npm install`. L’exemple suivant montre les commandes CLI permettant de créer un fichier `.zip` nommé `my_deployment_package.zip`, contenant le fichier `index.js` ou `index.mjs` (le gestionnaire Synthetics) ainsi que ses dépendances. Dans cet exemple, les dépendances sont installées à l’aide du gestionnaire de packages `npm`.
```
~/my_function
├── index.mjs
├── synthetics.json
├── myhelper-util.mjs
└── node_modules
├── mydependency
```
Créez un fichier `.zip` contenant le contenu de votre dossier de projet à la racine. Utilisez l’option `r` (récursive), comme dans l’exemple ci-dessous, pour que `zip` compresse également les sous-dossiers.
```
zip -r my_deployment_package.zip .
```
Ajoutez un fichier de configuration Synthetics pour configurer le comportement de Synthetics. CloudWatch Vous pouvez créer un fichier `synthetics.json` et l’enregistrer au même emplacement que votre point d’entrée ou fichier gestionnaire.
En option, vous pouvez également enregistrer votre fichier de point d’entrée dans une structure de dossiers de votre choix. Assurez-vous toutefois que le chemin du dossier est indiqué dans le nom de votre gestionnaire.
**Nom du gestionnaire**
Assurez-vous de définir le point d'entrée (gestionnaire) de votre script Canary de sorte que ` myCanaryFilename.functionName` corresponde au nom du fichier du point d'entrée de votre script. Vous pouvez également stocker le script Canary dans un dossier séparé, tel que ` myFolder/my_canary_filename.mjs`. Si vous le stockez dans un dossier séparé, spécifiez ce chemin dans le point d'entrée de votre script, tel que ` myFolder/my_canary_filename.functionName`.
## Modification d'un script de dramaturge existant pour l'utiliser comme canari CloudWatch Synthetics
Vous pouvez modifier un script existant pour Playwright et Node.js afin de l’utiliser comme script Canary. Pour plus d’informations sur Playwright, consultez la documentation de la [bibliothèque Playwright](https://playwright.dev/docs/api/class-playwright).
Vous pouvez utiliser le script Playwright suivant qui est enregistré dans le fichier ` exampleCanary.mjs`.
```
import { chromium } from 'playwright';
import { expect } from '@playwright/test';
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com', {timeout: 30000});
await page.screenshot({path: 'example-home.png'});
const title = await page.title();
expect(title).toEqual("Example Domain");
await browser.close();
```
Pour le convertir le script, procédez comme suit :
1. Créez et exportez une fonction `handler`. Le gestionnaire est la fonction de point d'entrée du script. Vous pouvez choisir n’importe quel nom pour la fonction de gestionnaire, mais celui utilisé dans votre script doit être identique à celui défini dans le gestionnaire Canary. Si le nom de votre script est `exampleCanary.mjs` et que le nom de la fonction de gestionnaire est `myhandler`, alors le gestionnaire Canary s’appelle `exampleCanary.myhandler`. Dans l’exemple suivant, le nom de fonction de gestionnaire est `handler`.
```
exports.handler = async () => {
// Your script here
};
```
1. Importez le `Synthetics Playwright module` en tant que dépendance.
```
import { synthetics } from '@aws/synthetics-playwright';
```
1. Lancez un navigateur à l’aide de la fonction `Launch` Synthetics.
```
const browser = await synthetics.launch();
```
1. Créez une nouvelle page Playwright à l’aide de la fonction Synthetics `newPage`.
```
const page = await synthetics.newPage();
```
Votre script est maintenant prêt à être exécuté en tant que script Canary Synthetics. Exemple de script mis à jour :
**Script mis à jour au ES6 format**
Le fichier de script est enregistré avec une extension `.mjs`.
```
import { synthetics } from '@aws/synthetics-playwright';
import { expect } from '@playwright/test';
export const handler = async (event, context) => {
try {
// Launch a browser
const browser = await synthetics.launch();
// Create a new page
const page = await synthetics.newPage(browser);
// Navigate to a website
await page.goto('https://www.example.com', {timeout: 30000});
// Take screenshot
await page.screenshot({ path: '/tmp/example.png' });
// Verify the page title
const title = await page.title();
expect(title).toEqual("Example Domain");
} finally {
// Ensure browser is closed
await synthetics.close();
}
};
```
**Script mis à jour au format CommonJS**
Le fichier de script est enregistré avec une extension `.js`.
```
const { synthetics } = require('@aws/synthetics-playwright');
const { expect } = require('@playwright/test');
exports.handler = async (event) => {
try {
const browser = await synthetics.launch();
const page = await synthetics.newPage(browser);
await page.goto('https://www.example.com', {timeout: 30000});
await page.screenshot({ path: '/tmp/example.png' });
const title = await page.title();
expect(title).toEqual("Example Domain");
} finally {
await synthetics.close();
}
};
```
## CloudWatch Configurations Synthetics
Vous pouvez configurer le comportement de l’exécution Playwright Synthetics à l’aide d’un fichier de configuration JSON facultatif nommé `synthetics.json`. Ce fichier doit être empaqueté au même emplacement que le fichier gestionnaire. Bien qu'un fichier de configuration soit facultatif, si vous ne fournissez pas de fichier de configuration ou si une clé de configuration est manquante, CloudWatch il utilise les valeurs par défaut.
**Empaquetage de votre fichier de configuration**
Les valeurs de configuration prises en charge et leurs valeurs par défaut sont les suivantes.
```
{
"step": {
"screenshotOnStepStart": false,
"screenshotOnStepSuccess": false,
"screenshotOnStepFailure": false,
"stepSuccessMetric": true,
"stepDurationMetric": true,
"continueOnStepFailure": true,
"stepsReport": true
},
"report": {
"includeRequestHeaders": true,
"includeResponseHeaders": true,
"includeUrlPassword": false,
"includeRequestBody": true,
"includeResponseBody": true,
"restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports
"restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these url parameters are redacted from logs and reports
},
"logging": {
"logRequest": false,
"logResponse": false,
"logResponseBody": false,
"logRequestBody": false,
"logRequestHeaders": false,
"logResponseHeaders": false
},
"httpMetrics": {
"metric_2xx": true,
"metric_4xx": true,
"metric_5xx": true,
"failedRequestsMetric": true,
"aggregatedFailedRequestsMetric": true,
"aggregated2xxMetric": true,
"aggregated4xxMetric": true,
"aggregated5xxMetric": true
},
"canaryMetrics": {
"failedCanaryMetric": true,
"aggregatedFailedCanaryMetric": true
},
"userAgent": "",
"har": true
}
```
**Étapes de configuration**
+ `screenshotOnStepStart` : détermine si Synthetics doit prendre une capture d’écran avant le début de l’étape. La valeur par défaut est `true`.
+ `screenshotOnStepSuccess` : détermine si Synthetics doit prendre une capture d’écran après la réussite d’une étape. La valeur par défaut est `true`.
+ `screenshotOnStepFailure` : détermine si Synthetics doit prendre une capture d’écran après l’échec d’une étape. La valeur par défaut est `true`.
+ `continueOnStepFailure` : détermine si un script doit continuer à s’exécuter même après l’échec d’une étape. La valeur par défaut est `false`.
+ `stepSuccessMetric` : détermine si la métrique ` SuccessPercent` d’une étape est émise. La métrique `SuccessPercent` d’une étape est `100` pour l’exécution du script Canary si l’étape réussit, et `0` si l’étape échoue. La valeur par défaut est `true`.
+ `stepDurationMetric` : détermine si la métrique `Duration` d’une étape est émise. La métrique `Duration` est émise sous forme de durée, en millisecondes, de l’exécution de l’étape. La valeur par défaut est `true`.
**Configurations des rapports**
Inclut tous les rapports générés par CloudWatch Synthetics, tels qu'un fichier HAR et un rapport sur les étapes de Synthetics. Les champs de masquage des données sensibles, `restrictedHeaders` et `restrictedUrlParameters`, s’appliquent également aux journaux générés par Synthetics.
+ `includeRequestHeaders` : indique s’il faut inclure les en-têtes de requête dans le rapport. La valeur par défaut est `false`.
+ `includeResponseHeaders` : s’il faut inclure les en-têtes de réponse dans le rapport. La valeur par défaut est `false`.
+ `includeUrlPassword` : indique s’il faut inclure un mot de passe présent dans l’URL. Par défaut, les mots de passe qui apparaissent dans URLs les journaux et les rapports sont supprimés afin d'empêcher la divulgation de données sensibles. La valeur par défaut est `false`.
+ `includeRequestBody` : indique s’il faut inclure le corps de la requête dans le rapport. La valeur par défaut est `false`.
+ `includeResponseBody` : indique s’il faut inclure le corps de la réponse dans le rapport. La valeur par défaut est `false`.
+ `restrictedHeaders` : une liste d’en-têtes à ignorer lorsque les en-têtes sont inclus. Cela s'applique à la fois aux en-têtes de demande et de réponse. Par exemple, vous pouvez masquer vos identifiants en définissant `includeRequestHeaders` sur « true » et `restrictedHeaders` sur `['Authorization']`.
+ `restrictedUrlParameters` : une liste de chemins d’URL ou de paramètres de requête à masquer. Cela s'applique à URLs ceux qui apparaissent dans les journaux, les rapports et les erreurs. Le paramètre est sensible à la casse. Vous pouvez utiliser un astérisque (`*`) pour masquer toutes les valeurs des chemins et paramètres d’URL. La valeur par défaut est un tableau vide.
+ `har` : indique s’il faut générer une archive HTTP (fichier HAR). La valeur par défaut est `true`.
L’exemple suivant illustre un fichier de configuration de rapports.
```
"includeRequestHeaders": true,
"includeResponseHeaders": true,
"includeUrlPassword": false,
"includeRequestBody": true,
"includeResponseBody": true,
"restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports
"restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these URL parameters are redacted from logs and reports
```
**Configurations d'enregistrement**
S'applique aux journaux générés par CloudWatch Synthetics. Contrôle la verbosité des journaux de requêtes et de réponses.
+ `logRequest` : indique s’il faut journaliser chaque requête dans les journaux du script Canary. Pour les scripts Canary d'interface utilisateur, cette option journalise chaque demande envoyée par le navigateur. La valeur par défaut est ` false`.
+ `logResponse` : indique s’il faut journaliser chaque réponse dans les journaux du script Canary. Pour les scripts Canary d'interface utilisateur, cette option journalise chaque réponse reçue par le navigateur. La valeur par défaut est ` false`.
+ `logRequestBody` : indique s’il faut journaliser le corps des requêtes en même temps que les requêtes dans les journaux du script Canary. Cette configuration s’applique uniquement si `logRequest` est défini sur « true ». La valeur par défaut est `false`.
+ `logResponseBody` : indique s’il faut journaliser le corps des réponses en même temps que les requêtes dans les journaux du script Canary. Cette configuration s’applique uniquement si `logResponse` est défini sur « true ». La valeur par défaut est `false`.
+ `logRequestHeaders` : indique s’il faut journaliser les en-têtes de requête avec les requêtes dans les journaux du script Canary. Cette configuration s’applique uniquement si ` logRequest` est défini sur « true ». La valeur par défaut est `false`.
+ `logResponseHeaders` : indique s’il faut journaliser les en-têtes de réponse avec les réponses dans les journaux du script Canary. Cette configuration s’applique uniquement si ` logResponse` est défini sur « true ». La valeur par défaut est `false`.
**Configurations des métriques HTTP**
Configurations pour les métriques liées au nombre de requêtes réseau avec différents codes d'état HTTP, émises par CloudWatch Synthetics pour ce canari.
+ `metric_2xx` : indique s’il faut émettre la métrique `2xx` (avec la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est ` true`.
+ `metric_4xx` : indique s’il faut émettre la métrique `4xx` (avec la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est ` true`.
+ `metric_5xx` : indique s’il faut émettre la métrique `5xx` (avec la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est ` true`.
+ `failedRequestsMetric` : indique s’il faut émettre la métrique ` failedRequests` (avec la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est `true`.
+ `aggregatedFailedRequestsMetric` : indique s’il faut émettre la métrique ` failedRequests` (sans la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est `true`.
+ `aggregated2xxMetric` : indique s’il faut émettre la métrique `2xx` (sans la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est `true`.
+ `aggregated4xxMetric` : indique s’il faut émettre la métrique `4xx` (sans la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est `true`.
+ `aggregated5xxMetric` : indique s’il faut émettre la métrique `5xx` (sans la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est `true`.
**Configurations des métriques du script Canary**
Configurations pour les autres métriques émises par CloudWatch Synthetics.
+ `failedCanaryMetric` : indique s’il faut émettre la métrique `Failed` (avec la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est ` true`.
+ `aggregatedFailedCanaryMetric` : indique s’il faut émettre la métrique ` Failed` (sans la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est `true`.
**Autres configurations**
+ `userAgent` : chaîne à ajouter à l’agent utilisateur. L'agent utilisateur est une chaîne incluse dans l'en-tête de la demande et identifie votre navigateur auprès des sites Web que vous visitez lorsque vous utilisez le navigateur sans en-tête. CloudWatch Synthetics ajoute automatiquement. `CloudWatchSynthetics/canary-arn to the user agent` La configuration spécifiée est ajoutée à l’agent utilisateur généré. Par défaut, la valeur ajoutée à l’agent est une chaîne vide (`""`).
### CloudWatch Variables d'environnement Synthetics
Configurez le niveau de journalisation et le format des journaux à l’aide de variables d’environnement.
**Format du journal**
Le runtime CloudWatch Synthetics Playwright CloudWatch crée des journaux pour chaque course de Canary. Les journaux sont écrits au format JSON pour faciliter les requêtes. Vous pouvez éventuellement modifier le format du journal en `TEXT`.
+ `Environment variable name` : CW\$1SYNTHETICS\$1LOG\$1FORMAT
+ `Supported values` : JSON, TEXT
+ `Default` : JSON
**Niveaux de journalisation**
Bien que l’activation du mode `Debug` augmente la quantité de détails enregistrés, cela peut s’avérer utile pour la résolution des problèmes.
+ `Environment variable name` : CW\$1SYNTHETICS\$1LOG\$1LEVEL
+ `Supported values` : TRACE, DEBUG, INFO, WARN, ERROR, FATAL
+ `Default` : INFO
# Écriture d’un script Canary Node.js utilisant l’exécution Puppeteer
**Topics**
+ [Création d'un CloudWatch canari Synthetics à partir de zéro](#CloudWatch_Synthetics_Canaries_write_from_scratch)
+ [Empaquetage de vos fichiers Canary Node.js](#CloudWatch_Synthetics_Canaries_package)
+ [Modification d'un script Puppeteer existant pour l'utiliser en tant que script Canary Synthetics](#CloudWatch_Synthetics_Canaries_modify_puppeteer_script)
+ [Variables d’environnement](#CloudWatch_Synthetics_Environment_Variables)
+ [Intégrer votre Canary à d'autres AWS services](#CloudWatch_Synthetics_Canaries_AWS_integrate)
+ [Utilisation forcée d'une adresse IP statique par le script Canary](#CloudWatch_Synthetics_Canaries_staticIP)
## Création d'un CloudWatch canari Synthetics à partir de zéro
Voici un exemple minimal de script Canary Synthetics. Ce script est transmis comme une exécution réussie et renvoie une chaîne. Pour voir à quoi ressemble un script Canary qui a échoué, remplacez `let fail = false;` par `let fail = true;`.
Vous devez définir une fonction de point d'entrée pour le script Canary. Pour observer comment les fichiers sont téléchargés dans l’emplacement Amazon S3 défini comme `ArtifactS3Location` du script Canary, créez ces fichiers dans le dossier `/tmp`. Tous les artefacts du script Canary doivent être enregistrés dans `/tmp`, car il s’agit du seul répertoire accessible en écriture. Assurez-vous que le chemin des captures d’écran est défini sur `/tmp` pour toutes les captures ou autres fichiers créés par le script. Synthetics charge automatiquement les fichiers ` /tmp` dans un compartiment S3.
```
/tmp/
```
Une fois le script exécuté, les métriques d' pass/fail état et de durée sont publiées dans un compartiment S3 CloudWatch et les fichiers situés en dessous `/tmp` sont chargés dans un compartiment S3.
```
const basicCustomEntryPoint = async function () {
// Insert your code here
// Perform multi-step pass/fail check
// Log decisions made and results to /tmp
// Be sure to wait for all your code paths to complete
// before returning control back to Synthetics.
// In that way, your canary will not finish and report success
// before your code has finished executing
// Throw to fail, return to succeed
let fail = false;
if (fail) {
throw "Failed basicCanary check.";
}
return "Successfully completed basicCanary checks.";
};
exports.handler = async () => {
return await basicCustomEntryPoint();
};
```
Ensuite, nous allons développer le script pour utiliser la journalisation Synthetics et passer un appel à l'aide du SDK. AWS À des fins de démonstration, ce script créera un client Amazon DynamoDB et réalisera un appel à l'API ListTables DynamoDB. Il enregistre la réponse à la demande et les journaux réussissent ou échouent selon le succès de la demande.
```
const log = require('@aws/synthetics-logger');
const AWS = require('aws-sdk');
// Require any dependencies that your script needs
// Bundle additional files and dependencies into a .zip file with folder structure
// nodejs/node_modules/additional files and folders
const basicCustomEntryPoint = async function () {
log.info("Starting DynamoDB:listTables canary.");
let dynamodb = new AWS.DynamoDB();
var params = {};
let request = await dynamodb.listTables(params);
try {
let response = await request.promise();
log.info("listTables response: " + JSON.stringify(response));
} catch (err) {
log.error("listTables error: " + JSON.stringify(err), err.stack);
throw err;
}
return "Successfully completed DynamoDB:listTables canary.";
};
exports.handler = async () => {
return await basicCustomEntryPoint();
};
```
## Empaquetage de vos fichiers Canary Node.js
**Pour syn-nodejs-puppeteer -11,0 et plus**
L'ancienne structure d'empaquetage (pour syn-nodejs-puppeteer -10.0 et versions inférieures) est toujours prise en charge dans les nouvelles versions.
Créez un script en utilisant l’une des options suivantes :
+ fichier .js (syntaxe CommonJS)
+ fichier .mjs (syntaxe des modules ES)
Pour les modules ES, utilisez l’une des options suivantes :
+ fichier .js (syntaxe CommonJS)
+ fichier .mjs (syntaxe des modules ES)
La structure du package est définie ci-dessous :
+ Fichier gestionnaire à la racine (index.js/index.mjs)
+ Fichier de configuration facultatif (synthetics.json)
+ Dépendances supplémentaires dans node\$1modules (si nécessaire)
Exemple de structure d’empaquetage :
```
my_function/
├── index.mjs
├── synthetics.json
├── helper-utils.mjs
└── node_modules/
└── dependencies
```
Pour empaqueter, procédez comme suit :
1. Installez les dépendances (le cas échéant).
```
npm install
```
1. Créer un package .zip.
```
zip -r my_deployment_package.zip
```
**Pour syn-nodejs-puppeteer -11,0 et moins**
La structure suivante est requise lorsque vous utilisez Amazon S3 :
```
nodejs/
└── node_modules/
└── myCanaryFilename.js
```
**Pour ajouter un support de sous-dossier facultatif dans syn-nodejs-puppeteer -3.4\$1 :**
```
nodejs/
└── node_modules/
└── myFolder/
└── myCanaryFilename.js
```
**Note**
Le chemin du gestionnaire indiqué dans la configuration doit correspondre à l’emplacement réel du fichier.
**Nom du gestionnaire**
Assurez-vous de définir le point d'entrée (gestionnaire) de votre script Canary de sorte que ` myCanaryFilename.functionName` corresponde au nom du fichier du point d'entrée de votre script. Si vous utilisez une exécution antérieure à `syn-nodejs-puppeteer-3.4`, alors `functionName` doit être `handler`. Si vous utilisez ` syn-nodejs-puppeteer-3.4` ou une version ultérieure, vous pouvez choisir n'importe quel nom de fonction comme gestionnaire. Si vous utilisez `syn-nodejs-puppeteer-3.4` ou une version ultérieure, vous pouvez également stocker le script canary dans un dossier séparé tel que ` nodejs/node_modules/myFolder/my_canary_filename`. Si vous le stockez dans un dossier séparé, spécifiez ce chemin dans le point d'entrée de votre script, tel que ` myFolder/my_canary_filename.functionName`.
## Modification d'un script Puppeteer existant pour l'utiliser en tant que script Canary Synthetics
Cette section explique comment prendre des scripts Puppeteer, pour ensuite les modifier afin qu'ils s'exécutent en tant que scripts Canary Synthetics. Pour de plus amples informations sur Puppeteer, consultez [Puppeteer API v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md).
Nous allons commencer avec cet exemple de script Puppeteer :
```
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({path: 'example.png'});
await browser.close();
})();
```
Les étapes de conversion sont les suivantes :
+ Créez et exportez une fonction `handler`. Le gestionnaire est la fonction de point d'entrée du script. Si vous utilisez une exécution antérieure à ` syn-nodejs-puppeteer-3.4`, la fonction du gestionnaire doit être nommée `handler`. Si vous utilisez `syn-nodejs-puppeteer-3.4` ou une version ultérieure, la fonction peut porter n'importe quel nom, mais il doit être identique à celui utilisé dans le script. De plus, si vous utilisez `syn-nodejs-puppeteer-3.4` ou une version ultérieure, vous pouvez stocker vos scripts dans n'importe quel dossier et spécifier ce dossier dans le nom du gestionnaire.
```
const basicPuppeteerExample = async function () {};
exports.handler = async () => {
return await basicPuppeteerExample();
};
```
+ Utilisez la dépendance `Synthetics`.
```
var synthetics = require('@aws/synthetics-puppeteer');
```
+ Utilisez la fonction `Synthetics.getPage` pour obtenir un objet `Page` Puppeteer.
```
const page = await synthetics.getPage();
```
L'objet de page renvoyé par la fonction Synthetics.getPage contient le **page.on et les événements sont instrumentés pour** `request` la journalisation. `response` ` requestfailed` Synthetics configure également la génération de fichiers HAR pour les demandes et les réponses sur la page, et ajoute l'ARN du script Canary aux en-têtes des demandes sortantes de l'agent utilisateur sur la page.
Le script est maintenant prêt à être exécuté en tant que script Canary Synthetics. Voici le script mis à jour :
```
var synthetics = require('@aws/synthetics-puppeteer'); // Synthetics dependency
const basicPuppeteerExample = async function () {
const page = await synthetics.getPage(); // Get instrumented page from Synthetics
await page.goto('https://example.com');
await page.screenshot({path: '/tmp/example.png'}); // Write screenshot to /tmp folder
};
exports.handler = async () => { // Exported handler function
return await basicPuppeteerExample();
};
```
## Variables d’environnement
Vous pouvez utiliser des variables d'environnement lorsque vous créez des scripts Canary. Cela vous permet d'écrire un seul script Canary, puis d'utiliser ce script avec des valeurs différentes pour créer rapidement plusieurs scripts Canary ayant une tâche similaire.
Par exemple, supposons que votre organisation dispose de points de terminaison tels que `prod`, ` dev` et `pre-release` pour les différentes étapes de votre développement logiciel et que vous devez créer des scripts Canary pour tester chacun de ces points de terminaison. Vous pouvez écrire un seul script Canary qui teste votre logiciel, puis spécifier différentes valeurs pour la variable d'environnement de point de terminaison lorsque vous créez chacun des trois scripts Canary. Ensuite, lorsque vous créez un script Canary, vous spécifiez le script et les valeurs à utiliser pour les variables d'environnement.
Les noms des variables d'environnement peuvent contenir des lettres, des chiffres et le caractère de soulignement. Ils doivent commencer par une lettre et comporter au moins deux caractères. La taille totale de vos variables d'environnement ne peut pas dépasser 4 Ko. Vous ne pouvez pas spécifier de variables d'environnement réservées Lambda comme noms pour vos variables d'environnement. Pour plus d'informations sur les variables d'environnement réservées, consultez [ Variables d'environnement d'exécution](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime).
**Important**
Les clés et valeurs des variables d'environnement sont chiffrées au repos à l'aide de AWS KMS clés AWS détenues. Cependant, les variables d’environnement ne sont pas chiffrées côté client. Ne stockez pas d'informations sensibles dans celles-ci.
L'exemple de script suivant utilise deux variables d'environnement. Ce script est destiné à un script Canary qui vérifie si une page web est disponible. Il utilise des variables d'environnement pour paramétrer à la fois l'URL qu'il vérifie et le niveau de journal Synthetics qu'il utilise CloudWatch .
La fonction suivante définit `LogLevel` sur la valeur de la variable d'environnement ` LOG_LEVEL`.
```
synthetics.setLogLevel(process.env.LOG_LEVEL);
```
Cette fonction définit `URL` sur la valeur de la variable d'environnement `URL`.
```
const URL = process.env.URL;
```
C'est le script complet. Lorsque vous créez un script Canary à l'aide de ce script, vous spécifiez les valeurs pour les variables d'environnement `LOG_LEVEL` et `URL`.
```
var synthetics = require('@aws/synthetics-puppeteer');
const log = require('@aws/synthetics-logger');
const pageLoadEnvironmentVariable = async function () {
// Setting the log level (0-3)
synthetics.setLogLevel(process.env.LOG_LEVEL);
// INSERT URL here
const URL = process.env.URL;
let page = await synthetics.getPage();
//You can customize the wait condition here. For instance,
//using 'networkidle2' may be less restrictive.
const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000});
if (!response) {
throw "Failed to load page!";
}
//Wait for page to render.
//Increase or decrease wait time based on endpoint being monitored.
await page.waitFor(15000);
await synthetics.takeScreenshot('loaded', 'loaded');
let pageTitle = await page.title();
log.info('Page title: ' + pageTitle);
log.debug('Environment variable:' + process.env.URL);
//If the response status code is not a 2xx success code
if (response.status() < 200 || response.status() > 299) {
throw "Failed to load page!";
}
};
exports.handler = async () => {
return await pageLoadEnvironmentVariable();
};
```
### Transmission de variables d'environnement à votre script
Pour transmettre des variables d'environnement à votre script lorsque vous créez un script Canary dans la console, spécifiez les clés et les valeurs des variables d'environnement dans la section **Environment variables (Variables d'environnement)** de la console. Pour de plus amples informations, veuillez consulter [Création d'un Canary](CloudWatch_Synthetics_Canaries_Create.md).
Pour transmettre des variables d'environnement via l'API AWS CLI, utilisez le ` EnvironmentVariables` paramètre de la `RunConfig` section. Voici un exemple de AWS CLI commande qui crée un canari qui utilise deux variables d'environnement avec les clés de `Environment` et`Region`.
```
aws synthetics create-canary --cli-input-json '{
"Name":"nameofCanary",
"ExecutionRoleArn":"roleArn",
"ArtifactS3Location":"s3://amzn-s3-demo-bucket-123456789012-us-west-2",
"Schedule":{
"Expression":"rate(0 minute)",
"DurationInSeconds":604800
},
"Code":{
"S3Bucket": "canarycreation",
"S3Key": "cwsyn-mycanaryheartbeat-12345678-d1bd-1234-abcd-123456789012-12345678-6a1f-47c3-b291-123456789012.zip",
"Handler":"pageLoadBlueprint.handler"
},
"RunConfig": {
"TimeoutInSeconds":60,
"EnvironmentVariables": {
"Environment":"Production",
"Region": "us-west-1"
}
},
"SuccessRetentionPeriodInDays":13,
"FailureRetentionPeriodInDays":13,
"RuntimeVersion":"syn-nodejs-2.0"
}'
```
## Intégrer votre Canary à d'autres AWS services
Tous les canaris peuvent utiliser la bibliothèque du AWS SDK. Vous pouvez utiliser cette bibliothèque lorsque vous écrivez votre canari pour intégrer le canari à d'autres AWS services.
Pour ce faire, vous devez ajouter le code suivant à votre script canary. Pour ces exemples, AWS Secrets Manager il est utilisé comme service auquel le canari s'intègre.
+ Importez le AWS SDK.
```
const AWS = require('aws-sdk');
```
+ Créez un client pour le AWS service auquel vous souhaitez procéder à l'intégration.
```
const secretsManager = new AWS.SecretsManager();
```
+ Utilisez le client pour effectuer des appels d'API vers ce service.
```
var params = {
SecretId: secretName
};
return await secretsManager.getSecretValue(params).promise();
```
L'extrait de code de script Canary suivant illustre une intégration à Secrets Manager de manière plus détaillée.
```
var synthetics = require('@aws/synthetics-puppeteer');
const log = require('@aws/synthetics-logger');
const AWS = require('aws-sdk');
const secretsManager = new AWS.SecretsManager();
const getSecrets = async (secretName) => {
var params = {
SecretId: secretName
};
return await secretsManager.getSecretValue(params).promise();
}
const secretsExample = async function () {
let URL = "";
let page = await synthetics.getPage();
log.info(`Navigating to URL: ${URL}`);
const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000});
// Fetch secrets
let secrets = await getSecrets("secretname")
/**
* Use secrets to login.
*
* Assuming secrets are stored in a JSON format like:
* {
* "username": "",
* "password": ""
* }
**/
let secretsObj = JSON.parse(secrets.SecretString);
await synthetics.executeStep('login', async function () {
await page.type(">USERNAME-INPUT-SELECTOR<", secretsObj.username);
await page.type(">PASSWORD-INPUT-SELECTOR<", secretsObj.password);
await Promise.all([
page.waitForNavigation({ timeout: 30000 }),
await page.click(">SUBMIT-BUTTON-SELECTOR<")
]);
});
// Verify login was successful
await synthetics.executeStep('verify', async function () {
await page.waitForXPath(">SELECTOR<", { timeout: 30000 });
});
};
exports.handler = async () => {
return await secretsExample();
};
```
## Utilisation forcée d'une adresse IP statique par le script Canary
Vous pouvez configurer un script Canary afin qu'il utilise une adresse IP statique.
**Pour forcer un script Canary à utiliser une adresse IP statique**
1. Créez un nouveau VPC. Pour plus d'informations, consultez [Utilisation de DNS avec votre VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html).
1. Créez une nouvelle passerelle Internet. Pour plus d'informations, consultez [Ajout d'une passerelle Internet à votre VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#working-with-igw).
1. Créez un sous-réseau public dans votre nouveau VPC.
1. Ajoutez une nouvelle table de routage au VPC.
1. Ajoutez un routage dans la nouvelle table de routage, qui va de `0.0.0.0/0` à la passerelle Internet.
1. Associez la nouvelle table de routage au sous-réseau public.
1. Créez une adresse IP Elastic. Pour plus d'informations, consultez [Adresses IP élastiques](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html).
1. Créez une nouvelle passerelle NAT et affectez-la au sous-réseau public et à l'adresse IP Elastic.
1. Créez un sous-réseau privé dans le VPC.
1. Ajoutez un routage à la table de routage par défaut du VPC, qui va de `0.0.0.0/0` à la passerelle NAT.
1. Créez votre script Canary.
# Écriture d'un script Canary Python
Ce script est transmis comme une exécution réussie et renvoie une chaîne. Pour voir à quoi ressemble un script Canary en échec, remplacez fail = False par fail = True
```
def basic_custom_script():
# Insert your code here
# Perform multi-step pass/fail check
# Log decisions made and results to /tmp
# Be sure to wait for all your code paths to complete
# before returning control back to Synthetics.
# In that way, your canary will not finish and report success
# before your code has finished executing
fail = False
if fail:
raise Exception("Failed basicCanary check.")
return "Successfully completed basicCanary checks."
def handler(event, context):
return basic_custom_script()
```
## Empaquetage de vos fichiers Canary Python
Si vous avez plusieurs fichiers .py ou une dépendance à votre script, vous pouvez les regrouper dans un seul fichier ZIP. Si vous utilisez l'exécution `syn-python-selenium-1.1`, le fichier ZIP doit contenir votre fichier .py canary principal dans un dossier `python`, tel que `python/my_canary_filename.py`. Si vous utilisez ` syn-python-selenium-1.1` ou une version ultérieure, vous pouvez éventuellement utiliser un autre dossier, tel que `python/myFolder/my_canary_filename.py`.
Ce fichier ZIP doit contenir tous les dossiers et fichiers nécessaires, mais les autres fichiers n'ont pas besoin de se trouver dans le dossier `python`.
Assurez-vous de définir le point d'entrée de votre script Canary de sorte que ` my_canary_filename.functionName` corresponde au nom du fichier et de la fonction du point d'entrée de votre script. Si vous utilisez une exécution `syn-python-selenium-1.0`, alors `functionName` doit être `handler`. Si vous utilisez ` syn-python-selenium-1.1` ou une version ultérieure, cette restriction du nom du gestionnaire ne s'applique pas et vous pouvez également stocker le script Canary dans un dossier séparé tel que ` python/myFolder/my_canary_filename.py`. Si vous le stockez dans un dossier séparé, spécifiez ce chemin dans le point d'entrée de votre script, tel que ` myFolder/my_canary_filename.functionName`.
## Modification d'un script Selenium existant pour l'utiliser en tant que script Canary Synthetics
Vous pouvez rapidement modifier un script existant pour Python et Selenium pour l'utiliser comme script Canary. Pour plus d'informations sur Selenium, consultez le [site www.selenium.dev/](https://www.selenium.dev/).
Pour cet exemple, nous commencerons par le script Selenium suivant :
```
from selenium import webdriver
def basic_selenium_script():
browser = webdriver.Chrome()
browser.get('https://example.com')
browser.save_screenshot('loaded.png')
basic_selenium_script()
```
Les étapes de conversion sont les suivantes.
**Pour convertir un script Selenium à utiliser comme script Canary**
1. Modifier l'instruction `import` pour utiliser Selenium à partir du module ` aws_synthetics` :
```
from aws_synthetics.selenium import synthetics_webdriver as webdriver
```
Le module Selenium de `aws_synthetics` garantit que le Canary peut émettre des métriques et des journaux, générer un fichier HAR et fonctionner avec d'autres fonctionnalités de CloudWatch Synthetics.
1. Créez une fonction de gestionnaire et appelez votre méthode Selenium. Le gestionnaire est la fonction de point d'entrée du script.
Si vous utilisez `syn-python-selenium-1.0`, la fonction du gestionnaire doit être nommée `handler`. Si vous utilisez `syn-python-selenium-1.1` ou une version ultérieure, la fonction peut porter n'importe quel nom, mais il doit être identique à celui utilisé dans le script. De plus, si vous utilisez `syn-python-selenium-1.1` ou une version ultérieure, vous pouvez stocker vos scripts dans n'importe quel dossier et spécifier ce dossier dans le nom du gestionnaire.
```
def handler(event, context):
basic_selenium_script()
```
Le script est maintenant mis à jour pour devenir un canari CloudWatch Synthetics. Voici le script mis à jour :
`webdriver`Il s'agit d'une instance de la classe [ SyntheticsWebDriver](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library_Python.html#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver)et le navigateur renvoyé par `webdriver.Chrome()` est une instance de [ SyntheticsBrowser](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library_Python.html#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser).
```
from aws_synthetics.selenium import synthetics_webdriver as webdriver
def basic_selenium_script():
browser = webdriver.Chrome()
browser.get('https://example.com')
browser.save_screenshot('loaded.png')
def handler(event, context):
basic_selenium_script()
```
## Modification d’un script Synthetics Puppeteer existant pour authentifier des certificats non standard
Un cas d’utilisation fréquent des scripts Canary Synthetics consiste à surveiller vos propres points de terminaison. Si vous souhaitez surveiller un point de terminaison non encore accessible au trafic externe, il se peut que vous n’ayez pas encore de certificat valide signé par une autorité de certification tierce reconnue.
Les deux solutions possibles pour ce scénario sont les suivantes :
+ Pour authentifier un certificat client, consultez [Comment valider l'authentification à l'aide d'Amazon CloudWatch Synthetics — Partie 2](https://aws.amazon.com/blogs/mt/how-to-validate-authentication-using-amazon-cloudwatch-synthetics-part-2/).
+ Pour authentifier un certificat auto-signé, consultez [Comment valider l'authentification à l'aide de certificats auto-signés dans](https://aws.amazon.com/blogs/mt/how-to-validate-authentication-with-self-signed-certificates-in-amazon-cloudwatch-synthetics/) Amazon Synthetics CloudWatch
Vous n'êtes pas limité à ces deux options lorsque vous utilisez les canaris CloudWatch Synthetics. Vous pouvez étendre ces fonctionnalités et ajouter votre propre logique métier en modifiant le code du script Canary.
**Note**
Les scripts Canary exécutés avec l’exécution Python disposent nativement du paramètre ` --ignore-certificate-errors` activé, ce qui leur permet d’accéder sans problème à des sites utilisant des certificats non standard.
# Écrire une configuration JSON pour le plan Node.js Multi Checks
Le plan multi-contrôles Node.js vous permet de créer des canaris qui effectuent plusieurs contrôles de validation au cours d'une seule exécution Canary. Ce plan est utile lorsque vous souhaitez tester plusieurs points de terminaison, valider différents aspects de votre application ou effectuer une série de vérifications connexes en séquence.
**Topics**
+ [Structure de configuration racine](#root-configuration-structure)
+ [Paramètres globaux](#global-settings)
+ [Gestion des variables et des données](#variables-data-management)
+ [Définitions des étapes](#step-definitions)
+ [Types de chèques](#check-types)
+ [Méthodes d’authentification](#authentication-methods)
+ [Assertions et validation](#assertions-validation)
+ [Extraction de données](#data-extraction)
## Structure de configuration racine
La configuration racine définit la structure globale de votre plan d'API avancé Canary.
**Propriétés du schéma**
| Propriété | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| globalSettings | Objet | Non | Configurations par défaut appliquées à toutes les étapes |
| variables | Objet | Non | Valeurs réutilisables d'une étape à l'autre (10 au maximum) |
| steps | Objet | Oui | Recueil des étapes de surveillance (1 à 10 étapes) |
**Exemple**
```
{
"globalSettings": {
"stepTimeout": 30000,
"userAgent": "CloudWatch-Synthetics-Advanced/1.0"
},
"variables": {
"baseUrl": "https://api.example.com",
"apiVersion": "v1"
},
"steps": {
"1": {
"stepName": "healthCheck",
"checkerType": "HTTP",
"url": "${baseUrl}/health",
"httpMethod": "GET"
}
}
}
```
**Règles de validation**
+ Doit contenir au moins une étape
+ Maximum de 10 étapes autorisées
+ Aucune propriété supplémentaire n'est autorisée au-delà de `globalSettings`` variables`, et `steps`
## Paramètres globaux
Les paramètres globaux fournissent des configurations par défaut qui s'appliquent à toutes les étapes sauf si elles sont remplacées au niveau de l'étape.
**Propriétés**
**Propriétés des paramètres globaux**
| Propriété | Type | Par défaut | Range | Description |
| --- | --- | --- | --- | --- |
| stepTimeout | integer | 30 000 | 5000-300000 | Délai d'expiration par défaut pour toutes les étapes (millisecondes) |
**Exemple**
```
{
"globalSettings": {
"stepTimeout": 60000,
}
}
```
## Gestion des variables et des données
Les variables vous permettent de définir des valeurs réutilisables qui peuvent être référencées dans l'ensemble de votre configuration à l'aide de `${variableName}` la syntaxe.
**Propriétés variables**
| Propriété | Type | Description |
| --- | --- | --- |
| Noms de variables | chaîne | Doit correspondre au modèle ^[a-zA-Z][a-zA-Z0-9\$1]\$1\$1 |
| Valeurs variables | chaîne | N'importe quelle valeur de chaîne |
**Limites**
+ Maximum de 10 variables par configuration
+ Les noms de variables doivent commencer par une lettre
+ Les noms de variables ne peuvent contenir que des lettres, des chiffres et des traits de soulignement
+ Longueur maximale non spécifiée dans le schéma
**Exemple**
```
{
"variables": {
"baseUrl": "https://api.example.com",
"apiKey": "${AWS_SECRET:my-api-key}",
"timeout": "30000",
"userEmail": "test@example.com"
}
}
```
**Utilisation de la configuration**
```
{
"steps": {
"1": {
"url": "${baseUrl}/users",
"timeout": "${timeout}",
"headers": {
"Authorization": "Bearer ${apiKey}"
}
}
}
}
```
## Définitions des étapes
Les étapes définissent les opérations de surveillance individuelles. Chaque étape est numérotée de 1 à 10 et contient un type de contrôle spécifique.
*Propriétés communes des étapes*
| Propriété | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| stepName | chaîne | Oui | Identifiant unique pour l'étape |
| checkerType | chaîne | Oui | Type de contrôle : HTTPDNS,SSL, TCP |
| extractors | array | Non | Configuration de l'extraction des données |
*Validation du nom des étapes*
+ Motif - ^ [A-zA-z] [A-zA-Z0-9\$1-] \$1\$1
+ Longueur maximale : 64 caractères
+ Doit commencer par une lettre
*Numérotation des étapes*
+ Les étapes sont numérotées sous forme de chaînes de caractères : « 1 », « 2 »,..., « 10 »
+ Motif : ^ ([1-9] \$110) \$1
+ 1 étape minimum requise
+ Maximum de 10 étapes autorisées
*Exemple*
```
{
"steps": {
"1": {
"stepName": "loginAPI",
"checkerType": "HTTP",
"url": "https://api.example.com/login",
"httpMethod": "POST"
},
"2": {
"stepName": "dnsCheck",
"checkerType": "DNS",
"domain": "example.com"
}
}
}
```
## Types de chèques
### Contrôles HTTP
Surveillez les points de terminaison Web APIs grâce à une validation complète des demandes et des réponses.
**Propriétés requises**
| Propriété | Type | Description |
| --- | --- | --- |
| url | chaîne | URL cible (le format d'URI doit être valide) |
| httpMethod | chaîne | Méthode HTTP :GET,POST,PUT, PATCH,DELETE,HEAD, OPTIONS |
**Propriétés facultatives**
| Propriété | Type | Par défaut | Range | Description |
| --- | --- | --- | --- | --- |
| timeout | integer | 30 000 | 5000-300000 | Délai d'expiration de la demande (millisecondes) |
| waitTime | entier | 0 | 0 à 60 | Délai avant la demande (secondes) |
| headers | objet | - | - | En-têtes HTTP personnalisés |
| body | chaîne | - | - | Organisme demandeur pour les POST/PUT opérations |
| authentication | objet | - | - | Configuration de l’authentification |
| assertions | array | - | - | Règles de validation des réponses |
**Exemple**
```
{
"stepName": "createUser",
"checkerType": "HTTP",
"url": "https://api.example.com/users",
"httpMethod": "POST",
"timeout": 15000,
"headers": {
"Content-Type": "application/json",
"X-API-Version": "v1"
},
"body": "{\"name\":\"John Doe\",\"email\":\"john@example.com\"}",
"authentication": {
"type": "API_KEY",
"apiKey": "${AWS_SECRET:api-credentials}",
"headerName": "X-API-Key"
},
"assertions": [
{
"type": "STATUS_CODE",
"operator": "EQUALS",
"value": 201
}
]
}
```
### Contrôles DNS
Validez la résolution DNS et enregistrez les informations.
**Propriétés requises**
| Propriété | Type | Description |
| --- | --- | --- |
| domain | chaîne | Nom de domaine à interroger (format de nom d'hôte) |
**Propriétés facultatives**
| Propriété | Type | Par défaut | Description |
| --- | --- | --- | --- |
| recordType | chaîne | « UN » | Type d'enregistrement DNS : ACNAME,MX, TXT, NS |
| nameserver | chaîne | - | Serveur DNS spécifique à interroger |
| timeout | entier | 30 000 | Délai d'expiration de la requête (5000-300000 ms) |
| port | entier | 53 | Port du serveur DNS (1-65535) |
| protocol | chaîne | « UDP » | Protocole : UDP ou TCP |
| assertions | array | - | Règles de validation des réponses DNS |
**Exemple**
```
{
"stepName": "dnsResolution",
"checkerType": "DNS",
"domain": "example.com",
"recordType": "A",
"nameserver": "8.8.8.8",
"timeout": 10000,
"assertions": [
{
"type": "RECORD_VALUE",
"operator": "CONTAINS",
"value": "192.168"
}
]
}
```
### Contrôles SSL
Surveillez l'état et la configuration des certificats SSL.
**Propriétés requises**
| Propriété | Type | Description |
| --- | --- | --- |
| hostname | chaîne | Nom d'hôte cible (format du nom d'hôte) |
**Propriétés facultatives**
| Propriété | Type | Par défaut | Description |
| --- | --- | --- | --- |
| port | integer | 443 | Port SSL (1-65535) |
| timeout | entier | 30 000 | Délai d'expiration de la connexion (5000-300000 ms) |
| sni | boolean | TRUE | Indication du nom du serveur |
| verifyHostname | boolean | TRUE | Vérification du nom d'hôte |
| allowSelfSigned | boolean | FALSE | Accepter les certificats auto-signés |
| assertions | array | - | Règles de validation des certificats |
**Exemple**
```
{
"stepName": "sslCertCheck",
"checkerType": "SSL",
"hostname": "secure.example.com",
"port": 443,
"sni": true,
"verifyHostname": true,
"assertions": [
{
"type": "CERTIFICATE_EXPIRY",
"operator": "GREATER_THAN",
"value": 30,
"unit": "DAYS"
}
]
}
```
### Contrôles TCP
Testez la connectivité du port TCP et la validation des réponses.
**Propriétés requises**
| Propriété | Type | Description |
| --- | --- | --- |
| hostname | chaîne | Nom d'hôte cible (format du nom d'hôte) |
| port | entier | Port cible (1-65535) |
**Propriétés facultatives**
| Propriété | Type | Par défaut | Description |
| --- | --- | --- | --- |
| timeout | integer | 30 000 | Délai d'attente global (5000-300000 ms) |
| connectionTimeout | entier | 3000 | Délai d'expiration de la connexion (5000-300000 ms) |
| readTimeout | entier | 2000 | Délai de lecture des données (5000-300000 ms) |
| sendData | chaîne | - | Données à envoyer après la connexion |
| expectedResponse | chaîne | - | Données relatives aux réponses attendues |
| encoding | chaîne | « UTF-8 » | Codage des données : UTF-8ASCII, HEX |
| assertions | array | - | Validation de la connexion et des réponses |
**Exemple**
```
{
"stepName": "databaseConnection",
"checkerType": "TCP",
"hostname": "db.example.com",
"port": 3306,
"connectionTimeout": 5000,
"sendData": "SELECT 1",
"expectedResponse": "1",
"assertions": [
{
"type": "CONNECTION_SUCCESSFUL",
"value": true
}
]
}
```
## Méthodes d’authentification
**Aucune authentification**
```
{
"type": "NONE"
}
```
**Authentification basique**
| Propriété | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| type | chaîne | Oui | Doit être "BASIC" |
| username | chaîne | Oui | Nom d'utilisateur pour l'authentification |
| password | chaîne | Oui | Mot de passe pour l'authentification |
**Exemple**
```
{
"type": "BASIC",
"username": "admin",
"password": "${AWS_SECRET:basic-auth:password}"
}
```
**Authentification par clé d'API**
| Propriété | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "API\$1KEY" |
| apiKey | chaîne | Oui | - | Valeur de la clé d'API |
| headerName | chaîne | Non | « Clé X-API » | Nom de l'en-tête de la clé API |
**Exemple**
```
{
"type": "API_KEY",
"apiKey": "${AWS_SECRET:api-credentials}",
"headerName": "Authorization"
}
```
**OAuth informations d'identification du client**
| Propriété | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "OAUTH\$1CLIENT\$1CREDENTIALS" |
| tokenUrl | chaîne | Oui | - | OAuth URL du terminal du jeton |
| clientId | chaîne | Oui | - | OAuth identifiant du client |
| clientSecret | chaîne | Oui | - | OAuth secret du client |
| scope | chaîne | Non | - | OAuth portée |
| audience | chaîne | Non | - | OAuth public |
| resource | chaîne | Non | - | OAuth ressource |
| tokenApiAuth | array | Non | - | Méthodes d'authentification de l'API Token :BASIC\$1AUTH\$1HEADER, REQUEST\$1BODY |
| tokenCacheTtl | entier | Non | 3600 | Cache de jetons TTL (minimum 60 secondes) |
**Exemple**
```
{
"type": "OAUTH_CLIENT_CREDENTIALS",
"tokenUrl": "https://auth.example.com/oauth/token",
"clientId": "${AWS_SECRET:oauth-creds:client_id}",
"clientSecret": "${AWS_SECRET:oauth-creds:client_secret}",
"scope": "read write",
"tokenCacheTtl": 7200
}
```
**AWS Signature (version 4)**
| Propriété | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| type | chaîne | Oui | Doit être "SIGV4" |
| service | chaîne | Oui | Nom du AWS service (par exemple, « execute-api ») |
| region | chaîne | Oui | AWS région |
| roleArn | chaîne | Oui | ARN du rôle IAM pour la signature |
**Exemple**
```
{
"type": "SIGV4",
"service": "execute-api",
"region": "us-east-1",
"roleArn": "arn:aws:iam::123456789012:role/SyntheticsRole"
}
```
## Assertions et validation
### assertions HTTP
**Assertions de code d'état**
| Propriété | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| type | chaîne | Oui | Doit être "STATUS\$1CODE" |
| operator | chaîne | Oui | EQUALS, NOT\$1EQUALS, GREATER\$1THAN, LESS\$1THAN, IN\$1RANGE |
| value | entier | Conditionnel | Code d'état HTTP (100-599) |
| rangeMin | entier | Conditionnel | Valeur de plage minimale (pourIN\$1RANGE) |
| rangeMax | entier | Conditionnel | Valeur de plage maximale (pourIN\$1RANGE) |
```
{
"type": "STATUS_CODE",
"operator": "EQUALS",
"value": 200
}
```
**Assertions relatives au temps de réponse**
| Propriété | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "RESPONSE\$1TIME" |
| operator | chaîne | Oui | - | LESS\$1THAN, GREATER\$1THAN, EQUALS |
| value | number | Oui | - | Valeur temporelle (minimum 0) |
| unit | chaîne | Non | « MILLISECONDES » | Doit être "MILLISECONDS" |
```
{
"type": "RESPONSE_TIME",
"operator": "LESS_THAN",
"value": 500,
"unit": "MILLISECONDS"
}
```
**Affirmations de la tête**
| Propriété | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| type | chaîne | Oui | Doit être "HEADER" |
| headerName | chaîne | Oui | Nom de l'en-tête à valider |
| operator | chaîne | Oui | EQUALS, NOT\$1EQUALS, CONTAINS, NOT\$1CONTAINS, REGEX\$1MATCH, EXIST |
| value | chaîne/booléen | Conditionnel | Valeur attendue (booléen pour EXIST opérateur) |
```
{
"type": "HEADER",
"headerName": "Content-Type",
"operator": "CONTAINS",
"value": "application/json"
}
```
**Assertions corporelles**
| Propriété | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "BODY" |
| target | chaîne | Non | « JSON » | JSON ou TEXT |
| path | chaîne | Conditionnel | - | JSONPath (obligatoire pour la cible JSON) |
| operator | chaîne | Oui | - | CONTAINS, NOT\$1CONTAINS, EQUALS, NOT\$1EQUALS, EXISTS |
| value | chaîne/booléen | Oui | - | Valeur attendue (booléen pour EXISTS opérateur) |
```
{
"type": "BODY",
"target": "JSON",
"path": "$.users[0].name",
"operator": "EQUALS",
"value": "John Doe"
}
```
### Assertions DNS
**Assertions de valeur d'enregistrement**
| Propriété | Type | Obligatoire | Range | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "RECORD\$1VALUE" |
| operator | chaîne | Oui | - | EQUALS, NOT\$1EQUALS, CONTAINS, NOT\$1CONTAINS, REGEX\$1MATCH |
| value | chaîne | Oui | - | Valeur d'enregistrement attendue |
**Assertions relatives au nombre record**
| Propriété | Type | Obligatoire | Range | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "RECORD\$1COUNT" |
| operator | chaîne | Oui | - | EQUALS, GREATER\$1THAN, LESS\$1THAN |
| value | entier | Oui | ≥ 0 | Nombre attendu (minimum 0) |
**Assertions faisant autorité**
| Propriété | Type | Obligatoire | Range | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "AUTHORITATIVE" |
| value | boolean | Oui | - | Statut d'autorité attendu |
**Assertions TTL**
| Propriété | Type | Obligatoire | Range | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "TTL" |
| operator | chaîne | Oui | - | EQUALS, GREATER\$1THAN, LESS\$1THAN |
| value | entier | Oui | ≥ 0 | TTL attendu (minimum 0) |
### Assertions SSL
**Assertions relatives à l'expiration des certificats**
| Propriété | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "CERTIFICATE\$1EXPIRY" |
| operator | chaîne | Oui | - | GREATER\$1THAN, LESS\$1THAN |
| value | entier | Oui | - | Valeur temporelle (minimum 0) |
| unit | chaîne | Non | « JOURS » | DAYS, HOURS |
**Assertions relatives au sujet du certificat**
| Propriété | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "CERTIFICATE\$1SUBJECT" |
| field | chaîne | Oui | - | Domaine :CN,O,OU,C,ST, L |
| operator | chaîne | Oui | - | CONTAINS, EQUALS, REGEX\$1MATCH |
| value | chaîne | Oui | - | Valeur de champ attendue |
**Assertions de l'émetteur du certificat**
| Propriété | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "CERTIFICATE\$1ISSUER" |
| field | chaîne | Oui | - | Champ émetteur :CN, O |
| operator | chaîne | Oui | - | CONTAINS, EQUALS |
| value | chaîne | Oui | - | Valeur de champ attendue |
### Assertions TCP
**Assertions de réussite de la connexion**
| Propriété | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "CONNECTION\$1SUCCESSFUL" |
| value | boolean | Oui | - | État de connexion attendu |
**Assertions relatives aux données de réponse**
| Propriété | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| type | chaîne | Oui | - | Doit être "RESPONSE\$1DATA" |
| operator | chaîne | Oui | - | CONTAINS, EQUALS, NOT\$1CONTAINS, REGEX\$1MATCH, STARTS\$1WITH, ENDS\$1WITH |
| value | chaîne | Oui | - | Données relatives aux réponses attendues |
| encoding | chaîne | Non | « UTF-8 » | UTF-8, ASCII, HEX |
## Extraction de données
Les extracteurs vous permettent de saisir des données à partir des réponses pour les utiliser dans les étapes suivantes ou à des fins de reporting.
**Propriétés d'extraction**
| Propriété | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| name | chaîne | Oui | - | Nom de variable pour les données extraites |
| type | chaîne | Oui | - | Type d'extraction : BODY |
| path | chaîne | Non | - | JSONPath pour l'extraction du corps |
| regex | chaîne | Non | - | Modèle d'expression régulière |
| regexGroup | entier | Non | 0 | Groupe de capture Regex (minimum 0) |
**Validation du nom d'extraction**
+ Modèle : `^[a-zA-Z][a-zA-Z0-9_]*$`
+ Doit commencer par une lettre
+ Peut contenir des lettres, des chiffres et des traits de soulignement
**Limitation** — La substitution ne s'applique pas aux champs du schéma qui ont des valeurs ENUM spécifiques
**Types d'extraction**
```
{
"name": "userId",
"type": "BODY",
"path": "$.user.id"
}
```
```
{
"stepName": "loginAndExtract",
"checkerType": "HTTP",
"url": "https://api.example.com/login",
"httpMethod": "POST",
"body": "{\"username\":\"test\",\"password\":\"pass\"}",
"extractors": [
{
"name": "textVariable",
"type": "BODY",
"path": "$.myvalue"
}
]
},
{
"stepName": "substituteVariable",
"checkerType": "HTTP",
"url": "https://api.example.com/get/${textVariable}",
"httpMethod": "GET",
"assertions": [
{
"type": "BODY",
"target": "JSON",
"path": "$.users[0].name",
"operator": "EQUALS",
"value": "${textVariable}"
}
]
}
```