本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

可用於使用 Selenium 的 Python Canary 指令碼的程式庫函數

本區段列出了適用於 Python Canary 指令碼的 Selenium 程式庫函數

適用於所有 Canary 的 Python 和 Selenium 程式庫類別和函數

下列適用於 Python 的 CloudWatch Synthetics Selenium 程式庫函數適用於所有 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)。預設不會啟用所有這些方法。

setConfig關於 CloudWatch 指標的 （選項）

對於使用 syn-python-selenium-1.1或更新版本的 Canary， 的 （選項） setConfig 可以包含下列布林參數，這些參數可決定 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（彙總2xxMetric）

接受布林值引數，它會指定是否為此 Canary 發出沒有維度的 2xx 指標。

withAggregated4xxMetric（彙總4xxMetric）

接受布林值引數，它會指定是否為此 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 中的使用方式

首先，匯入綜合相依性並擷取組態。然後，使用下列其中一個選項呼叫 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)

對於 UI Canary，以 syn-python-selenium-1.1 為開頭的 set_config 可以包括下列布林值參數：

SyntheticsLogger 類別

synthetics_logger 會將日誌同時寫入至主控台和相同日誌層級的本機日誌檔案。只有在日誌層級等於或低於呼叫之日誌函數所需的日誌層級時，才會將此日誌檔案同時寫入至這兩個位置。

本機日誌檔案中的記錄陳述式前面加上 "DEBUG："、"INFO：" 等，以符合呼叫之函數的日誌層級。

使用 synthetics_logger 並不需要建立上傳至 Simple Storage Service (Amazon S3) 結果位置的日誌檔案。您可改為在 /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)

如需偵錯參數的相關資訊，請參閱 logging.debug 中的標準的 Python 文件，網址為記錄 .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 層級的訊息。例外狀況資訊會新增至記錄訊息。您應該只從例外狀況處理常式呼叫此函數。

如需例外狀況參數的相關資訊，請參閱 logging.exception 中的標準的 Python 文件。

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 是螢幕擷取畫面的檔案名稱，suffix 是用來命名螢幕擷取畫面的選用字串。

範例：

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)

處理一個函數。它也會執行以下操作：

範例：

from selenium.webdriver.common.by import By

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)