# 编写蓝图代码
<a name="developing-blueprints-code"></a>

您创建的每个蓝图项目必须至少包含以下文件：
+ 定义工作流的 Python 布局脚本。该脚本包含一个函数，用于定义工作流中的实体（任务和爬网程序）以及它们之间的依赖关系。
+ 配置文件 `blueprint.cfg`，它定义了：
  + 工作流布局定义函数的完整路径。
  + 蓝图接受的参数。

**Topics**
+ [创建蓝图布局脚本](developing-blueprints-code-layout.md)
+ [创建配置文件](developing-blueprints-code-config.md)
+ [指定蓝图参数](developing-blueprints-code-parameters.md)

# 创建蓝图布局脚本
<a name="developing-blueprints-code-layout"></a>

蓝图布局脚本必须包含在工作流中生成实体的函数。您可以随意命名此函数。AWS Glue 使用配置文件确定函数的完全限定名称。

您的布局函数执行以下操作：
+ （可选）实例化 `Job` 类来创建 `Job` 对象，并传递诸如 `Command` 和 `Role` 的参数。如果您使用 AWS Glue 控制台或 API 来创建任务，这些是您要指定的任务属性。
+ （可选）实例化 `Crawler` 类来创建 `Crawler` 对象，并传递名称、角色和目标参数。
+ 要指示对象（工作流实体）之间的依赖项，请将 `DependsOn` 和 `WaitForDependencies` 等其他参数传递到 `Job()` 和 `Crawler()`。此部分的后面将说明这些参数。
+ 实例化 `Workflow` 类以创建返回到 AWS Glue 的工作流对象，传递 `Name` 参数、`Entities` 参数和可选的 `OnSchedule` 参数。`Entities` 参数指定要包含在工作流中的所有任务和爬网程序。如需了解如何构建 `Entities` 对象，请参阅此部分后面的示例项目。
+ 返回 `Workflow` 对象。

有关 `Job`、`Crawler` 和 `Workflow` 类的定义，请参阅[AWS Glue 蓝图类参考](developing-blueprints-code-classes.md)。

该布局函数接受以下输入参数。


| 参数 | 说明 | 
| --- | --- | 
| user\$1params | 蓝图参数名称和值的 Python 词典。有关更多信息，请参阅 [指定蓝图参数](developing-blueprints-code-parameters.md)。 | 
| system\$1params | Python 词典包含两个属性：region 和 accountId。 | 

这里是一个文件名为 `Layout.py` 的简单布局生成器脚本：

```
import argparse
import sys
import os
import json
from awsglue.blueprint.workflow import *
from awsglue.blueprint.job import *
from awsglue.blueprint.crawler import *


def generate_layout(user_params, system_params):

    etl_job = Job(Name="{}_etl_job".format(user_params['WorkflowName']),
                  Command={
                      "Name": "glueetl",
                      "ScriptLocation": user_params['ScriptLocation'],
                      "PythonVersion": "2"
                  },
                  Role=user_params['PassRole'])
    post_process_job = Job(Name="{}_post_process".format(user_params['WorkflowName']),
                            Command={
                                "Name": "pythonshell",
                                "ScriptLocation": user_params['ScriptLocation'],
                                "PythonVersion": "2"
                            },
                            Role=user_params['PassRole'],
                            DependsOn={
                                etl_job: "SUCCEEDED"
                            },
                            WaitForDependencies="AND")
    sample_workflow = Workflow(Name=user_params['WorkflowName'],
                            Entities=Entities(Jobs=[etl_job, post_process_job]))
    return sample_workflow
```

示例脚本会导入所需的蓝图库，并包含 `generate_layout` 函数，用于生成包含两个任务的工作流。这是一个非常简单的脚本。更复杂的脚本可以使用额外的逻辑和参数来生成具有许多任务和爬网程序（甚至可变数量的任务和爬网程序）的工作流。

## 使用 DependsOn 参数
<a name="developing-blueprints-code-layout-depends-on"></a>

`DependsOn` 参数是此实体对工作流中其他实体所具有的依赖关系的字典表示形式。格式如下。

```
DependsOn = {dependency1 : state, dependency2 : state, ...}
```

