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

# 步驟 1. 建立 JSON 組態檔案
<a name="custom-visual-transform-json-config-file"></a>

 需要 JSON 組態檔案才能定義和描述您的自訂視覺化轉換。組態檔案的結構描述如下。

## JSON 檔案結構
<a name="custom-visual-transform-json-file-structure"></a>

 **欄位** 
+  `name: string` – (必要) 用來識別轉換的轉換系統名稱。遵循為 Python 變數名稱 (識別符) 設定的相同命名規則。具體來說，名稱必須以字母或底線開頭，且完全由字母、數字和/或底線組成。
+  `displayName: string` – (選用) AWS Glue Studio 視覺化任務編輯器中顯示的轉換名稱。如果未指定 `displayName`，則 `name` 會用作 AWS Glue Studio 中的轉換名稱。
+  `description: string` – (選用) 轉換描述會顯示在 AWS Glue Studio 中，且可供搜尋。
+  `functionName: string` – (必要) Python 函數名稱用於識別要在 Python 指令碼中呼叫的函數。
+  `path: string` – (選用) Python 來源檔案的完整 Amazon S3 路徑。如果未指定，則 AWS Glue 使用檔案名稱比對功能將 .json 和 .py 檔案配對在一起。例如，JSON 檔案的名稱 `myTransform.json` 會與位於同一個 Amazon S3 位置的 Python 檔案 `myTransform.py` 配對。
+  `parameters: Array of TransformParameter object` – (選用) 在 AWS Glue Studio 視覺化編輯器中設定參數時顯示的參數清單。

