# 步骤 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 数据类型的参数类型。

 **转换参数列表选项字段** 
+  `value: string | int | float | bool` —（必需）选项值。
+  `label: string` —（可选）显示在选择下拉列表中的选项标签。

## AWS Glue Studio 中的转换参数
<a name="custom-visual-transform-parameters"></a>

 默认情况下，除非在 .json 文件中标记为 `isOptional`，否则参数为必填。在 AWS Glue Studio 中，参数显示在 **Transform**（转换）选项卡中。该示例显示了用户定义的参数，例如电子邮件地址、电话号码、您的年龄、您的性别和您的原籍国。

![\[屏幕截图显示了一个选定的自定义视觉转换以及一个“Transform”（转换）选项卡，其中包含用户定义的参数。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/dynamic-transform-parameters.png)


 通过在 json 文件中使用正则表达式指定 `validationRule` 参数并在 `validationMessage` 中指定验证消息，在 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_cn/glue/latest/dg/images/dynamic-transform-validation-message.png)


 参数会根据参数配置显示在 AWS Glue Studio 中。
+  当 `type` 为以下任一项时：`str`、`int` 或 `float`，将显示一个文本输入字段。例如，屏幕截图显示了“Email Address”和“Your age”参数的输入字段。  
![\[屏幕截图显示了一个自定义视觉转换参数以及文本输入字段。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/dynamic-transform-email-address.png)  
![\[屏幕截图显示了一个自定义视觉转换参数以及文本输入字段。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/dynamic-transform-your-age.png)
+  当 `type` 为 `bool` 时，将显示一个复选框。  
![\[屏幕截图显示了一个自定义视觉转换参数以及文本输入字段。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/dynamic-transform-bool.png)
+  当 `type` 为 `str` 且提供了 `listOptions` 时，将显示一个单选列表。  
![\[屏幕截图显示了一个自定义视觉转换参数以及一个单选下拉列表。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/dynamic-transform-single-list.png)
+  当 `type` 为 `list` 且提供了 `listOptions` 和 `listType` 时，将显示一个多选列表。  
![\[屏幕截图显示了带有下拉列表的自定义视觉转换参数。\]](http://docs.aws.amazon.com/zh_cn/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_cn/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_cn/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_cn/glue/latest/dg/images/custom-visual-transform-example-listoptions-column-type-list.png)