此字典中的密钥表示实体的对象引用，而不是名称，而值是对应于要监视的状态的字符串。AWS Glue 推断合适的触发器。有关有效状态，请参阅[条件结构](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-jobs-trigger.html#aws-glue-api-jobs-trigger-Condition)。

例如，任务可能依赖于爬网程序的成功完成。如果您定义了名为 `crawler2` 的爬网程序对象，如下所示：

```
crawler2 = Crawler(Name="my_crawler", ...)
```

然后一个依赖于 `crawler2` 的对象将包含一个构造函数参数，例如：

```
DependsOn = {crawler2 : "SUCCEEDED"}
```

例如：

```
job1 = Job(Name="Job1", ..., DependsOn = {crawler2 : "SUCCEEDED", ...})
```

如果实体省略了 `DependsOn`，则该实体依赖于工作流启动触发器。

## 使用 WaitForDependencies 参数
<a name="developing-blueprints-code-layout-wait-for-dependencies"></a>

`WaitForDependencies` 参数定义任务或爬网程序实体是应该等待它依赖的*全部*实体完成，还是等待*任意*实体完成。

允许的值为“`AND`”或”`ANY`“。

## 使用 OnSchedule 参数
<a name="developing-blueprints-code-layout-on-schedule"></a>

`Workflow` 类构造函数的 `OnSchedule` 参数是 `cron` 表达式，用于定义工作流的启动触发器。

如果指定此参数，AWS Glue 创建一个带有相应计划的计划触发器。如果未指定启动触发器，则工作流的启动触发器是按需触发器。

# 创建配置文件
<a name="developing-blueprints-code-config"></a>

蓝图配置文件是必需的文件，用于定义生成工作流的脚本入口点以及蓝图接受的参数。文件必须命名为 `blueprint.cfg`。

下面是示例配置文件。

```
{
    "layoutGenerator": "DemoBlueprintProject.Layout.generate_layout",
    "parameterSpec" : {
           "WorkflowName" : {
                "type": "String",
                "collection": false
           },
           "WorkerType" : {
                "type": "String",
                "collection": false,
                "allowedValues": ["G1.X", "G2.X"],
                "defaultValue": "G1.X"
           },
           "Dpu" : {
                "type" : "Integer",
                "allowedValues" : [2, 4, 6],
                "defaultValue" : 2
           },
           "DynamoDBTableName": {
                "type": "String",
                "collection" : false
           },
           "ScriptLocation" : {
                "type": "String",
                "collection": false
    	}
    }
}
```

`layoutGenerator` 属性指定生成布局的脚本中函数的完全限定名称。

`parameterSpec` 属性指定此蓝图接受的参数。有关更多信息，请参阅 [指定蓝图参数](developing-blueprints-code-parameters.md)。

**重要**  
配置文件必须包含工作流名称作为蓝图参数，或者必须在布局脚本中生成唯一的工作流名称。

# 指定蓝图参数
<a name="developing-blueprints-code-parameters"></a>

配置文件包含 `parameterSpec` JSON 对象中的蓝图参数规范。`parameterSpec` 包含一个或多个参数对象。

```
"parameterSpec": {
    "<parameter_name>": {
      "type": "<parameter-type>",
      "collection": true|false, 
      "description": "<parameter-description>",
      "defaultValue": "<default value for the parameter if value not specified>"
      "allowedValues": "<list of allowed values>" 
    },
    "<parameter_name>": {    
       ...
    }
  }
```

以下是编码每个参数对象的规则：
+ 参数名称和 `type` 是必需的。所有其他属性均为可选属性。
+ 如果您指定 `defaultValue` 属性，则该参数是可选的。否则，参数是必需参数，并且从蓝图创建工作流的数据分析员必须为其提供值。
+ 如果您将 `collection` 属性设置为 `true`，参数可以采用值的集合。集合可以是任意数据类型。
+ 如果您指定 `allowedValues`，则 AWS Glue 控制台显示一个值下拉列表，供数据分析人员在从蓝图创建工作流时进行选择。

以下是 `type` 允许的值：


| 参数数据类型 | 备注 | 
| --- | --- | 
| String | - | 
| Integer | - | 
| Double | - | 
| Boolean | 可能的值为 true 和 false。AWS Glue 控制台的 Create a workflow from <blueprint>（从 <蓝图> 创建工作流）页面生成的一个复选框。 | 
| S3Uri | 从 s3:// 开始完成 Amazon S3 路径。Create a workflow from <blueprint> (从 <blueprint> 创建工作流) 页面生成文本字段和 Browse (浏览) 按钮。 | 
| S3Bucket | 仅限 Amazon S3 存储桶名称。在 Create a workflow from <blueprint> (从 <blueprint> 创建工作流) 页生成存储桶选取器。 | 
| IAMRoleArn | AWS Identity and Access Management（IAM）角色的 Amazon Resource Name（ARN）。在 Create a workflow from <blueprint> (从 <blueprint> 创建工作流) 页生成角色选取器。 | 
| IAMRoleName | IAM 角色的名称。在 Create a workflow from <blueprint> (从 <blueprint> 创建工作流) 页生成角色选取器。 |