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

# 可用於使用 Selenium 的 Python Canary 指令碼的程式庫函數
<a name="CloudWatch_Synthetics_Canaries_Library_Python"></a>

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

**Topics**
+ [適用於所有 Canary 的 Python 和 Selenium 程式庫類別和函數](#CloudWatch_Synthetics_Library_allcanaries_Python)
+ [僅適用於 UI Canary 的 Python 和 Selenium 程式庫類別和函數](#CloudWatch_Synthetics_Library_Python_UIcanaries)

## 適用於所有 Canary 的 Python 和 Selenium 程式庫類別和函數
<a name="CloudWatch_Synthetics_Library_allcanaries_Python"></a>

下列適用於 Python 的 CloudWatch Synthetics Selenium 程式庫函數可用於所有 Canary。

**Topics**
+ [SyntheticsConfiguration 類別](#CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python)
+ [SyntheticsLogger 類別](#CloudWatch_Synthetics_Library_SyntheticsLogger_Python)

### SyntheticsConfiguration 類別
<a name="CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python"></a>

您可以使用 SyntheticsConfiguration 類別來設定 Synthetics 程式庫函數的行為。例如，您可以使用此類別來將 ` executeStep()` 函數設定為不擷取螢幕擷取畫面。

您可以在全域層級設定 CloudWatch Synthetics 組態。

函數定義：

#### set\$1config(options)
<a name="CloudWatch_Synthetics_Library_setConfig_Python"></a>

```
from aws_synthetics.common import synthetics_configuration
```

` options ` 是一個物件，適用於您的 Canary 的可設定選項集。以下各節會說明了 ` options ` 中的可能欄位。
+ `screenshot_on_step_start` (布林值)— 是否在開始步驟之前擷取螢幕擷取畫面。
+ `screenshot_on_step_success` (布林值)— 是否在成功完成步驟之後擷取螢幕擷取畫面。
+ `screenshot_on_step_failure` (布林值)— 是否在步驟失敗之後擷取螢幕擷取畫面。

 **with\$1screenshot\$1on\$1step\$1start(screenshot\$1on\$1step\$1start)** 

接受布林值引數，它會指示是否在開始步驟之前擷取螢幕擷取畫面。

 **with\$1screenshot\$1on\$1step\$1success(screenshot\$1on\$1step\$1success)** 

接受布林值引數，它會指示是否在成功完成步驟之後擷取螢幕擷取畫面。

 **with\$1screenshot\$1on\$1step\$1failure(screenshot\$1on\$1step\$1failure)** 

接受布林值引數，它會指示是否在步驟失敗之後擷取螢幕擷取畫面。

 **get\$1screenshot\$1on\$1step\$1start()** 

傳回是否在開始步驟之前擷取螢幕擷取畫面。

 **get\$1screenshot\$1on\$1step\$1success()** 

傳回是否在成功完成步驟之後擷取螢幕擷取畫面。

 **get\$1screenshot\$1on\$1step\$1failure()** 

傳回是否在步驟失敗之後擷取螢幕擷取畫面。

 **disable\$1step\$1screenshots()** 

停用所有螢幕擷取畫面選項 (get\$1screenshot\$1on\$1step\$1start、get\$1screenshot\$1on\$1step\$1success 和 get\$1screenshot\$1on\$1step\$1failure)。

 **enable\$1step\$1screenshots()** 

啟用所有螢幕擷取畫面選項 (get\$1screenshot\$1on\$1step\$1start、get\$1screenshot\$1on\$1step\$1success 和 get\$1screenshot\$1on\$1step\$1failure)。預設不會啟用所有這些方法。

 **關於 CloudWatch 指標的 setConfig(options)** 

對於使用 `syn-python-selenium-1.1`或更新版本的 Canary，**setConfig** 的 **（選項）** 可以包含下列布林值參數，以決定 Canary 發佈哪些指標。這些選項的預設值為 `true`。以 ` aggregated` 開頭的選項可判斷是否會發出沒有 ` CanaryName` 維度的指標。您可以使用這些指標來查看所有 Canary 的彙總結果。其他選項可判斷是否會發出具有 `CanaryName` 維度的指標。您可以使用這些指標來查看每個 Canary 的結果。

如需 Canary 發出的 CloudWatch 指標清單，請參閱 [Canary 公佈的 CloudWatch 指標](CloudWatch_Synthetics_Canaries_metrics.md)。
+ `failed_canary_metric` (布林值)— 是否為此 canary 發出 ` Failed` 指標 (具有 `CanaryName` 維度)。預設值為 `true`。
+ `failed_requests_metric` (布林值)— 是否為此 canary 發出 `Failed requests` 指標 (具有 `CanaryName` 維度)。預設值為 `true`。
+ `2xx_metric` (布林值)— 是否為此 canary 發出 `2xx` 指標 (具有 `CanaryName` 維度)。預設值為 `true`。
+ `4xx_metric` (布林值)— 是否為此 canary 發出 `4xx` 指標 (具有 `CanaryName` 維度)。預設值為 `true`。
+ `5xx_metric` (布林值)— 是否為此 canary 發出 `5xx` 指標 (具有 `CanaryName` 維度)。預設值為 `true`。
+ `step_duration_metric` (布林值)— 是否為此 canary 發出 `Step duration` 指標 (具有 `CanaryName` `StepName` 維度)。預設值為 `true`。
+ `step_success_metric` (布林值)— 是否為此 canary 發出 `Step success` 指標 (具有 `CanaryName` `StepName` 維度)。預設值為 `true`。
+ `aggregated_failed_canary_metric` (布林值)— 是否為此 canary 發出 `Failed` 指標 (沒有 `CanaryName` 維度)。預設值為 `true`。
+ `aggregated_failed_requests_metric` (布林值)— 是否為此 canary 發出 `Failed Requests` 指標 (沒有 `CanaryName` 維度)。預設值為 `true`。
+ `aggregated_2xx_metric` (布林值)— 是否為此 canary 發出 ` 2xx` 指標 (沒有 `CanaryName` 維度)。預設值為 `true`。
+ `aggregated_4xx_metric` (布林值)— 是否為此 canary 發出 ` 4xx` 指標 (沒有 `CanaryName` 維度)。預設值為 `true`。
+ `aggregated_5xx_metric` (布林值)— 是否為此 canary 發出 ` 5xx` 指標 (沒有 `CanaryName` 維度)。預設值為 `true`。

 **with\$12xx\$1metric(2xx\$1metric)** 

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

 **with\$14xx\$1metric(4xx\$1metric)** 

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

 **with\$15xx\$1metric(5xx\$1metric)** 

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

 **withAggregated2xxMetric(aggregated2xxMetric)** 

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

 **withAggregated4xxMetric(aggregated4xxMetric)** 

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

 **with\$1aggregated\$15xx\$1metric(aggregated\$15xx\$1metric)** 

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

 ** with\$1aggregated\$1failed\$1canary\$1metric(aggregated\$1failed\$1canary\$1metric)** 

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

 ** with\$1aggregated\$1failed\$1requests\$1metric(aggregated\$1failed\$1requests\$1metric)** 

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

 **with\$1failed\$1canary\$1metric(failed\$1canary\$1metric)** 

接受布林值引數，它會指定是否為此 Canary 發出具有 `CanaryName` 維度的 `Failed` 指標。

 **with\$1failed\$1requests\$1metric(failed\$1requests\$1metric)** 

接受布林值引數，它會指定是否為此 Canary 發出具有 `CanaryName` 維度的 `Failed requests` 指標。

 **with\$1step\$1duration\$1metric(step\$1duration\$1metric)** 

接受布林值引數，它會指定是否為此 Canary 發出具有 `CanaryName` 維度的 `Duration` 指標。

 **with\$1step\$1success\$1metric(step\$1success\$1metric)** 

接受布林值引數，它會指定是否為此 Canary 發出具有 `CanaryName` 維度的 `StepSuccess` 指標。

##### 啟用或停用指標的方法
<a name="CloudWatch_Synthetics_Python_setConfig_metrics"></a>

 **disable\$1aggregated\$1request\$1metrics()** 

禁止 Canary 發出所有沒有 ` CanaryName` 維度發出的請求指標。

 **disable\$1request\$1metrics()** 

停用所有請求指標，包括每個 Canary 指標和彙總所有 Canary 的指標。

 **disable\$1step\$1metrics()** 

停用所有步驟指標，包括步驟成功指標和步驟持續時間指標。

 **enable\$1aggregated\$1request\$1metrics()** 

啟用 Canary，使其可以發出所有沒有 ` CanaryName` 維度發出的請求指標。

 **enable\$1request\$1metrics()** 

啟用所有請求指標，包括每個 Canary 指標和彙總所有 Canary 的指標。

 **enable\$1step\$1metrics()** 

啟用所有步驟指標，包括步驟成功指標和步驟持續時間指標。

 **在 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\$1config(options)
<a name="CloudWatch_Synthetics_Library_Python_UI"></a>

對於 UI Canary，以 `syn-python-selenium-1.1` 為開頭的 ` set_config` 可以包括下列布林值參數：
+ `continue_on_step_failure` （布林值） — 是否在步驟失敗後繼續執行 Canary 指令碼 （這是指 ** executeStep** 函數）。如果任何步驟失敗，Canary 執行仍將被標記為失敗。預設值為 `false`。

### SyntheticsLogger 類別
<a name="CloudWatch_Synthetics_Library_SyntheticsLogger_Python"></a>

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

本機日誌檔案中的日誌陳述式會加上「偵錯」、「資訊」等前綴，以符合呼叫之函數的日誌層級。

使用 `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.warning(message, *args, **kwargs)
```

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

如需偵錯參數的相關資訊，請參閱 [logging.debug](https://docs.python.org/3/library/logging.html#logging.debug) 中的標準的 Python 文件，網址為記錄 .debug。

在這些記錄函數中，`message` 是訊息格式字串。`args` 是使用字串格式化運算符合併到 `msg` 的引數。

`kwargs` 中有三個關鍵字引數：
+ `exc_info`— 如果未評估為 false，則會將例外狀況資訊新增至記錄訊息。
+ `stack_info`– 預設為 false。如果為 true，則將堆疊資訊新增至日誌訊息，包括實際的日誌記錄呼叫。
+ `extra`— 第三個選用關鍵字引數，您可以使用此引數傳入字典，而該字典可用來使用使用者定義的屬性填入為日誌事件建立的 `LogRecord` 的 `__dict__`。

範例：

記錄 `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.warning('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 文件。](https://docs.python.org/3/library/logging.html#logging.exception)

`message` 是訊息格式字串。`args` 是使用字串格式化運算符合併到 `msg` 的引數。

`kwargs` 中有三個關鍵字引數：
+ `exc_info`— 如果未評估為 false，則會將例外狀況資訊新增至記錄訊息。
+ `stack_info`– 預設為 false。如果為 true，則將堆疊資訊新增至日誌訊息，包括實際的日誌記錄呼叫。
+ `extra`— 第三個選用關鍵字引數，您可以使用此引數傳入字典，而該字典可用來使用使用者定義的屬性填入為日誌事件建立的 `LogRecord` 的 `__dict__`。

範例：

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

## 僅適用於 UI Canary 的 Python 和 Selenium 程式庫類別和函數
<a name="CloudWatch_Synthetics_Library_Python_UIcanaries"></a>

下列僅適用於 Python 的 CloudWatch Synthetics Selenium 程式庫函數可用於 UI Canary。

**Topics**
+ [SyntheticsBrowser 類別](#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser)
+ [SyntheticsWebDriver class](#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver)

### SyntheticsBrowser 類別
<a name="CloudWatch_Synthetics_Library_Python_SyntheticsBrowser"></a>

**注意**  
僅 Chrome 瀏覽器支援 `SyntheticsBrowser`。

當您透過呼叫 `synthetics_webdriver.Chrome()` 建立瀏覽器執行個體時，傳回的瀏覽器執行個體是類型 `SyntheticsBrowser`。` SyntheticsBrowser` 類別會繼承 WebDriver 類別，並提供對 [WebDriver](https://www.selenium.dev/documentation/webdriver/) 公開之所有方法的存取權。它會控制 ChromeDriver，並使 Canary 指令碼驅動瀏覽器，允許搭配使用 Selenium WebDriver 與 Synthetics。

**注意**  
Synthetics 會覆寫 WebDriver [退出](https://www.selenium.dev/selenium/docs/api/py/selenium_webdriver_firefox/selenium.webdriver.firefox.webdriver.html)方法，不採取任何動作。您不需要擔心退出瀏覽器，因為 Synthetics 會為您處理。

除了標準 Selenium 方法，它還提供了以下方法。

**Topics**
+ [set\$1viewport\$1size(width, height)](#CloudWatch_Synthetics_Library_set_viewport_size)
+ [save\$1screenshot(filename, suffix)](#CloudWatch_Synthetics_Library_save_screenshot)

#### set\$1viewport\$1size(width, height)
<a name="CloudWatch_Synthetics_Library_set_viewport_size"></a>

設定瀏覽器的檢視區。範例：

```
browser.set_viewport_size(1920, 1080)
```

#### save\$1screenshot(filename, suffix)
<a name="CloudWatch_Synthetics_Library_save_screenshot"></a>

將螢幕擷取畫面儲存至 `/tmp` 目錄。螢幕擷取畫面從那裡上傳到 S3 儲存貯體中的 Canary 成品資料夾。

*filename* 是螢幕擷取畫面的檔案名稱，*尾碼*是用於命名螢幕擷取畫面的選用字串。

範例：

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

### SyntheticsWebDriver class
<a name="CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver"></a>

若要使用此類別，請在指令碼中使用以下內容：

```
from aws_synthetics.selenium import synthetics_webdriver
```

**Topics**
+ [add\$1execution\$1error(errorMessage, ex);](#CloudWatch_Synthetics_Library_Python_addExecutionError)
+ [add\$1user\$1agent(user\$1agent\$1str)](#CloudWatch_Synthetics_Library_add_user_agent)
+ [execute\$1step(step\$1name, function\$1to\$1execute)](#CloudWatch_Synthetics_Library_Python_execute_step)
+ [get\$1http\$1response(url)](#CloudWatch_Synthetics_Library_Python_get_http_response)
+ [Chrome()](#CloudWatch_Synthetics_Library_Python_Chrome)

#### add\$1execution\$1error(errorMessage, ex);
<a name="CloudWatch_Synthetics_Library_Python_addExecutionError"></a>

`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\$1user\$1agent(user\$1agent\$1str)
<a name="CloudWatch_Synthetics_Library_add_user_agent"></a>

將 `user_agent_str` 的數值附加到瀏覽器的使用者代理程式標頭。您必須先指派 `user_agent_str`，再建立瀏覽器執行個體。

範例：

```
await synthetics_webdriver.add_user_agent('MyApp-1.0')
```

應該在 `async` 函式內使用 `add_user_agent`。

#### execute\$1step(step\$1name, function\$1to\$1execute)
<a name="CloudWatch_Synthetics_Library_Python_execute_step"></a>

處理一個函數。它也會執行以下操作：
+ 記錄步驟已開始。
+ 建立名為 `<stepName>-starting` 的螢幕擷取畫面。
+ 啟動計時器。
+ 執行提供的函數。
+ 如果函數正常傳回結果，則會計為通過。如果函數擲回錯誤，則會計為失敗。
+ 結束計時器。
+ 記錄步驟是否已通過或失敗
+ 建立名為 `<stepName>-succeeded` 或 ` <stepName>-failed` 的螢幕擷取畫面。
+ 發出 `stepName` `SuccessPercent` 指標，100 代表通過，0 代表失敗。
+ 發出 `stepName` `Duration` 指標，顯示根據步驟開始和結束時間的值。
+ 最後，傳回 `functionToExecute` 已傳回的結果，或重新擲回 `functionToExecute` 已擲回的錯誤。

範例：

```
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)
```

#### get\$1http\$1response(url)
<a name="CloudWatch_Synthetics_Library_Python_get_http_response"></a>

對提供的 URL 提出 HTTP 請求，並傳回 HTTP 請求的回應碼。如果在 HTTP 請求期間發生例外狀況，系統會傳回值為 "error" 的字串。

範例：

```
response_code = syn_webdriver.get_http_response(url)
if not response_code or response_code == "error" or response_code < 200 or response_code > 299:
    raise Exception("Failed to load page!")
```

#### Chrome()
<a name="CloudWatch_Synthetics_Library_Python_Chrome"></a>

啟動 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)
```