# 設計図コードを記述する
<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 | 2 つのプロパティ (region および accountId) を含む Python ディクショナリ。 | 

次に、`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
```

このサンプルスクリプトは、必要な設計図ライブラリをインポートし、2 つのジョブを含むワークフローを生成する `generate_layout` 関数をインクルードします。これは非常にシンプルなスクリプトです。より複雑なスクリプトでは、追加のロジックとパラメータを使用して、多数のジョブとクローラを含むワークフローを生成できます。さらに、ジョブとクローラの数を可変にすることも可能です

## DependsOn 引数を使用する
<a name="developing-blueprints-code-layout-depends-on"></a>

引数 `DependsOn` は、このエンティティがワークフロー内の他のエンティティに対し維持する依存関係を、ディクショナリ向けに表現したものです。これには、以下の形式が使用されます。

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

このディクショナリーのキーはエンティティの名前ではなく、オブジェクトリファレンスを表し、値は監視すべき状態に対応する文字列です。AWS Glue 適切なトリガーを推測します。有効な状態については、「[Condition Structure](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` には、1 つ以上のパラメータオブジェクトが含まれます。

```
"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>] (<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 リソースネーム (ARN)。[Create a workflow from <blueprint>] (<blueprint> からのワークフローの作成) ページで、ロールピッカーを生成します。 | 
| IAMRoleName | IAM ロールの名前。[Create a workflow from <blueprint>] (<blueprint> からのワークフローの作成) ページで、ロールピッカーを生成します。 |