Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

可用于使用 Selenium 的 Python Canary 脚本的库函数

本节列出了可用于 Python Canary 脚本的 Selenium 库函数。

适用于所有 Canary 的 Python 和 Selenium 库类和函数

以下用于 Python 的 CloudWatch Synthetics 库函数适用于所有 Canary。

SyntheticsConfiguration 类

您可以使用 SyntheticsConfiguration 类来配置 Synthetics 库函数的行为。例如，您可以使用此类将 executeStep() 函数配置为不捕获屏幕截图。

您可以在全局级别设置 CloudWatch Synthetics 配置。

函数定义：

set_config(options)

from aws_synthetics.common import synthetics_configuration

options 是一个对象，它是一组适用于您的 Canary 的可配置选项。以下各节将介绍 options 中的可能字段。

with_screenshot_on_step_start(screenshot_on_step_start)

接受一个布尔参数，该参数指示是否在开始步骤之前捕获屏幕截图。

with_screenshot_on_step_success(screenshot_on_step_success)

接受一个布尔参数，该参数指示是否在成功完成步骤后捕获屏幕截图。

with_screenshot_on_step_failure(screenshot_on_step_failure)

接受一个布尔参数，该参数指示是否在步骤失败后捕获屏幕截图。

get_screenshot_on_step_start()

返回是否在开始步骤之前捕获屏幕截图。

get_screenshot_on_step_success()

返回是否在成功完成步骤后捕获屏幕截图。

get_screenshot_on_step_failure()

返回是否在步骤失败后捕获屏幕截图。

disable_step_screenshots()

禁用所有屏幕截图选项（get_screenshot_on_step_start、get_screenshot_on_step_success 和 get_screenshot_on_step_failure）。

enable_step_screenshots()

启用所有屏幕截图选项（get_screenshot_on_step_start、get_screenshot_on_step_success 和 get_screenshot_on_step_failure)。预设情况下，这些方法均未启用。

