可用于 Node.js 金丝雀脚本的库函数

此示例使用以下内容： Failed to load url: https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200

第一步，设置 Synthetics 配置。

// Import Synthetics dependency
const synthetics = require('Synthetics');
// Import Synthetics logger for logging url
const log = require('SyntheticsLogger');
// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();
// Set restricted parameters
synConfig.setConfig({
   restrictedUrlParameters: ['access_token'];
              
接下来，清理并记录错误消息
              
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('SyntheticsLogHelper');
try {
   // Your code which can throw an error containing url which your script logs
} catch (error) {
    const sanitizedErrorMessage = synthetics.getSanitizedErrorMessage(errorMessage);
    logger.info(sanitizedErrorMessage);
              
这一步会将以下内容记录在您的金丝雀日志中。
              
Failed to load url: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200
              
getSanitizedHeaders(headers, stepConfig=null) 
              
此函数在 syn-nodejs-puppeteer-3.2 和更高版本中可用。它根据 syntheticsConfiguration 的 restrictedHeaders 属性返回经清理的标头。restrictedHeaders 属性中指定的标头是在日志、HAR 文件和报告中编辑的。
              
headers 是一个包含要清理的标题的对象。
StepConfig（可选）覆盖此函数的全局 Synthetics 配置。如果 stepConfig 未传入，则使用全局配置来清理标头。
          
以下用于 Node.js 的 CloudWatch Synthetics 库函数仅适用于 UI 金丝雀。
          
主题
Synthetics 类
BrokenLinkCheckerReport 类
SyntheticsLink 类
            
Synthetics 类
            
以下函数位于 Synthetics 类中。
              
async addUserAgent(page, userAgentString);
              
此函数可将 userAgentString 附加到指定页面的 User-Agent 标头。
              
await synthetics.addUserAgent(page, "MyApp-1.0");
              
结果是页面的 User-Agent 标头被设置为 browsers-user-agent-header-valueMyApp-1.0
              
async executeStep(stepName, functionToExecute, [stepConfig]);
              
执行提供的步骤，并使用开始/通过/失败日志记录、开始/通过/失败屏幕截图，以及通过/失败和持续时间指标对其进行包装。
                
注意
如果您使用的是 syn-nodejs-2.1 或更高版本的运行时，您可以配置是否以及何时捕获屏幕截图。有关更多信息，请参阅SyntheticsConfiguration 类。
                
executeStep 函数还执行以下操作：
              
记录步骤开始。
获取名为 <stepName>-starting 的屏幕截图。
启动计时器。
执行提供的函数。
如果函数正常返回，则计为通过。如果函数引发异常，则计为失败。
结束计时器。
记录步骤是通过还是失败
获取名为 <stepName>-succeeded 或 <stepName>-failed 的屏幕截图。
发出 stepName SuccessPercent 指标，100 表示通过，0 表示失败。
发出 stepName Duration 指标，指标的值基于步骤开始和结束时间。
最后，返回 functionToExecute 返回的内容或重新抛出 functionToExecute 抛出的内容。
              
如果金丝雀使用 syn-nodejs-2.0 或更高版本的运行时，则此函数还将步骤执行摘要添加到金丝雀的报告中。摘要包括有关每个步骤的详细信息，例如开始时间、结束时间、状态 (PASSED/FAILED)、故障原因（如失败）以及在每个步骤执行过程中捕获的屏幕截图。
              
await synthetics.executeStep('navigateToUrl', async function (timeoutInMillis = 30000) {
           await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});});
              
返回 functionToExecute 返回的内容。
              
syn-nodejs-2.2 的更新
              
从 syn-nodejs-2.2 开始，您可以选择传递步骤配置来在步骤级别覆盖 CloudWatch Synthetics 配置。有关可以传递给 executeStep 的选项列表，请参阅 SyntheticsConfiguration 类。
                
在以下示例中，用 true 覆盖 continueOnStepFailure 的默认 false 配置，并指定捕获屏幕截图的时间。
                  
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();
            
getDefaultLaunchOptions() 函数返回 CloudWatch Synthetics 使用的浏览器启动选项。有关更多信息，请参阅 启动选项类型 
              
// This function returns default launch options used by Synthetics.
const defaultOptions = await synthetics.getDefaultLaunchOptions();
              
返回当前打开的页面作为 Puppeteer 对象。有关更多信息，请参阅 Puppeteer API v1.14.0。
              
let page = synthetics.getPage();
              
在当前浏览器会话中打开的页面（Puppeteer 对象）。
              
getRequestResponseLogHelper();
              
重要
在使用 syn-nodejs-puppeteer-3.2 或更高版本运行时的金丝雀中，此函数将与 RequestResponseLogHelper 类一起弃用。对此函数的任何使用都会导致在金丝雀日志中出现警告。将在未来的运行时版本中删除此函数。如果您正在使用此函数，请改为使用 RequestResponseLogHelper 类。
 
              
将此函数用作生成器模式，用于调整请求和响应日志记录标记。
              
synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));;
              