<a name="transformparameter-fields"></a> **TransformParameter 欄位** 
+  `name: string` – (必要) 將作為任務指令碼中的具名引數傳遞至 Python 函數的參數名稱。遵循為 Python 變數名稱 (識別符) 設定的相同命名規則。具體來說，名稱必須以字母或底線開頭，且完全由字母、數字和/或底線組成。
+  `displayName: string` – (選用) AWS Glue Studio 視覺化任務編輯器中顯示的轉換名稱。如果未指定 `displayName`，則 `name` 會用作 AWS Glue Studio 中的轉換名稱。
+  `type: string` – (必要) 接受常見 Python 資料類型的參數類型。有效值： 'str' \$1 'int' \$1 'float' \$1 'list' \$1 'bool'。
+  `isOptional: boolean`：(選用) 決定參數是否為選用參數。依預設，所有參數皆為必要參數。
+  `description: string` – (選用) 描述會顯示在 AWS Glue Studio 中，可協助使用者設定轉換參數。
+  `validationType: string` – (選用) 定義驗證此參數的方式。目前僅支援規則運算式。依預設，系統會將驗證類型設定為 `RegularExpression`。
+  `validationRule: string` – (選用) 在 `validationType` 設定為 `RegularExpression` 時，用於在提交之前驗證表單輸入的規則運算式。規則運算式語法必須相容於 [RegExp Ecmascript 規格](https://tc39.es/ecma262/multipage/text-processing.html#sec-regexp-regular-expression-objects)。
+  `validationMessage: string` – (選用) 驗證失敗時顯示的訊息。
+  `listOptions: An array of TransformParameterListOption object` 或 `string` 或字串值 "column"：(選用) 用於在單選或複選 UI 控制中顯示的選項。接受逗號分隔值清單或 `TransformParameterListOption` 類型的強型別 JSON 物件。您也可以透過指定字串值 "column" 動態填入父節點結構描述中的資料欄清單。
+  `listType: string` – (選用) 定義類型 = 'list' 的選項類型。有效值： 'str' \$1 'int' \$1 'float' \$1 'list' \$1 'bool'。接受常見 Python 資料類型的參數類型。

 **TransformParameterListOption 欄位** 
+  `value: string | int | float | bool` – (必要) 選項值。
+  `label: string` - (可選) 在選取下拉式選單中顯示的選項標籤。

## AWS Glue Studio 中的轉換參數
<a name="custom-visual-transform-parameters"></a>

 依預設，除非參數在 .json 檔案中標記為 `isOptional`，否則參數為必要項。在 AWS Glue Studio 中，參數會顯示在 **Transform** (轉換) 索引標籤中。範例顯示使用者定義的參數，例如電子郵件地址、電話號碼、年齡、性別和原籍國家/地區。

![\[螢幕擷取畫面顯示選取的自訂視覺化轉換，以及包含使用者定義參數的轉換索引標籤。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/dynamic-transform-parameters.png)


 您可以在 `validationMessage` 中指定 `validationRule` 參數並指定驗證訊息，使用 json 檔案中的規則運算式強制執行 AWS Glue Studio 中的某些驗證。

```
      "validationRule": "^\\(?(\\d{3})\\)?[- ]?(\\d{3})[- ]?(\\d{4})$",
      "validationMessage": "Please enter a valid US number"
```

**注意**  
 由於驗證發生在瀏覽器中，您的規則運算式語法必須相容於 [RegExp Ecmascript 規格](https://tc39.es/ecma262/multipage/text-processing.html#sec-regexp-regular-expression-objects)。這些規則運算式不支援 Python 語法。

 新增驗證可防止使用者儲存具有錯誤之使用者輸入的任務。AWS Glue Studio 顯示驗證訊息，如範例所示：

![\[螢幕擷取畫面顯示含有驗證錯誤訊息的自訂視覺化轉換參數：Please enter a valid email address (請輸入有效的電子郵件地址)。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/dynamic-transform-validation-message.png)


 系統會根據參數組態在 AWS Glue Studio 中顯示參數。
+  如果 `type` 是 `str`、`int` 或 `float` 中的任何一項，則會顯示文字輸入欄位。例如，螢幕擷取畫面會顯示「電子郵件地址」和「您的年齡」參數的輸入欄位。  
![\[螢幕擷取畫面顯示含有文字輸入欄位的自訂視覺化轉換參數。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/dynamic-transform-email-address.png)  
![\[螢幕擷取畫面顯示含有文字輸入欄位的自訂視覺化轉換參數。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/dynamic-transform-your-age.png)
+  如果 `type` 為 `bool`，則會顯示核取方塊。  
![\[螢幕擷取畫面顯示含有文字輸入欄位的自訂視覺化轉換參數。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/dynamic-transform-bool.png)
+  如果 `type` 為 `str` 且提供 `listOptions`，則會顯示單一選取清單。  
![\[螢幕擷取畫面顯示含有單一選取清單下拉式選單的自訂視覺化轉換參數。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/dynamic-transform-single-list.png)
+  如果 `type` 為 `list` 和 `listOptions` 且提供 `listType`，則會顯示多選清單。  
![\[螢幕擷取畫面顯示含有清單下拉式選單的自訂視覺化轉換參數。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/dynamic-transform-list-options.png)

### 顯示資料欄選取器作為參數
<a name="custom-visual-transform-parameters-column-selector"></a>

 如果組態要求使用者從結構描述選擇資料欄，您可以顯示資料欄選取器，讓使用者不需要輸入資料欄名稱。透過將 `listOptions` 欄位設定為 "column"，AWS Glue Studio 會根據父節點輸出結構描述動態顯示資料欄選取器。AWS Glue Studio 可以顯示單個或多個資料欄選取器。

 下列範例使用結構描述：

![\[螢幕擷取畫面顯示範例輸出結構描述。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/custom-visual-transform-example-schema.png)


**若要定義「自訂視覺化轉換」參數以顯示單一資料欄：**

1.  在您的 JSON 檔案中，對於 `parameters` 物件，將 `listOptions` 值設為 "column"。這可讓使用者從 AWS Glue Studio 中的點選清單中選擇資料欄。  
![\[螢幕擷取畫面會顯示範例 JSON 檔案 (其中 listOptions 參數設定為 "column") 並在 AWS Glue Studio 中顯示產生的使用者介面。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/custom-visual-transform-example-listoptions-column.png)

1.  您也可以透過將參數定義為以下項目來允許選取多個資料欄：
   +  `listOptions: "column"` 
   +  `type: "list"`   
![\[螢幕擷取畫面會顯示範例 JSON 檔案 (其中 listOptions 參數設定為 "column" 且類型設定為 "list")，並在 AWS Glue Studio 中顯示產生的使用者介面。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/custom-visual-transform-example-listoptions-column-type-list.png)