CloudWatch 指标的相关 setConfig(options

对于使用 syn-python-selenium-1.1 或更高版本的 Canary，setConfig 的 (options) 可包含以下布尔参数，这些参数决定将由 Canary 发布的指标。其中每个选项的默认值均为 true。以 aggregated 开头的选项决定是否不带 CanaryName 维度发出指标。您可以使用该等指标查看所有 Canary 的聚合结果。其他选项决定是否带 CanaryName 维度发出指标。您可以使用该等指标查看每个 Canary 的结果。

with_2xx_metric(2xx_metric)

接受一个布尔参数，该参数指定是否为此 Canary 发出带 CanaryName 维度的 2xx 指标。

with_4xx_metric(4xx_metric)

接受一个布尔参数，该参数指定是否为此 Canary 发出带 CanaryName 维度的 4xx 指标。

with_5xx_metric(5xx_metric)

接受一个布尔参数，该参数指定是否为此 Canary 发出带 CanaryName 维度的 5xx 指标。

withAggregated2xxMetric(aggregated2xxMetric)

接受一个布尔参数，该参数指定是否为此 Canary 发出不带维度的 2xx 指标。

withAggregated4xxMetric(aggregated4xxMetric)

接受一个布尔参数，该参数指定是否为此 Canary 发出不带维度的 4xx 指标。

with_aggregated_5xx_metric(aggregated_5xx_metric)

接受一个布尔参数，该参数指定是否为此 Canary 发出不带维度的 5xx 指标。

with_aggregated_failed_canary_metric(aggregated_failed_canary_metric)

接受一个布尔参数，该参数指定是否为此 Canary 发出不带维度的 Failed 指标。

with_aggregated_failed_requests_metric(aggregated_failed_requests_metric)

接受一个布尔参数，该参数指定是否为此 Canary 发出不带维度的 Failed requests 指标。

with_failed_canary_metric(failed_canary_metric)

接受一个布尔参数，该参数指定是否为此 Canary 发出带 CanaryName 维度的 Failed 指标。

with_failed_requests_metric(failed_requests_metric)

接受一个布尔参数，该参数指定是否为此 Canary 发出带 CanaryName 维度的 Failed requests 指标。

with_step_duration_metric(step_duration_metric)

接受一个布尔参数，该参数指定是否为此 Canary 发出带 CanaryName 维度的 Duration 指标。

with_step_success_metric(step_success_metric)

接受一个布尔参数，该参数指定是否为此 Canary 发出带 CanaryName 维度的 StepSuccess 指标。

用于启用或禁用指标的方法

disable_aggregated_request_metrics()

禁用 Canary 发出以不带 CanaryName 维度形式发出的所有请求指标。

disable_request_metrics()

禁用所有请求指标，包括每个 Canary 的指标和跨所有 Canary 聚合的指标。

disable_step_metrics()

禁用所有步骤指标，包括步骤成功指标和步骤持续时间指标。

enable_aggregated_request_metrics()

启用 Canary 发出以不带 CanaryName 维度形式发出的所有请求指标。

enable_request_metrics()

启用所有请求指标，包括每个 Canary 的指标和跨所有 Canary 聚合的指标。

enable_step_metrics()

启用所有步骤指标，包括步骤成功指标和步骤持续时间指标。

在 UI Canary 中的使用情况

首先，导入 Synthetics 依赖关系并获取配置。然后，通过使用以下选项之一调用 setConfig 方法来设置每个选项的配置。

from aws_synthetics.common import synthetics_configuration

synthetics_configuration.set_config(
     {
        "screenshot_on_step_start": False,
        "screenshot_on_step_success": False,
        "screenshot_on_step_failure": True
     }
)

or 

或者

synthetics_configuration.with_screenshot_on_step_start(False).with_screenshot_on_step_success(False).with_screenshot_on_step_failure(True)

若要禁用所有屏幕截图，请使用 disableStepScreenshots() 函数，如本示例所示。

synthetics_configuration.disable_step_screenshots()

您可以在代码中的任何位置启用和禁用屏幕截图。例如，若要仅禁用一个步骤的屏幕截图，请在运行该步骤之前禁用屏幕截图，然后在该步骤后启用它们。

用于 UI Canary 的 set_config(options)

从 syn-python-selenium-1.1 开始，对于 UI Canary，set_config 可包含以下布尔参数:

SyntheticsLogger 类

synthetics_logger 将日志写入控制台和同一日志级别的本地日志文件。仅当日志级别与所调用的日志函数所需的日志记录级别相同或比其级别低时，此日志文件才会写入到这两个位置。

本地日志文件中的日志记录语句前面加上“DEBUG:”、“INFO:”等，以便与所调用的函数的日志级别相匹配。

如果要创建上载到 Amazon S3 结果位置的日志文件，不需要使用 synthetics_logger。您可以在 /tmp 文件夹中创建不同的日志文件。在 /tmp 文件夹下创建的任何文件都会作为构件上载到 S3 存储桶中的结果位置。

若要使用 synthetics_logger：

from aws_synthetics.common import synthetics_logger

有用的函数定义：

获取日志级别：

log_level = synthetics_logger.get_level()

设置日志级别：

synthetics_logger.set_level()

使用指定级别记录消息。该级别可以是 DEBUG、INFO、WARN，或 ERROR，如以下语法示例所示：

synthetics_logger.debug(message, *args, **kwargs)

synthetics_logger.info(message, *args, **kwargs)

synthetics_logger.log(message, *args, **kwargs)

synthetics_logger.warn(message, *args, **kwargs)

synthetics_logger.error(message, *args, **kwargs)

有关调试参数的信息，请参阅标准 Python 文档中的 logging.debug

在这些日志记录函数中，message 为消息格式的字符串。args 为合并到使用字符串格式运算符的 msg 中的参数。

kwargs 中有三个关键字参数：

示例：

使用 DEBUG 级别记录消息：

synthetics_logger.debug('Starting step - login.')

使用 INFO 级别记录消息。logger.log 是 logger.info 的同义词：

synthetics_logger.info('Successfully completed step - login.')

或

synthetics_logger.log('Successfully completed step - login.')

使用 WARN 级别记录消息：

synthetics_logger.warn('Warning encountered trying to publish %s', 'CloudWatch Metric')

使用 ERROR 级别记录消息：

synthetics_logger.error('Error encountered trying to publish %s', 'CloudWatch Metric')

记录异常：

synthetics_logger.exception(message, *args, **kwargs)

使用 ERROR 级别记录消息。异常信息将会添加到日志记录消息中。您应该只从异常处理程序调用此函数。

有关异常参数的信息，请参阅标准 Python 文档中的 logging.exception

message 为消息格式的字符串。args 为合并到使用字符串格式运算符的 msg 中的参数。

kwargs 中有三个关键字参数：

例如：

synthetics_logger.exception('Error encountered trying to publish %s', 'CloudWatch Metric')

仅适用于 UI Canary 的 Python 和 Selenium 库类和函数

以下用于 Python 的 CloudWatch Synthetics Selenium 库函数仅适用于 UI Canary。

SyntheticsBrowser 类

当您通过调用 synthetics_webdriver.Chrome() 创建浏览器实例时，返回的浏览器实例类型为 SyntheticsBrowser。SyntheticsBrowser 类控制 ChromeDriver，并使 Canary 脚本能够驱动浏览器，从而允许 Selenium WebDriver 使用 Synthetics。

除了标准的 Selenium 方法之外，它还提供了以下方法。

set_viewport_size(width, height)

设置浏览器的视区。例如：

browser.set_viewport_size(1920, 1080)

save_screenshot(filename, suffix)

将屏幕截图保存到 /tmp 目录。屏幕截图将上载到 S3 存储桶中的 Canary 构件文件夹。

filename 是屏幕截图的文件名，后缀是用于命名屏幕截图的可选字符串。

例如：

browser.save_screenshot('loaded.png', 'page1')

SyntheticsWebDriver 类

要使用此类，请在脚本中使用以下内容：

from aws_synthetics.selenium import synthetics_webdriver

add_execution_error(errorMessage, ex);

errorMessage 描述错误，ex 指遇到的异常

您可以使用 add_execution_error 来设置 Canary 的执行错误。它会在不中断脚本执行的情况下导致 Canary 失败。它也不会影响 successPercent 指标。

只有当错误对于指示 Canary 脚本成功或故障并不重要时，才应将错误作为执行错误进行跟踪。

以下是使用 add_execution_error 的示例。您将会监控端点的可用性，并在页面加载完成后捕获屏幕截图。由于捕获屏幕截图故障并不会决定端点的可用性，因此您可以捕获在截图时遇到的任何错误，并将它们添加为执行错误。可用性指标仍会指示端点已启动并正在运行，但 Canary 状态会被标记为失败。以下示例代码块将会捕获此类错误并将其添加为执行错误。

try:
    browser.save_screenshot("loaded.png")  
except Exception as ex:
   self.add_execution_error("Unable to take screenshot", ex)

add_user_agent(user_agent_str)

将 user_agent_str 的值附加到浏览器的用户代理标头。您必须在创建浏览器实例之前分配 user_agent_str。

例如：

synthetics_webdriver.add_user_agent('MyApp-1.0')

execute_step(step_name, function_to_execute)

处理一个函数。它还执行以下操作：

例如：

def custom_actions():
        #verify contains
        browser.find_element_by_xpath("//*[@id=\"id_1\"][contains(text(),'login')]")
        #click a button
        browser.find_element_by_xpath('//*[@id="submit"]/a').click()

    await synthetics_webdriver.execute_step("verify_click", custom_actions)

Chrome()

启动 Chromium 浏览器的实例并返回创建的浏览器实例。

例如：

browser = synthetics_webdriver.Chrome()
browser.get("https://example.com/)

要以隐身模式启动浏览器，请遵循以下说明:

add_argument('——incognito')

要添加代理设置，请遵循以下说明:

add_argument('--proxy-server=%s' % PROXY)

例如：

from selenium.webdriver.chrome.options import Options
chrome_options = Options()
chrome_options.add_argument("——incognito")
browser = syn_webdriver.Chrome(chrome_options=chrome_options)