{RequestResponseLogHelper}
              
launch(options)
              
此函数的选项仅在 syn-nodejs-2.1 版本或更高版本的运行时中可用。
              
此函数仅用于 UI 金丝雀。它的作用是关闭现有浏览器并启动一个新的浏览器。
              
注意
在开始运行脚本之前，CloudWatch Synthetics 始终启动浏览器。除非您想使用自定义选项启动新浏览器，否则不需要调用 launch()。
              
(options) 是在浏览器上设置的一组可配置的选项。有关更多信息，请参阅 启动选项类型。
              
如果您在不设置选项的情况下调用此函数，Synthetics 会以默认参数、executablePath 和 defaultViewport 启动浏览器。CloudWatch Synthetics 中的默认视区是 1920 x 1080。
              
您可以覆盖 CloudWatch Synthetics 使用的启动参数，并在启动浏览器时传递其他参数。例如，以下代码段以默认参数和默认可执行文件路径启动浏览器，但视区为 800 x 600。
              
await synthetics.launch({
        defaultViewport: { 
            "deviceScaleFactor": 1, 
            "width": 800,
            "height": 600 
              
以下示例代码向 CloudWatch Synthetics 启动参数中添加了一个新的 ignoreHTTPSErrors 参数。
              
await synthetics.launch({
        ignoreHTTPSErrors: true
              
您可以通过向 CloudWatch Synthetics 启动参数中的参数添加一个 --disable-web-security 标志来禁用 Web 安全：
              
// 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 类
              
重要
在使用 syn-nodejs-puppeteer-3.2 或更高版本运行时的金丝雀中，此类将被弃用。对此类的任何使用都会导致在金丝雀日志中出现警告。将在未来的运行时版本中删除此函数。如果您正在使用此函数，请改为使用 RequestResponseLogHelper 类。
              
处理精细配置，以及创建请求和响应负载的字符串表示。
              
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);
              
synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper()
.withLogRequestPostData(true)
.withLogRequestHeaders(true)
.withLogResponseHeaders(true));
              
{RequestResponseLogHelper}
              
setRequestResponseLogHelper();
              
重要
在使用 syn-nodejs-puppeteer-3.2 或更高版本运行时的金丝雀中，此函数将与 RequestResponseLogHelper 类一起弃用。对此函数的任何使用都会导致在金丝雀日志中出现警告。将在未来的运行时版本中删除此函数。如果您正在使用此函数，请改为使用 RequestResponseLogHelper 类。
              
将此函数用作成生器模式，用于设置请求和响应日志记录标记。
              
synthetics.setRequestResponseLogHelper().withLogRequestHeaders(true).withLogResponseHeaders(true);
              
{RequestResponseLogHelper}
              
await synthetics.takeScreenshot("navigateToUrl", "loaded")
              
在此示例中，捕获了名为 01-navigateToUrl-loaded.png 的屏幕截图并将其上载到金丝雀的 S3 存储桶。
                
您可以传递 stepName 作为第一个参数，捕获特定金丝雀步骤的屏幕截图。屏幕截图会链接到报告中的金丝雀步骤，以帮助您在调试时跟踪每个步骤。
                
CloudWatch Synthetics 金丝雀会在开始步骤之前（executeStep 函数）和步骤完成后自动捕获屏幕截图（除非您将金丝雀配置为禁用屏幕截图）。您可以通过将步骤名称传入 takeScreenshot 函数来捕获多个屏幕截图。
                
在以下示例中，捕获屏幕截图并将 signupForm 作为 stepName 的值。屏幕截图将被命名为 02-signupForm-address，并链接到金丝雀报告中名为 signupForm 的步骤。
                
await synthetics.takeScreenshot('signupForm', 'address')
            
BrokenLinkCheckerReport 类
            
此类提供了添加 Synthetics 链接的方法。仅在使用 syn-nodejs-2.0-beta 或更高版本运行时的金丝雀上支持此类。
            
若要使用 BrokenLinkCheckerReport，脚本中需包括以下行：
            
const BrokenLinkCheckerReport = require('BrokenLinkCheckerReport');
const brokenLinkCheckerReport = new BrokenLinkCheckerReport();
            
有用的函数定义：
            
addLink(syntheticsLink, isBroken)
            
syntheticsLink 是一个 SyntheticsLink 对象，表示链接。此函数根据状态代码添加链接。预设情况下，如果状态代码不可用或状态代码为 400 或以上，则其会将链接视为无效。您可以通过传入可选参数 isBrokenLink（带有值 true 或 false）来覆盖此默认行为。
            
此函数无返回值。
            
getLinks()
            
此函数返回一组 SyntheticsLink 对象，这些对象包含在无效链接检查器报告。
            
getTotalBrokenLinks()
            
此函数返回一个表示无效链接总数的数字。
            
getTotalLinksChecked()
            
此函数返回一个表示包含在报告中的链接总数的数字。
            
如何使用 BrokenLinkCheckerReport
            
以下金丝雀脚本代码段展示了导航到链接并将其添加到无效链接检查器报告的示例。
            
导入 SyntheticsLink、BrokenLinkCheckerReport 和 Synthetics。
                
const BrokenLinkCheckerReport = require('BrokenLinkCheckerReport');
const SyntheticsLink = require('SyntheticsLink');
// Synthetics dependency
const synthetics = require('Synthetics');
              
若要向报告添加链接，请创建 BrokenLinkCheckerReport 实例。
                
let brokenLinkCheckerReport = new BrokenLinkCheckerReport();
导航到 URL 并将其添加到无效链接检查器报告中。
                
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);
将报告添加到 Synthetics。这样，金丝雀每次运行都会在 S3 存储桶中创建一个名为 BrokenLinkCheckerReport.json 的 JSON 文件。您可以在控制台中查看金丝雀每次运行的链接报告以及屏幕截图、日志和 HAR 文件。
                
await synthetics.addReport(brokenLinkCheckerReport);
            
            
此类提供了包装信息的方法。仅在使用 syn-nodejs-2.0-beta 或更高版本运行时的金丝雀上支持此类。
            
若要使用 SyntheticsLink，脚本中需包括以下行：
            
const SyntheticsLink = require('SyntheticsLink');
const syntheticsLink = new SyntheticsLink("https://www.amazon.com");
            
此函数返回 syntheticsLinkObject
            
有用的函数定义：
            
withUrl(url)
            
url 是一个 URL 字符串。此函数返回 syntheticsLinkObject
            
withText(text)
            
text 是一个表示锚文本的字符串。此函数返回 syntheticsLinkObject。它会添加与链接相对应的锚文本。
            
withParentUrl(parentUrl)
            
parentUrl 是一个表示父（源页面）URL 的字符串。此函数返回 syntheticsLinkObject
            
withStatusCode(statusCode)
            
statusCode 是一个表示状态代码的字符串。此函数返回 syntheticsLinkObject
            
withFailureReason(failureReason)
            
failureReason 是一个表示故障原因的字符串。此函数返回 syntheticsLinkObject
            
addScreenshotResult(screenshotResult)
            
screenshotResult 是一个对象。它是 Synthetics 函数 takeScreenshot 返回的 ScreenshotResult 的实例。此对象包括以下属性：
          
以下用于 Node.js 的 CloudWatch Synthetics 库函数仅适用于 API 金丝雀。
          
主题
executeHttpStep(stepName, requestOptions, [callback], [stepConfig])
            
executeHttpStep(stepName, requestOptions, [callback], [stepConfig])
            
作为步骤执行提供的 HTTP 请求，并发布 SuccessPercent（通过/失败）和 Duration 指标。
            
executeHttpStep 在后台使用 HTTP 或 HTTPS 本机函数，具体取决于请求中指定的协议。
              
此函数还将步骤执行摘要添加到金丝雀的报告中。摘要中包括有关每个 HTTP 请求的详细信息，如下所示：
              
requestOptions(Object or String)
              
此参数的值可以是 URL、URL 字符串或对象。如果为对象，则必须是用以发出 HTTP 请求的一组可配置选项。其支持 Node.js 文档中 http.request(options[, callback]) 中的所有选项。
              
除了这些 Node.js 选项之外，requestOptions 支持附加参数 body。您可以使用 body 参数将数据作为请求体传递。
              
callback(response)
              
（可选）此函数是与 HTTP 响应一起调用的用户函数。响应的类型为 Class: http.IncomingMessage。
              
stepConfig(object)
                
（可选）使用此参数，可以用此步骤的不同配置覆盖全局 synthetics 配置。
以下一系列示例相互依存，以说明此选项的各种用途。
              
第一个示例展示配置请求参数。您可以将 URL 作为 requestOptions 传递：
let requestOptions = 'https://www.amazon.com';
    
或者，您也可以传递一组选项：
              
let requestOptions = {
        'hostname': 'myproductsEndpoint.com',
        'method': 'GET',
        'path': '/test/product/validProductName',
        'port': 443,
        'protocol': 'https:'
              
在下一个示例中，创建一个接受响应的回调函数。预设情况下，如果您未指定 callback，CloudWatch Synthetics 会验证状态是否介于 200 和 299 之间（含）。
              
// 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();
              
下一个示例展示为此步骤创建覆盖全局 CloudWatch Synthetics 配置的配置。在本示例中，步骤配置允许报告中包含请求标头、响应标头、请求体（发布数据）和响应体，并限制了“X-Amz-Security-Token”和“Authorization”标头值。预设情况下，出于安全原因，报告中不包括这些值。如果您选择将它们包含在报告中，则这些数据仅存储在 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
最后一个例子展示将请求传递给 executeHttpStep 并对步骤命名。
 
await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig);
在这组示例中，CloudWatch Synthetics 将每个步骤的详细信息添加在报告中，并使用 stepName 生成每个步骤的指标。