# AWS Glue for Spark ETL スクリプトのプログラミングの機能と最適化 以下のセクションでは、言語を問わず、AWS Glue for Spark ETL (抽出、変換、ロード) プログラミングに適用される一般的な手法と値について説明します。 **Topics** + [AWS Glue for Spark での ETL の接続タイプとオプション](aws-glue-programming-etl-connect.md) + [AWS Glue for Spark での入出力のデータ形式に関するオプション](aws-glue-programming-etl-format.md) + [Spark SQL ジョブ用の AWS Glue Data Catalog のサポート](aws-glue-programming-etl-glue-data-catalog-hive.md) + [ジョブのブックマークを使用する](programming-etl-connect-bookmarks.md) + [AWS Glue Studio 外での機密データ検出の使用](aws-glue-api-sensitive-data-example.md) + [AWS Glue ビジュアルジョブ API](visual-job-api-chapter.md) # AWS Glue for Spark での ETL の接続タイプとオプション AWS Glue for Spark では、PySpark と Scala のさまざまなメソッドと変換で、`connectionType` パラメータを使用しながら接続タイプを指定します。`connectionOptions` または `options` パラメータを使用して接続オプションを指定します。 `connectionType` パラメータには、次の表に示す値を指定できます。各タイプの関連する `connectionOptions` (または `options`) パラメータ値については、以下のセクションで説明します。特に明記されていない限り、パラメータは、接続がソースまたはシンクとして使用されるときに適用されます。 接続オプションの設定と使用方法を示すサンプルコードについては、「各接続タイプのホームページ」を参照してください。 | `connectionType` | 接続先 | | --- | --- | | [dynamodb](aws-glue-programming-etl-connect-dynamodb-home.md) | [Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) データベース | | [kinesis](aws-glue-programming-etl-connect-kinesis-home.md) | [Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/introduction.html) | | [s3](aws-glue-programming-etl-connect-s3-home.md) | [Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/dev/) | | [documentdb](aws-glue-programming-etl-connect-documentdb-home.md#aws-glue-programming-etl-connect-documentdb) | [Amazon DocumentDB (MongoDB 互換)](https://docs.aws.amazon.com/documentdb/latest/developerguide/) データベース | | [opensearch](aws-glue-programming-etl-connect-opensearch-home.md) | [Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/)。 | | [Redshift](aws-glue-programming-etl-connect-redshift-home.md) | [Amazon Redshift](https://aws.amazon.com/redshift/) データベース | | [kafka](aws-glue-programming-etl-connect-kafka-home.md) | [Kafka](https://kafka.apache.org/) または [Amazon Managed Streaming for Apache Kafka](https://docs.aws.amazon.com/msk/latest/developerguide/what-is-msk.html) | | [azurecosmos](aws-glue-programming-etl-connect-azurecosmos-home.md) | Azure Cosmos for NoSQL。 | | [azuresql](aws-glue-programming-etl-connect-azuresql-home.md) | Azure SQL。 | | [bigquery](aws-glue-programming-etl-connect-bigquery-home.md) | Google BigQuery。 | | [mongodb](aws-glue-programming-etl-connect-mongodb-home.md) | [MongoDB](https://www.mongodb.com/what-is-mongodb) データベース (MongoDB Atlas を含む)。 | | [sqlserver](aws-glue-programming-etl-connect-jdbc-home.md) | Microsoft SQL Server データベース (「[JDBC 接続](aws-glue-programming-etl-connect-jdbc-home.md)」を参照) | | [mysql](aws-glue-programming-etl-connect-jdbc-home.md) | [MySQL](https://www.mysql.com/) データベース (「[JDBC 接続](aws-glue-programming-etl-connect-jdbc-home.md)」を参照) | | [oracle](aws-glue-programming-etl-connect-jdbc-home.md) | [Oracle](https://www.oracle.com/database/) データベース (「[JDBC 接続](aws-glue-programming-etl-connect-jdbc-home.md)」を参照) | | [postgresql](aws-glue-programming-etl-connect-jdbc-home.md) | [PostgreSQL](https://www.postgresql.org/) データベース (「[JDBC 接続](aws-glue-programming-etl-connect-jdbc-home.md)」を参照) | | [saphana](aws-glue-programming-etl-connect-saphana-home.md) | SAP HANA。 | | [snowflake](aws-glue-programming-etl-connect-snowflake-home.md) | [Snowflake](https://www.snowflake.com/) データレイク | | [teradata](aws-glue-programming-etl-connect-teradata-home.md) | Teradata Vantage。 | | [vertica](aws-glue-programming-etl-connect-vertica-home.md) | Vertica。 | | [カスタム。\$1](#aws-glue-programming-etl-connect-market) | Spark、Athena、または JDBC データストア (「[カスタムと AWS Marketplace での、connectionType の値](#aws-glue-programming-etl-connect-market)」 を参照 | | [marketplace.\$1](#aws-glue-programming-etl-connect-market) | Spark、Athena、または JDBC データストア (「[カスタムと AWS Marketplace での、connectionType の値](#aws-glue-programming-etl-connect-market)」を参照) | # DynamoDB 接続　 Spark 用の AWS Glue を使用して AWS Glue の DynamoDB 内のテーブルに対する読み込みと書き込みを行うことができます。AWS Glue ジョブにアタッチされている IAM 権限を使用して DynamoDB に接続します。AWS Glue は、別の AWS アカウントの DynamoDB テーブルに対するデータの書き込みをサポートしています。詳細については、「[DynamoDB テーブルへのクロスアカウントおよびクロスリージョンでのアクセス](aws-glue-programming-etl-dynamo-db-cross-account.md)」を参照してください。 元の DynamoDB コネクタは Glue DynamicFrame オブジェクトを使用して、DynamoDB から抽出されたデータを操作します。AWSGlue 5.0\$1 では、Spark DataFrame をネイティブにサポートする新しい [Spark DataFrame をサポートする DynamoDB コネクタ](aws-glue-programming-etl-connect-dynamodb-dataframe-support.md)が導入されています。 AWS Glue DynamoDB ETL コネクターに加えて、DynamoDB エクスポートコネクターを使用して DynamoDB から読み取ることができます。このコネクターは、DynamoDB `ExportTableToPointInTime` リクエストを呼び出し、これを指定した Amazon S3 の場所に [DynamoDB JSON](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataExport.Output.html) 形式で保存します。次に、AWS Glue は、Amazon S3 のエクスポート場所からデータを読み取ることによって DynamicFrame オブジェクトを作成します。 DynamoDB のライターは、AWS Glue バージョン 1.0 以降で利用可能です。AWS Glue DynamoDB のエクスポートコネクターは、AWS Glue バージョン 2.0 以降で利用可能です。新しい DataFrame ベースの DynamoDB コネクタは、AWS Glue バージョン 5.0 以降で利用可能です。 DynamoDB の詳細については、[Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) のドキュメントを参照してください。 **注記** DynamoDB ETL リーダーでは、フィルタまたはプッシュダウン述語は使用できません。 ## DynamoDB 接続の設定 AWS Glue から DynamoDB に接続するには、AWS Glue ジョブに関連付けられた IAM ロールに DynamoDB と対話する権限を付与します。DynamoDB からの読み取りまたは書き込みに必要な権限の詳細については、「IAM ドキュメント」の [DynamoDB のアクション、リソース、および条件キー](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazondynamodb.html)を参照してください。 次の状況では、追加の設定が必要になる場合があります。　 + DynamoDB エクスポートコネクターを使用するときは、ジョブが DynamoDB テーブルのエクスポートをリクエストできるように IAM を設定する必要があります。さらに、エクスポート用の Amazon S3 バケットを特定し、DynamoDB がそのバケットに書き込むための適切な権限と、AWS Glue ジョブがそこから読み取るための適切な権限を IAM に付与する必要があります。詳細については、「[DynamoDB でテーブルのエクスポートをリクエストする](https://docs.aws.amazon.com//amazondynamodb/latest/developerguide/S3DataExport_Requesting.html)」を参照してください。　　 + AWS Glue ジョブに特定の Amazon VPC 接続要件がある場合は、`NETWORK` AWS Glue 接続タイプを使用してネットワークオプションを指定します。DynamoDB へのアクセスは IAM によって承認されるため、AWS Glue DynamoDB 接続タイプは必要ありません。　 ## DynamoDB からの読み込みと書き込み 次のコード例では、DynamoDB テーブルからの読み取り (ETL コネクタ経由) と、DynamoDB のテーブルへの書き込み方法を示します。ここでは、あるテーブルから読み取りを行い、別のテーブルに対して書き込みを行っています。 ------ #### [ Python ] ``` import sys from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.job import Job from awsglue.utils import getResolvedOptions args = getResolvedOptions(sys.argv, ["JOB_NAME"]) glue_context= GlueContext(SparkContext.getOrCreate()) job = Job(glue_context) job.init(args["JOB_NAME"], args) dyf = glue_context.create_dynamic_frame.from_options( connection_type="dynamodb", connection_options={"dynamodb.input.tableName": test_source, "dynamodb.throughput.read.percent": "1.0", "dynamodb.splits": "100" } ) print(dyf.getNumPartitions()) glue_context.write_dynamic_frame_from_options( frame=dyf, connection_type="dynamodb", connection_options={"dynamodb.output.tableName": test_sink, "dynamodb.throughput.write.percent": "1.0" } ) job.commit() ``` ------ #### [ Scala ] ``` import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.util.GlueArgParser import com.amazonaws.services.glue.util.Job import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.DynamoDbDataSink import org.apache.spark.SparkContext import scala.collection.JavaConverters._ object GlueApp { def main(sysArgs: Array[String]): Unit = { val glueContext = new GlueContext(SparkContext.getOrCreate()) val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) val dynamicFrame = glueContext.getSourceWithFormat( connectionType = "dynamodb", options = JsonOptions(Map( "dynamodb.input.tableName" -> test_source, "dynamodb.throughput.read.percent" -> "1.0", "dynamodb.splits" -> "100" )) ).getDynamicFrame() print(dynamicFrame.getNumPartitions()) val dynamoDbSink: DynamoDbDataSink = glueContext.getSinkWithFormat( connectionType = "dynamodb", options = JsonOptions(Map( "dynamodb.output.tableName" -> test_sink, "dynamodb.throughput.write.percent" -> "1.0" )) ).asInstanceOf[DynamoDbDataSink] dynamoDbSink.writeDynamicFrame(dynamicFrame) Job.commit() } } ``` ------ ## DynamoDB エクスポートコネクタを使用する DynamoDB テーブルサイズが 80 GB を超える場合、エクスポートコネクタは ETL コネクタよりもパフォーマンスが向上します。さらに、エクスポートリクエストが AWS Glue ジョブで Spark プロセスの外部で実行される場合、[AWS Glue ジョブの自動スケーリング](https://docs.aws.amazon.com/glue/latest/dg/auto-scaling.html)を有効にして、エクスポートリクエスト中の DPU 使用量を節約できます。エクスポートコネクタでは、Spark エグゼキューターの並列処理のためのスプリット数や、DynamoDB スループットの読み取り率を設定する必要がありません。 **注記** DynamoDBには、`ExportTableToPointInTime` リクエストを呼び出すための特定の要件があります。詳細については、「[DynamoDB でテーブルのエクスポートをリクエストする](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataExport.Requesting.html)」を参照してください。例えば、このコネクタを使用するには、テーブルでポイントインタイムリストア (PITR) を有効にする必要があります。DynamoDB コネクタは、Amazon S3 への DynamoDB エクスポートの AWS KMS 暗号化もサポートします。AWS Glue ジョブの設定でセキュリティ設定を指定することで、DynamoDB エクスポートの AWS KMS 暗号化が有効になります。KMS キーは、Amazon S3 バケットと同じリージョンにある必要があります。 DynamoDB エクスポートと Amazon S3 ストレージのコストに追加料金が適用されることに注意してください。Amazon S3 でエクスポートされたデータは、ジョブ実行の終了後も保持されるため、DynamoDB を追加でエクスポートしなくても再利用できます。このコネクタを使用するための要件として、テーブルに対してポイントインタイムリカバリ (PITR) が有効になっていることが必要です。 DynamoDB ETL コネクタまたはエクスポートコネクタは、DynamoDB ソースに適用されるフィルタまたはプッシュダウン述語をサポートしていません。 次のコード例は、（エクスポートコネクタを経由して）読み取り、パーティションの数を出力する方法を示しています。 ------ #### [ Python ] ``` import sys from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.job import Job from awsglue.utils import getResolvedOptions args = getResolvedOptions(sys.argv, ["JOB_NAME"]) glue_context= GlueContext(SparkContext.getOrCreate()) job = Job(glue_context) job.init(args["JOB_NAME"], args) dyf = glue_context.create_dynamic_frame.from_options( connection_type="dynamodb", connection_options={ "dynamodb.export": "ddb", "dynamodb.tableArn": test_source, "dynamodb.s3.bucket": bucket_name, "dynamodb.s3.prefix": bucket_prefix, "dynamodb.s3.bucketOwner": account_id_of_bucket, } ) print(dyf.getNumPartitions()) job.commit() ``` ------ #### [ Scala ] ``` import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.util.GlueArgParser import com.amazonaws.services.glue.util.Job import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.DynamoDbDataSink import org.apache.spark.SparkContext import scala.collection.JavaConverters._ object GlueApp { def main(sysArgs: Array[String]): Unit = { val glueContext = new GlueContext(SparkContext.getOrCreate()) val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) val dynamicFrame = glueContext.getSourceWithFormat( connectionType = "dynamodb", options = JsonOptions(Map( "dynamodb.export" -> "ddb", "dynamodb.tableArn" -> test_source, "dynamodb.s3.bucket" -> bucket_name, "dynamodb.s3.prefix" -> bucket_prefix, "dynamodb.s3.bucketOwner" -> account_id_of_bucket, )) ).getDynamicFrame() print(dynamicFrame.getNumPartitions()) Job.commit() } } ``` ------ これらの例は、（エクスポートコネクタを介して）読み取りを行い、`dynamodb` 分類を持つ AWS Glue データカタログテーブルからパーティションの数を出力する方法を示しています。　　　　　　 ------ #### [ Python ] ``` import sys from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.job import Job from awsglue.utils import getResolvedOptions args = getResolvedOptions(sys.argv, ["JOB_NAME"]) glue_context= GlueContext(SparkContext.getOrCreate()) job = Job(glue_context) job.init(args["JOB_NAME"], args) dynamicFrame = glue_context.create_dynamic_frame.from_catalog( database=catalog_database, table_name=catalog_table_name, additional_options={ "dynamodb.export": "ddb", "dynamodb.s3.bucket": s3_bucket, "dynamodb.s3.prefix": s3_bucket_prefix } ) print(dynamicFrame.getNumPartitions()) job.commit() ``` ------ #### [ Scala ] ``` import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.util.GlueArgParser import com.amazonaws.services.glue.util.Job import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.DynamoDbDataSink import org.apache.spark.SparkContext import scala.collection.JavaConverters._ object GlueApp { def main(sysArgs: Array[String]): Unit = { val glueContext = new GlueContext(SparkContext.getOrCreate()) val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) val dynamicFrame = glueContext.getCatalogSource( database = catalog_database, tableName = catalog_table_name, additionalOptions = JsonOptions(Map( "dynamodb.export" -> "ddb", "dynamodb.s3.bucket" -> s3_bucket, "dynamodb.s3.prefix" -> s3_bucket_prefix )) ).getDynamicFrame() print(dynamicFrame.getNumPartitions()) ) ``` ------ ## DynamoDB エクスポート JSON の使用を簡素化 AWS Glue DynamoDB エクスポートコネクタを使用した DynamoDB エクスポートでは、特殊なネスト構造の JSON ファイルが生成されます。詳細については、[データオブジェクト](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/S3DataExport.Output.html)を参照してください。 AWS Glue は DynamicFrame 変換を提供します。これを使用して、このような構造をダウンストリームアプリケーションで使いやすい形式に変換できます。 変換は 2 つの方法のいずれかで起動できます。。DynamoDB から読み取るメソッドを呼び出すときに、値 `"true"` を使用して接続オプション `"dynamodb.simplifyDDBJson"` を設定できます。また、AWS Glue ライブラリで独立して利用可能なメソッドとして変換を呼び出すこともできます。 DynamoDB エクスポートによって生成された次のスキーマを考えてみましょう。 ``` root |-- Item: struct | |-- parentMap: struct | | |-- M: struct | | | |-- childMap: struct | | | | |-- M: struct | | | | | |-- appName: struct | | | | | | |-- S: string | | | | | |-- packageName: struct | | | | | | |-- S: string | | | | | |-- updatedAt: struct | | | | | | |-- N: string | |-- strings: struct | | |-- SS: array | | | |-- element: string | |-- numbers: struct | | |-- NS: array | | | |-- element: string | |-- binaries: struct | | |-- BS: array | | | |-- element: string | |-- isDDBJson: struct | | |-- BOOL: boolean | |-- nullValue: struct | | |-- NULL: boolean ``` この `simplifyDDBJson` 変換により、以下のように簡略化されます。 ``` root |-- parentMap: struct | |-- childMap: struct | | |-- appName: string | | |-- packageName: string | | |-- updatedAt: string |-- strings: array | |-- element: string |-- numbers: array | |-- element: string |-- binaries: array | |-- element: string |-- isDDBJson: boolean |-- nullValue: null ``` **注記** `simplifyDDBJson` は、AWS Glue バージョン 3.0 以降で有効です。`unnestDDBJson` トランスフォームを使用して DynamoDB のエクスポート JSON を簡略化することもできます。ユーザーには `unnestDDBJson` から `simplifyDDBJson` への移行をお勧めします。 ## DynamoDB オペレーションにおける並列処理の設定 パフォーマンスを向上させるために、DynamoDB コネクタで使用できる特定のパラメーターを調整できます。並列処理パラメーターを調整する際の目標は、プロビジョニングされた AWS Glue ワーカーを最大限に活用することです。そして、さらにパフォーマンスを向上させる必要がある場合は、DPU 数を増加してジョブをスケールアウトすることをお勧めします。 ETL コネクタを使用する場合、`dynamodb.splits` パラメータを使用して DynamoDB 読み取りオペレーションの並列処理を変更できます。　 エクスポートコネクタで読み込みをする場合は、Spark エグゼキュータの並列処理の分割数を構成する必要がありません。DynamoDB 書き込みオペレーションの並列処理は、`dynamodb.output.numParallelTasks` を使用して変更できます。 **DynamoDB ETL コネクターによる読み取り** `dynamodb.splits`ジョブ構成に設定されている最大ワーカー数と以下 `numSlots` の計算に基づいて計算することをお勧めします。自動スケーリングの場合、実際に利用可能なワーカー数は、その上限に基づいて変更される可能性があります。最大ワーカー数の設定についての詳細は、「[AWS Glue で Spark ジョブに関するジョブプロパティの構成](add-job.md)」の「**[ワーカー数**] (`NumberOfWorkers`)」を参照してください。 + `numExecutors = NumberOfWorkers - 1` 1 つのエグゼキューターが Spark ドライバー専用になっている場合、他のエグゼキューターはデータの処理に使用されます。 + `numSlotsPerExecutor =` ------ #### [ AWS Glue 3.0 and later versions ] + `WorkerType` が `G.1X` の場合は `4` + `WorkerType` が `G.2X` の場合は `8` + `WorkerType` が `G.4X` の場合は `16` + `WorkerType` が `G.8X` の場合は `32` ------ #### [ AWS Glue 2.0 and legacy versions ] + `WorkerType` が `G.1X` の場合は `8` + `WorkerType` が `G.2X` の場合は `16` ------ + `numSlots = numSlotsPerExecutor * numExecutors` `dynamodb.splits` を使用可能なスロット数、`numSlots` に設定することをおすすめします。 **DynamoDB への書き込み**　 この `dynamodb.output.numParallelTasks` パラメータは、以下の計算を使用して Spark タスクごとの WCU を決定するために使用されます。 `permittedWcuPerTask = ( TableWCU * dynamodb.throughput.write.percent ) / dynamodb.output.numParallelTasks` DynamoDB ライターは、設定が DynamoDB に書き込まれる Spark タスクの数を正確に表している場合に最適に機能します。場合によっては、書き込みパフォーマンスを向上させるために、デフォルトの計算をオーバーライドする必要がある場合があります。このパラメータを指定しない場合、Spark タスクごとに許可される WCU は、次の式により自動的に計算されます。 + + `numPartitions = dynamicframe.getNumPartitions()` + `numSlots` (このセクションすでに定義したとおり) + `numParallelTasks = min(numPartitions, numSlots)` + 例 1。DPU=10、WorkerType=Standard。入力 DynamicFrame には、100 個の RDD パーティションがあります。 + `numPartitions = 100` + `numExecutors = (10 - 1) * 2 - 1 = 17` + `numSlots = 4 * 17 = 68` + `numParallelTasks = min(100, 68) = 68` + 例 2。DPU=10、WorkerType=Standard。入力 DynamicFrame には、20 個の RDD パーティションがあります。 + `numPartitions = 20` + `numExecutors = (10 - 1) * 2 - 1 = 17` + `numSlots = 4 * 17 = 68` + `numParallelTasks = min(20, 68) = 20` **注記** 従来の AWS Glue バージョンのジョブと Standard Worker を使用するジョブでは、スロット数を計算するために違った方法が必要となります。これらのジョブのパフォーマンスを調整する必要がある場合は、サポートされている AWS Glue バージョンに移行することをおすすめします。 ## DynamoDB 接続オプションのリファレンス Amazon DynamoDB への接続を指定します。 接続オプションは、ソース接続とシンク接続とで異なります。 ### "connectionType": ソースとして ETL コネクタを使用する "dynamodb" AWS Glue DynamoDB ETL コネクタを使用している場合は、`"connectionType": "dynamodb"` をソースとして次の接続オプションを使用します。 + `"dynamodb.input.tableName"`: (必須) 読み取り元の DynamoDB テーブル。 + `"dynamodb.throughput.read.percent"`: (オプション) 使用する読み込みキャパシティーユニット (RCU) の割合。デフォルトでは、"0.5" に設定されます。許容値は "0.1" から "1.5" (これらの値を含む) です。 + `0.5` ではデフォルトの読み込み速度を表し、AWS Glue はテーブルの読み込み容量の半分を消費しようとすることを意味します。上記の値を `0.5` より上に設定すると、AWS Glue は読み取りのリクエストレートを増加させ、`0.5` より低くした場合はそのリクエストレートを減少させます。(実際の読み込みレートは、DynamoDB テーブルに、統一ディストリビューションのキーがあるかどうかなどの要因によって変わります。) + DynamoDB テーブルがオンデマンドモードの場合、AWS Glue はテーブルの読み取り容量を 40000 として処理します。大きなテーブルをエクスポートする場合は、DynamoDB テーブルをオンデマンドモードに切り替えることをお勧めします。 + `"dynamodb.splits"`: (オプション) 読み取り中にこの DynamoDB テーブルを分割するパーティションの数を定義します。デフォルトでは、"1" に設定されます。許容値は "1" から "1,000,000" (これらの値を含む) です。 `1` は並列処理がないことを表します。より良いパフォーマンスを得るためには、より大きな値を (以下の式を使用して) 指定することを強くお勧めします。値を適切に設定する方法の詳細は、「[DynamoDB オペレーションにおける並列処理の設定](#aws-glue-programming-etl-connect-dynamodb-parallelism)」を参照してください。 + `"dynamodb.sts.roleArn"`: (オプション) クロスアカウントアクセスのために引き受ける IAM ロール の ARN。このパラメータは、AWS Glue 1.0 以降で使用可能です。 + `"dynamodb.sts.roleSessionName"`: (任意) STS セッション名。デフォルトでは、「glue-dynamodb-read-sts-session」に設定されています。このパラメータは、AWS Glue 1.0 以降で使用可能です。 ### "connectionType"：AWS Glue DynamoDB エクスポートコネクタをソースとする "dynamodb" AWS Glue バージョン 2.0 以降でのみ使用可能な AWS Glue DynamoDB エクスポートコネクタを使用する場合は、ソースとして "connectionType": "dynamodb" で次の接続オプションを使用します。 + `"dynamodb.export"`: (必須) 文字列値: + `ddb` に設定すると、AWS Glue DynamoDB エクスポートコネクタが有効になり、AWS Glue ジョブ中に新しい `ExportTableToPointInTimeRequest` が呼び出されます。`dynamodb.s3.bucket` と `dynamodb.s3.prefix` から渡された場所で新しいエクスポートが生成されます。 + `s3` に設定すると、AWS Glue DynamoDB エクスポートコネクタが有効になりますが、新しい DynamoDB エクスポートの作成はスキップされ、代わりに `dynamodb.s3.bucket` と `dynamodb.s3.prefix` がそのテーブルの過去のエクスポートの Amazon S3 ロケーションとして使用されます。 + `"dynamodb.tableArn"`: (必須) 読み取り元の DynamoDB テーブル。 + `"dynamodb.unnestDDBJson"`: (オプション) デフォルト: false。　 有効な値: ブール値　 true に設定すると、エクスポートに存在する DynamoDB JSON 構造体のネスト解除の変換が実行されます。`"dynamodb.unnestDDBJson"` と `"dynamodb.simplifyDDBJson"` を同時に true に設定するとエラーになります。AWS Glue 3.0 以降のバージョンでは、DynamoDB マップタイプを簡略化するときの動作を改善するために `"dynamodb.simplifyDDBJson"` を使用することをおすすめします。詳細については、「[DynamoDB エクスポート JSON の使用を簡素化](#etl-connect-dynamodb-traversing-structure)」を参照してください。 + `"dynamodb.simplifyDDBJson"`: (オプション) デフォルト: false。　 有効な値: ブール値　 true に設定すると、エクスポートに存在する DynamoDB JSON 構造のスキーマを簡素化するための変換を実行します。これは `"dynamodb.unnestDDBJson"` オプションと同じ目的ですが、DynamoDB テーブル内の DynamoDB マップタイプやネストされたマップタイプをより適切にサポートします。このオプションは、AWS Glue バージョン 3.0 以降でのみ有効です。`"dynamodb.unnestDDBJson"` と `"dynamodb.simplifyDDBJson"` を同時に true に設定するとエラーになります。詳細については、「[DynamoDB エクスポート JSON の使用を簡素化](#etl-connect-dynamodb-traversing-structure)」を参照してください。 + `"dynamodb.s3.bucket"`: (オプション) DynamoDB `ExportTableToPointInTime` プロセスが実行される Simple Storage Service (Amazon S3) バケットの場所を示します。エクスポートファイル形式は DynamoDB JSON です。 + `"dynamodb.s3.prefix"`: (オプション) DynamoDB `ExportTableToPointInTime` の読み込みが保存される Simple Storage Service (Amazon S3) バケット内の Amazon S3 プレフィックスの場所を示します。`dynamodb.s3.prefix` と `dynamodb.s3.bucket` のどちらも指定しなかった場合、これらの値は AWS Glue ジョブの設定で指定された一時ディレクトリの場所がデフォルトとなります。詳細については、「[AWS Glue で使用される特別なパラメータ](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-glue-arguments.html)」を参照してください。 + `"dynamodb.s3.bucketOwner"`: クロスアカウント Simple Storage Service (Amazon S3) アクセスのために必要なバケット所有者を示します。 + `"dynamodb.sts.roleArn"`: (オプション) DynamoDB テーブルのクロスアカウントアクセスおよび/またはクロスリージョンアクセスのために割り当てる IAM ロール の ARN。注: 同じ IAM ロール のARN を使用して、`ExportTableToPointInTime` リクエストに指定された Simple Storage Service (Amazon S3) の場所にアクセスします。 + `"dynamodb.sts.roleSessionName"`: (任意) STS セッション名。デフォルトでは、「glue-dynamodb-read-sts-session」に設定されています。 + `"dynamodb.exportTime"` (オプション) 有効な値: ISO-8601 インスタントを表す文字列。　 エクスポートが実行されるべき時点。 + `"dynamodb.sts.region"`: (リージョンのエンドポイントを使用してリージョン間通話を行う場合は必須) 読み取りたい DynamoDB テーブルをホストするリージョン。 ### "connectionType": ETLコネクタをシンクとして使用する "dynamodb" `"connectionType": "dynamodb"` をシンクとして、次の接続オプションを使用します。 + `"dynamodb.output.tableName"`: (必須) 書き込み先の DynamoDB テーブル。 + `"dynamodb.throughput.write.percent"`: (オプション) 使用する書き込みキャパシティーユニット (WCU) の割合。デフォルトでは、"0.5" に設定されます。許容値は "0.1" から "1.5" (これらの値を含む) です。 + `0.5` ではデフォルトの読み込み速度を表し、AWS Glue はテーブルの書き込み容量の半分を消費しようとすることを意味します。上記の値を 0.5 より上に設定すると、AWS Glue は書き込みリクエストレートを増加させ、0.5 より低くした場合はそのリクエストレートを減少させます。(実際の書き込みレートは、統一されたキーのディストリビューションが、DynamoDB テーブルにあるかどうかなどの要因によって変わります)。 + DynamoDB テーブルがオンデマンドモードの場合、AWS Glue はテーブルの書き込み容量を `40000` として処理します。大きなテーブルをインポートする場合は、DynamoDB テーブルをオンデマンドモードに切り替えることをお勧めします。 + `"dynamodb.output.numParallelTasks"`: (オプション) 同時に DynamoDB に書き込める並列タスクの数を定義します。Spark タスクごとに許容される WCU を計算するために使用されます。ほとんどの場合、AWS Glue はこの値の妥当なデフォルト値を計算します。　 詳細については、「[DynamoDB オペレーションにおける並列処理の設定](#aws-glue-programming-etl-connect-dynamodb-parallelism)」を参照してください。 + `"dynamodb.output.retry"`: (オプション) DynamoDB から `ProvisionedThroughputExceededException` が送られている場合の、再試行の実行回数を定義します。デフォルトでは、"10" に設定されています。 + `"dynamodb.sts.roleArn"`: (オプション) クロスアカウントアクセスのために引き受ける IAM ロール の ARN。 + `"dynamodb.sts.roleSessionName"`: (任意) STS セッション名。デフォルトでは、「glue-dynamodb-write-sts-session」に設定されています。 # DynamoDB テーブルへのクロスアカウントおよびクロスリージョンでのアクセス AWS Glue ETL ジョブでは、DynamoDB テーブルに対する、クロスリージョンならびにクロスアカウントでのアクセスを供にサポートしています。AWS GlueETL ジョブは、別の AWS アカウントの DynamoDB テーブルからのデータ読み取り、および別の AWS アカウントの DynamoDB テーブルへのデータ書き込みをサポートしています。加えて AWS Glue では、別のリージョンの DynamoDB テーブルからの読み取りと、別のリージョンの DynamoDB テーブルへの書き込みもサポートしています。このセクションでは、このアクセスを設定する手順と、スクリプトの例を示します。 このセクションに示す手順では、IAM のチュートリアルに則り、IAM ロールを作成しそのロールにアクセス許可を付与しています。このチュートリアルでは、ロールの引き受けについても解説されていますが、今回はその代わりに、AWS Glue でのロールの引き受けにはジョブ・スクリプトを使用します。また、このチュートリアルでは、クロスアカウントに関連した一般的な作業についても説明しています。詳しくは、*IAM ユーザーガイド*の「[チュートリアル: IAMロールを使用した AWS アカウント間のアクセス権の委譲](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html)」を参照してください。 ## ロールを作成する [チュートリアルのステップ 1](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html#tutorial_cross-account-with-roles-1) に従い、アカウント A に IAM ロールを作成します。ロールのアクセス許可を定義する際に、`AmazonDynamoDBReadOnlyAccess` または `AmazonDynamoDBFullAccess` など既存のポリシーをアタッチして、ロールに対し DynamoDB の読み取り/書き込みを許可します。次の例に、アクセス許可ポリシー `AmazonDynamoDBFullAccess` を使用する、`DynamoDBCrossAccessRole` という名前のロールを作成する方法を示します。 ## ロールにアクセス許可を付与する *IAM ユーザーガイド*にある[チュートリアルのステップ 2](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html#tutorial_cross-account-with-roles-2) に従い、アカウント B が新しく作成されたロールに切り替えることを許可します。次の例では、ここで示されるステートメントを使用して新しいポリシーを作成しています。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::111122223333:role/DynamoDBCrossAccessRole" } } ``` ------ 次に、DynamoDB へのアクセスに使用するグループ/ロール/ユーザーに、このポリシーをアタッチします。 ## AWS Glue Job スクリプトの中でロールを引き受ける この段階で、アカウント B にログインして、AWS Glue ジョブを作成できるようになっています。ジョブを作成するには、[AWS Glue で Spark ジョブに関するジョブプロパティの構成](add-job.md) にある手順を参照してください。 ジョブスクリプト内で `DynamoDBCrossAccessRole` ロールを引き受けるには、`dynamodb.sts.roleArn` パラメーターを使用する必要があります。このロールを引き受けることで、アカウント B の DynamoDB にアクセスするために必要な、一時的な認証情報を取得できます。このためのサンプルスクリプトを示します。 リージョン間でのクロスアカウント読み取りの場合 (ETL コネクタ): ``` import sys from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.job import Job from awsglue.utils import getResolvedOptions args = getResolvedOptions(sys.argv, ["JOB_NAME"]) glue_context= GlueContext(SparkContext.getOrCreate()) job = Job(glue_context) job.init(args["JOB_NAME"], args) dyf = glue_context.create_dynamic_frame_from_options( connection_type="dynamodb", connection_options={ "dynamodb.region": "us-east-1", "dynamodb.input.tableName": "test_source", "dynamodb.sts.roleArn": "" } ) dyf.show() job.commit() ``` リージョン間でのクロスアカウント読み取りの場合 (ETL コネクタ): ``` import sys from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.job import Job from awsglue.utils import getResolvedOptions args = getResolvedOptions(sys.argv, ["JOB_NAME"]) glue_context= GlueContext(SparkContext.getOrCreate()) job = Job(glue_context) job.init(args["JOB_NAME"], args) dyf = glue_context.create_dynamic_frame_from_options( connection_type="dynamodb", connection_options={ "dynamodb.export": "ddb", "dynamodb.tableArn": "", "dynamodb.sts.roleArn": "" } ) dyf.show() job.commit() ``` リージョンにまたがるクロスアカウント読み取りおよび書き込みの場合: ``` import sys from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.job import Job from awsglue.utils import getResolvedOptions args = getResolvedOptions(sys.argv, ["JOB_NAME"]) glue_context= GlueContext(SparkContext.getOrCreate()) job = Job(glue_context) job.init(args["JOB_NAME"], args) dyf = glue_context.create_dynamic_frame_from_options( connection_type="dynamodb", connection_options={ "dynamodb.region": "us-east-1", "dynamodb.input.tableName": "test_source" } ) dyf.show() glue_context.write_dynamic_frame_from_options( frame=dyf, connection_type="dynamodb", connection_options={ "dynamodb.region": "us-west-2", "dynamodb.output.tableName": "test_sink", "dynamodb.sts.roleArn": "" } ) job.commit() ``` # Spark DataFrame をサポートする DynamoDB コネクタ Spark DataFrame をサポートする DynamoDB コネクタを使用すると、Spark DataFrame API を使用して DynamoDB 内のテーブルとの間で読み書きを行うことができます。コネクタのセットアップ手順は DynamicFrame ベースのコネクタの場合と同じで、[こちら](aws-glue-programming-etl-connect-dynamodb-home.md#aws-glue-programming-etl-connect-dynamodb-configure)から確認できます。 DataFrame ベースのコネクタライブラリにロードするには、必ず DynamoDB 接続を Glue ジョブにアタッチしてください。 **注記** Glue コンソール UI は現在、DynamoDB 接続の作成をサポートしていません。Glue CLI ([CreateConnection](https://docs.aws.amazon.com/cli/latest/reference/glue/create-connection.html)) を使用して DynamoDB 接続を作成できます。 ``` aws glue create-connection \ --connection-input '{ \ "Name": "my-dynamodb-connection", \ "ConnectionType": "DYNAMODB", \ "ConnectionProperties": {}, \ "ValidateCredentials": false, \ "ValidateForComputeEnvironments": ["SPARK"] \ }' ``` DynamoDB 接続を作成すると、Glue ジョブに CLI ([CreateJob](https://docs.aws.amazon.com/cli/latest/reference/glue/create-job.html)、[UpdateJob](https://docs.aws.amazon.com/cli/latest/reference/glue/update-job.html)) を介してアタッチするか、「ジョブの詳細」ページで直接アタッチすることができます。 ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/images/dynamodb-dataframe-connector.png) DYNAMODB タイプの接続が Glue ジョブにアタッチされたら、DataFrame ベースのコネクタから次の読み取り、書き込み、エクスポートオペレーションを使用できます。 ## DataFrame ベースのコネクタを使用した DynamoDB からの読み取りと書き込み 次のコード例は、DynamoDB ベースのコネクタを介した DynamoDB に対する読み込みと書き込みを行う方法を方法を示します。ここでは、あるテーブルから読み取りを行い、別のテーブルに対して書き込みを行っています。 ------ #### [ Python ] ``` import sys from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.job import Job from awsglue.utils import getResolvedOptions args = getResolvedOptions(sys.argv, ["JOB_NAME"]) glue_context= GlueContext(SparkContext.getOrCreate()) spark = glueContext.spark_session job = Job(glue_context) job.init(args["JOB_NAME"], args) # Read from DynamoDB df = spark.read.format("dynamodb") \ .option("dynamodb.input.tableName", "test-source") \ .option("dynamodb.throughput.read.ratio", "0.5") \ .option("dynamodb.consistentRead", "false") \ .load() print(df.rdd.getNumPartitions()) # Write to DynamoDB df.write \ .format("dynamodb") \ .option("dynamodb.output.tableName", "test-sink") \ .option("dynamodb.throughput.write.ratio", "0.5") \ .option("dynamodb.item.size.check.enabled", "true") \ .save() job.commit() ``` ------ #### [ Scala ] ``` import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.util.GlueArgParser import com.amazonaws.services.glue.util.Job import org.apache.spark.SparkContext import scala.collection.JavaConverters._ object GlueApp { def main(sysArgs: Array[String]): Unit = { val glueContext = new GlueContext(SparkContext.getOrCreate()) val spark = glueContext.getSparkSession val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) val df = spark.read .format("dynamodb") .option("dynamodb.input.tableName", "test-source") .option("dynamodb.throughput.read.ratio", "0.5") .option("dynamodb.consistentRead", "false") .load() print(df.rdd.getNumPartitions) df.write .format("dynamodb") .option("dynamodb.output.tableName", "test-sink") .option("dynamodb.throughput.write.ratio", "0.5") .option("dynamodb.item.size.check.enabled", "true") .save() job.commit() } } ``` ------ ## DataFrame ベースのコネクタを介して DynamoDB エクスポートを使用する 80 GB を超える DynamoDB テーブルサイズの読み取りオペレーションでは、エクスポートオペレーションが向上します。次のコード例は、DataFrame ベースのコネクタを介してテーブルからの読み取り、S3 へのエクスポート、パーティションの数の出力を行う例を示します。 **注記** DynamoDB エクスポート機能は Scala `DynamoDBExport` オブジェクトから使用できます。Python ユーザーは、Spark の JVM インターロープを介してアクセスするか、DynamoDB `ExportTableToPointInTime` API で AWS SDK for Python (boto3) を使用することができます。 ------ #### [ Scala ] ``` import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.util.{GlueArgParser, Job} import org.apache.spark.SparkContext import glue.spark.dynamodb.DynamoDBExport import scala.collection.JavaConverters._ object GlueApp { def main(sysArgs: Array[String]): Unit = { val glueContext = new GlueContext(SparkContext.getOrCreate()) val spark = glueContext.getSparkSession val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) val options = Map( "dynamodb.export" -> "ddb", "dynamodb.tableArn" -> "arn:aws:dynamodb:us-east-1:123456789012:table/my-table", "dynamodb.s3.bucket" -> "my-s3-bucket", "dynamodb.s3.prefix" -> "my-s3-prefix", "dynamodb.simplifyDDBJson" -> "true" ) val df = DynamoDBExport.fullExport(spark, options) print(df.rdd.getNumPartitions) df.count() Job.commit() } } ``` ------ ## 設定オプション ### 読み取りオプション | オプション | 説明 | デフォルト | | --- | --- | --- | | dynamodb.input.tableName | DynamoDB テーブル名 (必須) | - | | dynamodb.throughput.read | 使用する読み込みキャパシティーユニット (RCU)。指定しない場合、dynamodb.throughput.read.ratio が計算に使用されます。 | - | | dynamodb.throughput.read.ratio | 使用する読み込みキャパシティーユニット (RCU) の比率。 | 0.5 | | dynamodb.table.read.capacity | スループットの計算に使用されるオンデマンドテーブルの読み込みキャパシティーユニット。このパラメータは、オンデマンドキャパシティーテーブルでのみ有効です。デフォルトはウォームスループット読み込みユニットです。 | - | | dynamodb.splits | 並列スキャンオペレーションで使用されるセグメントの数を定義します。指定しない場合、コネクタは妥当なデフォルト値を計算します。 | - | | dynamodb.consistentRead | 強力な整合性のある読み込みを使用するかどうか。 | FALSE | | dynamodb.input.retry | 再試行可能な例外がある場合に実行する再試行回数を定義します。 | 10 | ### 書き込みオプション | オプション | 説明 | デフォルト | | --- | --- | --- | | dynamodb.output.tableName | DynamoDB テーブル名 (必須) | - | | dynamodb.throughput.write | 使用する書き込みキャパシティーユニット (WCU)。指定しない場合、dynamodb.throughput.write.ratio が計算に使用されます。 | - | | dynamodb.throughput.write.ratio | 使用する書き込みキャパシティーユニット (WCU) の比率。 | 0.5 | | dynamodb.table.write.capacity | スループットの計算に使用されるオンデマンドテーブルの書き込みキャパシティーユニット。このパラメータは、オンデマンドキャパシティーテーブルでのみ有効です。デフォルトはウォームスループット書き込みユニットです。 | - | | dynamodb.item.size.check.enabled | true の場合、コネクタは項目サイズを計算して、サイズが最大サイズを超えた場合はDynamoDB テーブルに書き込む前に中止します。 | TRUE | | dynamodb.output.retry | 再試行可能な例外がある場合に実行する再試行回数を定義します。 | 10 | ### エクスポートオプション | オプション | 説明 | デフォルト | | --- | --- | --- | | dynamodb.export | ddb に設定すると、AWS Glue DynamoDB エクスポートコネクタが有効になり、AWS Glue ジョブ中に新しい ExportTableToPointInTimeRequet が呼び出されます。dynamodb.s3.bucket と dynamodb.s3.prefix から渡された場所で新しいエクスポートが生成されます。s3 に設定すると、AWS DynamoDB エクスポートコネクタが有効になりますが、新しい DynamoDB エクスポートの作成はスキップされ、代わりに dynamodb.s3.bucket と dynamodb.s3.prefix がそのテーブルの過去のエクスポートの Amazon S3 ロケーションとして使用されます。 | ddb | | dynamodb.tableArn | 読み取り元の DynamoDB テーブル。dynamodb.export が ddb に設定されている場合は必須です。 | | | dynamodb.simplifyDDBJson | true に設定すると、エクスポートに存在する DynamoDB JSON 構造のスキーマを簡素化するための変換を実行します。 | FALSE | | dynamodb.s3.bucket | DynamoDB エクスポート中に一時データを保存する S3 バケット (必須)。 | | | dynamodb.s3.prefix | DynamoDB エクスポート中に一時データを保存する S3 プレフィックス。 | | | dynamodb.s3.bucketOwner | クロスアカウント Simple Storage Service (Amazon S3) アクセスのために必要なバケット所有者を示します。 | | | dynamodb.s3.sse.algorithm | 一時データが保存されるバケットで使用される暗号化のタイプ。有効な値は、AES256 および KMS です。 | | | dynamodb.s3.sse.kmsKeyId | 一時データが保存される S3 バケットの暗号化に使用される AWS KMS マネージドキーの ID (該当する場合)。 | | | dynamodb.exportTime | エクスポートが実行されるべき時点。有効な値: ISO-8601 インスタントを表す文字列。　 | | ### 汎用オプション | オプション | 説明 | デフォルト | | --- | --- | --- | | dynamodb.sts.roleArn | クロスアカウントアクセスのために引き受ける IAM ロール の ARN。 | - | | dynamodb.sts.roleSessionName | STS セッション名。 | glue-dynamodb-sts-session | | dynamodb.sts.region | STS クライアントのリージョン (クロスリージョンロールの引き受け用)。 | region オプションと同じ。 | # Kinesis 接続 Kinesis 接続を使用すると、データカタログ テーブルに保存されている情報を使用して、またはデータ ストリームに直接アクセスするための情報を提供することで、Amazon Kinesis データ ストリームの読み取りと書き込みを行うことができます。Kinesis から Spark DataFrame に情報を読み取り、それを AWS Glue DynamicFrame に変換できます。DynamicFrames は JSON 形式で Kinesis に書き込むことができます。データストリームに直接アクセスする場合は、これらのオプションを使用して、データストリームへのアクセス方法に関する情報を提供します。 `getCatalogSource` または `create_data_frame_from_catalog` を使用して Kinesis ストリーミングソースからレコードを消費する場合、ジョブはデータカタログデータベースとテーブル名の情報を持っており、それを使用して Kinesis ストリーミングソースから読み込むためのいくつかの基本パラメータを取得することができます。`getSource`、`getSourceWithFormat`、`createDataFrameFromOptions`、または `create_data_frame_from_options` を使用している場合、ここで説明する接続オプションを使用して、これらの基本パラメータを指定する必要があります。 Kinesis の接続オプションは、`GlueContext` クラス内の指定されたメソッドに対して以下の引数で指定することができます。 + Scala + `connectionOptions`: `getSource`、`createDataFrameFromOptions`、`getSink` で使用 + `additionalOptions`: `getCatalogSource`、`getCatalogSink` で使用 + `options`: `getSourceWithFormat`、`getSinkWithFormat` で使用 + Python + `connection_options`: `create_data_frame_from_options`、`write_dynamic_frame_from_options` で使用 + `additional_options`: `create_data_frame_from_catalog`、`write_dynamic_frame_from_catalog` で使用 + `options`: `getSource`、`getSink` で使用 ストリーミング ETL ジョブに関する注意事項と制限事項については、「[ストリーミング ETL に関する注意と制限](add-job-streaming.md#create-job-streaming-restrictions)」を参照してください。 ## Kinesis の設定 AWS Glue Spark ジョブで Kinesis データストリームに接続するには、いくつかの前提条件が必要です。 + 読み取る場合、AWS Glue ジョブには、Kinesis データストリームへの読み取りアクセスレベルの IAM 権限が必要です。 + 書き込みの場合、AWS Glue ジョブには、Kinesis データストリームへの書き込みアクセスレベルの IAM 権限が必要です。 場合によっては、追加の前提条件を設定する必要があります。 + AWS Glue ジョブが (通常は他のデータセットに接続するための) **追加のネットワーク接続**で設定されていて、その接続のいずれかが Amazon VPC **ネットワークオプション**を提供している場合、ジョブは Amazon VPC 経由で通信するように指示されます。この場合、Amazon VPC を介して通信するように Kinesis データストリームを設定する必要もあります。そのためには、Amazon VPC と Kinesis データストリームの間にインターフェイス VPC エンドポイントを作成します。詳細については、「[インターフェイス VPC エンドポイントと Amazon Kinesis Data Streams の使用](https://docs.aws.amazon.com//streams/latest/dev/vpc.html)」を参照してください。 + 別のアカウントで Amazon Kinesis Data Streams を指定する場合は、クロスアカウントアクセスを許可するようにロールとポリシーを設定する必要があります。詳細については、「[例: 別のアカウントで Kinesis Stream から読み込む](https://docs.aws.amazon.com/kinesisanalytics/latest/java/examples-cross.html)」を参照してください。 ストリーミング ETL ジョブの前提条件の詳細については、「[AWS Glue でのストリーミング ETL ジョブ](add-job-streaming.md)」を参照してください。 ## 例: Kinesis ストリームからの読み込み ### 例: Kinesis ストリームからの読み込み [forEachBatch](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-forEachBatch) と組み合わせて使用します。 Amazon Kinesis ストリーミングソースの例: ``` kinesis_options = { "streamARN": "arn:aws:kinesis:us-east-2:777788889999:stream/fromOptionsStream", "startingPosition": "TRIM_HORIZON", "inferSchema": "true", "classification": "json" } data_frame_datasource0 = glueContext.create_data_frame.from_options(connection_type="kinesis", connection_options=kinesis_options) ``` ## 例: Kinesis ストリームへの書き込み ### 例: Kinesis ストリームからの読み込み [forEachBatch](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-forEachBatch) と組み合わせて使用します。 Amazon Kinesis ストリーミングソースの例: ``` kinesis_options = { "streamARN": "arn:aws:kinesis:us-east-2:777788889999:stream/fromOptionsStream", "startingPosition": "TRIM_HORIZON", "inferSchema": "true", "classification": "json" } data_frame_datasource0 = glueContext.create_data_frame.from_options(connection_type="kinesis", connection_options=kinesis_options) ``` ## Kinesis 接続オプションのリファレンス Amazon Kinesis Data Streams への接続を指定します。 Kinesis ストリーミングデータソースには、次の接続オプションを使用します。 + `"streamARN"` (必須) 読み取り/書き込みに使用されます。Kinesis データストリームの ARN。 + `"classification"` (読み取りに必須) 読み取りで使用。レコード内のデータで使用されるファイル形式。データカタログを通じて提供されていない限り、必須です。 + `"streamName"` - (オプション) 読み取りで使用。読み取り対象/読み取り元の Kinesis データストリームの名前。`endpointUrl` で使用。 + `"endpointUrl"` - (オプション) 読み取りで使用。デフォルト: "https://kinesis.us-east-1.amazonaws.com"。Kinesis エンドポイントの AWS エンドポイント。特別なリージョンに接続する場合を除き、これを変更する必要はありません。 + `"partitionKey"` - (オプション) 書き込みに使用。レコードを作成する際に使用される Kinesis パーティションキー。 + `"delimiter"` (オプション) 読み取りに使用。`classification` が CSV の場合に使用される値の区切り文字。デフォルトは「`,`」です。 + `"startingPosition"`: (オプション) 読み込みに使用。Kinesis データストリーム内の、データの読み取り開始位置。指定できる値は `"latest"`、`"trim_horizon"`、`"earliest"`、または UTC 形式のタイムスタンプ文字列であり、この文字列のパターンは `yyyy-mm-ddTHH:MM:SSZ` です (`Z` は UTC タイムゾーンのオフセットを \$1/- で表します。例:「2023-04-04T08:00:00-04:00」)。デフォルト値は `"latest"` です。注意: `"startingPosition"` の UTC 形式のタイムスタンプ文字列は AWS Glue バージョン 4.0 以降のみでサポートされます。 + `"failOnDataLoss"`: (オプション) アクティブなシャードがないか、有効期限が切れている場合、ジョブは失敗します。デフォルト値は `"false"` です。 + `"awsSTSRoleARN"`: (オプション) 読み取り/書き込みに使用。AWS Security Token Service (AWS STS) を使用して担うロールの Amazon リソースネーム (ARN)。このロールには、Kinesis データストリームのレコードの説明操作または読み取り操作の権限が必要です。このパラメーターは、別のアカウントのデータストリームにアクセスするときに使用する必要があります。`"awsSTSSessionName"` と組み合わせて使用します。 + `"awsSTSSessionName"`: (オプション) 読み取り/書き込みに使用。AWS STS を使って、ロールを担うセッションの識別子。このパラメータは、別のアカウントのデータストリームにアクセスするときに使用する必要があります。`"awsSTSRoleARN"` と組み合わせて使用します。 + `"awsSTSEndpoint"`: (オプション) 引き受けたロールで Kinesis に接続するときに使用する AWS STS エンドポイント。これにより、デフォルトのグローバルエンドポイントでは不可能な VPC 内のリージョナル AWS STS エンドポイントを使用できます。 + `"maxFetchTimeInMs"`: (オプション) 読み込みに使用。ジョブエグゼキューターが Kinesis データストリームから現在のバッチのレコードを読み取るために費やした最大時間は、ミリ秒 (ms) 単位で指定されます。この時間内に複数の `GetRecords` API コールを行うことができます。デフォルト値は `1000` です。 + `"maxFetchRecordsPerShard"`: (オプション) 読み込みに使用。1 マイクロバッチ当たりに Kinesis データストリームでシャードごとにフェッチするレコードの最大数。メモ: ストリーミングジョブが既に Kinesis (同じ get-records 呼び出しで) から余分なレコードを読み取っている場合、クライアントはこの制限を超えることができます。`maxFetchRecordsPerShard` が厳密である必要がある場合、`maxRecordPerRead` の倍数にする必要があります。デフォルト値は `100000` です。 + `"maxRecordPerRead"`: (オプション) 読み込みに使用。`getRecords` オペレーションごとに、Kinesis データストリームからフェッチするレコードの最大数。デフォルト値は `10000` です。 + `"addIdleTimeBetweenReads"`: (オプション) 読み込みに使用。2 つの連続する `getRecords` オペレーション間の遅延時間を追加します。デフォルト値は `"False"` です。このオプションは、Glue バージョン 2.0 以降でのみ設定可能です。 + `"idleTimeBetweenReadsInMs"`: (オプション) 読み込みに使用。2 つの連続する `getRecords` オペレーション間での、最短の遅延時間 (ミリ秒単位で指定)。デフォルト値は `1000` です。このオプションは、Glue バージョン 2.0 以降でのみ設定可能です。 + `"describeShardInterval"`: (オプション) 読み込みに使用。スクリプトが呼び出す 2 つの `ListShards` API 間での、再シャーディングを考慮すべき最小時間。詳細については、「*Amazon Kinesis Data Streams デベロッパーガイド*」の「[リシャーディングのための戦略](https://docs.aws.amazon.com//streams/latest/dev/kinesis-using-sdk-java-resharding-strategies.html)」を参照してください。デフォルト値は `1s` です。 + `"numRetries"`: (オプション) 読み込みに使用。Kinesis Data Streams API リクエストを再試行する最大の回数。デフォルト値は `3` です。 + `"retryIntervalMs"`: (オプション) 読み込みに使用。Kinesis Data Streams API 呼び出しを再試行するまでのクールオフ期間 (ミリ秒単位で指定)。デフォルト値は `1000` です。 + `"maxRetryIntervalMs"`: (オプション) 読み込みに使用。再試行で 2 つの Kinesis Data Streams API を呼び出す間の最大クールオフ期間 (ミリ秒単位で指定)。デフォルト値は `10000` です。 + `"avoidEmptyBatches"`: (オプション) 読み込みに使用。バッチ処理を開始する前に、Kinesis データストリームで未読のデータをチェックすることで、空のマイクロバッチジョブを作成しないようにします。デフォルト値は `"False"` です。 + `"schema"`: (inferSchema に false を設定した場合は必須) 読み取りに使用。ペイロードの処理に使用するスキーマ。分類が `avro` である場合、提供されるスキーマには Avro スキーマ形式を使用する必要があります。分類が `avro` 以外の場合、提供されるスキーマは DDL スキーマ形式である必要があります。 以下に、スキーマの例を示します。 ------ #### [ Example in DDL schema format ] ``` `column1` INT, `column2` STRING , `column3` FLOAT ``` ------ #### [ Example in Avro schema format ] ``` { "type":"array", "items": { "type":"record", "name":"test", "fields": [ { "name":"_id", "type":"string" }, { "name":"index", "type": [ "int", "string", "float" ] } ] } } ``` ------ + `"inferSchema"`: (オプション) 読み込みに使用。デフォルト値は、「false」です。「true」に設定すると、実行時に、スキーマが `foreachbatch` 内のペイロードから検出されます。 + `"avroSchema"`: (非推奨) 読み取りに使用。Avro 形式を使用する場合に、Avro データのスキーマを指定するために使用されるパラメータです。このパラメータは非推奨となりました。`schema` パラメータを使用します。 + `"addRecordTimestamp"`: (オプション) 読み込みに使用。このオプションが「true」に設定されている場合、データ出力には、対応するレコードがストリームによって受信された時刻を表示する「\$1\$1src\$1timestamp」という名前が付けられた追加の列が含まれます。デフォルト値は、「false」です。このオプションは AWS Glue バージョン 4.0 以降でサポートされています。 + `"emitConsumerLagMetrics"`: (オプション) 読み込みに使用。このオプションを「true」に設定すると、バッチごとに、ストリームが受信した最も古いレコードと、それが AWS Glue で CloudWatch に到着した時間との間隔のメトリクスが出力されます。メトリクスの名前は「glue.driver.streaming.maxConsumerLagInMs」です。デフォルト値は、「false」です。このオプションは AWS Glue バージョン 4.0 以降でサポートされています。 + `"fanoutConsumerARN"`: (オプション) 読み込みに使用。`streamARN` で指定されたストリームの Kinesis ストリームコンシューマの ARN。Kinesis 接続の拡張ファンアウトモードを有効にするために使用されます。拡張ファンアウトが使用された Kinesis ストリームの使用に関する詳細については、「[Kinesis ストリーミングジョブでの拡張ファンアウトの使用](aws-glue-programming-etl-connect-kinesis-efo.md)」を参照してください。 + `"recordMaxBufferedTime"` - (オプション) 書き込みに使用。デフォルト: 1000 (ミリ秒)。レコードが書き込まれるのを待っている間にバッファリングされる最大時間。 + `"aggregationEnabled"` - (オプション) 書き込みに使用。デフォルト: true。Kinesis に送信する前にレコードを集約するかどうかを指定します。 + `"aggregationMaxSize"` - (オプション) 書き込みに使用。デフォルト: 51200 (バイト) レコードがこの制限よりも大きい場合、そのレコードはアグリゲータをバイパスします。注: Kinesis では、レコードサイズに 50 KB の制限が適用されます。これを 50 KB を超えて設定すると、サイズ超過のレコードは Kinesis によって拒否されます。 + `"aggregationMaxCount"` - (オプション) 書き込みに使用。デフォルト: 4294967295。集計されたレコードにパックされる項目の最大数。 + `"producerRateLimit"` - (オプション) 書き込みに使用。デフォルト: 150 (%)。1 つのプロデューサー (ジョブなど) からの送信されるシャード単位のスループットをバックエンド制限のパーセンテージとして制限できます。 + `"collectionMaxCount"` - (オプション) 書き込みに使用。デフォルト: 500。PutRecords レコードにパックされる項目の最大数。 + `"collectionMaxSize"` - (オプション) 書き込みに使用。デフォルト: 5242880 (バイト)。PutRecords リクエストで送信するデータの最大量。 # Kinesis ストリーミングジョブでの拡張ファンアウトの使用 拡張ファンアウトコンシューマは、通常のコンシューマよりも高い専用スループットで Kinesis ストリームからレコードを受信できます。これは、ジョブなどの Kinesis コンシューマにデータを提供するために使用される転送プロトコルを最適化することによって行われます。Kinesis 拡張ファンアウトの詳細については、[Kinesis のドキュメント](https://docs.aws.amazon.com//streams/latest/dev/enhanced-consumers.html)を参照してください。 拡張ファンアウトモードでは、`maxRecordPerRead` および `idleTimeBetweenReadsInMs` 接続オプションは適用されなくなりました。拡張ファンアウトを使用する場合、これらのパラメータは設定できないためです。リトライの設定オプションは説明どおりに機能します。 以下の手順に従って、ストリーミングジョブの拡張ファンアウトを有効または無効にします。ストリームのデータを消費するジョブごとに、ストリームコンシューマを登録する必要があります。 **ジョブの拡張ファンアウト消費を有効にするには:** 1. Kinesis API を使用してジョブのストリームコンシューマを登録します。手順に従って、[Kinesis ドキュメント](https://docs.aws.amazon.com//streams/latest/dev/building-enhanced-consumers-api)の *Kinesis Data Streams API を使用して、拡張ファンアウトでコンシューマを登録*します。必要なのは、最初のステップである [RegisterStreamConsumer](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_RegisterStreamConsumer.html) を呼び出すことだけです。リクエストは ARN、*consumerARN* を返す必要があります。 1. 接続メソッドの引数で接続オプション `fanoutConsumerARN` を *consumerARN* に設定します。 1. ジョブを再開してください。 **ジョブの拡張ファンアウト消費を無効にするには:** 1. メソッド呼び出しから接続オプション `fanoutConsumerARN` を削除します。 1. ジョブを再開してください。 1. [Kinesis ドキュメント](https://docs.aws.amazon.com/streams/latest/dev/building-enhanced-consumers-console.html)の指示に従ってコンシューマを登録解除します。これらの手順はコンソールに適用されますが、Kinesis API を使用して実行することもできます。Kinesis API によるストリームコンシューマの登録解除の詳細については、Kinesis ドキュメントの「[DeregisterStreamConsumer](https://docs.aws.amazon.com//kinesis/latest/APIReference/API_DeregisterStreamConsumer.html)」を参照してください。 # Amazon S3 接続 AWS Glue for Spark を使用して Amazon S3 内のファイルの読み込みと書き込みを行うことができます。AWSGlue for Spark は、CSV、Avro、JSON、Orc、Parquet など、Amazon S3 に保存されている多くの一般的なデータ形式をそのままでサポートしています。サポートされるデータ形式の詳細については、「[AWS Glue for Spark での入出力のデータ形式に関するオプション](aws-glue-programming-etl-format.md)」を参照してください。各データ形式が、異なる AWS Glue の機能のセットをサポートする場合があります。機能のサポートの詳細については、使用しているデータ形式のページを参照してください。さらに、Hudi、Iceberg、Delta Lake のデータレイクフレームワークに保存されているバージョン対応ファイルを読み書きできます。データレイクフレームワークの詳細については、「[AWS Glue ETL ジョブでのデータレイクフレームワークの使用](aws-glue-programming-etl-datalake-native-frameworks.md)」を参照してください。 AWS Glue を使用すると、書き込み中に Amazon S3 オブジェクトをフォルダ構造に分割し、簡単な設定でパーティションごとに取得してパフォーマンスを向上させることができます。また、データを変換する際に小さなファイルをまとめてグループ化するように設定してパフォーマンスを向上させることもできます。Amazon S3 では、`bzip2` の読み込み、書き込み、`gzip` アーカイブを行うことができます。 **Topics** + [S3 接続の設定](#aws-glue-programming-etl-connect-s3-configure) + [Amazon S3 接続のオプションのリファレンス](#aws-glue-programming-etl-connect-s3) + [廃止されたデータ形式の接続構文](#aws-glue-programming-etl-connect-legacy-format) + [Amazon S3 ストレージクラスの除外](aws-glue-programming-etl-storage-classes.md) + [AWS Glue での ETL 出力のパーティションの管理](aws-glue-programming-etl-partitions.md) + [大きなグループの入力ファイルの読み取り](grouping-input-files.md) + [Amazon S3 用の VPC エンドポイント](vpc-endpoints-s3.md) ## S3 接続の設定 AWS Glue with Spark ジョブで Amazon S3 に接続するには、いくつかの前提条件が必要です。 + AWS Glue ジョブには、関連する Amazon S3 バケットに対する IAM 権限が必要です。 場合によっては、追加の前提条件を設定する必要があります。 + クロスアカウントアクセスを設定するときは、Amazon S3 バケットで適切なアクセス制御を行います。 + セキュリティ上の理由から、Amazon S3 リクエストを Amazon VPC 経由でルーティングすることもできます。このアプローチでは、帯域幅や可用性の課題が生じる場合があります。詳細については、「[Amazon S3 用の VPC エンドポイント](vpc-endpoints-s3.md)」を参照してください。 ## Amazon S3 接続のオプションのリファレンス Simple Storage Service (Amazon S3) への接続を指定します。 Amazon S3 はテーブルではなくファイルを管理するため、このドキュメントに記載されている接続プロパティを指定することに加えて、ファイルタイプに関する追加の設定を指定する必要があります。この情報はデータ形式オプションを使用して指定します。形式オプションの詳細については、「[AWS Glue for Spark での入出力のデータ形式に関するオプション](aws-glue-programming-etl-format.md)」を参照してください。AWS Glue データカタログと統合してこの情報を指定することもできます。 接続オプションとフォーマットオプションの違いの例として、[create\$1dynamic\$1frame\$1from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_options) メソッドが `connection_type`、`connection_options`、`format` および `format_options` をどのように使用するかを考えてみます。このセクションでは、`connection_options` に提供されるパラメータについて具体的に説明します。 `"connectionType": "s3"` では、次の接続オプションを使用します。 + `"paths"`: (必須) 読み取りのソースとなる Amazon S3 パスのリスト。 + `"exclusions"`: (オプション) 除外する Unix スタイルの glob パターンの JSON リストを含む文字列。例えば、`"[\"**.pdf\"]"` はすべての PDF ファイルを除外します。AWS Glue がサポートする glob 構文の詳細については、「[包含パターンと除外パターンを使用する](https://docs.aws.amazon.com/glue/latest/dg/define-crawler.html#crawler-data-stores-exclude)」を参照してください。 + `"compressionType"`: または「`compression`」: (オプション) データの圧縮方法を指定します。Simple Storage Service (Amazon S3) ソース用には `"compressionType"` を、Simple Storage Service (Amazon S3) ターゲット用には `"compression"` を使用します。データに標準のファイル拡張子が付いている場合、このオプションは一般的に不要です。指定できる値は `"gzip"` および `"bzip2"` です。特定の形式では、他の圧縮形式がサポートされている場合もあります。機能のサポートの詳細については、データ形式のページを参照してください。 + `"groupFiles"`: (オプション) 入力ファイルが 50,000 個を超える場合、デフォルトでファイルのグループ化が有効化されます。入力ファイルが 50,000 個未満の場合にグループ化を有効化するには、このパラメータに `"inPartition"` を設定します。入力ファイルが 50,000 個を超える場合に、グループ化を無効にするには、このパラメータを `"none"` に設定します。 + `"groupSize"`: (オプション) ターゲットグループのサイズ (バイト単位)。デフォルトは、入力データのサイズとクラスターのサイズに基づいて計算されます。入力ファイルが 50,000 個未満の場合、このオプションを有効にするには、`"groupFiles"` を `"inPartition"` に設定する必要があります。 + `"recurse"`: (オプション) true に設定した場合は、指定したパスの下にあるすべてのサブディレクトリ内のファイルを再帰的に読み取ります。 + `"maxBand"`: (オプション、詳細設定) このオプションでは、`s3` リストの一貫性が認められるまでの期間をミリ秒単位で指定します。Amazon S3 の結果整合性を担保するために、直前の `maxBand` ミリ秒以内の変更タイムスタンプが付いたファイルが、特に `JobBookmarks` の使用時に追跡されます。ほとんどのユーザーはこのオプションを設定する必要はありません。デフォルトは 900000 ミリ秒 (15 分) です。 + `"maxFilesInBand"`: (オプション、詳細設定) このオプションは、直前の `maxBand` 秒間に保存するファイルの最大数を指定します。この数を超えた場合、余分なファイルはスキップされ、次のジョブ実行時にのみ処理されます。ほとんどのユーザーはこのオプションを設定する必要はありません。 + `"isFailFast"`: (オプション) このオプションにより、AWS Glue ETL ジョブがリーダー解析の例外をスローするかどうかを決定します。`true` に設定すると、Spark タスクが 4 回の再試行のうちにデータを正しく解析できなかった場合、ジョブは速やかに失敗します。 + `"catalogPartitionPredicate"`: (オプション) 読み込みに使用。SQL `WHERE` 句の内容。非常に多数のパーティションを含むデータカタログテーブルから読み込むときに使用されます。データカタログインデックスから一致するパーティションを取得します。[create\$1dynamic\$1frame\$1from\$1catalog](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_catalog) メソッド (および他の類似メソッド) のオプション `push_down_predicate` と共に使用します。詳細については、「[カタログのパーティション述語を使用したサーバー側のフィルタリング](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-cat-predicates)」を参照してください。 + `"partitionKeys"`: (オプション) 書き込みに使用。列ラベル文字列の配列。AWSGlue は、この設定で指定されたとおりにデータを分割します。詳細については、「[パーティションの書き込み](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-writing)」を参照してください。 + `"excludeStorageClasses"`: (オプション) 読み込みに使用。Amazon S3 ストレージクラスを指定する文字列の配列。AWSGlue は、この設定に基づいて Amazon S3 オブジェクトを除外します。詳細については、「[Amazon S3 ストレージクラスの除外](aws-glue-programming-etl-storage-classes.md)」を参照してください。 ## 廃止されたデータ形式の接続構文 特定のデータ形式には、特定の接続タイプ構文を使用してアクセスできます。この構文は廃止されました。代わりに [AWS Glue for Spark での入出力のデータ形式に関するオプション](aws-glue-programming-etl-format.md) で提供されている `s3` 接続タイプと形式オプションを使用して形式を指定することをお勧めします。 ### "connectionType": "orc" [Apache Hive Optimized Row Columnar (ORC)](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+ORC) ファイル形式で、Amazon S3 に保存されるファイルへの接続を指定します。 `"connectionType": "orc"` では、次の接続オプションを使用します。 + `paths`: (必須) 読み取りのソースとなる Amazon S3 パスのリスト。 + *(その他のオプション名/値ペア)*: 書式設定オプションなどのその他のオプションはすべて SparkSQL `DataSource` に直接渡されます。 ### "connectionType": "parquet" [Apache Parquet](https://parquet.apache.org/docs/) ファイル形式で、Amazon S3 に保存されるファイルへの接続を指定します。 `"connectionType": "parquet"` では、次の接続オプションを使用します。 + `paths`: (必須) 読み取りのソースとなる Amazon S3 パスのリスト。 + *(その他のオプション名/値ペア)*: 書式設定オプションなどのその他のオプションはすべて SparkSQL `DataSource` に直接渡されます。 # Amazon S3 ストレージクラスの除外 Amazon Simple Storage Service (Amazon S3) からファイルまたはパーティションを読み取る AWS Glue ETL ジョブを実行している場合は、一部の Amazon S3 ストレージクラスタイプを除外できます。 Amazon S3 には、次のストレージクラスがあります。 + `STANDARD` – 頻繁にアクセスされるデータの汎用ストレージ向け。 + `INTELLIGENT_TIERING` – アクセスパターンが不明または変化するデータ向け。 + `STANDARD_IA` および `ONEZONE_IA` – 保持期間が長くアクセス頻度の低いデータ向け。 + `GLACIER`、`DEEP_ARCHIVE`、および `REDUCED_REDUNDANCY` – 長期アーカイブおよびデジタル保存向け。 詳細については、「*Amazon S3 デベロッパーガイド*」の「[Amazon S3 ストレージクラス](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-class-intro.html)」を参照してください。 このセクションの例では、`GLACIER` および `DEEP_ARCHIVE` ストレージクラスを除外する方法を示します。これらのクラスではファイルをリストできますが、復元されない限り、ファイルを読み取ることはできません (さらに詳細な情報については、「*Amazon S3 デベロッパーガイド*」の「[Restoring Archived Objects](https://docs.aws.amazon.com/AmazonS3/latest/dev/restoring-objects.html)」を参照してください。) ストレージクラスの除外を使用することで、これらのストレージクラス層にまたがるパーティションを持つテーブルで AWS Glue ジョブを確実に動作させることができます。除外がない場合、これらの階層からデータを読み取るジョブは、次のエラーで失敗します。 AmazonS3Exception: オペレーションはオブジェクトのストレージクラスに対して有効ではありません。 AWS Glue で Amazon S3 ストレージクラスをフィルタリングするには、さまざまな方法があります 。 **Topics** + [動的フレームの作成時の Amazon S3 ストレージクラスの除外](#aws-glue-programming-etl-storage-classes-dynamic-frame) + [Data Catalog テーブルでの Amazon S3 ストレージクラスの除外](#aws-glue-programming-etl-storage-classes-table) ## 動的フレームの作成時の Amazon S3 ストレージクラスの除外 ダイナミックフレームの作成時に Amazon S3 のストレージクラスを除外するには、`excludeStorageClasses` で `additionalOptions` を使います。AWS Glue では指定されたストレージクラスに対応するファイルを、独自の Amazon S3 `Lister` の実装を使用して自動的にリストアップし、除外します。 次に、動的フレームの作成時に `GLACIER` および `DEEP_ARCHIVE` ストレージクラスを除外する、Python および Scala の例を示します。 Python の例 ``` glueContext.create_dynamic_frame.from_catalog( database = "my_database", tableName = "my_table_name", redshift_tmp_dir = "", transformation_ctx = "my_transformation_context", additional_options = { "excludeStorageClasses" : ["GLACIER", "DEEP_ARCHIVE"] } ) ``` Scala の例 ``` val* *df = glueContext.getCatalogSource( nameSpace, tableName, "", "my_transformation_context", additionalOptions = JsonOptions( Map("excludeStorageClasses" -> List("GLACIER", "DEEP_ARCHIVE")) ) ).getDynamicFrame() ``` ## Data Catalog テーブルでの Amazon S3 ストレージクラスの除外 AWS Glue ETL のジョブによるストレージクラスの除外は、AWS Glue Data Catalog のテーブルパラメータとして指定できます。このパラメータは、AWS Command Line Interface (AWS CLI) を使用するか、API を使用してプログラミングによって `CreateTable` オペレーションに含むことができます。詳細については、「[テーブル構造](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-catalog-tables.html#aws-glue-api-catalog-tables-Table)」および「[CreateTable](https://docs.aws.amazon.com/glue/latest/webapi/API_CreateTable.html)」を参照してください。 AWS Glue コンソールで除外されるストレージクラスを指定することもできます。 **Amazon S3 ストレージクラスを除外するには (コンソール)** 1. AWS マネジメントコンソール にサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)) を開きます。 1. 左側のナビゲーションペインで、[**Tables (テーブル)**] を選択します。 1. リストでテーブル名を選択し、[**Edit table (テーブルの編集)**] を選択します。 1. [**Table properties (テーブルプロパティ)**] で、キーとして **excludeStorageClasses** を、値として **[\$1"GLACIER\$1",\$1"DEEP\$1ARCHIVE\$1"]** を追加します。 1. **[Apply]** (適用) を選択します。 # AWS Glue での ETL 出力のパーティションの管理 パーティション分割は、データセットを整理して効率的にクエリを実行可能にする重要な手法です。1 つまたは複数の列の個別の値に基づいて、データを階層形式のディレクトリ構造に整理します。 たとえば、Amazon Simple Storage Service (Amazon S3) のアプリケーションログを、年、月、日で分類しながら、日付についてパーティション化できます。次に 1 日分のデータに対応するファイルを `s3://my_bucket/logs/year=2018/month=01/day=23/` などのプレフィックス別に配置します。Amazon Athena、Amazon Redshift Spectrum、そして AWS Glue などのシステムでは、基になるデータ全体を Amazon S3 から読み取ることなく、これらのパーティションを使用してパーティション値でデータをフィルタリングできます。 クローラは、ファイルタイプとスキーマを推定するだけでなく、AWS Glue Data Catalog を構成する際に、データセットのパーティション構造も自動的に特定します。これにより出力されるパーティション列に対しては、AWS Glue ETL ジョブやクエリエンジン (Amazon Athena など) からクエリを実行できます。 テーブルのクロールが完了すると、クローラが作成したパーティションを表示できます。AWS Glue コンソールの左のナビゲーションペインで、[**Tables**] (テーブル) をクリックします。クローラで作成されたテーブルを選択した後、[**View Partitions**] (パーティション) の表示をクリックします。 Apache Hive 形式のパーティション分割されたパス (`key=val` 形式) の場合、クローラはキー名を使用して自動的に列名を事前設定します。それ以外の場合は、`partition_0`、`partition_1` などのデフォルト名が使用されます。コンソールでデフォルトの名前を変更できます。そのためには、テーブルに移動します。**[インデックス]** タブにインデックスが存在するかどうかを確認します。ある場合は、削除してから続行する必要があります (後で新しい列名を使用して再作成できます)。次に、**[スキーマの編集]** を選択し、そこでパーティション列の名前を変更します。 次に、ETL スクリプトでパーティション列をフィルタリングできます。パーティション情報は Data Catalog に格納されるため、パーティション列を `DynamicFrame` に含めるには `from_catalog` API 呼び出しを使用します。例えば、`create_dynamic_frame.from_options` ではなく `create_dynamic_frame.from_catalog` を使用します。 パーティション化は、データスキャンを減らす最適化手法です。この手法が適切であることを特定するプロセスの詳細については、「AWS 規範的ガイダンス」の「Best practices for performance tuning AWS Glue for Apache Spark jobs」ガイドにある「[Reduce the amount of data scan](https://docs.aws.amazon.com/prescriptive-guidance/latest/tuning-aws-glue-for-apache-spark/reduce-data-scan.html)」を参照してください。 ## プッシュダウン述語を使用した事前フィルタ処理 多くの場合、プッシュダウン述語を使用してパーティションをフィルタリングできます。データセットのすべてのファイルをリストアップして読み取る必要はありません。データセット全体を読み取って DynamicFrame でフィルタリングする代わりに、Data Catalog 内でパーティションのメタデータに直接フィルターを適用できます。次に、実際に必要なものだけをリストアップして DynamicFrame 内に読み取ることができます。 たとえば、Python では以下のように記述できます。 ``` glue_context.create_dynamic_frame.from_catalog( database = "my_S3_data_set", table_name = "catalog_data_table", push_down_predicate = my_partition_predicate) ``` これによって作成される DynamicFrame では、Data Catalog のパーティションのうち、述語式を満たすものだけがロードされます。ロードするデータのサブセットを絞り込む度合いに応じて、処理時間を大幅に短縮できる場合があります。 述語式として、Spark SQL でサポートされている任意のブール式を使用できます。Spark SQL クエリで `WHERE` 句に指定できる条件は、すべて正常に動作します。例えば述語式 `pushDownPredicate = "(year=='2017' and month=='04')"` では、Data Catalog 内で `year` が「2017」に等しく、また `month` が「04」に等しいパーティションのみロードされます。詳細については、[Apache Spark SQL のドキュメント](https://spark.apache.org/docs/2.1.1/sql-programming-guide.html)を参照してください。特に [Scala SQL 関数リファレンス](https://spark.apache.org/docs/2.1.1/api/scala/index.html#org.apache.spark.sql.functions$)が参考になります。 ## カタログのパーティション述語を使用したサーバー側のフィルタリング `push_down_predicate` オプションは、カタログからすべてのパーティションを一覧表示した後、Amazon S3 にあるそれらのパーティションからファイルをリストする前に適用されます。テーブルに多数のパーティションがある場合、カタログパーティションのリストに、時間的なオーバーヘッドが余計に発生する可能性があります。このオーバーヘッドに対処するには、`catalogPartitionPredicate` オプションを指定して AWS Glue Data Catalog の[パーティションインデックス](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html)を使用しながら、サーバー側のパーティションでプルーニングを行います。1 つのテーブルに数百万のパーティションがある場合、これにより、パーティションのフィルタリングを大幅に高速化できます。カタログのパーティションインデックスではまだサポートされていない述語構文が、`catalogPartitionPredicate` で必要となる場合には、`additional_options` の中で `push_down_predicate` と `catalogPartitionPredicate` の両方を使用することもできます Python: ``` dynamic_frame = glueContext.create_dynamic_frame.from_catalog( database=dbname, table_name=tablename, transformation_ctx="datasource0", push_down_predicate="day>=10 and customer_id like '10%'", additional_options={"catalogPartitionPredicate":"year='2021' and month='06'"} ) ``` Scala: ``` val dynamicFrame = glueContext.getCatalogSource( database = dbname, tableName = tablename, transformationContext = "datasource0", pushDownPredicate="day>=10 and customer_id like '10%'", additionalOptions = JsonOptions("""{ "catalogPartitionPredicate": "year='2021' and month='06'"}""") ).getDynamicFrame() ``` **注記** `push_down_predicate` と `catalogPartitionPredicate` では、使用される構文が異なります。前者では Spark SQL の標準構文を使用し、後者では JSQL パーサーを使用します。 ## パーティションの書き込み デフォルトでは、DynamicFrame は書き込むときにパーティション分割されません。すべての出力ファイルは、指定した出力パスの最上位レベルに書き込まれます。最近まで、DynamicFrame をパーティションに書き込む唯一の方法は、書き込む前に Spark SQL DataFrame に変換することでした。 ただし、DynamicFrames ではキーのシーケンスを使用したネイティブのパーティション分割がサポートされるようになりました。この場合、シンクの作成時に `partitionKeys` オプションを使用します。例えば、次の Python コードではデータセットを Parquet 形式で Amazon S3 のディレクトリに書き込みます。これらのディレクトリでは、型フィールドごとにパーティション分割されています。これらのパーティションに対しては、他のシステム (Amazon Athena など) を使用しての処理が行えます。 ``` glue_context.write_dynamic_frame.from_options( frame = projectedEvents, connection_type = "s3", connection_options = {"path": "$outpath", "partitionKeys": ["type"]}, format = "parquet") ``` # 大きなグループの入力ファイルの読み取り テーブルのプロパティを設定しておくと、Amazon S3 データストアからファイルが読み取られる際に、AWS Glue の ETL ジョブでそれらのファイルをグループ化させることができます。これらのプロパティを使用すると、各 ETL タスクでは入力ファイルのグループを単一のインメモリパーティションに読み取ることができます。これは、Amazon S3 データストアに多数の小さいファイルがある場合に便利です。特定のプロパティを定義する際には、Amazon S3 データパーティション内のファイルをグループ化し、そのグループの読み取り用のサイズを設定することを AWS Glue に指示します。また、`create_dynamic_frame.from_options` メソッドを使用した Amazon S3 データストアからの読み取りのために、これらのオプションを設定することもできます。 テーブルのファイルをグループ化するには、テーブル構造のパラメータフィールドにキーと値のペアを設定します。テーブルのパラメータフィールドに値を設定するには、JSON 表記を使用します。テーブルのプロパティを編集する詳しい方法については、「[テーブルの詳細の表示と管理](tables-described.md#console-tables-details)」を参照してください。 このメソッドを使用すると、Amazon S3 データストアにある Data Catalog でテーブルをグループ化できます。 **groupFiles** Amazon S3 データパーティションにあるファイルのグループ化を有効にするには、**groupFiles** に `inPartition` を設定します。入力ファイル数が 50,000 を超える場合には、次の例のように AWS Glue がグループ化を自動的に有効にします。 ``` 'groupFiles': 'inPartition' ``` **groupSize** **groupSize** をグループのターゲットサイズ (バイト単位) に設定します。**groupSize** プロパティはオプションです。指定しない場合、AWS Glue はクラスター内のすべての CPU コアを使用すると同時に、ETL タスクとメモリ内パーティションの総数を減らすようにサイズを計算します。 たとえば、次の例では、グループサイズを 1 MB に設定します。 ``` 'groupSize': '1048576' ``` `groupsize`​ は、計算の結果を使用して設定する必要があることに注意してください。例: 1024 \$1 1024 = 1048576。 **recurse** **recurse** に `True`を設定し、`paths` によりパスの配列を指定すると、すべてのサブディレクトリのファイルを再帰的に読み取ることができます。次の例のように、`paths` が Amazon S3 のオブジェクトキーの配列である場合、または入力フォーマットが parquet/orc の場合、**recurse** を設定する必要はありません。 ``` 'recurse':True ``` `create_dynamic_frame.from_options` メソッドを使用して Amazon S3 から直接読み取る場合は、以下の接続オプションを追加します。たとえば、ファイルを 1 MB のグループにグループ化する方法は次のとおりです。 ``` df = glueContext.create_dynamic_frame.from_options("s3", {'paths': ["s3://s3path/"], 'recurse':True, 'groupFiles': 'inPartition', 'groupSize': '1048576'}, format="json") ``` **注記** `groupFiles` は、csv、Ion、grokLog、json、および xml のデータ形式から作成された DynamicFrames でサポートされています。このオプションは、avro、parquet、orc ではサポートされていません。 # Amazon S3 用の VPC エンドポイント セキュリティ上の理由から、多くの AWS ユーザーがアプリケーションを Amazon Virtual Private Cloud 環境 (Amazon VPC) 内で実行しています。Amazon VPC を使用すると、Amazon EC2 インスタンスを仮想プライベートクラウドで作成できます。そのため、パブリックインターネットなどの他のネットワークから論理的に分離されます。Amazon VPC を使用すると、IP アドレスの範囲、サブネット、ルーティングテーブル、ネットワークゲートウェイ、セキュリティ設定を適切に管理できます。 **注記** 2013 年 12 月 4 日より後に AWS アカウントを作成した場合は、各 AWS リージョンにデフォルトで VPC が用意されています。追加設定なしにデフォルトの VPC をすぐに使用できます。 デフォルト VPC の詳細については、Amazon VPC ユーザーガイドの「[デフォルト VPC とデフォルトサブネット](https://docs.aws.amazon.com/vpc/latest/userguide/default-vpc.html)」を参照してください。 多くのお客様が、パブリックインターネット間のデータ送受信に関して、プライバシーとセキュリティに関する正当な懸念を抱いています。こういったお客様は、この懸念事項を解決するために、バーチャルプライベートネットワーク (VPN) を使用して、すべての Amazon S3 ネットワークトラフィックを、自社内の企業ネットワークのインフラストラクチャ経由でルーティングします。ただし、このアプローチでは、帯域幅や可用性の課題が生じる場合があります。 Amazon S3 用の VPC エンドポイントにより、これらの課題が軽減されます。Amazon S3 用 VPC エンドポイントを使用することで、AWS Glue はプライベート IP アドレスを使用して、パブリックインターネットに公開されることなく Amazon S3 にアクセスできるようになります。AWS Glue はパブリック IP アドレスを必要とせず、VPC のためのインターネットゲートウェイ、NAT デバイス、仮想プライベートゲートウェイは不要です。Amazon S3 へのアクセスを制御するには、エンドポイントのポリシーを使用します。VPC と AWS サービス間のトラフィックは、Amazon ネットワークを離れません。 Amazon S3 用に VPC エンドポイントを作成する際、リージョン内の Amazon S3 エンドポイント (例: *s3.us-west-2.amazonaws.com*) に対するリクエストはすべて、Amazon ネットワーク内のプライベートの Amazon S3 エンドポイントにルーティングされます。VPC の Amazon EC2 インスタンスで実行されているアプリケーションを変更する必要はありません。エンドポイント名は変わりませんが、Amazon S3 へのルーティングは完全に Amazon ネットワーク内で行われ、パブリックインターネットにアクセスすることはありません。 エンドポイントの詳細については、Amazon VPC ユーザーガイドの「[VPC Endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints.html)」を参照してください。 AWS Glue が VPC エンドポイントを使用して Amazon S3 にアクセスする様子を、次の図に示します。 ![\[ネットワークトラフィックフローは、Amazon S3 への VPC 接続を示しています。\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/images/PopulateCatalog-vpc-endpoint.png) **Amazon S3 のアクセスをセットアップするには** 1. AWS マネジメントコンソール にサインインして、Amazon VPC コンソール ([https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)) を開きます。 1. 左のナビゲーションペインで [**エンドポイント**] を選択してください。 1. [**Create Endpoint**] (エンドポイントの作成) をクリックし、ステップに従ってゲートウェイタイプの Amazon S3 VPC エンドポイントを作成します。 # Amazon DocumentDB の接続　 Spark 用の AWS Glue を使用して Amazon DocumentDB 内のテーブルに対する読み込みと書き込みを行うことができます。AWS Glue 接続を介して AWS Secrets Manager で保存されている認証情報を使用して Amazon DocumentDB に接続できます。 Amazon DocumentDB の詳細については、「[Amazon DocumentDB のドキュメント](https://docs.aws.amazon.com/documentdb/latest/developerguide/what-is.html)」を参照してください。 **注記** Amazon DocumentDB エラスティッククラスターは、現在 AWS Glue コネクタを使用する場合にはサポートされていません。エラスティッククラスターの詳細については、「[Amazon DocumentDB エラスティッククラスターの使用](https://docs.aws.amazon.com/documentdb/latest/developerguide/docdb-using-elastic-clusters.html)」を参照してください。 ## Amazon DocumentDB コレクションへの読み取りと書き込み **注記** Amazon DocumentDB に接続する ETL ジョブを作成する際、`Connections` ジョブのプロパティにおいて、Amazon DocumentDB が実行されている Virtual Private Cloud (VPC) を特定するための、接続オブジェクトを指定する必要があります。接続オブジェクトの場合、接続タイプは `JDBC` で、`JDBC URL` は `mongo://:27017` である必要があります。 **注記** これらのコードサンプルは AWS Glue 3.0 用に開発されました。AWS Glue 4.0 への移行については、[MongoDB](migrating-version-40.md#migrating-version-40-connector-driver-migration-mongodb) を参照してください。`uri` パラメータが変更されました。　 **注記** Amazon DocumentDB を使用する場合、書かれた文書に `_id` が指定されている場合など、特定の状況では、`retryWrites` は false に設定する必要があります。詳細については、Amazon DocumentDB ドキュメントの「[MongoDB との機能の違い](https://docs.aws.amazon.com/documentdb/latest/developerguide/functional-differences.html#functional-differences.retryable-writes)」を参照してください。　 次の Python スクリプトでは、Amazon DocumentDB に対する読み取りと書き込みのための、接続タイプと接続オプションの使用方法を示しています。 ``` import sys from awsglue.transforms import * from awsglue.utils import getResolvedOptions from pyspark.context import SparkContext, SparkConf from awsglue.context import GlueContext from awsglue.job import Job import time ## @params: [JOB_NAME] args = getResolvedOptions(sys.argv, ['JOB_NAME']) sc = SparkContext() glueContext = GlueContext(sc) spark = glueContext.spark_session job = Job(glueContext) job.init(args['JOB_NAME'], args) output_path = "s3://some_bucket/output/" + str(time.time()) + "/" documentdb_uri = "mongodb://:27017" documentdb_write_uri = "mongodb://:27017" read_docdb_options = { "uri": documentdb_uri, "database": "test", "collection": "coll", "username": "username", "password": "1234567890", "ssl": "true", "ssl.domain_match": "false", "partitioner": "MongoSamplePartitioner", "partitionerOptions.partitionSizeMB": "10", "partitionerOptions.partitionKey": "_id" } write_documentdb_options = { "retryWrites": "false", "uri": documentdb_write_uri, "database": "test", "collection": "coll", "username": "username", "password": "pwd" } # Get DynamicFrame from DocumentDB dynamic_frame2 = glueContext.create_dynamic_frame.from_options(connection_type="documentdb", connection_options=read_docdb_options) # Write DynamicFrame to MongoDB and DocumentDB glueContext.write_dynamic_frame.from_options(dynamic_frame2, connection_type="documentdb", connection_options=write_documentdb_options) job.commit() ``` 次の Scala スクリプトでは、Amazon DocumentDB に対する読み取りと書き込みのための、接続タイプと接続オプションの使用方法を示しています。 ``` import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.MappingSpec import com.amazonaws.services.glue.errors.CallSite import com.amazonaws.services.glue.util.GlueArgParser import com.amazonaws.services.glue.util.Job import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.DynamicFrame import org.apache.spark.SparkContext import scala.collection.JavaConverters._ object GlueApp { val DOC_URI: String = "mongodb://:27017" val DOC_WRITE_URI: String = "mongodb://:27017" lazy val documentDBJsonOption = jsonOptions(DOC_URI) lazy val writeDocumentDBJsonOption = jsonOptions(DOC_WRITE_URI) def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) // Get DynamicFrame from DocumentDB val resultFrame2: DynamicFrame = glueContext.getSource("documentdb", documentDBJsonOption).getDynamicFrame() // Write DynamicFrame to DocumentDB glueContext.getSink("documentdb", writeJsonOption).writeDynamicFrame(resultFrame2) Job.commit() } private def jsonOptions(uri: String): JsonOptions = { new JsonOptions( s"""{"uri": "${uri}", |"database":"test", |"collection":"coll", |"username": "username", |"password": "pwd", |"ssl":"true", |"ssl.domain_match":"false", |"partitioner": "MongoSamplePartitioner", |"partitionerOptions.partitionSizeMB": "10", |"partitionerOptions.partitionKey": "_id"}""".stripMargin) } } ``` ## Amazon DocumentDB 接続のオプションのリファレンス Amazon DocumentDB (MongoDB 互換) への接続を指定します。 接続オプションは、ソース接続とシンク接続とで異なります。 ### "connectionType": "Documentdb" ソースとする `"connectionType": "documentdb"` をソースとして、次の接続オプションを使用します。 + `"uri"`: (必須) 読み取り元の Amazon DocumentDB ホスト (`mongodb://:` 形式)。 + `"database"`: (必須) 読み取り元の Amazon DocumentDB データベース。 + `"collection"`: (必須) 読み取り元の Amazon DocumentDB コレクション。 + `"username"`: (必須) Amazon DocumentDB のユーザー名。 + `"password"`: (必須) Amazon DocumentDB のパスワード。 + `"ssl"`: (SSL を使用する場合は必須) SSL を使用して接続する場合は、このオプションの値を `"true"` に設定する必要があります。 + `"ssl.domain_match"`: (SSL を使用する場合は必須) SSL を使用して接続する場合は、このオプションの値を `"false"` に設定する必要があります。 + `"batchSize"`: (オプション): 内部バッチのカーソル内で使用される、バッチごとに返されるドキュメントの数。 + `"partitioner"`: (オプション) Amazon DocumentDB から入力データを読み取るためのパーティショナーのクラス名。コネクタには、次のパーティショナーがあります。 + `MongoDefaultPartitioner` (デフォルト) (AWS Glue 4.0 ではサポートされていません) + `MongoSamplePartitioner` (AWS Glue 4.0 ではサポートされていません) + `MongoShardedPartitioner` + `MongoSplitVectorPartitioner` + `MongoPaginateByCountPartitioner` + `MongoPaginateBySizePartitioner` (AWS Glue 4.0 ではサポートされていません) + `"partitionerOptions"` (オプション): 指定されたパーティショナーのオプション。各パーティショナーでは、次のオプションがサポートされています。 + `MongoSamplePartitioner`: `partitionKey`, `partitionSizeMB`, `samplesPerPartition` + `MongoShardedPartitioner`: `shardkey` + `MongoSplitVectorPartitioner`: `partitionKey`、partitionSizeMB + `MongoPaginateByCountPartitioner`: `partitionKey`, `numberOfPartitions` + `MongoPaginateBySizePartitioner`: `partitionKey`、partitionSizeMB これらのオプションの詳細については、MongoDB のドキュメントの「[Partitioner Configuration](https://docs.mongodb.com/spark-connector/master/configuration/#partitioner-conf)」を参照してください。 ### "connectionType": "documentdb" as Sink `"connectionType": "documentdb"` をシンクとして、次の接続オプションを使用します。 + `"uri"`: (必須) 書き込み先の Amazon DocumentDB ホスト (`mongodb://:` 形式)。 + `"database"`: (必須) 書き込み先の Amazon DocumentDB データベース。 + `"collection"`: (必須) 書き込み先の Amazon DocumentDB コレクション。 + `"username"`: (必須) Amazon DocumentDB のユーザー名。 + `"password"`: (必須) Amazon DocumentDB のパスワード。 + `"extendedBsonTypes"`: (オプション) `true` が指定されている場合、Amazon DocumentDB へのデータ書き込み時に拡張 BSON 型を使用できます。デフォルトは `true` です。 + `"replaceDocument"`: (オプション) `true` の場合、`_id` フィールドを含むデータセットを保存するときに、ドキュメント全体を置き換えます。`false` の場合、データセットのフィールドと一致するドキュメントのフィールドのみが更新されます。デフォルトは `true` です。 + `"maxBatchSize"`: (オプション): データを保存するときの一括オペレーションの最大バッチサイズ。デフォルトは 512 です。 + `"retryWrites"`: (オプション): AWS Glue でネットワークエラーが発生した場合、特定の書き込みオペレーションを 1 回自動的に再試行します。 # OpenSearch Service 接続 AWS Glue for Spark を使用して、AWS Glue 4.0 以降のバージョンの OpenSearch Service のテーブルからの読み取りとテーブルへの書き込みを行うことができます。OpenSearch クエリを使用して、OpenSearch Service から何を読み取るかを定義できます。AWS Glue 接続を通じて AWS Secrets Manager で保存されている HTTP 基本認証情報を使用して OpenSearch Service に接続します。この機能は OpenSearch サービスのサーバーレスとは互換性がありません。　 Amazon OpenSearch Service の詳細については、[Amazon OpenSearch Service ドキュメント](https://docs.aws.amazon.com/opensearch-service/)を参照してください。 ## OpenSearch Service 接続の設定 AWS Glue から OpenSearch Service に接続するには、OpenSearch Service 認証情報を作成して AWS Secrets Manager シークレットに保存し、そのシークレットを OpenSearch Service AWS Glue 接続に関連付ける必要があります。 **前提条件:** + 読み取り元とするドメインエンドポイント *aosEndpoint* とポート *aosPort* を特定するか、または Amazon OpenSearch Service ドキュメントの手順に従ってリソースを作成します。ドメインの作成の詳細については、Amazon OpenSearch Service ドキュメントの「[Amazon OpenSearch Service ドメインの作成と管理](https://docs.aws.amazon.com//opensearch-service/latest/developerguide/createupdatedomains.html)」を参照してください。 Amazon OpenSearch Service ドメインエンドポイントのデフォルト形式は、https://search-*domainName*-*unstructuredIdContent*.*region*.es.amazonaws.com です。ドメインエンドポイントの識別の詳細については、Amazon OpenSearch Service ドキュメントの「[Amazon OpenSearch Service ドメインの作成と管理](https://docs.aws.amazon.com//opensearch-service/latest/developerguide/createupdatedomains.html)」を参照してください。 ドメインの HTTP 基本認証情報、*aosUser*、および *aosPassword* を特定または生成します。 **OpenSearch Service に対する接続を設定するには:** 1. AWS Secrets Manager で、OpenSearch Service 認証情報を使用してシークレットを作成します。Secrets Manager でシークレットを作成するには、AWS Secrets Manager ドキュメントの [AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html) にあるチュートリアルに従ってください。シークレットを作成したら、次のステップのためにシークレット名 *secretName* を保存しておきます。 + **[key/value ペア]** を選択する際に、*aosUser* という値を持つキー `USERNAME` のペアを作成します。 + **[key/value ペア]** を選択する際に、*aosPassword* という値を持つキー `PASSWORD` のペアを作成します。 1. AWS Glue コンソールで、「[AWS Glue 接続の追加](console-connections.md)」にあるステップに従って接続を作成します。接続を作成したら、将来的に AWS Glue で使用するために、接続名 *connectionName* を維持します。 + **[接続タイプ]** を選択する場合は、[OpenSearch Service] を選択します。 + ドメインエンドポイントを選択する場合は、*aosEndpoint* を入力します。 + ポートを選択する場合は、*aosPort* を入力します。 + **[AWS Secret]** をクリックして、*secretName* を入力します。 AWS Glue OpenSearch Service 接続を作成した後、AWS Glue ジョブを実行する前に次のステップを実行する必要があります。 + AWS Glue ジョブに関連付けられている IAM ロールに *secretName* を読み取るアクセス許可を付与します。 + AWS Glue ジョブ設定で、**追加のネットワーク接続**として *connectionName* を指定します。 ## OpenSearch Service のインデックスからの読み取り **前提条件:** + 読み取り元とする OpenSearch Service インデックスである *aosIndex*。 + 認証およびネットワーク位置情報を提供するように設定された AWS Glue OpenSearch Service 接続。これを取得するには、前の手順の「*OpenSearch Service に対する接続を設定するには*」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 この例では、Amazon OpenSearch Service からインデックスを読み取ります。`pushdown` パラメータを入力する必要があります。 例えば、次のようになります。 ``` opensearch_read = glueContext.create_dynamic_frame.from_options( connection_type="opensearch", connection_options={ "connectionName": "connectionName", "opensearch.resource": "aosIndex", "pushdown": "true", } ) ``` クエリ文字列を指定して、DynamicFrame で返される結果をフィルタリングすることもできます。`opensearch.query` を設定する必要があります。 `opensearch.query` は、URL クエリパラメータ文字列である *queryString* またはクエリ DSL JSON オブジェクトである *queryObject* を受け取ることができます。クエリ DSL の詳細については、OpenSearch ドキュメントの「[クエリ DSL](https://opensearch.org/docs/latest/query-dsl/index/)」を参照してください。URL クエリパラメータ文字列を入力するには、完全修飾 URL の場合と同様に、クエリの前に `?q=` を付加します。クエリ DSL オブジェクトを入力するには、入力する前に JSON オブジェクトを文字列エスケープします。 例えば、次のようになります。 ``` queryObject = "{ "query": { "multi_match": { "query": "Sample", "fields": [ "sample" ] } } }" queryString = "?q=queryString" opensearch_read_query = glueContext.create_dynamic_frame.from_options( connection_type="opensearch", connection_options={ "connectionName": "connectionName", "opensearch.resource": "aosIndex", "opensearch.query": queryString, "pushdown": "true", } ) ``` 特定の構文以外でクエリを作成する方法の詳細については、OpenSearch ドキュメントの「[クエリ文字列構文](https://opensearch.org/docs/latest/query-dsl/full-text/query-string/#query-string-syntax)」を参照してください。 配列型データを含む OpenSearch コレクションから読み取る場合は、`opensearch.read.field.as.array.include` パラメーターを使用してメソッド呼び出しでどのフィールドが配列型であるかを指定する必要があります。 例えば、次のドキュメントを読み取ると、`genre` と `actor` 配列フィールドが表示されます。 ``` { "_index": "movies", "_id": "2", "_version": 1, "_seq_no": 0, "_primary_term": 1, "found": true, "_source": { "director": "Frankenheimer, John", "genre": [ "Drama", "Mystery", "Thriller", "Crime" ], "year": 1962, "actor": [ "Lansbury, Angela", "Sinatra, Frank", "Leigh, Janet", "Harvey, Laurence", "Silva, Henry", "Frees, Paul", "Gregory, James", "Bissell, Whit", "McGiver, John", "Parrish, Leslie", "Edwards, James", "Flowers, Bess", "Dhiegh, Khigh", "Payne, Julie", "Kleeb, Helen", "Gray, Joe", "Nalder, Reggie", "Stevens, Bert", "Masters, Michael", "Lowell, Tom" ], "title": "The Manchurian Candidate" } } ``` この場合、メソッド呼び出しにそれらのフィールド名を含めます。例えば、次のようになります。 ``` "opensearch.read.field.as.array.include": "genre,actor" ``` 配列フィールドがドキュメント構造内にネストされている場合は、ドット表記を使用して参照してください: `"genre,actor,foo.bar.baz"`。これにより、埋め込みドキュメント `bar` を含む埋め込みドキュメント `foo` を介してソースドキュメントに含まれる配列 `baz` が指定されます。 ## OpenSearch Service テーブルへの書き込み この例では、既存の DynamicFrame である *dynamicFrame* から OpenSearch Service に情報を書き込みます。インデックスに既に情報がある場合、AWS Glue は DynamicFrame からのデータを付加します。`pushdown` パラメータを入力する必要があります。 **前提条件:** + 書き込み先とする OpenSearch Service テーブル。テーブルの識別情報が必要になります。これに *tableName* と名前を付けます。 + 認証およびネットワークの場所の情報を提供するように設定された AWS Glue OpenSearch Service 接続。これを取得するには、前の手順の「OpenSearch Service に対する接続を設定するには」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 例えば、次のようになります。 ``` glueContext.write_dynamic_frame.from_options( frame=dynamicFrame, connection_type="opensearch", connection_options={ "connectionName": "connectionName", "opensearch.resource": "aosIndex", }, ) ``` ## OpenSearch Service 接続のオプションのリファレンス + `connectionName` — 必須。読み込み/書き込みに使用されます。認証およびネットワークの場所の情報を接続方法に提供するように設定された AWS Glue OpenSearch Service 接続の名前。 + `opensearch.resource` — 必須。読み込み/書き込みに使用されます。有効な値: OpenSearch インデックス名。接続メソッドがインタラクションするインデックスの名前。 + `opensearch.query` — 読み取りに使用。有効な値: JSON をエスケープした文字列、またはこの文字列が `?` で始まる場合は URL の検索部分。読み取り時に取得する内容をフィルタリングする OpenSearch クエリ。このパラメータの使用方法の詳細については、前のセクション「[OpenSearch Service のインデックスからの読み取り](#aws-glue-programming-etl-connect-opensearch-read)」を参照してください。 + `pushdown` — 次の場合は必須です。読み取りに使用されます。有効な値: ブール値。Spark に読み取りクエリを OpenSearch に渡し、データベースが関連ドキュメントのみを返すように指示します。 + `opensearch.read.field.as.array.include` — 配列タイプのデータを読み取る場合は必須。読み取りに使用されます。有効値: カンマで区切られた、フィールド名のリスト。OpenSearch ドキュメントから配列として読み取るフィールドを指定します。このパラメータの使用方法の詳細については、前のセクション「[OpenSearch Service のインデックスからの読み取り](#aws-glue-programming-etl-connect-opensearch-read)」を参照してください。 # Redshift 接続 AWS Glue for Spark を使用して Amazon Redshift データベース内のテーブルに対する読み込みと書き込みを行うことができます。AWS Glue は Amazon Redshift SQL の `COPY` および `UNLOAD` コマンドを使用して、Amazon S3 を介してデータを移動し、スループットを最大化します。AWS Glue 4.0 以降では、[Apache Spark 用の Amazon Redshift インテグレーション](https://docs.aws.amazon.com/redshift/latest/mgmt/spark-redshift-connector.html)を使用して、Amazon Redshift 固有の最適化と機能を使用して読み込みと書き込みを行うことができます。また、以前のバージョンで接続する場合には利用できなかった機能もあります。 AWS Glue によって Amazon Redshift ユーザーがサーバーレスデータ統合と ETL のための AWS Glue への移行がこれまでになく簡単になった方法をご覧ください。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/ZapycBq8TKU/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/ZapycBq8TKU) ## Redshift 接続の設定 AWS Glue で Amazon Redshift クラスターを使用するには、いくつかの前提条件が必要です。 + データベースの読み込みおよび書き込み時に一時的なストレージとして使用する Amazon S3 ディレクトリがあること。 + Amazon Redshift クラスター、AWS Glue ジョブ、Amazon S3 ディレクトリ間の通信を可能にする Amazon VPC があること。 + AWS Glue ジョブと Amazon Redshift クラスターに対する適切な IAM アクセス許可があること。 ### IAM ロールを設定する **Amazon Redshift クラスターのロールを設定する** AWS Glue ジョブと統合するため、Amazon Redshift クラスターによる Amazon S3 への読み取りおよび書き込みが可能である必要があります。これを可能にするには、接続する Amazon Redshift クラスターに IAM ロールを関連付けます。ロールには、Amazon S3 の一時ディレクトリからの読み取り、および一時ディレクトリへの書き込みを許可するポリシーが必要です。ロールには、`redshift.amazonaws.com` サービスで `AssumeRole` を許可する信頼関係が必要です。 **IAM ロールを Amazon Redshift に関連付けるには** 1. **前提条件:** ファイルの一時的なストレージとして使用する Amazon S3 バケットまたはディレクトリがあること。 1. Amazon Redshift クラスターに必要な Amazon S3 のアクセス許可を特定します。Amazon Redshift クラスターとの間でデータを移動する場合、AWS Glue ジョブは Amazon Redshift に対して COPY および UNLOAD ステートメントを発行します。ジョブによって Amazon Redshift のテーブルが変更された場合、AWS Glue は CREATE LIBRARY ステートメントも発行します。Amazon Redshift がこれらのステートメントを実行するために必要な特定の Amazon S3 のアクセス許可については、Amazon Redshift のドキュメント「[Amazon Redshift: 他の AWS リソースにアクセスするアクセス許可](https://docs.aws.amazon.com/redshift/latest/dg/copy-usage_notes-access-permissions.html)」を参照してください。 1. IAM コンソールで、必要なアクセス許可を持つ IAM ポリシーを作成します。ポリシーの作成についての詳細は、[IAM ポリシーの作成](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) を参照してください。 1. IAM コンソールで、ロールと信頼関係を作成し、Amazon Redshift がロールを継承できるようにします。これについては、IAM のドキュメントにある [AWS のサービス用ロールの作成 (コンソール)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console) の手順に従ってください。 + AWS サービスのユースケースを選択するように求められた場合、[Redshift - カスタマイズ可能] を選択します。 + ポリシーをアタッチするように求められた場合、以前に定義したポリシーを選択します。 **注記** Amazon Redshiftのロールの詳細については、Amazon Redshift のドキュメントの「[ユーザーに代わって Amazon Redshift が他の AWS サービスにアクセスすることを許可する](https://docs.aws.amazon.com/redshift/latest/mgmt/authorizing-redshift-service.html)」を参照してください。 1. Amazon Redshift コンソールで、ロールを Amazon Redshift クラスターに関連付けます。これについては、[Amazon Redshift のドキュメント](https://docs.aws.amazon.com/redshift/latest/mgmt/copy-unload-iam-role.html)に記載されている手順に従ってください。 Amazon Redshift コンソールでハイライト表示されているオプションを選択して、この設定を行えます。 ![\[Amazon Redshift コンソールで IAM アクセス許可を管理する場所の例。\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/images/RS-role-config.png) **注記** AWS Glue はデフォルトで、ジョブを実行するために指定したロールを使用して作成された、Amazon Redshift の一時的な認証情報を渡します。これらの認証情報を使用することはお勧めしません。これらの認証情報は、セキュリティ上の理由により 1 時間後に失効します。 **AWS Glue ジョブのロールを設定する** AWS Glue ジョブには Amazon S3 バケットにアクセスするためのロールが必要です。Amazon Redshift クラスターの IAM アクセス許可は必要ありません。アクセスは Amazon VPC の接続とデータベースの認証情報によって制御されます。 ### Amazon VPC を設定する **Amazon Redshift データストアへのアクセスをセットアップするには** 1. AWS マネジメントコンソール にサインインして、[https://console.aws.amazon.com/redshiftv2/](https://console.aws.amazon.com/redshiftv2/) で Amazon Redshift コンソールを開きます。 1. 左のナビゲーションペインで、**[Clusters (クラスター)]** を選択してください。 1. AWS Glue からアクセスするクラスターの名前を選択します。 1. [**Cluster Properties (クラスターのプロパティ)**] セクションで、[**VPC security groups (VPC セキュリティグループ)**] 内のセキュリティグループを選択し、AWS Glue が使用できるようにします。今後の参照用に選択したセキュリティグループの名前を記録します。Amazon EC2 コンソールでセキュリティグループを選択すると、[**Security Groups**] (セキュリティグループ) の一覧が開きます。 1. 変更するセキュリティグループを選択し、[**Inbound (インバウンド)**] タブに移動します。 1. 自己参照ルールを追加して、AWS Glue コンポーネントが通信できるようにします。具体的には、[**Type (タイプ)**] `All TCP`、[**Protocol (プロトコル)**] は `TCP`、[**Port Range (ポート範囲)**] にはすべてのポートが含まれ、[**Source (ソース)**] は [**Group ID (グループ ID)**] と同じセキュリティグループ名であるというルールを追加または確認します。 インバウンドルールは以下のようになります。 **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/aws-glue-programming-etl-connect-redshift-home.html) 例: ![\[自己参照のインバウンドルールの例。\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/images/SetupSecurityGroup-Start.png) 1. アウトバウンドトラフィックのルールも追加します。すべてのポートへのアウトバウンドトラフィックを開きます。以下に例を示します。 **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/aws-glue-programming-etl-connect-redshift-home.html) または、[**Type (タイプ)**] は `All TCP`、[**Protocol (プロトコル)**] は `TCP`、[**Port Range (ポート範囲)**] にすべてのポートが含まれ、[**Destination (宛先)**] は [**Group ID (グループ ID)**] と同じセキュリティグループ名の自己参照ルールを作成します。Amazon S3 VPC エンドポイントを使用している場合は、Amazon S3 にアクセスするための HTTPS ルールも追加します。セキュリティグループルールには、VPC から Amazon S3 VPC エンドポイントへのトラフィックを許可するために、*s3-prefix-list-id* が必要です。 例: **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/aws-glue-programming-etl-connect-redshift-home.html) ### AWS Glue をセットアップ Amazon VPC 接続情報を提供する AWS Glue データカタログ接続を作成する必要があります。 **コンソールで AWS Glue への Amazon Redshift Amazon VPC 接続を設定するには** 1. 「[AWS Glue 接続の追加](console-connections.md)」のステップに従ってデータカタログ接続を作成します。接続を作成したら、次のステップのために接続名 *connectionName* を保存しておきます。 + **接続タイプ**を選択するときは、**Amazon Redshift** を選択します。 + **Redshift クラスター**を選択するときは、クラスターを名前で選択します。 + クラスターの Amazon Redshift ユーザーのデフォルト接続情報を指定します。 + Amazon VPC 設定は自動的に設定されます。 **注記** AWS SDK を使用して **Amazon Redshift** 接続を作成する場合は、Amazon VPC の `PhysicalConnectionRequirements` を手動で指定する必要があります。 1. AWS Glue ジョブ設定で、**追加のネットワーク接続**として *connectionName* を指定します。 ## 例: Amazon Redshift テーブルからの読み取り Amazon Redshift クラスターと Amazon Redshift Serverless 環境から読み込みを行うことができます。 **前提条件:** 読み込む目的の Amazon Redshift テーブルがあること。前のセクション [Redshift 接続の設定](#aws-glue-programming-etl-connect-redshift-configure) の手順を実行してください。実行後に、一時ディレクトリ *temp-s3-dir* および IAM ロール *rs-role-name* 用の Amazon S3 URI が用意されるはずです (*role-account-id* アカウント内)。 ------ #### [ Using the Data Catalog ] **その他の前提条件:** 読み取る目的の Amazon Redshift テーブル用のテーブルとデータカタログのデータベースがあること。データカタログの詳細については、[AWS Glue でのデータ検出とカタログ化](catalog-and-crawler.md) を参照してください。Amazon Redshift テーブルのエントリを作成したら、*redshift-dc-database-name* および *redshift-table-name* を使用して接続を識別します。 **設定:** 関数オプションで、`database` および `table_name` パラメータを使用してデータカタログテーブルを識別します。`redshift_tmp_dir` を使用して、Amazon S3 の一時ディレクトリを識別します。また、`additional_options` パラメータの `aws_iam_role` キーを使用して、*rs-role-name* を指定します。 ``` glueContext.create_dynamic_frame.from_catalog( database = "redshift-dc-database-name", table_name = "redshift-table-name", redshift_tmp_dir = args["temp-s3-dir"], additional_options = {"aws_iam_role": "arn:aws:iam::role-account-id:role/rs-role-name"}) ``` ------ #### [ Connecting directly ] **その他の前提条件:** Amazon Redshift テーブルの名前 (*redshift-table-name*) が必要です。そのテーブルを格納する Amazon Redshift クラスターの JDBC 接続情報が必要です。*host*、*port*、*redshift-database-name*、*username*、*password* で接続情報を入力します。 Amazon Redshift クラスターを操作するときは、Amazon Redshift コンソールから接続情報を取得できます。Amazon Redshift サーバーレスを使用する場合は、Amazon Redshift ドキュメントの「[Amazon Redshift Serverless への接続](https://docs.aws.amazon.com//redshift/latest/mgmt/serverless-connecting.html)」を参照してください。 **設定:** 関数オプションでは、`url`、`dbtable`、`user` および `password` を使用して接続パラメータを識別します。`redshift_tmp_dir` を使用して、Amazon S3 の一時ディレクトリを識別します。`from_options` を使用する場合は、`aws_iam_role` を使用して IAM ロールを指定できます。この構文はデータカタログを介して接続するのと似ていますが、`connection_options` マップにパラメータを配置します。 パスワードを AWS Glue のスクリプトにハードコードする方法は、好ましくありません。SDK for Python (Boto3) を使用して AWS Secrets Manager にパスワードを保存し、スクリプトで取得することを検討してください。 ``` my_conn_options = { "url": "jdbc:redshift://host:port/redshift-database-name", "dbtable": "redshift-table-name", "user": "username", "password": "password", "redshiftTmpDir": args["temp-s3-dir"], "aws_iam_role": "arn:aws:iam::account id:role/rs-role-name" } df = glueContext.create_dynamic_frame.from_options("redshift", my_conn_options) ``` ------ ## 例: Amazon Redshift テーブルへの書き込み Amazon Redshift クラスターと Amazon Redshift Serverless 環境に書き込みを行うことができます。 **前提条件:** Amazon Redshift クラスターがあり、前のセクション「[Redshift 接続の設定](#aws-glue-programming-etl-connect-redshift-configure)」の手順を実行すること。実行後に、一時ディレクトリ *temp-s3-dir* および IAM ロール *rs-role-name* 用の Amazon S3 URI が用意されるはずです (*role-account-id* アカウント内)。また、データベースに書き込むコンテンツがある `DynamicFrame` も必要です。 ------ #### [ Using the Data Catalog ] **その他の前提条件** Amazon Redshift クラスター用のデータカタログのデータベースと、読み取る目的のテーブルがあること。データカタログの詳細については、[AWS Glue でのデータ検出とカタログ化](catalog-and-crawler.md) を参照してください。*redshift-dc-database-name* を使用して接続を識別し、*redshift-table-name* を使用してターゲットテーブルを識別します。 **設定:** 関数オプションで、`database` パラメータを使用してデータカタログのデータベースを識別し、`table_name` を使用してテーブルを指定します。`redshift_tmp_dir` を使用して、Amazon S3 の一時ディレクトリを識別します。また、`additional_options` パラメータの `aws_iam_role` キーを使用して、*rs-role-name* を指定します。 ``` glueContext.write_dynamic_frame.from_catalog( frame = input dynamic frame, database = "redshift-dc-database-name", table_name = "redshift-table-name", redshift_tmp_dir = args["temp-s3-dir"], additional_options = {"aws_iam_role": "arn:aws:iam::account-id:role/rs-role-name"}) ``` ------ #### [ Connecting through a AWS Glue connection ] `write_dynamic_frame.from_options` メソッドを使用して、Amazon Redshift に直接接続できます。ただし、接続の詳細をスクリプトに直接挿入するのではなく、`from_jdbc_conf` メソッドを使用してデータカタログの接続に保存されている接続の詳細を参照します。これは、データベースのデータカタログテーブルをクロールまたは作成することなく実行できます。データカタログの接続ついての詳細は、[データへの接続](glue-connections.md) を参照してください。 **その他の前提条件:** データベース用のデータカタログの接続と、読み取る目的の Amazon Redshift テーブルがあること。 **設定:** *dc-connection-name* を使用して、データカタログの接続を識別します。*redshift-table-name* および *redshift-database-name* を使用して、Amazon Redshift のデータベースおよびテーブルを識別します。`catalog_connection` を使用してデータカタログの接続情報を指定し、`dbtable` および `database` を使用して Amazon Redshift の情報を指定します。この構文はデータカタログを介して接続するのと似ていますが、`connection_options` マップにパラメータを配置します。 ``` my_conn_options = { "dbtable": "redshift-table-name", "database": "redshift-database-name", "aws_iam_role": "arn:aws:iam::role-account-id:role/rs-role-name" } glueContext.write_dynamic_frame.from_jdbc_conf( frame = input dynamic frame, catalog_connection = "dc-connection-name", connection_options = my_conn_options, redshift_tmp_dir = args["temp-s3-dir"]) ``` ------ ## Amazon Redshift 接続のオプションに関するリファレンス `url`、`user` および `password` などの情報を設定するため、AWS Glue の JDBC 接続に使用される基本的な接続オプションはすべて、全 JDBC タイプで共通しています。JDBC のパラメータの詳細については、[JDBC 接続オプションのリファレンス](aws-glue-programming-etl-connect-jdbc-home.md#aws-glue-programming-etl-connect-jdbc) を参照してください。 Amazon Redshift 接続のタイプには、その他の接続オプションがいくつかあります。 + `"redshiftTmpDir"`: (必須) データベースからコピーする際に一時的なデータをステージングできる Amazon S3 パス。 + `"aws_iam_role"`: (オプション) IAM ロールの ARN。AWS Glue ジョブはこのロールを Amazon Redshift クラスターに渡し、ジョブの手順を完了するために必要なアクセス許可をクラスターに付与します。 ### AWS Glue 4.0 以降で利用可能なその他の接続オプション 新しい Amazon Redshift コネクタのオプションを、AWS Glue の接続オプションを介して渡すこともできます。サポートされているコネクタオプションの詳細なリストについては、[Apache Spark 用の Amazon Redshift の統合](https://docs.aws.amazon.com/redshift/latest/mgmt/spark-redshift-connector.html) の *Spark SQL パラメータ* セクションを参照してください。 参考までに、いくつかの新しいオプションをここで再度確認します。 | 名前 | 必須 | デフォルト | 説明 | | --- | --- | --- | --- | | autopushdown | なし | TRUE | SQL オペレーションの Spark 論理プランをキャプチャして分析することにより、述語とクエリのプッシュダウンを適用します。オペレーションは SQL クエリに変換され、Amazon Redshift で実行されることでパフォーマンスが向上します。 | | autopushdown.s3\$1result\$1cache | いいえ | FALSE | SQL クエリをキャッシュして Amazon S3 パスマッピングのデータをメモリにアンロードします。これにより、同じクエリを同じ Spark セッションで再度実行する必要がなくなります。`autopushdown` が有効な場合のみサポートされます。 | | unload\$1s3\$1format | いいえ | [PARQUET] | PARQUET - クエリ結果をパーケット形式でアンロードします。 TEXT - クエリ結果をパイプ区切りのテキスト形式でアンロードします。 | | sse\$1kms\$1key | いいえ | 該当なし | AWS のデフォルトの暗号化の代わりに `UNLOAD` オペレーション中の暗号化に使用する AWS SSE-KMS キー。 | | extracopyoptions | いいえ | 該当なし | データロード時に Amazon Redshift `COPY` コマンドに付加する追加オプション (`TRUNCATECOLUMNS`、`MAXERROR n` など) のリスト (その他のオプションについては、「[COPY: 任意指定のパラメータ](https://docs.aws.amazon.com/redshift/latest/dg/r_COPY.html#r_COPY-syntax-overview-optional-parameters)」を参照してください)。 これらのオプションは`COPY`コマンドの最後に付加されるため、使用できるのはコマンドの最後で意味のあるオプションのみであることに注意してください。これで、考えられるほとんどのユースケースがカバーされるはずです。 | | csvnullstring (実験的) | いいえ | NULL | CSV `tempformat` を使用するときに NULL として書き込む文字列値。これは実際のデータには出現しない値でなければなりません。 | これらの新しいパラメータは、次の方法で使用できます。 **パフォーマンス向上のための新しいオプション** 新しいコネクタには、パフォーマンス向上のための新しいオプションがいくつか導入されています。 + `autopushdown`: デフォルトでは有効になっています。 + `autopushdown.s3_result_cache`: デフォルトでは無効になっています。 + `unload_s3_format`: デフォルトでは `PARQUET` になっています。 これらのオプションの使用方法については、[Apache Spark 用の Amazon Redshift の統合](https://docs.aws.amazon.com/redshift/latest/mgmt/spark-redshift-connector.html) を参照してください。キャッシュされた結果には古い情報が含まれている可能性があるため、読み取りと書き込みのオペレーションが混在している場合は ` autopushdown.s3_result_cache` をオンにしないことをお勧めします。パフォーマンスを向上させ、ストレージコストを削減するために、`UNLOAD` コマンドの `unload_s3_format` オプションはデフォルトで `PARQUET` に設定されています。`UNLOAD` コマンドのデフォルト動作を使用するには、オプションを `TEXT` にリセットします。 **読み取り用の新しい暗号化オプション** デフォルトでは、Amazon Redshift テーブルからデータを読み取る際に AWS Glue が使用する一時フォルダ内のデータは、`SSE-S3` 暗号化を使用して暗号化されます。AWS Key Management Service (AWS KMS) のカスタマーマネージドキーを使用してデータを暗号化するには、AWS Glue バージョン 3.0 の従来の設定オプション `("extraunloadoptions" → s"ENCRYPTED KMS_KEY_ID '$kmsKey'")` ではなく、ksmKey が [AWS KMS からのキー ID](https://docs.aws.amazon.com/kms/latest/developerguide/find-cmk-id-arn.html) になるように `("sse_kms_key" → kmsKey)` を設定します。 ``` datasource0 = glueContext.create_dynamic_frame.from_catalog( database = "database-name", table_name = "table-name", redshift_tmp_dir = args["TempDir"], additional_options = {"sse_kms_key":""}, transformation_ctx = "datasource0" ) ``` **IAM ベースの JDBC URL をサポート** 新しいコネクタは IAM ベースの JDBC URL をサポートしているため、ユーザーやパスワード、またはシークレットを渡す必要はありません。IAM ベースの JDBC URL では、コネクタはジョブのランタイムロールを使用して Amazon Redshift データソースにアクセスします。 ステップ 1: 次の最低限必要なポリシーを AWS Glue ジョブランタイムロールにアタッチします。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": "redshift:GetClusterCredentials", "Resource": [ "arn:aws:redshift:us-east-1:111122223333:dbgroup:/*", "arn:aws:redshift:*:111122223333:dbuser:*/*", "arn:aws:redshift:us-east-1:111122223333:dbname:/" ] }, { "Sid": "VisualEditor1", "Effect": "Allow", "Action": "redshift:DescribeClusters", "Resource": "*" } ] } ``` ------ ステップ 2: IAM ベースの JDBC URL を次のように使用します。接続している Amazon Redshift ユーザー名で新しいオプション `DbUser` を指定します。 ``` conn_options = { // IAM-based JDBC URL "url": "jdbc:redshift:iam://:/", "dbtable": dbtable, "redshiftTmpDir": redshiftTmpDir, "aws_iam_role": aws_iam_role, "DbUser": "" // required for IAM-based JDBC URL } redshift_write = glueContext.write_dynamic_frame.from_options( frame=dyf, connection_type="redshift", connection_options=conn_options ) redshift_read = glueContext.create_dynamic_frame.from_options( connection_type="redshift", connection_options=conn_options ) ``` **注記** `DynamicFrame` は現在、`GlueContext.create_dynamic_frame.from_options` ワークフローに ` DbUser` が含まれている IAM ベースの JDBC URL のみをサポートしています。 ## AWS Glue バージョン 3.0 からバージョン 4.0 への移行 AWS Glue 4.0 では、さまざまなオプションと設定を搭載した新しい JDBC ドライバーや Amazon Redshift Spark コネクタに ETL ジョブでアクセスできます。新しい Amazon Redshift コネクタとドライバーはパフォーマンスを念頭に置いて作成されており、データのトランザクションの一貫性が保たれます。これらの製品については、Amazon Redshift のドキュメントに記載されています。詳細については、以下を参照してください。 + [Apache Spark 用の Amazon Redshift インテグレーション](https://docs.aws.amazon.com/redshift/latest/mgmt/spark-redshift-connector.html) + [Amazon Redshift JDBC ドライバー、バージョン 2.1](https://docs.aws.amazon.com/redshift/latest/mgmt/jdbc20-download-driver.html) **テーブル/列名と識別子の制限** 新しい Amazon Redshift Spark コネクタとドライバーで、Redshift テーブル名の要件が厳しくなっています。Amazon Redshift のテーブル名定義の詳細については、[名前と識別子](https://docs.aws.amazon.com/redshift/latest/dg/r_names.html) を参照してください。ジョブブックマークのワークフローは、ルールに一致しないテーブル名やスペースなどの特定の文字があると機能しない場合があります。 [名前と識別子](https://docs.aws.amazon.com/redshift/latest/dg/r_names.html) のルールに適合しない名前のレガシーテーブルがあり、ブックマーク (古い Amazon Redshift テーブルデータを再処理するジョブ) に問題がある場合は、テーブル名を変更することをお勧めします。詳細については、[ALTER TABLE の例](https://docs.aws.amazon.com/redshift/latest/dg/r_ALTER_TABLE_examples_basic.html) を参照してください。 **データフレームのデフォルトの一時形式の変更** AWS Glue バージョン 3.0 の Spark コネクタでは、Amazon Redshift への書き込み時にデフォルトで `tempformat` が CSV に設定されます。一貫性を保つために、AWS Glue バージョン 3.0 でも、` DynamicFrame` ではデフォルトで `tempformat` に `CSV` を使用するようになっています。以前に Amazon Redshift Spark コネクタで Spark データフレーム API を直接使用していた場合は、`DataframeReader`/`Writer` オプションで `tempformat` を CSV に明示的に設定できます。それ以外の場合は、新しい Spark コネクタで `tempformat` はデフォルトで `AVRO` になります。 **動作の変更: Amazon Redshift データ型 REAL を Spark データ型 DOUBLE ではなく FLOAT にマッピングする** AWS Glue バージョン 3.0 では、Amazon Redshift の `REAL` は Spark の ` DOUBLE` 型に変換されます。新しい Amazon Redshift Spark コネクタでは、動作が更新され、Amazon Redshift の ` REAL` 型が Spark の `FLOAT` 型に変換されたり、その逆の変換が行われたりするようになりました。従来のユースケースで引き続き Amazon Redshift の `REAL` 型を Spark の `DOUBLE` 型にマッピングする場合は、次の回避策を使用できます。 + `DynamicFrame` の場合、`DynamicFrame.ApplyMapping` で `Float` 型を `Double` 型にマッピングします。`Dataframe` の場合、`cast` を使用する必要があります。 コードサンプル: ``` dyf_cast = dyf.apply_mapping([('a', 'long', 'a', 'long'), ('b', 'float', 'b', 'double')]) ``` **VARBYTE データ型の処理** AWS Glue 3.0 および Amazon Redshift データ型を使用する場合、AWS Glue 3.0 は Amazon Redshift `VARBYTE` を Spark `STRING` 型に変換します。ただし、最新の Amazon Redshift Spark コネクタは `VARBYTE` データ型をサポートしていません。この制限を回避するには、`VARBYTE` 列をサポートされているデータ型に変換する [Redshift ビューを作成](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_VIEW.html) できます。次に、新しいコネクタを使用して、元のテーブルではなくこのビューからデータをロードします。これにより、`VARBYTE` データへのアクセスを維持しながら互換性が確保されます。 Redshift クエリの例: ``` CREATE VIEW view_name AS SELECT FROM_VARBYTE(varbyte_column, 'hex') FROM table_name ``` # Kafka 接続 Kafka 接続を使用すると、Data Catalog テーブルに格納されている情報を使用するか、データストリームに直接アクセスするための情報を指定することにより、Kafka データストリームへ読み込むまたは書き込むことができます。接続は、Kafka クラスターまたは Amazon Managed Streaming for Apache Kafka クラスターをサポートします。Kafka から Spark DataFrame に情報を読み込み、AWS Glue DynamicFrame に変換できます。DynamicFrames を JSON 形式で Kafka に書き込むことができます。データストリームに直接アクセスする場合は、これらのオプションを使用して、データストリームへのアクセス方法に関する情報を提供します。 `getCatalogSource` または `create_data_frame_from_catalog` を使用して Kafka ストリーミングソースからレコードを消費するか、`getCatalogSink` または `write_dynamic_frame_from_catalog` を使用して Kafka にレコードを書き込み、ジョブに Data Catalog データベースおよびテーブル名の情報があり、それを使用して Kafka ストリーミングソースから読み込むためのいくつかの基本パラメータを取得できる場合。`getSource`、`getCatalogSink`、`getSourceWithFormat`、`getSinkWithFormat`、`createDataFrameFromOptions`、`create_data_frame_from_options`、`write_dynamic_frame_from_catalog` を使用する場合、ここで説明する接続オプションを使用し、これらの基本パラメータを指定する必要があります。 `GlueContext` クラスで指定されたメソッドの次の引数を使用し、Kafka の接続オプションを指定できます。 + Scala + `connectionOptions`: `getSource`、`createDataFrameFromOptions`、`getSink` で使用 + `additionalOptions`: `getCatalogSource`、`getCatalogSink` で使用 + `options`: `getSourceWithFormat`、`getSinkWithFormat` で使用 + Python + `connection_options`: `create_data_frame_from_options`、`write_dynamic_frame_from_options` で使用 + `additional_options`: `create_data_frame_from_catalog`、`write_dynamic_frame_from_catalog` で使用 + `options`: `getSource`、`getSink` で使用 ストリーミング ETL ジョブに関する注意事項と制限事項については、「[ストリーミング ETL に関する注意と制限](add-job-streaming.md#create-job-streaming-restrictions)」を参照してください。 **Topics** + [Kafka の設定](#aws-glue-programming-etl-connect-kafka-configure) + [例: Kafka ストリームからの読み込み](#aws-glue-programming-etl-connect-kafka-read) + [例: Kafka ストリームへの書き込み](#aws-glue-programming-etl-connect-kafka-write) + [Kafka 接続オプションのリファレンス](#aws-glue-programming-etl-connect-kafka) ## Kafka の設定 インターネット経由で利用可能な Kafka ストリームに接続するための AWS の前提条件はありません。 AWS Glue Kafka 接続を作成して、接続認証情報を管理できます。詳細については、「[Apache Kafka データストリームの AWS Glue 接続の作成](add-job-streaming.md#create-conn-streaming)」を参照してください。AWS Glue ジョブ設定で、*connectionName* を**追加ネットワーク接続**として指定し、メソッド呼び出しで `connectionName` パラメータに *connectionName* を指定します。 場合によっては、追加の前提条件を設定する必要があります。 + IAM 認証で Amazon Managed Streaming for Apache Kafka を使用する場合は、適切な IAM 設定が必要になります。 + Amazon VPC で Amazon Managed Streaming for Apache Kafka を使用する場合は、適切な Amazon VPC 設定が必要になります。Amazon VPC 接続情報を提供する AWS Glue 接続を作成する必要があります。AWS Glue 接続を**追加ネットワーク接続**として含めるには、ジョブ設定が必要です。 ストリーミング ETL ジョブの前提条件の詳細については、「[AWS Glue でのストリーミング ETL ジョブ](add-job-streaming.md)」を参照してください。 ## 例: Kafka ストリームからの読み込み [forEachBatch](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-forEachBatch) と組み合わせて使用します。 Kafka ストリーミングソースの例： ``` kafka_options = { "connectionName": "ConfluentKafka", "topicName": "kafka-auth-topic", "startingOffsets": "earliest", "inferSchema": "true", "classification": "json" } data_frame_datasource0 = glueContext.create_data_frame.from_options(connection_type="kafka", connection_options=kafka_options) ``` ## 例: Kafka ストリームへの書き込み Kafka への書き込み例: `getSink` メソッドを使った例: ``` data_frame_datasource0 = glueContext.getSink( connectionType="kafka", connectionOptions={ JsonOptions("""{ "connectionName": "ConfluentKafka", "classification": "json", "topic": "kafka-auth-topic", "typeOfData": "kafka"} """)}, transformationContext="dataframe_ApacheKafka_node1711729173428") .getDataFrame() ``` `write_dynamic_frame.from_options` メソッドを使った例: ``` kafka_options = { "connectionName": "ConfluentKafka", "topicName": "kafka-auth-topic", "classification": "json" } data_frame_datasource0 = glueContext.write_dynamic_frame.from_options(connection_type="kafka", connection_options=kafka_options) ``` ## Kafka 接続オプションのリファレンス 読み込むとき、`"connectionType": "kafka"` に次の接続オプションを使用します。 + `"bootstrap.servers"` (必須) ブートストラップサーバーの URL のリスト (例: `b-1.vpc-test-2.o4q88o.c6.kafka.us-east-1.amazonaws.com:9094`)。このオプションは API 呼び出しで指定するか、データカタログ内のテーブルメタデータで定義する必要があります。 + `"security.protocol"` (必須) ブローカーと通信するために使用されるプロトコル。使用できる値は、`"SSL"` または `"PLAINTEXT"` です。 + `"topicName"` (必須) サブスクライブするトピックのカンマ区切りリスト。`"topicName"`、`"assign"`、または `"subscribePattern"` の中から、いずれか 1 つのみを指定する必要があります。 + `"assign"`: (必須) 消費する特定の `TopicPartitions` を指定する JSON 文字列。`"topicName"`、`"assign"`、または `"subscribePattern"` の中から、いずれか 1 つのみを指定する必要があります。 例: '\$1"topicA":[0,1],"topicB":[2,4]\$1' + `"subscribePattern"`: (必須) サブスクライブする先のトピックリストを識別する Java の正規表現文字列。`"topicName"`、`"assign"`、または `"subscribePattern"` の中から、いずれか 1 つのみを指定する必要があります。 例: 'topic.\$1' + `"classification"` (必須) レコード内のデータで使用されるファイル形式。データカタログを通じて提供されていない限り、必須です。 + `"delimiter"` (オプション) `classification` が CSV の場合に使用される値の区切り文字。デフォルトは「`,`」です。 + `"startingOffsets"`: (オプション) Kafka トピック内で、データの読み取りを開始する位置 使用できる値は、`"earliest"` または `"latest"` です。デフォルト値は `"latest"` です。 + `"startingTimestamp"`: (オプション、AWS Glue バージョン 4.0 以降でのみサポート) Kafka トピック内で、データの読み込みを開始するレコードのタイムスタンプ。指定できる値は UTC 形式 (`yyyy-mm-ddTHH:MM:SSZ` のパターン) のタイムスタンプ文字列です (`Z` は UTC タイムゾーンのオフセットを \$1/- で表します。例: 「2023-04-04T08:00:00-04:00」)。 注: AWS Glue ストリーミングスクリプトの接続オプションリストには、「startingOffsets」または「startingTimestamp」のいずれかしか表示できません。これらのプロパティの両方を含めると、ジョブが失敗します。 + `"endingOffsets"`: (オプション) バッチクエリの終了位置。設定が可能な値は、`"latest"` または、各 `TopicPartition` の終了オフセットを指定する JSON 文字列のいずれかです。 JSON 文字列の場合、`{"topicA":{"0":23,"1":-1},"topicB":{"0":-1}}` の形式を使用します。オフセットとして値 `-1` を設定する場合、`"latest"` の意味になります。 + `"pollTimeoutMs"`: (オプション) Spark ジョブエグゼキュータで、Kafka からデータをポーリングする際のタイムアウト値 (ミリ秒単位)。デフォルト値は `600000` です。 + `"numRetries"`: (オプション) Kafka オフセットのフェッチが失敗したと判断される前の再試行回数。デフォルト値は `3` です。 + `"retryIntervalMs"`: (オプション) Kafka オフセットのフェッチを開始するまでの待機時間 (ミリ秒)。デフォルト値は `10` です。 + `"maxOffsetsPerTrigger"`: (オプション) 処理されるオフセットの最大数を、トリガー間隔ごとのレート上限で指定する値。指定されたオフセットの合計数は、異なるボリュームの `topicPartitions` 間で均等に分割されます。デフォルト値は「null」です。この場合、コンシューマーは既知の最新のオフセットまで、すべてのオフセットを読み取ります。 + `"minPartitions"`: (オプション) Kafka から読み取ることを想定する、最小のパーティション数。デフォルト値は「null」です。これは、Spark パーティションの数が Kafka パーティションの数に等しいことを意味します。 + `"includeHeaders"`: (オプション) Kafka ヘッダーを含めるかどうかを決定します。このオプションが「true」に設定されている場合、データ出力には、「glue\$1streaming\$1kafka\$1headers」という名前で `Array[Struct(key: String, value: String)]` 型の列が追加されます。デフォルト値は『false』です。このオプションは、AWS Glue バージョン 3.0 以降でのみ使用可能です。 + `"schema"`: (inferSchema に false を設定した場合は必須) ペイロードの処理に使用するスキーマ。分類が `avro` である場合、提供されるスキーマには Avro スキーマ形式を使用する必要があります。分類が `avro` 以外の場合、提供されるスキーマは DDL スキーマ形式である必要があります。 以下に、スキーマの例を示します。 ------ #### [ Example in DDL schema format ] ``` 'column1' INT, 'column2' STRING , 'column3' FLOAT ``` ------ #### [ Example in Avro schema format ] ``` { "type":"array", "items": { "type":"record", "name":"test", "fields": [ { "name":"_id", "type":"string" }, { "name":"index", "type": [ "int", "string", "float" ] } ] } } ``` ------ + `"inferSchema"`: (オプション) デフォルト値は「false」です。「true」に設定すると、実行時に、スキーマが `foreachbatch` 内のペイロードから検出されます。 + `"avroSchema"`: (非推奨) Avro 形式を使用する場合に、Avro データのスキーマを指定するために使用されるパラメータです。このパラメータは非推奨となりました。`schema` パラメータを使用します。 + `"addRecordTimestamp"`: (オプション) このオプションを「true」に設定すると、トピックが対応するレコードを受信した時刻を表示する「\$1\$1src\$1timestamp」という列が、データ出力に追加で表示されます。デフォルト値は、「false」です。このオプションは AWS Glue のバージョン 4.0 以降でサポートされています。 + `"emitConsumerLagMetrics"`: (オプション) このオプションを「true」に設定すると、バッチごとに、トピックが受信した最も古いレコードと、それが AWS Glue で CloudWatch に到着した時間との、間隔のメトリクスが出力されます。このメトリクスの名前は「glue.driver.streaming.maxConsumerLagInMs」です。デフォルト値は、「false」です。このオプションは AWS Glue バージョン 4.0 以降でサポートされています。 書き込むとき、`"connectionType": "kafka"` に次の接続オプションを使用します。 + `"connectionName"` (必須) Kafka クラスターへの接続に使用される AWS Glue 接続の名前 (Kafka ソースと同様)。 + `"topic"` (必須) トピック列が存在する場合、トピック設定オプションが設定されていない限り、指定された行を Kafka に書き込む際にトピック列の値がトピックとして使用されます。つまり、`topic` 設定オプションはトピック列をオーバーライドします。 + `"partition"` (オプション) 有効なパーティション番号が指定された場合、レコードの送信時にその `partition` が使用されます。 パーティションが指定されずに `key` が存在する場合、キーのハッシュを使用してパーティションが選択されます。 `key` と `partition` のどちらも存在しない場合、そのパーティションに少なくとも batch.size バイトが生成された際に変更内容のスティッキーパーティション分割に基づいてパーティションが選択されます。 + `"key"` (オプション) `partition` が null の場合、パーティション分割に使用されます。 + `"classification"` (オプション) レコードのデータに使用されるファイル形式。JSON、CSV、Avro のみをサポートしています。 Avro 形式を使用すると、シリアル化するためにカスタムの AvroSchema を提供できますが、シリアル化解除する場合にもソースに提供する必要があることに注意してください。それ以外の場合、デフォルトで Apache AvroSchema を使用してシリアル化します。 さらに、[Kafka プロデューサーの設定パラメーター](https://kafka.apache.org/documentation/#producerconfigs)を更新することにより、必要に応じて Kafka シンクを微調整できます。接続オプションには許可リストがないことに注意してください。すべてのキー値のペアはそのままシンクに保持されます。 ただし、有効にならないオプションの小さな拒否リストがあります。詳細については、「[Apache 固有の設定](https://spark.apache.org/docs/latest/structured-streaming-kafka-integration.html)」を参照してください。 # Azure Cosmos DB 接続 AWS Glue for Spark を使用すると、AWS Glue 4.0 以降のバージョンの NoSQL API を使用して、Azure Cosmos DB の既存のコンテナとの間で読み取りと書き込みを行うことができます。SQL クエリを使用して、Azure Cosmos DB から何を読み取るかを定義できます。AWS Glue 接続を通じて AWS Secrets Manager に保存されている Azure Cosmos DB キーを使用して Azure Cosmos DB に接続します。 Azure Cosmos DB for NoSQL の詳細については、[Azure のドキュメント](https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/)を参照してください。 ## Azure Cosmos DB 接続の設定 AWS Glue から Azure Cosmos DB に接続するには、Azure Cosmos DB キーを作成して AWS Secrets Manager シークレットに保存し、そのシークレットを Azure Cosmos DB AWS Glue 接続に関連付ける必要があります。 **前提条件:** + Azure では、AWS Glue で使用する Azure Cosmos DB キー (`cosmosKey`) を特定または生成する必要があります。詳細については、Azure ドキュメントの「[Azure Cosmos DB のデータへのアクセスをセキュリティで保護する](https://learn.microsoft.com/en-us/azure/cosmos-db/secure-access-to-data?tabs=using-primary-key)」を参照してください。 **Azure Cosmos DB に対する接続を設定するには:** 1. AWS Secrets Manager で、Azure Cosmos DB キーを使用してシークレットを作成します。Secrets Manager でシークレットを作成するには、AWS Secrets Manager ドキュメントの [AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html) にあるチュートリアルに従ってください。シークレットを作成したら、次のステップのためにシークレット名 *secretName* を保存しておきます。 + **[key/value ペア]** を選択する際に、*cosmosKey* という値を持つキー `spark.cosmos.accountKey` のペアを作成します。 1. AWS Glue コンソールで、「[AWS Glue 接続の追加](console-connections.md)」にあるステップに従って接続を作成します。接続を作成したら、将来的に AWS Glue で使用するために、接続名 *connectionName* を維持します。 + **[接続タイプ]** を選択する際に、[Azure Cosmos DB] を選択します。 + **[AWS Secret]** をクリックして、*secretName* を入力します。 AWS Glue Azure Cosmos DB 接続を作成した後、AWS Glue ジョブを実行する前に次のステップを実行する必要があります。 + AWS Glue ジョブに関連付けられている IAM ロールに *secretName* を読み取るアクセス許可を付与します。 + AWS Glue ジョブ設定で、**追加のネットワーク接続**として *connectionName* を指定します。 ## Azure Cosmos DB for NoSQL コンテナからの読み取り **前提条件:** + 読み取り元とする Azure Cosmos DB for NoSQL コンテナ。コンテナの識別情報が必要になります。 Azure Cosmos for NoSQL コンテナは、データベースとコンテナによって識別されます。Azure Cosmos for NoSQL API に接続する際には、データベース *cosmosDBName* とコンテナ *cosmosContainerName* の名前を指定する必要があります。 + 認証およびネットワークの場所の情報を提供するように設定された AWS Glue Azure Cosmos DB 接続。これを取得するには、前の手順の「*Azure Cosmos DB に対する接続を設定するには*」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 例えば、次のようになります。 ``` azurecosmos_read = glueContext.create_dynamic_frame.from_options( connection_type="azurecosmos", connection_options={ "connectionName": connectionName, "spark.cosmos.database": cosmosDBName, "spark.cosmos.container": cosmosContainerName, } ) ``` SELECT SQL クエリを指定して、DynamicFrame に返される結果をフィルタリングすることもできます。`query` を設定する必要があります。 例えば、次のようになります。 ``` azurecosmos_read_query = glueContext.create_dynamic_frame.from_options( connection_type="azurecosmos", connection_options={ "connectionName": "connectionName", "spark.cosmos.database": cosmosDBName, "spark.cosmos.container": cosmosContainerName, "spark.cosmos.read.customQuery": "query" } ) ``` ## Azure Cosmos DB for NoSQL コンテナへの書き込み この例では、既存の DynamicFrame である *dynamicFrame* から Azure Cosmos DB に情報を書き込みます。コンテナに既に情報がある場合、AWS Glue は DynamicFrame からのデータを付加します。コンテナ内の情報のスキーマが、書き込む情報と異なる場合、エラーが発生します。 **前提条件:** + 書き込み先とする Azure Cosmos DB テーブル。コンテナの識別情報が必要になります。**接続メソッドを呼び出す前にコンテナを作成する必要があります。** Azure Cosmos for NoSQL コンテナは、データベースとコンテナによって識別されます。Azure Cosmos for NoSQL API に接続する際には、データベース *cosmosDBName* とコンテナ *cosmosContainerName* の名前を指定する必要があります。 + 認証およびネットワークの場所の情報を提供するように設定された AWS Glue Azure Cosmos DB 接続。これを取得するには、前の手順の「Azure Cosmos DB に対する接続を設定するには」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 例えば、次のようになります。 ``` azurecosmos_write = glueContext.write_dynamic_frame.from_options( frame=dynamicFrame, connection_type="azurecosmos", connection_options={ "connectionName": connectionName, "spark.cosmos.database": cosmosDBName, "spark.cosmos.container": cosmosContainerName ) ``` ## Azure Cosmos DB 接続オプションのリファレンス + `connectionName` — 必須。読み込み/書き込みに使用されます。認証およびネットワークの場所の情報を接続方法に提供するように設定された AWS Glue Azure Cosmos DB 接続の名前。 + `spark.cosmos.database` — 必須。読み込み/書き込みに使用されます。有効な値: データベース名。Azure Cosmos DB for NoSQL のデータベース名。 + `spark.cosmos.container` — 必須。読み込み/書き込みに使用されます。有効な値: コンテナ名。Azure Cosmos DB for NoSQL のコンテナ名。 + `spark.cosmos.read.customQuery` — 読み取りに使用。有効な値: SELECT SQL クエリ。読み取るドキュメントを選択するためのカスタムクエリ。 # Azure SQL 接続 AWS Glue for Spark を使用して、AWS Glue 4.0 以降のバージョンの Azure SQL Managed Instances のテーブルからの読み取りとテーブルへの書き込みを行うことができます。SQL クエリを使用して、Azure SQL から何を読み取るかを定義できます。AWS Glue 接続を介して AWS Secrets Manager で保存されているユーザーおよびパスワードの認証情報を使用して Azure SQL に接続します。 Azure SQL の詳細については、[Azure SQL のドキュメント](https://azure.microsoft.com/en-us/products/azure-sql)を参照してください。 ## Azure SQL 接続の設定 AWS Glue から Azure SQL に接続するには、Azure SQL 認証情報を作成して AWS Secrets Manager シークレットに保存し、そのシークレットを Azure SQL AWS Glue 接続に関連付ける必要があります。 **Azure SQL に対する接続を設定するには:** 1. AWS Secrets Manager で、Azure SQL 認証情報を使用してシークレットを作成します。Secrets Manager でシークレットを作成するには、AWS Secrets Manager ドキュメントの [AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html) にあるチュートリアルに従ってください。シークレットを作成したら、次のステップのためにシークレット名 *secretName* を保存しておきます。 + **[key/value ペア]** を選択する際に、*azuresqlUsername* という値を持つキー `user` のペアを作成します。 + **[key/value ペア]** を選択する際に、*azuresqlPassword* という値を持つキー `password` のペアを作成します。 1. AWS Glue コンソールで、「[AWS Glue 接続の追加](console-connections.md)」にあるステップに従って接続を作成します。接続を作成したら、将来的に AWS Glue で使用するために、接続名 *connectionName* を維持します。 + **[接続タイプ]** を選択する際に、[Azure SQL] を選択します。 + **Azure SQL URL** を指定する場合は、JDBC エンドポイント URL を入力します。 URL は、次のような形式になります: `jdbc:sqlserver://databaseServerName:databasePort;databaseName=azuresqlDBname;`。 AWS Glue には次の URL プロパティが必要です。 + `databaseName` – 接続先の Azure SQL のデフォルトデータベース。 Azure SQL Managed Instances の JDBC URL の詳細については、[Microsoft のドキュメント](https://learn.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=azuresqldb-mi-current)を参照してください。 + **[AWS Secret]** をクリックして、*secretName* を入力します。 AWS Glue Azure SQL 接続を作成した後、AWS Glue ジョブを実行する前に次のステップを実行する必要があります。 + AWS Glue ジョブに関連付けられている IAM ロールに *secretName* を読み取るアクセス許可を付与します。 + AWS Glue ジョブ設定で、**追加のネットワーク接続**として *connectionName* を指定します。 ## Azure SQL テーブルからの読み取り **前提条件:** + 読み取り元とする Azure SQL テーブル。テーブルの識別情報である *databaseName* および *tableIdentifier* が必要になります。 Azure SQL テーブルは、データベース、スキーマ、テーブル名によって識別されます。Azure SQL に接続する際には、データベース名とテーブル名を指定する必要があります。スキーマがデフォルトの「public」でない場合は、スキーマも指定する必要があります。データベースは、*connectionName* の URL プロパティ、`dbtable` を通じたスキーマおよびテーブル名を介して指定されます。 + 認証情報を提供するように設定された AWS Glue Azure SQL 接続。認証情報を設定するには、前の手順「Azure SQL に対する接続を設定するには」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 例えば、次のようになります。 ``` azuresql_read_table = glueContext.create_dynamic_frame.from_options( connection_type="azuresql", connection_options={ "connectionName": "connectionName", "dbtable": "tableIdentifier" } ) ``` SELECT SQL クエリを指定して、DynamicFrame に返される結果をフィルタリングすることもできます。`query` を設定する必要があります。 例えば、次のようになります。 ``` azuresql_read_query = glueContext.create_dynamic_frame.from_options( connection_type="azuresql", connection_options={ "connectionName": "connectionName", "query": "query" } ) ``` ## Azure SQL テーブルへの書き込み この例では、既存の DynamicFrame である *dynamicFrame* から Azure SQL に情報を書き込みます。テーブルに既に情報がある場合、AWS Glue は DynamicFrame からのデータを付加します。 **前提条件:** + 書き込み先とする Azure SQL テーブル。テーブルの識別情報である *databaseName* および *tableIdentifier* が必要になります。 Azure SQL テーブルは、データベース、スキーマ、テーブル名によって識別されます。Azure SQL に接続する際には、データベース名とテーブル名を指定する必要があります。スキーマがデフォルトの「public」でない場合は、スキーマも指定する必要があります。データベースは、*connectionName* の URL プロパティ、`dbtable` を通じたスキーマおよびテーブル名を介して指定されます。 + Azure SQL 認証情報。認証情報を設定するには、前の手順「Azure SQL に対する接続を設定するには」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 例えば、次のようになります。 ``` azuresql_write = glueContext.write_dynamic_frame.from_options( connection_type="azuresql", connection_options={ "connectionName": "connectionName", "dbtable": "tableIdentifier" } ) ``` ## Azure SQL 接続オプションのリファレンス + `connectionName` — 必須。読み込み/書き込みに使用されます。認証情報を接続方法に提供するように設定された AWS Glue Azure SQL 接続の名前。 + `databaseName` — 読み込み/書き込みに使用されます。有効な値: Azure SQL データベース名。接続先の Azure SQL のデータベースの名前。 + `dbtable` — 書き込みの場合は必須。`query` が指定されていない限り、読み取りの場合は必須。読み込み/書き込みに使用されます。有効な値: Azure SQL テーブルの名前、またはピリオドで区切られたスキーマ/テーブル名の組み合わせ。接続先のテーブルを識別するテーブルとスキーマを指定するために使用されます。デフォルトのスキーマは「public」です。テーブルがデフォルト以外のスキーマにある場合は、この情報を `schemaName.tableName` の形式で入力します。 + `query` — 読み取りに使用。Azure SQL から読み取るときに何を取得するかを定義する Transact-SQL SELECT クエリ。詳細については、[Microsoft のドキュメント](https://learn.microsoft.com/en-us/sql/t-sql/queries/select-transact-sql?view=azuresqldb-mi-current)を参照してください。 # BigQuery 接続 AWS Glue for Spark を使用して、AWS Glue 4.0 以降のバージョンの Google BigQuery のテーブルからの読み取りとテーブルへの書き込みを行うことができます。Google SQL クエリを使用して BigQuery からの読み取りを行うことができます。AWS Glue 接続を介して AWS Secrets Manager で保存されている認証情報を使用して BigQuery に接続します。 Google BigQuery の詳細については、[Google Cloud BigQuery のウェブサイト](https://cloud.google.com/bigquery)を参照してください。 ## BigQuery 接続を設定する AWS Glue から Google BigQuery へ接続するには、Google Cloud Platform の認証情報を作成して AWS Secrets Manager シークレットに保存し、そのシークレットを Google BigQuery AWS Glue 接続に関連付ける必要があります。 **BigQuery への接続を設定するには:** 1. Google Cloud Platform で、関連するリソースを作成して特定します。 + 接続したい BigQuery テーブルを含む GCP プロジェクトを作成または特定します。 + BigQuery API を有効にします。詳細については、「[Use the BigQuery Storage Read API to read table data](https://cloud.google.com/bigquery/docs/reference/storage/#enabling_the_api)」を参照してください。 1. Google Cloud Platform で、サービスアカウントの認証情報を作成してエクスポートします。 BigQuery 認証情報ウィザードを使用すると、[認証情報の作成](https://console.cloud.google.com/apis/credentials/wizard?api=bigquery.googleapis.com) というステップを迅速に実行できます。 GCP でサービスアカウントを作成するには、[サービスアカウントを作成する](https://cloud.google.com/iam/docs/service-accounts-create) にあるチュートリアルに従ってください。 + **プロジェクト** を選択するときは、BigQuery テーブルを含むプロジェクトを選択します。 + サービスアカウントの GCP IAM ロールを選択するときは、BigQuery テーブルの読み取り、書き込み、作成を行う BigQuery ジョブを実行するための適切な権限を付与するロールを追加または作成します。 サービスアカウントの認証情報を作成するには、[サービスアカウントキーを作成する](https://cloud.google.com/iam/docs/keys-create-delete#creating) にあるチュートリアルに従ってください。 + キータイプを選択するときは、**[JSON]** を選択します。 これで、サービスアカウントの認証情報が記載された JSON ファイルがダウンロードされたはずです。これは次のように表示されます。 ``` { "type": "service_account", "project_id": "*****", "private_key_id": "*****", "private_key": "*****", "client_email": "*****", "client_id": "*****", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "*****", "universe_domain": "googleapis.com" } ``` 1. 認証情報 JSON ファイルを、適切に安全な Amazon S3 の場所にアップロードします。ファイルへのパス、*s3secretpath* は、今後の手順に備えて保持してください。 1. AWS Secrets Manager で、Google Cloud Platform の認証情報を使用してシークレットを作成します。Secrets Manager でシークレットを作成するには、AWS Secrets Manager ドキュメントの [AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html) にあるチュートリアルに従ってください。シークレットを作成したら、次のステップのためにシークレット名 *secretName* を保存しておきます。 キー/値のペアを作成するときは、次のようにキーと値を指定します。 + `token_uri`、`client_x509_cert_url`、`private_key_id`、`project_id`、`universe_domain`、`auth_provider_x509_cert_url`、`auth_uri`、`client_email`、`private_key`、`type`、`client_id` キーの場合は、ダウンロードした JSON ファイル内の対応する値を指定します。 + `spark.hadoop.google.cloud.auth.service.account.json.keyfile` キーには、*s3secretpath* を指定します。 1. AWS Glue データカタログで、[AWS Glue 接続の追加](console-connections.md) にある手順に従って接続を作成します。接続を作成したら、次のステップのために接続名 *connectionName* を保存しておきます。 + **[接続タイプ]** を選択するときは、Google BigQuery を選択してください。 + **[AWS Secret]** をクリックして、*secretName* を入力します。 1. AWS Glue ジョブに関連付けられている IAM ロールに *secretName* を読み取るアクセス許可を付与します。 1. AWS Glue ジョブ設定で、**追加のネットワーク接続**として *connectionName* を指定します。 ## BigQuery テーブルから読み取る **前提条件:** + 読み取る対象の BigQuery テーブル。フォーム `[dataset].[table]` には BigQuery のテーブル名とデータセット名が必要です。これに *tableName* と名前を付けます。 + BigQuery テーブルの請求プロジェクト。そのためには、プロジェクトの名前、*parentProject* が必要です。請求元の親プロジェクトがない場合は、テーブルを含むプロジェクトを使用してください。 + BigQuery の認証情報。「**AWS Glue で接続認証情報を管理するには」の手順を実行して、認証情報を設定します。AWS Glue 接続、*connectionName* の名前が必要になります。 例えば、次のようになります。 ``` bigquery_read = glueContext.create_dynamic_frame.from_options( connection_type="bigquery", connection_options={ "connectionName": "connectionName", "parentProject": "parentProject", "sourceType": "table", "table": "tableName", } ``` クエリを指定して、DynamicFrame に返される結果をフィルタリングすることもできます。`query`、`sourceType`、`viewsEnabled` および `materializationDataset` を設定する必要があります。 例えば、次のようになります。 **追加の前提条件:** BigQuery がクエリのマテリアライズドビューを書き込むことのできる BigQuery データセット、*materializationDataset* を作成または特定する必要があります。 *materializationDataset* にテーブルを作成するには、サービスアカウントに適切な GCP IAM アクセス許可を付与する必要があります。 ``` glueContext.create_dynamic_frame.from_options( connection_type="bigquery", connection_options={ "connectionName": "connectionName", "materializationDataset": materializationDataset, "parentProject": "parentProject", "viewsEnabled": "true", "sourceType": "query", "query": "select * from bqtest.test" } ) ``` ## BigQuery テーブルへ書き込む この例では BigQuery サービスに直接書き込みます。BigQuery は「間接」書き込み方法もサポートしています。間接書き込みの設定の詳細については、[Google BigQuery での間接書き込みを使用する](#aws-glue-programming-etl-connect-bigquery-indirect-write) を参照してください。 **前提条件:** + 書き込む対象の BigQuery テーブル。フォーム `[dataset].[table]` には BigQuery のテーブル名とデータセット名が必要です。自動的に作成される新しいテーブル名を指定することもできます。これに *tableName* と名前を付けます。 + BigQuery テーブルの請求プロジェクト。そのためには、プロジェクトの名前、*parentProject* が必要です。請求元の親プロジェクトがない場合は、テーブルを含むプロジェクトを使用してください。 + BigQuery の認証情報。「**AWS Glue で接続認証情報を管理するには」の手順を実行して、認証情報を設定します。AWS Glue 接続、*connectionName* の名前が必要になります。 例えば、次のようになります。 ``` bigquery_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="bigquery", connection_options={ "connectionName": "connectionName", "parentProject": "parentProject", "writeMethod": "direct", "table": "tableName", } ) ``` ## BigQuery 接続オプションのリファレンス + `project` — デフォルト: Google Cloud サービスアカウントのデフォルト。読み込み/書き込みに使用されます。テーブルに関連付けられている Google Cloud プロジェクトの名前。 + `table` — (必須) 読み込み/書き込みに使用されます。`[[project:]dataset.]` フォーマット内の BigQuery テーブルの名前。 + `dataset` — `table` オプションで定義されていない場合は必須。読み込み/書き込みに使用されます。BigQuery テーブルを含むデータセットの名前。 + `parentProject` — デフォルト: Google Cloud サービスアカウントのデフォルト。読み込み/書き込みに使用されます。請求に使用される `project` に関連付けられた Google Cloud プロジェクトの名前。 + `sourceType` — 読み取りに使用。読み取り時には必須です。有効値: `table`、`query` AWS Glue にテーブルで読み取るかクエリで読み取るかを通知します。 + `materializationDataset` — 読み取りに使用。有効な値: 文字列。ビューのマテリアライゼーションの保存に使用される BigQuery データセットの名前。 + `viewsEnabled` — 読み取りに使用。デフォルト: false。有効な値: true、false。BigQuery がビューを使用するかどうかを設定します。 + `query` — 読み取りに使用。`viewsEnabled` が true のときに使用されます。GoogleSQL DQL クエリ。 + `temporaryGcsBucket` — 書き込みに使用。`writeMethod` がデフォルト (`indirect`) に設定されている場合は必須です。BigQuery への書き込み中に中間形式のデータを保存するために使用される Google Cloud Storage バケットの名前。 + `writeMethod` - デフォルト: `indirect`。有効な値: `direct`、`indirect`。書き込みに使用。データの書き込みに使用する方法を指定します。 + `direct` に設定すると、コネクタは BigQuery Storage Write API を使用して書き込みを行います。 + `indirect` に設定すると、コネクタは Google Cloud Storage に書き込み、読み取り操作を使用して BigQuery に転送します。Google Cloud サービスアカウントには適切な GCS アクセス許可が必要です。 ## Google BigQuery での間接書き込みを使用する この例では、Google Cloud ストレージにデータを書き込み、それを Google BigQuery にコピーする間接書き込みを使用しています。 **前提条件:** Google Cloud Storage の一時的なバケット、*temporaryBucket* が必要になります。 AWS Glue の GCP サービスアカウントの GCP IAM ロールには、*temporaryBucket* にアクセスするための適切な GCS アクセス許可が必要です。 **追加設定:** **BigQuery による間接書き込みを設定するには:** 1. [BigQuery 接続を設定する](#aws-glue-programming-etl-connect-bigquery-configure) にアクセスして検索するか、GCP 認証情報の JSON ファイルを再ダウンロードします。ジョブで使用する Google BigQuery AWS Glue 接続の AWS Secrets Manager シークレットである *secretName* を特定します。 1. 認証情報 JSON ファイルを、適切に安全な Amazon S3 の場所にアップロードします。ファイルへのパス、*s3secretpath* は、今後の手順に備えて保持してください。 1. *secretName* を編集し、`spark.hadoop.google.cloud.auth.service.account.json.keyfile` キーを追加します。*s3secretpath* に値を設定します。 1. AWS Glue ジョブに、*s3secretpath* にアクセスするための Amazon S3 IAM アクセス許可を付与します。 一時的な GCS バケットの場所を書き込みメソッドに指定できるようになりました。`indirect` がこれまでデフォルトだったように、`writeMethod` を指定する必要はありません。 ``` bigquery_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="bigquery", connection_options={ "connectionName": "connectionName", "parentProject": "parentProject", "temporaryGcsBucket": "temporaryBucket", "table": "tableName", } ) ``` # JDBC 接続 特定の (通常はリレーショナル) データベースタイプは、JDBC 標準による接続をサポートします。JDBC の詳細については、[Java JDBC API](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) に関するドキュメントを参照してください。AWSGlue は JDBC コネクタを介した特定のデータベースへの接続をネイティブにサポートしています。JDBC ライブラリは AWS Glue Spark ジョブで提供されます。AWS Glue ライブラリを使用してこれらのデータベースタイプに接続すると、標準のオプションセットにアクセスできます。 JDBC connectionType の値には次のようなものがあります。 + `"connectionType": "sqlserver"`: Microsoft SQL Server データベースへの接続を指定します。 + `"connectionType": "mysql"`: MySQL データベースへの接続を指定します。 + `"connectionType": "oracle"`: Oracle データベースへの接続を指定します。 + `"connectionType": "postgresql"`: PostgreSQL データベースへの接続を指定します。 + `"connectionType": "redshift"`: Amazon Redshift データベースへの接続を指定します。詳細については、[Redshift 接続](aws-glue-programming-etl-connect-redshift-home.md) を参照してください。 次の表に、AWS Glue がサポートする JDBC ドライバーのバージョンを示します。 | 製品 | Glue 5.1 の JDBC ドライバーのバージョン | Glue 5.0 の JDBC ドライバーのバージョン | Glue 4.0 の JDBC ドライバーのバージョン | Glue 3.0 の JDBC ドライバーのバージョン | Glue 0.9、1.0、2.0 の JDBC ドライバーのバージョン | | --- | --- | --- | --- | --- | --- | | Microsoft SQL Server | 10.2.0 | 10.2.0 | 9.4.0 | 7.x | 6.x | | MySQL | 8.0.33 | 8.0.33 | 8.0.23 | 8.0.23 | 5.1 | | Oracle Database | 23.3.0.23.09 | 23.3.0.23.09 | 21.7 | 21.1 | 11.2 | | PostgreSQL | 42.7.3 | 42.7.3 | 42.3.6 | 42.2.18 | 42.1.x | | Amazon Redshift \$1 | redshift-jdbc42-2.1.0.29 | redshift-jdbc42-2.1.0.29 | redshift-jdbc42-2.1.0.16 | redshift-jdbc41-1.2.12.1017 | redshift-jdbc41-1.2.12.1017 | \$1 Amazon Redshift 接続タイプの場合は、書式設定オプションを含め、JDBC 接続用に接続オプションに含まれるその他のオプション名/値ペアはすべて、基になる SparkSQL DataSource に直接渡されます。AWS Glue 4.0 以降のバージョンの AWS Glue with Spark ジョブでは、Amazon Redshift の AWS Glue ネイティブコネクタは Apache Spark の Amazon Redshift インテグレーションを使用します。詳細については、「[Apache Spark 用の Amazon Redshift の統合](https://docs.aws.amazon.com/redshift/latest/mgmt/spark-redshift-connector.html)」を参照してください。以前のバージョンでは、「[Spark 用の Amazon Redshift データソース](https://github.com/databricks/spark-redshift)」を参照してください。 JDBC を使用して Amazon RDS データストアに接続するように Amazon VPC を設定するには、「[AWS Glue から Amazon RDS データストアに JDBC 接続するための Amazon VPC の設定](setup-vpc-for-glue-access.md)」を参照してください。 **注記** AWS Glue ジョブは、1 回の実行で 1 つのサブネットにのみ関連付けられます。これは、同じジョブで複数のデータソースに接続する能力に影響する可能性があります。この動作は JDBC ソースに限定されません。 **Topics** + [JDBC 接続オプションのリファレンス](#aws-glue-programming-etl-connect-jdbc) + [sampleQuery を使用](#aws-glue-programming-etl-jdbc-samplequery) + [カスタム JDBC ドライバーを使用](#aws-glue-programming-etl-jdbc-custom-driver) + [JDBC テーブルからの並列読み取り](run-jdbc-parallel-read-job.md) + [AWS Glue から Amazon RDS データストアに JDBC 接続するための Amazon VPC の設定](setup-vpc-for-glue-access.md) ## JDBC 接続オプションのリファレンス 既に JDBC AWS Glue 接続を定義している場合、URL、ユーザー、パスワードなど、その中で定義されている設定プロパティを再利用できるため、コードで接続オプションとして指定する必要はありません。この機能は、AWS Glue バージョン 3.0 以降でのみ有効です。これを行うには、次の接続プロパティを使用します。 + `"useConnectionProperties"`: この設定を接続から使用するときは、「true」に設定します。 + `"connectionName"`: この設定を取得する接続名を入力します。接続は、ジョブと同じリージョンで定義されている必要があります。 JDBC 接続では、次の接続オプションを使用します。 + `"url"`: (必須) データベースの JDBC URL。 + `"dbtable"`: (必須) 読み込み元のデータベーステーブル。データベース内でスキーマをサポートする JDBC データストアの場合、`schema.table-name` を指定します。スキーマを指定しない場合、デフォルトの「パブリック」スキーマが使用されます。 + `"user"`: (必須) 接続時に使用するユーザー名。 + `"password"`: (必須) 接続時に使用するパスワード。 + (オプション) 次のオプションを使用すると、カスタム JDBC ドライバーを指定できます。AWS Glue がネイティブでサポートしていないドライバーを使用する必要がある場合は、これらのオプションを使用します。 ソースおよびターゲットが同じデータベース製品の場合でも、ETL ジョブは、データソースおよびターゲットに対して、異なるバージョンの JDBC ドライバーを使用することができます。これにより、異なるバージョンのソースデータベースとターゲットデータベース間でデータを移行できます。これらのオプションを使用するには、最初に JDBC ドライバーの JAR ファイルを Amazon S3 にアップロードする必要があります。 + `"customJdbcDriverS3Path"`: カスタム JDBC ドライバーの Amazon S3 パス。 + `"customJdbcDriverClassName"`: JDBC ドライバーのクラス名。 + `"bulkSize"`:（オプション）JDBC ターゲットへのバルクロードを高速化するためのパラレル挿入を構成するために使用します。データの書き込みまたは挿入時に使用する並列度の整数値を指定します。このオプションは、Arch User Repository (AUR) などのデータベースへの書き込みのパフォーマンスを向上させるのに役立ちます。 + `"hashfield"` (オプション) JDBC テーブルから並列で読み込むときにデータをパーティションに分割するために使用される JDBC テーブル内の列の名前を指定するために使用される文字列。「hashfield」または「hashexpression」を指定します。詳細については、[JDBC テーブルからの並列読み取り](run-jdbc-parallel-read-job.md) を参照してください。 + `"hashexpression"` (オプション) 整数を返す SQL SELECT 句。JDBC テーブルから並列で読み込むときに、JDBC テーブル内のデータをパーティションに分割するために使用されます。「hashfield」または「hashexpression」を指定します。詳細については、[JDBC テーブルからの並列読み取り](run-jdbc-parallel-read-job.md) を参照してください。 + `"hashpartitions"` (オプション) 正の整数。JDBC テーブルから並列で読み込むときに、JDBC テーブルの並列読み込み数を指定するために使用されます。デフォルト: 7。詳細については、[JDBC テーブルからの並列読み取り](run-jdbc-parallel-read-job.md) を参照してください。 + `"sampleQuery"`: (オプション) カスタム SQL クエリステートメント。テーブル内の情報のサブセットを指定して、テーブルの内容のサンプルを取得するために使用されます。**データを考慮せずに設定すると、DynamicFrame メソッドよりも効率が悪くなり、タイムアウトやメモリ不足エラーが発生する可能性があります。**詳細については、[sampleQuery を使用](#aws-glue-programming-etl-jdbc-samplequery) を参照してください。 + `"enablePartitioningForSampleQuery"`: (オプション) ブール値。デフォルト: false。`sampleQuery` の指定時に、JDBC テーブルから並列で読み込むことを可能にするために使用されます。**true に設定すると、AWS Glue でパーティショニング条件を追加するためには、`sampleQuery` が「where」または「and」で終わる必要があります。**詳細については、[sampleQuery を使用](#aws-glue-programming-etl-jdbc-samplequery) を参照してください。 + `"sampleSize"`: (オプション) 正の整数。サンプルクエリによって返される行数を制限します。`enablePartitioningForSampleQuery` が true の場合にのみ動作します。パーティショニングが有効になっていない場合は、代わりに `sampleQuery` で `"limit x"` を追加してサイズを制限します。詳細については、[sampleQuery を使用](#aws-glue-programming-etl-jdbc-samplequery) を参照してください。 ## sampleQuery を使用 このセクションでは、`sampleQuery`、`sampleSize`、`enablePartitioningForSampleQuery` を使用する方法について説明します。 `sampleQuery` ではデータセットのいくつかの行を効率的にサンプリングできます。デフォルトでは、クエリは単一のエグゼキューターによって実行されます。データを考慮せずに設定すると、DynamicFrame メソッドよりも効率が悪くなり、タイムアウトやメモリ不足エラーが発生する可能性があります。ETL パイプラインの一部として基盤となるデータベースで SQL を実行することは、通常、パフォーマンス上の目的でのみ必要になります。データセットの数行をプレビューする場合は、[show](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-show) を使用することを検討してください。SQL を使用してデータセットを変換する場合は、[toDF](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-toDF) を使用して DataFrame フォーム内のデータに対して SparkSQL 変換を定義することを検討してください。 クエリではさまざまなテーブルを操作できますが、`dbtable` はやはり必須です。 **sampleQuery を使用してテーブルのサンプルを取得する** デフォルトの sampleQuery の動作を使用してデータのサンプルを取得する場合、AWS Glue は大きなスループットを期待しないため、クエリは 1 つのエグゼキューターで実行されます。提供するデータを制限し、パフォーマンス上の問題を引き起こさないようにするには、SQL に `LIMIT` 句を指定することをお勧めします。 **Example パーティション化せずに sampleQuery を使用する** 次のコード例は、パーティション化せずに `sampleQuery` を使用する方法を示しています。 ``` //A full sql query statement. val query = "select name from $tableName where age > 0 limit 1" val connectionOptions = JsonOptions(Map( "url" -> url, "dbtable" -> tableName, "user" -> user, "password" -> password, "sampleQuery" -> query )) val dyf = glueContext.getSource("mysql", connectionOptions) .getDynamicFrame() ``` **sampleQuery を大きなデータセットに対して使用する** 大きなデータセットを読み取る場合は、JDBC パーティション化を有効にして、テーブルを並列にクエリする必要がある場合があります。詳細については、[JDBC テーブルからの並列読み取り](run-jdbc-parallel-read-job.md) を参照してください。`sampleQuery` を JDBC パーティショニングで使用する場合は、`enablePartitioningForSampleQuery` を true に設定します。この機能を有効にするには、`sampleQuery` にいくつかの変更を加える必要があります。 `sampleQuery` で JDBC パーティショニングを使用するときに、パーティショニング条件を追加するためには、AWS Glue でクエリが「where」または「and」で終わる必要があります。 JDBC テーブルから並列で読み込むときに sampleQuery の結果を制限したい場合は、`LIMIT` 句を指定するのではなく、`"sampleSize"` パラメータを設定してください。 **Example JDBC パーティション化で sampleQuery を使用する** 次のコード例は、JDBC パーティション化で `sampleQuery` を使用する方法を示しています。 ``` //note that the query should end with "where" or "and" if use with JDBC partitioning. val query = "select name from $tableName where age > 0 and" //Enable JDBC partitioning by setting hashfield. //to use sampleQuery with partitioning, set enablePartitioningForSampleQuery. //use sampleSize to limit the size of returned data. val connectionOptions = JsonOptions(Map( "url" -> url, "dbtable" -> tableName, "user" -> user, "password" -> password, "hashfield" -> primaryKey, "sampleQuery" -> query, "enablePartitioningForSampleQuery" -> true, "sampleSize" -> "1" )) val dyf = glueContext.getSource("mysql", connectionOptions) .getDynamicFrame() ``` **注意と制限** サンプルクエリはジョブブックマークと一緒に使用することはできません。両方の設定を指定しても、ブックマークの状態は無視されます。 ## カスタム JDBC ドライバーを使用 次のコード例は、カスタム JDBC ドライバーを使用して JDBC データベースから読み書きする方法を示しています。データベース製品の 1 つのバージョンから読み取り、同じ製品の新しいバージョンに書き込んでいます。 ------ #### [ Python ] ``` import sys from awsglue.transforms import * from awsglue.utils import getResolvedOptions from pyspark.context import SparkContext, SparkConf from awsglue.context import GlueContext from awsglue.job import Job import time from pyspark.sql.types import StructType, StructField, IntegerType, StringType sc = SparkContext() glueContext = GlueContext(sc) spark = glueContext.spark_session # Construct JDBC connection options connection_mysql5_options = { "url": "jdbc:mysql://:3306/db", "dbtable": "test", "user": "admin", "password": "pwd"} connection_mysql8_options = { "url": "jdbc:mysql://:3306/db", "dbtable": "test", "user": "admin", "password": "pwd", "customJdbcDriverS3Path": "s3://amzn-s3-demo-bucket/mysql-connector-java-8.0.17.jar", "customJdbcDriverClassName": "com.mysql.cj.jdbc.Driver"} connection_oracle11_options = { "url": "jdbc:oracle:thin:@//:1521/ORCL", "dbtable": "test", "user": "admin", "password": "pwd"} connection_oracle18_options = { "url": "jdbc:oracle:thin:@//:1521/ORCL", "dbtable": "test", "user": "admin", "password": "pwd", "customJdbcDriverS3Path": "s3://amzn-s3-demo-bucket/ojdbc10.jar", "customJdbcDriverClassName": "oracle.jdbc.OracleDriver"} # Read from JDBC databases with custom driver df_mysql8 = glueContext.create_dynamic_frame.from_options(connection_type="mysql", connection_options=connection_mysql8_options) # Read DynamicFrame from MySQL 5 and write to MySQL 8 df_mysql5 = glueContext.create_dynamic_frame.from_options(connection_type="mysql", connection_options=connection_mysql5_options) glueContext.write_from_options(frame_or_dfc=df_mysql5, connection_type="mysql", connection_options=connection_mysql8_options) # Read DynamicFrame from Oracle 11 and write to Oracle 18 df_oracle11 = glueContext.create_dynamic_frame.from_options(connection_type="oracle", connection_options=connection_oracle11_options) glueContext.write_from_options(frame_or_dfc=df_oracle11, connection_type="oracle", connection_options=connection_oracle18_options) ``` ------ #### [ Scala ] ``` import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.MappingSpec import com.amazonaws.services.glue.errors.CallSite import com.amazonaws.services.glue.util.GlueArgParser import com.amazonaws.services.glue.util.Job import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.DynamicFrame import org.apache.spark.SparkContext import scala.collection.JavaConverters._ object GlueApp { val MYSQL_5_URI: String = "jdbc:mysql://:3306/db" val MYSQL_8_URI: String = "jdbc:mysql://:3306/db" val ORACLE_11_URI: String = "jdbc:oracle:thin:@//:1521/ORCL" val ORACLE_18_URI: String = "jdbc:oracle:thin:@//:1521/ORCL" // Construct JDBC connection options lazy val mysql5JsonOption = jsonOptions(MYSQL_5_URI) lazy val mysql8JsonOption = customJDBCDriverJsonOptions(MYSQL_8_URI, "s3://amzn-s3-demo-bucket/mysql-connector-java-8.0.17.jar", "com.mysql.cj.jdbc.Driver") lazy val oracle11JsonOption = jsonOptions(ORACLE_11_URI) lazy val oracle18JsonOption = customJDBCDriverJsonOptions(ORACLE_18_URI, "s3://amzn-s3-demo-bucket/ojdbc10.jar", "oracle.jdbc.OracleDriver") def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) // Read from JDBC database with custom driver val df_mysql8: DynamicFrame = glueContext.getSource("mysql", mysql8JsonOption).getDynamicFrame() // Read DynamicFrame from MySQL 5 and write to MySQL 8 val df_mysql5: DynamicFrame = glueContext.getSource("mysql", mysql5JsonOption).getDynamicFrame() glueContext.getSink("mysql", mysql8JsonOption).writeDynamicFrame(df_mysql5) // Read DynamicFrame from Oracle 11 and write to Oracle 18 val df_oracle11: DynamicFrame = glueContext.getSource("oracle", oracle11JsonOption).getDynamicFrame() glueContext.getSink("oracle", oracle18JsonOption).writeDynamicFrame(df_oracle11) Job.commit() } private def jsonOptions(url: String): JsonOptions = { new JsonOptions( s"""{"url": "${url}", |"dbtable":"test", |"user": "admin", |"password": "pwd"}""".stripMargin) } private def customJDBCDriverJsonOptions(url: String, customJdbcDriverS3Path: String, customJdbcDriverClassName: String): JsonOptions = { new JsonOptions( s"""{"url": "${url}", |"dbtable":"test", |"user": "admin", |"password": "pwd", |"customJdbcDriverS3Path": "${customJdbcDriverS3Path}", |"customJdbcDriverClassName" : "${customJdbcDriverClassName}"}""".stripMargin) } } ``` ------ # JDBC テーブルからの並列読み取り AWS Glue​ がデータを並列に読み込むように、JDBC テーブルのプロパティを設定できます。特定のプロパティを設定するときに、データの論理パーティションに対して、並列 SQL クエリを実行するように AWS Glue​ に指示します。ハッシュフィールド、またはハッシュ式を設定して、パーティション分割を制御できます。データにアクセスするために使用される、並列読み込みの数を制御することもできます。 JDBC テーブルからの並列読み取りは、パフォーマンスを向上させる最適化手法です。この手法が適切であることを特定するプロセスの詳細については、「AWS 規範的ガイダンス」の「Best practices for performance tuning AWS Glue for Apache Spark jobs」ガイドにある「[Reduce the amount of data scan](https://docs.aws.amazon.com/prescriptive-guidance/latest/tuning-aws-glue-for-apache-spark/parallelize-tasks.html)」を参照してください。 並列読み込みするに、テーブル構造のパラメータフィールドにキーと値のペアを設定できます。テーブルのパラメータフィールドに値を設定するには、JSON 表記を使用します。テーブルのプロパティを編集する詳しい方法については、「[テーブルの詳細の表示と管理](tables-described.md#console-tables-details)」を参照してください。ETL (抽出、変換、ロード) メソッド `create_dynamic_frame_from_options`​ および `create_dynamic_frame_from_catalog`​ を呼び出すときに、並列読み込みを有効にすることもできます。これらのメソッドのオプションの指定の詳細については、「[from\$1options](aws-glue-api-crawler-pyspark-extensions-dynamic-frame-reader.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-reader-from_options)」および「[from\$1catalog](aws-glue-api-crawler-pyspark-extensions-dynamic-frame-reader.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-reader-from_catalog)」を参照してください。 JDBC テーブル、つまり、ほとんどの基本データが JDBC データストアのテーブルで、このメソッドを使用できます。Amazon Redshift​ および ​Amazon S3 テーブルの読み取り時は、これらのプロパティは無視されます。 **hashfield** データをパーティションに分割するために使用する JDBC テーブルの列の名前を `hashfield`​ に設定します。最良の結果を得るために、この列の値は、パーティション間にデータを分散する、値の均等分散である必要があります。この列には任意のデータ型を使用できます。AWS Glue​ は、この列によってパーティション分割されたデータの並列読み込みを実行する、重複しないクエリを生成します。たとえば、データが毎月均等に分散される場合、`month`​ 列を使用して、各月のデータを並行して読み込むことができます。 ``` 'hashfield': 'month' ``` AWS Glue​ は、フィールド値をパーティション番号にハッシュするクエリを作成して、すべてのパーティションにクエリを並行して実行します。パーティションのテーブル読み込みに独自のクエリを使用するには、​`hashfield` の代わりに ​`hashexpression` を指定します。 **hashexpression** `hashexpression` を、すべての番号を返す SQL 式 (JDBC データベースエンジンの文法に準拠する) に設定します。単純式は、テーブル内の任意の数値列の名前です。AWS Glue​ は、パーティションデータの ​`WHERE` 句で、​`hashexpression` を使用して並行して JDBC データを読み込む SQL クエリを生成します。 たとえば、数値列 `customerID`​ を使用して、パーティション分割されたデータを顧客番号を使用して読み込みます。 ``` 'hashexpression': 'customerID' ``` AWS Glue​ がパーティション分割を制御するようにするには、​`hashexpression` の代わりに `hashfield`​ を指定します。 **hashpartitions** JDBC テーブルの並列読み込みの数を `hashpartitions`​ に設定します。このプロパティが設定されていない場合、デフォルト値は、7 です。 たとえば、並列読み込みの数に `5`​ を設定すると、AWS Glue​ は 5 (以下) のクエリを使用して、データを読み込みます。 ``` 'hashpartitions': '5' ``` # AWS Glue から Amazon RDS データストアに JDBC 接続するための Amazon VPC の設定 JDBC を使用して Amazon RDS のデータベースに接続すると、追加の設定を行う必要があります。AWS Glue コンポーネントが Amazon RDS を通信できるようにするには、Amazon VPC で Amazon RDS データストアへのアクセスを設定する必要があります。AWS Glue がコンポーネント間で通信できるようにするには、すべての TCP ポートに対して自己参照のインバウンドルールを持つセキュリティグループを指定します。自己参照ルールを作成することにより、ソースを VPC の同じセキュリティグループに制限することができます。自己参照ルールは、VPC をすべてのネットワークに開放しません。VPC のデフォルトのセキュリティグループには、すでに ALL Traffic (すべてのトラフィック) の自己参照インバウンドルールがある場合があります。 **AWS Glue と Amazon RDS データストア間のアクセスを設定する方法** 1. AWS マネジメントコンソール にサインインし、Amazon RDS コンソール ([https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/)) を開きます。 1. Amazon RDS コンソールで、Amazon RDS データベースへのアクセスを管理するために使用するセキュリティグループを特定します。 左側のナビゲーションペインで **[データベース]** を選択し、メインペインのリストから接続するインスタンスを選択します。 データベースの詳細ページで、**[接続とセキュリティ]** タブで **[VPC セキュリティグループ]** を見つけます。 1. ネットワークアーキテクチャに基づいて、AWS Glue サービスにアクセスを許可するための変更が最適な関連セキュリティグループを特定します。今後の参照のため、*database-security-group* の名前を保存します。適切なセキュリティグループがない場合、Amazon RDS ドキュメントの「[セキュリティグループを作成して VPC 内の DB インスタンスへのアクセスを提供する](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_SettingUp.html)」の指示に従ってください。 1. AWS マネジメントコンソール にサインインして、Amazon VPC コンソール ([https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)) を開きます。 1. Amazon VPC コンソールで、*database-security-group* を更新する方法を特定します。 左側のナビゲーションペインで **[セキュリティグループ]** を選択し、メインペインのリストから *database-security-group* を選択します。 1. *database-security-group* および *database-sg-id* のセキュリティグループ ID を特定します。今後の参照のために保存します。 セキュリティグループの詳細ページで、**[セキュリティグループ ID]** を探します。 1. *database-security-group* のインバウンドルールを変更し、AWS Glue コンポーネントが通信できるように自己参照ルールを追加します。具体的には、**[タイプ]** は `All TCP`、**[プロトコル]** は `TCP`、**[ポート範囲]** にすべてのポートが含まれ、**[ソース]** は *database-sg-id* であるルールを追加または存在することを確認します。**[ソース]** に入力したセキュリティグループが、編集中のセキュリティグループと同じであることを確認します。 セキュリティグループの詳細ページで、**[インバウンドルールの編集]** を選択します。 インバウンドルールは次のようになります。 **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/setup-vpc-for-glue-access.html) 1. アウトバウンドトラフィックのルールを追加します。 セキュリティグループの詳細ページで、**[アウトバウンドルールの編集]** を選択します。 セキュリティグループがすべてのアウトバウンドトラフィックを許可する場合、個別のルールは必要ありません。例えば、次のようになります。 **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/setup-vpc-for-glue-access.html) ネットワークアーキテクチャがアウトバウンドトラフィックを制限するために設計されている場合、次のアウトバウンドルールを作成してください。 **[タイプ]** は `All TCP`、**[プロトコル]** は `TCP`、**[ポート範囲]** にすべてのポートが含まれ、**[送信先]** は *database-sg-id* である自己参照ルールを作成します。**[送信先]** に入力したセキュリティグループが、編集中のセキュリティグループと同じであることを確認します。 Amazon S3 VPC エンドポイントを使用している場合、VPC から Amazon S3 へのトラフィックを許可する HTTPS ルールを追加します。**[タイプ]** は `HTTPS`、**[プロトコル]** は `TCP`、**[ポート範囲]** は `443`、**[送信先]** は Amazon S3 ゲートウェイエンドポイントのマネージドプレフィックスリストの ID である *s3-prefix-list-id* となるルールを作成します。プレフィックスのリストと Amazon S3 ゲートウェイエンドポイントの詳細については、Amazon VPC ドキュメントの「[Gateway endpoints for Amazon S3](https://docs.aws.amazon.com//vpc/latest/privatelink/vpc-endpoints-s3.html)」をご参照ください。 例えば、次のようになります。 **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/setup-vpc-for-glue-access.html) # MongoDB 接続 AWS Glue for Spark を使用して、AWS Glue 4.0 以降のバージョンの MongoDB および MongoDB Atlas のテーブルからの読み取りとテーブルへの書き込みを行うことができます。AWS Glue 接続を介して AWS Secrets Manager で保存されているユーザー名およびパスワードの認証情報を使用して MongoDB に接続できます。 MongoDB の詳細については、[MongoDB のドキュメント](https://www.mongodb.com/docs/)を参照してください。 ## MongoDB 接続の設定 AWS Glue から MongoDB に接続するには、MongoDB 認証情報、*mongodbUser* および *mongodbPass* が必要です。 AWS Glue から MongoDB に接続するには、いくつかの前提条件を満たす必要がある場合があります。 + MongoDB インスタンスが Amazon VPC 内にある場合は、トラフィックがパブリックインターネットを経由することなく、AWS Glue ジョブが MongoDB インスタンスと通信できるように Amazon VPC を設定します。 Amazon VPC で、AWS Glue がジョブの実行中に使用する **[VPC]**、**[サブネット]**、および **[セキュリティグループ]** を特定または作成します。さらに、MongoDB インスタンスとこの場所の間のネットワークトラフィックを許可するように Amazon VPC が設定されているようにする必要があります。ネットワークレイアウトに基づいて、セキュリティグループルール、ネットワーク ACL、NAT ゲートウェイ、およびピアリング接続の変更が必要になる場合があります。 その後、MongoDB で使用できるように AWS Glue を設定する作業に進むことができます。 **MongoDB に対する接続を設定するには:** 1. 必要に応じて、AWS Secrets Manager で、MongoDB 認証情報を使用してシークレットを作成します。Secrets Manager でシークレットを作成するには、AWS Secrets Manager ドキュメントの [AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html) にあるチュートリアルに従ってください。シークレットを作成したら、次のステップのためにシークレット名 *secretName* を保存しておきます。 + **[key/value ペア]** を選択する際に、*mongodbUser* という値を持つキー `username` のペアを作成します。 **[key/value ペア]** を選択する際に、*mongodbPass* という値を持つキー `password` のペアを作成します。 1. AWS Glue コンソールで、「[AWS Glue 接続の追加](console-connections.md)」にあるステップに従って接続を作成します。接続を作成したら、将来的に AWS Glue で使用するために、接続名 *connectionName* を維持します。 + **[接続タイプ]** を選択する際には、**[MongoDB]** または **[MongoDB Atlas]** を選択します。 + **[MongoDB URL]** または **[MongoDB Atlas URL]** を選択する場合は、MongoDB インスタンスのホスト名を入力します。 MongoDB URL は、`mongodb://mongoHost:mongoPort/mongoDBname` の形式で指定されます。 MongoDB Atlas URL は、`mongodb+srv://mongoHost/mongoDBname` の形式で指定されます。 + Secrets Manager シークレットを作成することを選択した場合は、AWS Secrets Manager の **[認証情報タイプ]** を選択します。 その後、**[AWS シークレット]** で *secretName* を入力します。 + **[ユーザー名とパスワード]** を入力することを選択した場合は、*mongodbUser* および *mongodbPass* を入力します。 1. 次の状況では、追加の設定が必要になる場合があります。 + Amazon VPC の AWS でホストされている MongoDB インスタンスの場合 + MongoDB セキュリティ認証情報を定義する AWS Glue 接続に、Amazon VPC 接続に関する情報を提供する必要があります。接続を作成または更新する際に、**[ネットワークオプション]** で **[VPC]**、**[サブネット]**、および **[セキュリティグループ]** を設定します。 AWS Glue MongoDB 接続を作成した後、接続メソッドを呼び出す前に次のアクションを実行する必要があります。 + Secrets Manager シークレットを作成することを選択した場合は、AWS Glue ジョブに関連付けられた IAM ロールに *secretName* を読み取るための許可を付与します。 + AWS Glue ジョブ設定で、**追加のネットワーク接続**として *connectionName* を指定します。 AWS Glue for Spark で AWS Glue MongoDB 接続を使用するには、接続メソッド呼び出しで `connectionName` オプションを指定します。あるいは、[ETL ジョブでの MongoDB 接続の操作](integrate-with-mongo-db.md) のステップに従って、AWS Glue データカタログと組み合わせて接続を使用することもできます。 ## AWS Glue 接続を使用した MongoDB からの読み取り **前提条件:** + 読み取り元とする MongoDB コレクション。コレクションの識別情報が必要になります。 MongoDB コレクションは、データベース名とコレクション名である *mongodbName* および *mongodbCollection* によって識別されます。 + 認証情報を提供するように設定された AWS Glue MongoDB 接続。認証情報を設定するには、前の手順「*MongoDB に対する接続を設定するには*」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 例えば、次のようになります。 ``` mongodb_read = glueContext.create_dynamic_frame.from_options( connection_type="mongodb", connection_options={ "connectionName": "connectionName", "database": "mongodbName", "collection": "mongodbCollection", "partitioner": "com.mongodb.spark.sql.connector.read.partitioner.SinglePartitionPartitioner", "partitionerOptions.partitionSizeMB": "10", "partitionerOptions.partitionKey": "_id", "disableUpdateUri": "false", } ) ``` ## MongoDB テーブルへの書き込み この例では、既存の DynamicFrame である *dynamicFrame* から MongoDB に情報を書き込みます。 **前提条件:** + 書き込み先とする MongoDB コレクション。コレクションの識別情報が必要になります。 MongoDB コレクションは、データベース名とコレクション名である *mongodbName* および *mongodbCollection* によって識別されます。 + 認証情報を提供するように設定された AWS Glue MongoDB 接続。認証情報を設定するには、前の手順「*MongoDB に対する接続を設定するには*」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 例えば、次のようになります。 ``` glueContext.write_dynamic_frame.from_options( frame=dynamicFrame, connection_type="mongodb", connection_options={ "connectionName": "connectionName", "database": "mongodbName", "collection": "mongodbCollection", "disableUpdateUri": "false", "retryWrites": "false", }, ) ``` ## MongoDB テーブルに対する読み書き この例では、既存の DynamicFrame である *dynamicFrame* から MongoDB に情報を書き込みます。 **前提条件:** + 読み取り元とする MongoDB コレクション。コレクションの識別情報が必要になります。 書き込み先とする MongoDB コレクション。コレクションの識別情報が必要になります。 MongoDB コレクションは、データベース名とコレクション名である *mongodbName* および *mongodbCollection* によって識別されます。 + MongoDB 認証情報である *mongodbUser* および *mongodbPassword*。 例えば、次のようになります。 ------ #### [ Python ] ``` import sys from awsglue.transforms import * from awsglue.utils import getResolvedOptions from pyspark.context import SparkContext, SparkConf from awsglue.context import GlueContext from awsglue.job import Job import time ## @params: [JOB_NAME] args = getResolvedOptions(sys.argv, ['JOB_NAME']) sc = SparkContext() glueContext = GlueContext(sc) spark = glueContext.spark_session job = Job(glueContext) job.init(args['JOB_NAME'], args) output_path = "s3://some_bucket/output/" + str(time.time()) + "/" mongo_uri = "mongodb://:27017" mongo_ssl_uri = "mongodb://:27017" write_uri = "mongodb://:27017" read_mongo_options = { "uri": mongo_uri, "database": "mongodbName", "collection": "mongodbCollection", "username": "mongodbUsername", "password": "mongodbPassword", "partitioner": "MongoSamplePartitioner", "partitionerOptions.partitionSizeMB": "10", "partitionerOptions.partitionKey": "_id"} ssl_mongo_options = { "uri": mongo_ssl_uri, "database": "mongodbName", "collection": "mongodbCollection", "ssl": "true", "ssl.domain_match": "false" } write_mongo_options = { "uri": write_uri, "database": "mongodbName", "collection": "mongodbCollection", "username": "mongodbUsername", "password": "mongodbPassword", } # Get DynamicFrame from MongoDB dynamic_frame = glueContext.create_dynamic_frame.from_options(connection_type="mongodb", connection_options=read_mongo_options) # Write DynamicFrame to MongoDB glueContext.write_dynamic_frame.from_options(dynamicFrame, connection_type="mongodb", connection_options=write_mongo_options) job.commit() ``` ------ #### [ Scala ] ``` import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.MappingSpec import com.amazonaws.services.glue.errors.CallSite import com.amazonaws.services.glue.util.GlueArgParser import com.amazonaws.services.glue.util.Job import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.DynamicFrame import org.apache.spark.SparkContext import scala.collection.JavaConverters._ object GlueApp { val DEFAULT_URI: String = "mongodb://:27017" val WRITE_URI: String = "mongodb://:27017" lazy val defaultJsonOption = jsonOptions(DEFAULT_URI) lazy val writeJsonOption = jsonOptions(WRITE_URI) def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) // Get DynamicFrame from MongoDB val dynamicFrame: DynamicFrame = glueContext.getSource("mongodb", defaultJsonOption).getDynamicFrame() // Write DynamicFrame to MongoDB glueContext.getSink("mongodb", writeJsonOption).writeDynamicFrame(dynamicFrame) Job.commit() } private def jsonOptions(uri: String): JsonOptions = { new JsonOptions( s"""{"uri": "${uri}", |"database":"mongodbName", |"collection":"mongodbCollection", |"username": "mongodbUsername", |"password": "mongodbPassword", |"ssl":"true", |"ssl.domain_match":"false", |"partitioner": "MongoSamplePartitioner", |"partitionerOptions.partitionSizeMB": "10", |"partitionerOptions.partitionKey": "_id"}""".stripMargin) } } ``` ------ ## MongoDB 接続オプションのリファレンス MongoDB への接続を指定します。接続オプションは、ソース接続とシンク接続とで異なります。 これらの接続プロパティは、ソース接続とシンク接続の間で共有されます。 + `connectionName` — 読み込み/書き込みに使用されます。認証およびネットワークの情報を接続方法に提供するように設定された AWS Glue MongoDB 接続の名前。前のセクション「[MongoDB 接続の設定](#aws-glue-programming-etl-connect-mongodb-configure)」で説明したように AWS Glue 接続が設定されている場合、`connectionName` を入力することで、`"uri"`、`"username"`、および `"password"` 接続オプションを入力する必要がなくなります。 + `"uri"`: (必須) 読み込み元の MongoDB ホスト (形式: `mongodb://:`)。AWS Glue 4.0 より前のバージョンの AWS Glue で使用されます。 + `"connection.uri"`: (必須) 読み込み元の MongoDB ホスト (形式: `mongodb://:`)。AWS Glue 4.0 以降のバージョンで使用されます。 + `"username"`: (必須) MongoDB のユーザー名。 + `"password"`: (必須) MongoDB のパスワード。 + `"database"`: (必須) 読み込み元の MongoDB データベース。このオプションは、ジョブスクリプトで `glue_context.create_dynamic_frame_from_catalog` を呼び出す際に、`additional_options` を介して渡すことも可能です。 + `"collection"`: (必須) 読み込み元の MongoDB コレクション。このオプションは、ジョブスクリプトで `glue_context.create_dynamic_frame_from_catalog` を呼び出す際に、`additional_options` を介して渡すことも可能です。 ### "connectionType": "mongodb" ソースとする `"connectionType": "mongodb"` をソースとして、次の接続オプションを使用します。 + `"ssl"`: (オプション) `true` の場合、SSL 接続を開始します。デフォルトは `false` です。 + `"ssl.domain_match"`: (任意) `true` と `ssl` が `true` の場合 、ドメイン一致チェックが実行されます。デフォルトは `true` です。 + `"batchSize"`: (オプション): 内部バッチのカーソル内で使用される、バッチごとに返されるドキュメントの数。 + `"partitioner"`: (オプション): MongoDB から入力データを読み取るためのパーティショナーのクラス名。コネクタには、次のパーティショナーがあります。 + `MongoDefaultPartitioner` (デフォルト) (AWS Glue 4.0 ではサポートされていません) + `MongoSamplePartitioner` (MongoDB 3.2 以降が必要) (AWS Glue 4.0 ではサポートされていません) + `MongoShardedPartitioner` (AWS Glue 4.0 ではサポートされていません) + `MongoSplitVectorPartitioner` (AWS Glue 4.0 ではサポートされていません) + `MongoPaginateByCountPartitioner` (AWS Glue 4.0 ではサポートされていません) + `MongoPaginateBySizePartitioner` (AWS Glue 4.0 ではサポートされていません) + `com.mongodb.spark.sql.connector.read.partitioner.SinglePartitionPartitioner` + `com.mongodb.spark.sql.connector.read.partitioner.ShardedPartitioner` + `com.mongodb.spark.sql.connector.read.partitioner.PaginateIntoPartitionsPartitioner` + `"partitionerOptions"` (オプション): 指定されたパーティショナーのオプション。各パーティショナーでは、次のオプションがサポートされています。 + `MongoSamplePartitioner`: `partitionKey`, `partitionSizeMB`, `samplesPerPartition` + `MongoShardedPartitioner`: `shardkey` + `MongoSplitVectorPartitioner`: `partitionKey`, `partitionSizeMB` + `MongoPaginateByCountPartitioner`: `partitionKey`, `numberOfPartitions` + `MongoPaginateBySizePartitioner`: `partitionKey`, `partitionSizeMB` これらのオプションの詳細については、MongoDB のドキュメントの「[Partitioner Configuration](https://docs.mongodb.com/spark-connector/master/configuration/#partitioner-conf)」を参照してください。 ### "connectionType": "mongodb" as Sink `"connectionType": "mongodb"` をシンクとして、次の接続オプションを使用します。 + `"ssl"`: (オプション) `true` の場合、SSL 接続を開始します。デフォルトは `false` です。 + `"ssl.domain_match"`: (任意) `true` と `ssl` が `true` の場合 、ドメイン一致チェックが実行されます。デフォルトは `true` です。 + `"extendedBsonTypes"`: (オプション) `true` が設定されている場合、MongoDB にデータを書き込む際に拡張 BSON 型を使用することを許可します。デフォルトは `true` です。 + `"replaceDocument"`: (オプション) `true` の場合、`_id` フィールドを含むデータセットを保存するときに、ドキュメント全体を置き換えます。`false` の場合、データセットのフィールドと一致するドキュメントのフィールドのみが更新されます。デフォルトは `true` です。 + `"maxBatchSize"`: (オプション): データを保存するときの一括オペレーションの最大バッチサイズ。デフォルトは 512 です。 + `"retryWrites"`: (オプション): AWS Glue でネットワークエラーが発生した場合、特定の書き込みオペレーションを 1 回自動的に再試行します。 # SAP HANA 接続 AWS Glue for Spark を使用して、AWS Glue 4.0 以降のバージョンの SAP HANA のテーブルからの読み取りとテーブルへの書き込みを行うことができます。SQL クエリを使用して、SAP HANA から何を読み取るかを定義できます。AWS Glue SAP HANA 接続を通じて AWS Secrets Manager に保存されている JDBC 認証情報を使用して SAP HANA に接続します。 SAP HANA JDBC の詳細については、[SAP HANA のドキュメント](https://help.sap.com/docs/SAP_HANA_PLATFORM/0eec0d68141541d1b07893a39944924e/ff15928cf5594d78b841fbbe649f04b4.html)を参照してください。 ## SAP HANA 接続の設定 AWS Glue から SAP HANA に接続するには、SAP HANA 認証情報を作成して AWS Secrets Manager シークレットに保存し、そのシークレットを SAP HANA AWS Glue 接続に関連付ける必要があります。SAP HANA サービスと AWS Glue の間のネットワーク接続を設定する必要があります。 SAP HANA に接続するには、いくつかの前提条件を満たす必要がある場合があります。 + SAP HANA サービスが Amazon VPC 内にある場合は、トラフィックがパブリックインターネットを経由することなく、AWS Glue ジョブが SAP HANA サービスと通信できるように Amazon VPC を設定します。 Amazon VPC で、AWS Glue がジョブの実行中に使用する **[VPC]**、**[サブネット]**、および **[セキュリティグループ]** を特定または作成します。さらに、SAP HANA エンドポイントとこの場所の間のネットワークトラフィックを許可するように Amazon VPC が設定されているようにする必要があります。ジョブでは、SAP HANA JDBC ポートとの TCP 接続を確立する必要があります。SAP HANA ポートの詳細については、[SAP HANA のドキュメント](https://help.sap.com/docs/HANA_SMART_DATA_INTEGRATION/7952ef28a6914997abc01745fef1b607/88e2e8bded9e4041ad3ad87dc46c7b55.html?locale=en-US)を参照してください。ネットワークレイアウトに基づいて、セキュリティグループルール、ネットワーク ACL、NAT ゲートウェイ、およびピアリング接続の変更が必要になる場合があります。 + SAP HANA エンドポイントがインターネットにアクセスできる場合、追加の前提条件はありません。 **SAP HANA に対する接続を設定するには:** 1. AWS Secrets Manager で、SAP HANA 認証情報を使用してシークレットを作成します。Secrets Manager でシークレットを作成するには、AWS Secrets Manager ドキュメントの [AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html) にあるチュートリアルに従ってください。シークレットを作成したら、次のステップのためにシークレット名 *secretName* を保存しておきます。 + **[key/value ペア]** を選択する際に、*saphanaUsername* という値を持つキー `username/USERNAME` のペアを作成します。 + **[key/value ペア]** を選択する際に、*saphanaPassword* という値を持つキー `password/PASSWORD` のペアを作成します。 1. AWS Glue コンソールで、「[AWS Glue 接続の追加](console-connections.md)」にあるステップに従って接続を作成します。接続を作成したら、将来的に AWS Glue で使用するために、接続名 *connectionName* を維持します。 + **[接続タイプ]** を選択する際に、[SAP HANA] を選択します。 + **[SAP HANA URL]** を入力する場合は、インスタンスの URL を入力します。 SAP HANA JDBC URL の形式は `jdbc:sap://saphanaHostname:saphanaPort/?databaseName=saphanaDBname,ParameterName=ParameterValue` です AWS Glue には次の JDBC URL パラメータが必要です。 + `databaseName` – 接続先の SAP HANA のデフォルトデータベース。 + **[AWS Secret]** をクリックして、*secretName* を入力します。 AWS Glue SAP HANA 接続を作成した後、AWS Glue ジョブを実行する前に次のステップを実行する必要があります。 + AWS Glue ジョブに関連付けられている IAM ロールに *secretName* を読み取るアクセス許可を付与します。 + AWS Glue ジョブ設定で、**追加のネットワーク接続**として *connectionName* を指定します。 ## SAP HANA テーブルからの読み取り **前提条件:** + 読み取り元とする SAP HANA テーブル。テーブルの識別情報が必要になります。 テーブルは、SAP HANA テーブル名とスキーマ名 (形式: `schemaName.tableName`) を使用して指定できます。テーブルがデフォルトのスキーマ「public」にある場合、スキーマ名と「.」区切り文字は必要ありません。この *tableIdentifier* を呼び出します。データベースは `connectionName` の JDBC URL パラメータとして指定されることに注意してください。 + 認証情報を提供するように設定された AWS Glue SAP HANA 接続。認証情報を設定するには、前の手順「SAP HANA に対する接続を設定するには」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 例えば、次のようになります。 ``` saphana_read_table = glueContext.create_dynamic_frame.from_options( connection_type="saphana", connection_options={ "connectionName": "connectionName", "dbtable": "tableIdentifier", } ) ``` SELECT SQL クエリを指定して、DynamicFrame に返される結果をフィルタリングすることもできます。`query` を設定する必要があります。 例えば、次のようになります。 ``` saphana_read_query = glueContext.create_dynamic_frame.from_options( connection_type="saphana", connection_options={ "connectionName": "connectionName", "query": "query" } ) ``` ## SAP HANA テーブルへの書き込み この例では、既存の DynamicFrame である *dynamicFrame* から SAP HANA に情報を書き込みます。テーブルに既に情報がある場合、AWS Glue はエラーになります。 **前提条件:** + 書き込み先とする SAP HANA テーブル。 テーブルは、SAP HANA テーブル名とスキーマ名 (形式: `schemaName.tableName`) を使用して指定できます。テーブルがデフォルトのスキーマ「public」にある場合、スキーマ名と「.」区切り文字は必要ありません。この *tableIdentifier* を呼び出します。データベースは `connectionName` の JDBC URL パラメータとして指定されることに注意してください。 + SAP HANA 認証情報。認証情報を設定するには、前の手順「SAP HANA に対する接続を設定するには」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 例えば、次のようになります。 ``` options = { "connectionName": "connectionName", "dbtable": 'tableIdentifier' } saphana_write = glueContext.write_dynamic_frame.from_options( frame=dynamicFrame, connection_type="saphana", connection_options=options ) ``` ## SAP HANA 接続オプションのリファレンス + `connectionName` — 必須。読み込み/書き込みに使用されます。認証およびネットワークの情報を接続方法に提供するように設定された AWS Glue SAP HANA 接続の名前。 + `databaseName` — 読み込み/書き込みに使用されます。有効な値: SAP HANA のデータベースの名前。接続先のデータベースの名前。 + `dbtable` — 書き込みの場合は必須。`query` が指定されていない限り、読み取りの場合は必須。読み込み/書き込みに使用されます。有効な値: SAP HANA SQL FROM 句の内容。接続先の SAP HANA 内のテーブルを識別します。サブクエリなど、テーブル名以外の他の SQL を入力することもできます。詳細については、SAP HANA ドキュメントの「[From 句](https://help.sap.com/docs/SAP_HANA_PLATFORM/4fe29514fd584807ac9f2a04f6754767/20fcf24075191014a89e9dc7b8408b26.html#loio20fcf24075191014a89e9dc7b8408b26__from_clause)」を参照してください。 + `query` — 読み取りに使用。SAP HANA から読み取るときに何を取得するかを定義する SAP HANA SQL SELECT クエリ。 # Snowflake 接続 AWS Glue for Spark を使用して、AWS Glue 4.0 以降のバージョンの Snowflake のテーブルからの読み込みとテーブルへの書き込みを行うことができます。Snowflake からの読み込みは SQL クエリで行うことができます。ユーザーとパスワードを使用して Snowflake に接続できます。AWS Glue データカタログを使用して AWS Secrets Manager に保存されている Snowflake 認証情報を参照できます。AWS Glue for Spark のデータカタログ Snowflake 認証情報は、クローラー用のデータカタログ Snowflake 認証情報とは別に保存されます。Snowflake に接続するように設定された `JDBC` タイプの接続ではなく、`SNOWFLAKE` タイプの接続を選択する必要があります。 Snowflake の詳細については、「[Snowflake ウェブサイト](https://www.snowflake.com/)」を参照してください。AWS 上の Snowflake の詳細については、「[Snowflake Data Warehouse on Amazon Web Services](https://aws.amazon.com/financial-services/partner-solutions/snowflake/)」を参照してください。 ## Snowflake 接続の設定 インターネット経由で利用できる Snowflake データベースに接続するための AWS の前提条件はありません。 オプションで、次の設定を実行して AWS Glue で接続認証情報を管理できます。 **AWS Glue で接続認証情報を管理するには** 1. Snowflake でユーザー *snowflakeUser* とパスワード *snowflakePassword* を作成します。 1. AWS Secrets Manager で、Snowflake の認証情報を使用してシークレットを作成します。Secrets Manager でシークレットを作成するには、AWS Secrets Manager ドキュメントの「[AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html#create_secret_cli)」にあるチュートリアルに従ってください。シークレットを作成したら、次のステップのためにシークレット名 *secretName* を保存しておきます。 + **[キー/値のペア]** をクリックして、`USERNAME` キーを使用して *snowflakeUser* のペアを作成します。 + **[キー/値のペア]** をクリックして、`PASSWORD` キーを使用して *snowflakePassword* のペアを作成します。 + **キーと値のペア**を選択するときに、Snowflake ウェアハウスにキー `sfWarehouse` を提供できます。 + **[キーと値のペア]** を選択する際、対応する Spark プロパティ名をキーとして使用し、追加の Snowflake 接続プロパティを指定できます。サポートされているプロパティには、次のものが含まれます。 + `sfDatabase` – Snowflake データベース名 + `sfSchema` – Snowflake スキーマ名 + `sfRole` – Snowflake ロール名 + `pem_private_key` – キーペア認証用のプライベートキー 1. AWS Glue データカタログで、**[接続]**、**[接続を作成]** の順に選択して、接続を作成します。次の接続ウィザードの手順に従って、プロセスを完了します。 + **[データソース]** を選択する際には、[Snowflake] を選択し、**[次へ]** を選択します。 + ホストやポートなどの接続の詳細を入力します。ホストである **[Snowflake URL]** を入力して、Snowflake インスタンスの URL を指定します。通常、URL では `account_identifier.snowflakecomputing.com` という形式のホスト名を使用します。ただし、URL 形式は Snowflake アカウントタイプ (AWS、Azure、Snowflake-hosted など) によって異なる場合があります。 + IAM サービスロールを選択する際には、ドロップダウンメニューから 選択します。これは、VPC が指定されている場合、AWS Secrets Manager にアクセスして IP を割り当てるために使用されるアカウントの IAM ロールです。 + **[AWS Secret]** をクリックして、*secretName* を入力します。 1. ウィザードの次のステップで、Snowflake 接続のプロパティを設定します。 1. ウィザードの最後のステップで、設定を確認し、接続を作成するプロセスを完了します。 次のような状況では、以下が必要になることがあります。 + Amazon VPC の AWS でホストされている Snowflake の場合 + Snowflake には適切な Amazon VPC 設定が必要です。Amazon VPC の設定方法の詳細については、Snowflake ドキュメントの「[AWS PrivateLink & Snowflake](https://docs.snowflake.com/en/user-guide/admin-security-privatelink)」を参照してください。 + AWS Glue には適切な Amazon VPC 設定が必要です。[AWS Glue (AWS PrivateLink) のインターフェイス VPC エンドポイントの設定 (AWS PrivateLink)](vpc-interface-endpoints.md)。 + (Snowflake のセキュリティ認証情報を定義する AWS Secrets Manager シークレットの ID に加えて) Amazon VPC 接続情報を提供する AWS Glue データカタログ接続を作成する必要があります。前の項目でリンクされている Snowflake ドキュメントで説明されているように、AWS PrivateLink の使用時に URL が変更されます。 + ジョブ設定には、データカタログ接続を**追加ネットワーク接続**として含める必要があります。 ## Snowflake テーブルからの読み込み **前提条件:** 読み込む目的の Snowflake テーブルがあること。Snowflake のテーブル名 *tableName* が必要になります。Snowflake の URL *snowflakeUrl*、ユーザー名 *snowflakeUser*、パスワード *snowflakePassword* が必要です。Snowflake ユーザーにデフォルトの名前空間が設定されていない場合は、Snowflake データベース名 *databaseName*、スキーマ名 *schemaName* が必要になります。さらに、Snowflake ユーザーにデフォルトのウェアハウスセットがない場合は、ウェアハウス名 *warehouseName* が必要になります。 例: **その他の前提条件:** 「AWS Glue で接続認証情報を管理するには」の手順を実行して、*snowflakeUrl*、*snowflakeUsername*、および *snowflakePassword* を設定します。これらのステップを確認するには、前のセクション「[Snowflake 接続の設定](#aws-glue-programming-etl-connect-snowflake-configure)」を参照してください。接続する**その他のネットワーク接続**を選択するには、`connectionName` パラメータを使用します。 ``` snowflake_read = glueContext.create_dynamic_frame.from_options( connection_type="snowflake", connection_options={ "connectionName": "connectionName", "dbtable": "tableName", "sfDatabase": "databaseName", "sfSchema": "schemaName", "sfWarehouse": "warehouseName", } ) ``` さらに、`autopushdown` および `query` パラメータを使用して Snowflake テーブルの一部を読み込むことができます。これは、Spark に読み込まれた後に結果をフィルタリングするよりもはるかに効率的です。すべての売上が同じテーブルに格納されているが、分析する必要があるのは休日の特定の店舗の売上だけだという例を考えてみましょう。その情報がテーブルに格納されている場合は、述語プッシュダウンを使用して次のように結果を取得できます。 ``` snowflake_node = glueContext.create_dynamic_frame.from_options( connection_type="snowflake", connection_options={ "autopushdown": "on", "query": "select * from sales where store='1' and IsHoliday='TRUE'", "connectionName": "snowflake-glue-conn", "sfDatabase": "databaseName", "sfSchema": "schemaName", "sfWarehouse": "warehouseName", } ) ``` ## Snowflake テーブルへの書き込み **前提条件:** 書き込み先の Snowflake データベース。現在の、または希望するテーブル名 *tableName* が必要です。Snowflake の URL *snowflakeUrl*、ユーザー名 *snowflakeUser*、パスワード *snowflakePassword* が必要です。Snowflake ユーザーにデフォルトの名前空間が設定されていない場合は、Snowflake データベース名 *databaseName*、スキーマ名 *schemaName* が必要になります。さらに、Snowflake ユーザーにデフォルトのウェアハウスセットがない場合は、ウェアハウス名 *warehouseName* が必要になります。 例: **その他の前提条件:** 「AWS Glue で接続認証情報を管理するには」の手順を実行して、*snowflakeUrl*、*snowflakeUsername*、および *snowflakePassword* を設定します。これらのステップを確認するには、前のセクション「[Snowflake 接続の設定](#aws-glue-programming-etl-connect-snowflake-configure)」を参照してください。接続する**その他のネットワーク接続**を選択するには、`connectionName` パラメータを使用します。 ``` glueContext.write_dynamic_frame.from_options( connection_type="snowflake", connection_options={ "connectionName": "connectionName", "dbtable": "tableName", "sfDatabase": "databaseName", "sfSchema": "schemaName", "sfWarehouse": "warehouseName", }, ) ``` ## Snowflake 接続オプションのリファレンス Snowflake 接続タイプには次の接続オプションがあります。 このセクションのパラメータの一部はデータカタログ接続 (`sfUrl`、`sfUser`、`sfPassword`) から取得できます。その場合は指定する必要はありません。これを行うには、`connectionName` パラメータを含めます。 `secretId` パラメータを使用して、AWS Secrets Manager シークレットから接続パラメータを取得できます。Secrets Manager を使用する際、次の Spark プロパティがシークレットに存在する場合、自動的に取得できます。 + `sfUser` (`USERNAME` または `sfUser` キーを使用) + `sfPassword` (`PASSWORD` または `sfPassword` キーを使用) + `sfWarehouse` (`sfWarehouse` キーを使用) + `sfDatabase` (`sfDatabase` キーを使用) + `sfSchema` (`sfSchema` キーを使用) + `sfRole` (`sfRole` キーを使用) + `pem_private_key` (`pem_private_key` キーを使用) **プロパティの優先順位:** 同じプロパティが複数の場所で指定されている場合、AWS Glue によって次の優先順位 (最高から最低) が使用されます。 1. ジョブコードで明示的に提供される接続オプション 1. データカタログ接続プロパティ 1. AWS Secrets Manager シークレット値 (`secretId` が指定されている場合) 1. Snowflake ユーザーのデフォルト 以下のパラメータは、Snowflake に接続する際に一般的に使用されます。 + `sfDatabase` — Snowflake でユーザーデフォルトが設定されていない場合は必須です。読み込み/書き込みに使用されます。接続後にセッションに使用するデータベース。 + `sfSchema` — Snowflake でユーザーデフォルトが設定されていない場合は必須です。読み込み/書き込みに使用されます。接続後にセッションに使用するスキーマ。 + `sfWarehouse` — Snowflake でユーザーデフォルトが設定されていない場合は必須です。読み込み/書き込みに使用されます。接続後にセッションに使用するデフォルトの仮想ウェアハウス。 + `sfRole` — Snowflake でユーザーデフォルトが設定されていない場合は必須です。読み込み/書き込みに使用されます。接続後にセッションに使用するデフォルトのセキュリティロール。 + `sfUrl` — (必須) 読み込み/書き込みに使用されます。アカウントのホスト名を `account_identifier.snowflakecomputing.com` の形式で指定します。アカウント識別子の詳細については、Snowflake ドキュメントの「[アカウント識別子](https://docs.snowflake.com/en/user-guide/admin-account-identifier)」を参照してください。 + `sfUser` — (必須) 読み込み/書き込みに使用されます。Snowflake ユーザーのログイン名。 + `sfPassword` - (`pem_private_key` 指定がない場合は必須) 読み取り/書き込みに使用します。　 Snowflake ユーザーのパスワード。 + `dbtable` — フルテーブルで作業する場合は必須です。読み込み/書き込みに使用されます。読み込まれるテーブルまたはデータが書き込まれるテーブルの名前。読み込み時には、すべての列とレコードが取得されます。 + `pem_private_key` — 読み込み/書き込みに使用されます。暗号化されていない b64 でエンコードされたプライベートキーの文字列。Snowflake ユーザーのプライベートキー。　 これを PEM ファイルからコピーするのが一般的です。詳細については、Snowflake ドキュメントの「[キーペア認証とキーペアローテーション](https://docs.snowflake.com/en/user-guide/key-pair-auth)」を参照してください。　 + `query` — クエリで読み込みを行う場合は必須です。読み込みに使用されます。実行する正確なクエリ (`SELECT` ステートメント) 以下のオプションを使用して、Snowflake への接続プロセス中の特定の動作を設定します。 + `preactions` — 読み込み/書き込みに使用されます。有効値: セミコロンで区切られた文字列形式の SQL ステートメントのリスト。SQL ステートメントは、AWS Glue と Snowflake の間でデータが転送される前に実行されます。ステートメントに `%s` が含まれる場合、`%s` は操作で参照されるテーブル名に置き換えられます。 + `postactions` — 読み込み/書き込みに使用されます。SQL ステートメントは、AWS Glue と Snowflake 間でデータが転送された後に実行されます。ステートメントに `%s` が含まれる場合、`%s` は操作で参照されるテーブル名に置き換えられます。 + `autopushdown` - デフォルト: `"on"`。有効な値: `"on"`、`"off"`。このパラメータは、自動クエリプッシュダウンを有効にするかどうかを制御します。プッシュダウンが有効になっている場合、Spark でクエリを実行すると、クエリの一部が Snowflake サーバーに「プッシュダウン」できる場合にクエリがプッシュダウンされます。これにより、一部のクエリのパフォーマンスが向上します。クエリをプッシュダウンできるかどうかについては、Snowflake ドキュメントの「[プッシュダウン](https://docs.snowflake.com/en/user-guide/spark-connector-use#pushdown)」を参照してください。 さらに、Snowflake Spark コネクタで使用できるオプションの一部が AWS Glue でサポートされている場合があります。Snowflake Spark コネクタで使用できるオプションの詳細については、Snowflake ドキュメントの「[コネクタの構成オプションの設定](https://docs.snowflake.com/en/user-guide/spark-connector-use#setting-configuration-options-for-the-connector)」を参照してください。 ## Snowflake 認証方法 AWS Glue は、Snowflake に接続するために次の認証方法をサポートしています。 + **ユーザー名とパスワード認証:** `sfUser` および `sfPassword` パラメータを指定します。 + **キーペア認証:** `sfUser` および `pem_private_key` パラメータを指定します。キーペア認証を使用する際、`sfPassword` パラメータは必要ありません。 どちらの認証方法とも完全にサポートされており、接続オプション、データカタログ接続、AWS Secrets Manager シークレットの任意の組み合わせを使用して設定できます。 ## Snowflake コネクタの制限事項 AWS Glue for Spark を使用してスノーフレークに接続することには、以下の制限があります。 + このコネクタはジョブブックマークをサポートしていません。ブックマークの詳細については、「[ジョブのブックマークを使用した処理済みデータの追跡](monitor-continuations.md)」を参照してください。 + このコネクタは、`create_dynamic_frame.from_catalog` および `write_dynamic_frame.from_catalog` メソッドを使用した AWS Glue データカタログのテーブルを介した Snowflake の読み込みと書き込みをサポートしていません。 + このコネクタでは、ユーザー名/パスワード認証およびキーペア認証がサポートされています。他の認証方法 (OAuth や SAML など) は現在サポートされていません。 + このコネクタはストリーミングジョブではサポートされていません。 + このコネクタは、情報を取得する (`query` パラメータを使用してなど) 際の `SELECT` ステートメントベースのクエリをサポートします。他の種類のクエリ (`SHOW`、`DESC`、DML ステートメントなど) はサポートされていません。 + Snowflake は、Snowflake クライアントを介して送信されるクエリテキスト (つまり、SQL ステートメント) のサイズをステートメントあたり 1 MB に制限しています。詳細については、「[クエリテキストサイズの制限](https://docs.snowflake.com/en/user-guide/query-size-limits)」を参照してください。 # Teradata Vantage 接続 AWS Glue for Spark を使用して、AWS Glue 4.0 以降のバージョンの Teradata Vantage の既存のテーブルからの読み取りとテーブルへの書き込みを行うことができます。SQL クエリを使用して、Teradata から何を読み取るかを定義できます。AWS Glue 接続を介して AWS Secrets Manager で保存されているユーザー名およびパスワードの認証情報を使用して Teradata に接続できます。 Teradata の詳細については、[Teradata ドキュメント](https://docs.teradata.com/)を参照してください。 ## Teradata 接続の設定 AWS Glue から Teradata に接続するには、Teradata 認証情報を作成して AWS Secrets Manager シークレットに保存し、そのシークレットを Teradata AWS Glue 接続に関連付ける必要があります。Teradata インスタンスが Amazon VPC 内にある場合は、AWS Glue Teradata 接続にネットワークオプションを提供する必要もあります。 AWS Glue から Teradata に接続するには、いくつかの前提条件を満たす必要がある場合があります。 + Amazon VPC を通じて Teradata 環境にアクセスしている場合は、AWS Glue ジョブが Teradata 環境と通信できるように Amazon VPC を設定します。パブリックインターネット経由で Teradata 環境にアクセスすることは推奨されていません。 Amazon VPC で、AWS Glue がジョブの実行中に使用する **[VPC]**、**[サブネット]**、および **[セキュリティグループ]** を特定または作成します。さらに、Teradata インスタンスとこの場所の間のネットワークトラフィックを許可するように Amazon VPC が設定されているようにする必要があります。ジョブでは、Teradata クライアントポートとの TCP 接続を確立する必要があります。Teradata ポートの詳細については、[Teradata のドキュメント](https://docs.teradata.com/r/Teradata-VantageTM-on-AWS-DIY-Installation-and-Administration-Guide/April-2020/Before-Deploying-Vantage-on-AWS-DIY/Security-Groups-and-Ports)を参照してください。 ネットワークレイアウトに応じて、安全な VPC 接続を実現するには、Amazon VPC および他のネットワークサービスの変更が必要な場合があります。AWS 接続の詳細については、Teradata ドキュメントの「[AWS 接続オプション](https://docs.teradata.com/r/Teradata-VantageCloud-Enterprise/Get-Started/Connecting-Your-Environment/AWS-Connectivity-Options)」を参照してください。 **AWS Glue Teradata 接続を設定するには:** 1. Teradata 設定で、AWS Glue が接続するユーザーとパスワード (*teradataUser* および *teradataPassword*) を識別または作成します。詳細については、Teradata ドキュメントの「[Vantage セキュリティの概要](https://docs.teradata.com/r/Configuring-Teradata-VantageTM-After-Installation/January-2021/Security-Overview/Vantage-Security-Overview)」を参照してください。 1. AWS Secrets Manager で、Teradata 認証情報を使用してシークレットを作成します。Secrets Manager でシークレットを作成するには、AWS Secrets Manager ドキュメントの [AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html) にあるチュートリアルに従ってください。シークレットを作成したら、次のステップのためにシークレット名 *secretName* を保存しておきます。 + **[key/value ペア]** を選択する際に、*teradataUsername* という値を持つキー `user` のペアを作成します。 + **[key/value ペア]** を選択する際に、*teradataPassword* という値を持つキー `password` のペアを作成します。 1. AWS Glue コンソールで、「[AWS Glue 接続の追加](console-connections.md)」にあるステップに従って接続を作成します。接続を作成したら、次のステップのために接続名 *connectionName* を保存しておきます。 + **[接続タイプ]** を選択する際に、[Teradata] を選択します。 + **[JDBC URL]** を入力する場合は、インスタンスの URL を入力します。JDBC URL に特定のカンマ区切りの接続パラメータをハードコーディングすることもできます。URL は次の形式に準拠する必要があります: `jdbc:teradata://teradataHostname/ParameterName=ParameterValue,ParameterName=ParameterValue` サポートされる URL パラメータには次が含まれます。 + `DATABASE` – デフォルトでアクセスするホスト上のデータベースの名前。 + `DBS_PORT` – データベースポート。非標準ポートで実行する場合に使用されます。 + **[認証情報タイプ]** を選択する場合は、**[AWS Secrets Manager]** を選択し、**[AWS シークレット]** を *secretName* に設定します。 1. 次の状況では、追加の設定が必要になる場合があります。 + Amazon VPC の AWS でホストされている Teradata インスタンスの場合 + Teradata セキュリティ認証情報を定義する AWS Glue 接続に、Amazon VPC 接続に関する情報を提供する必要があります。接続を作成または更新する際に、**[ネットワークオプション]** で **[VPC]**、**[サブネット]**、および **[セキュリティグループ]** を設定します。 AWS Glue Teradata 接続を作成した後、接続メソッドを呼び出す前に次のステップを実行する必要があります。 + AWS Glue ジョブに関連付けられている IAM ロールに *secretName* を読み取るアクセス許可を付与します。 + AWS Glue ジョブ設定で、**追加のネットワーク接続**として *connectionName* を指定します。 ## Teradata からの読み取り **前提条件:** + 読み取り元とする Teradata テーブル。テーブル名 *tableName* が必要になります。 + 認証情報を提供するように設定された AWS Glue Teradata 接続。認証情報を設定するには、「Teradata に対する接続を設定するには」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 例えば、次のようになります。 ``` teradata_read_table = glueContext.create_dynamic_frame.from_options( connection_type="teradata", connection_options={ "connectionName": "connectionName", "dbtable": "tableName" } ) ``` SELECT SQL クエリを指定して、DynamicFrame に返される結果をフィルタリングすることもできます。`query` を設定する必要があります。 例えば、次のようになります。 ``` teradata_read_query = glueContext.create_dynamic_frame.from_options( connection_type="teradata", connection_options={ "connectionName": "connectionName", "query": "query" } ) ``` ## Teradata テーブルへの書き込み **前提条件:** 書き込み先とする Teradata テーブルである *tableName*。**接続メソッドを呼び出す前にテーブルを作成する必要があります。** 例えば、次のようになります。 ``` teradata_write = glueContext.write_dynamic_frame.from_options( connection_type="teradata", connection_options={ "connectionName": "connectionName", "dbtable": "tableName" } ) ``` ## Teradata 接続オプションのリファレンス + `connectionName` — 必須。読み込み/書き込みに使用されます。認証およびネットワークの情報を接続方法に提供するように設定された AWS Glue Teradata 接続の名前。 + `dbtable` — 書き込みの場合は必須。`query` が指定されていない限り、読み取りの場合は必須。読み込み/書き込みに使用されます。接続メソッドがインタラクションするテーブルの名前。 + `query` — 読み取りに使用。Teradata から読み取るときに何を取得するかを定義する SELECT SQL クエリ。 # Teradata Vantage NOS 接続 Teradata NOS (Native Object Store) 接続は、Teradata Vantage の新しい接続です。これは、Teradata WRITE\$1NOS クエリを活用して既存のテーブルから読み取り、READ\$1NOS クエリを使用してテーブルに書き込みます。これらのクエリはステージングディレクトリとして Amazon S3 を使用するため、Teradata NOS コネクタは、既存の Teradata コネクタ (JDBC ベース) よりも高速で、特に大量のデータを処理できます。 Spark 向けの AWS Glue の Teradata NOS 接続を使用して、AWS Glue 5.0 以降のバージョンの Teradata Vantage の既存テーブルからの読み取りやテーブルへの書き込みを行うことができます。SQL クエリを使用して、Teradata から何を読み取るかを定義できます。AWS Glue 接続を介して AWS Secrets Manager に保存されているユーザー名およびパスワードの認証情報を使用して Teradata に接続できます。 Teradata の詳細については、[Teradata のドキュメント](https://docs.teradata.com/)を参照してください。 **Topics** + [Teradata NOS 接続の作成](#creating-teradata-nos-connection) + [Teradata テーブルからの読み取り](#reading-from-teradata-nos-tables) + [Teradata テーブルへの書き込み](#writing-to-teradata-nos-tables) + [Teradata 接続オプションのリファレンス](#teradata-nos-connection-option-reference) + [AWS Glue ビジュアル ETL UI のオプションを指定する](#teradata-nos-connection-option-visual-etl-ui) ## Teradata NOS 接続の作成 AWS Glue から Teradata NOS に接続するには、Teradata 認証情報を作成して AWS Secrets Manager シークレットに保存し、そのシークレットを AWS Glue Teradata NOS 接続に関連付ける必要があります。Teradata インスタンスが Amazon VPC 内にある場合は、AWS Glue Teradata NOS 接続にネットワークオプションを提供する必要もあります。 **前提条件**: + Amazon VPC を通じて Teradata 環境にアクセスしている場合は、AWS Glue ジョブが Teradata 環境と通信できるように Amazon VPC を設定します。パブリックインターネット経由で Teradata 環境にアクセスすることは推奨されていません。 + Amazon VPC で、AWS Glue がジョブの実行中に使用する [VPC]、[サブネット]、および [セキュリティグループ] を特定または作成します。さらに、Teradata インスタンスとこの場所の間のネットワークトラフィックを許可するように Amazon VPC が設定されているようにする必要があります。ジョブでは、Teradata クライアントポートとの TCP 接続を確立する必要があります。Teradata ポートの詳細については、「[Teradata Vantage のセキュリティグループ](https://docs.teradata.com/r/Teradata-VantageTM-on-AWS-DIY-Installation-and-Administration-Guide/April-2020/Before-Deploying-Vantage-on-AWS-DIY/Security-Groups-and-Ports)」を参照してください。 + ネットワークレイアウトに応じて、安全な VPC 接続を実現するには、Amazon VPC および他のネットワークサービスの変更が必要な場合があります。AWS 接続の詳細については、Teradata ドキュメントの「[AWS 接続オプション](https://docs.teradata.com/r/Teradata-VantageCloud-Enterprise/Get-Started/Connecting-Your-Environment/AWS-Connectivity-Options)」を参照してください。 ### AWS Glue Teradata NOS 接続を設定するには: 1. Teradata 設定で、AWS Glue が接続する *teradataUsername* と *teradataPassword* を識別または作成します。詳細については、Teradata ドキュメントの「[ Vantage セキュリティの概要を 参照してください](https://docs.teradata.com/r/Configuring-Teradata-VantageTM-After-Installation/January-2021/Security-Overview/Vantage-Security-Overview)」を参照してください。 1. AWS Secrets Manager で、Teradata 認証情報を使用してシークレットを作成します。AWS Secrets Manager でシークレットを作成するには、AWS Secrets Manager ドキュメントの「[AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)」にあるチュートリアルに従ってください。シークレットを作成したら、次のステップのためにシークレット名 *secretName* を保存しておきます。 + [Key/value ペア] を選択する際に、キー USERNAME と値 *teradataUsername* のペアを作成します。 + [Key/value ペア] を選択する際に、キー PASSWORD と値 *teradataPassword* のペアを作成します。 1. AWS Glue コンソールで、「[AWS Glue 接続の追加](https://docs.aws.amazon.com/glue/latest/dg/console-connections.html)」にあるステップに従って接続を作成します。接続を作成したら、次のステップのために接続名 *connectionName* を保存しておきます。 + **[接続タイプ]** を選択する際に、[Teradata Vantage NOS] を選択します。 + [JDBC URL] を入力する場合は、インスタンスの URL を入力します。JDBC URL に特定のカンマ区切りの接続パラメータをハードコーディングすることもできます。URL は次の形式に準拠する必要があります: ` jdbc:teradata://teradataHostname/ParameterName=ParameterValue,ParameterName=ParameterValue `。 + サポートされる URL パラメータには次が含まれます。 + `DATABASE` – デフォルトでアクセスするホスト上のデータベースの名前。 + `DBS_PORT` – データベースポート。非標準ポートで実行する場合に使用されます。 + **[認証情報タイプ]** を選択する際は、[AWS Secrets Manager] を選択し、**[AWS シークレット]** を *secretName* に設定します。 1. 次の状況では、追加の設定が必要になる場合があります。 + Amazon VPC 内の AWS でホストされている Teradata インスタンスの場合、Teradata セキュリティ認証情報を定義する AWS Glue 接続に、Amazon VPC 接続に関する情報を提供する必要があります。接続を作成または更新する際に、**[ネットワークオプション]** で **[VPC]**、**[サブネット]**、および **[セキュリティグループ]** を設定します。 AWS Glue Teradata Vantage NOS 接続を作成したら、接続メソッドを呼び出す前に次のステップを実行する必要があります。 1. AWS Glue ジョブに関連付けられている IAM ロールに *secretName* を読み取るアクセス許可を付与します。 1. AWS Glue ジョブ設定では、**[接続]** で **[Additional network connection] (追加のネットワーク接続)** として *connectionName* を指定します。 ## Teradata テーブルからの読み取り ### 前提条件: + 読み取り元とする Teradata テーブル。テーブル名 *tableName* が必要になります。 + Teradata 環境には、`staging_fs_url` オプションで指定された Amazon S3 パスである *stagingFsUrl* への書き込みアクセス権があります。 + AWS Glue ジョブに関連付けられた IAM ロールには、`staging_fs_url` オプションで指定された Amazon S3 ロケーションへの書き込みアクセス権があります。 + 認証情報を提供するように設定された AWS Glue Teradata NOS 接続。認証情報を設定するステップ [AWS Glue Teradata NOS 接続を設定するには:](#creating-teradata-nos-connection-procedure) を完了します。AWS Glue 接続の名前、*connectionName* が必要になります。 例: ``` teradata_read_table = glueContext.create_dynamic_frame.from_options( connection_type= "teradatanos", connection_options={ "connectionName": "connectionName", "dbtable": "tableName", "staging_fs_url": "stagingFsUrl" } ) ``` SELECT SQL クエリを指定して、DynamicFrame に返される結果をフィルタリングすることもできます。クエリを設定する必要があります。dbTable とクエリの両方を設定すると、コネクタはデータの読み取りに失敗します。例えば、次のようになります。 ``` teradata_read_query = glueContext.create_dynamic_frame.from_options( connection_type="teradatanos", connection_options={ "connectionName": "connectionName", "query": "query", "staging_fs_url": "stagingFsUrl" } ) ``` さらに、Spark DataFrame API を使用して Teradata テーブルから読み取ることができます。例えば、次のようになります。 ``` options = { "url": "JDBC_URL", "dbtable": "tableName", "user": "teradataUsername", # or use "username" as key here "password": "teradataPassword", "staging_fs_url": "stagingFsUrl" } teradata_read_table = spark.read.format("teradatanos").option(**options).load() ``` ## Teradata テーブルへの書き込み ### 前提条件 + 書き込み先とする Teradata テーブル: *tableName*。 + Teradata 環境には、`staging_fs_url` オプションで指定された Amazon S3 の場所である *stagingFsUrl* への読み取りアクセス権があります。 + AWS Glue ジョブに関連付けられた IAM ロールには、`staging_fs_url` オプションで指定された Amazon S3 ロケーションへの書き込みアクセス権があります。 + 認証情報を提供するように設定された AWS Glue Teradata 接続。認証情報を設定するには、「[AWS Glue Teradata NOS 接続を設定するには:](#creating-teradata-nos-connection-procedure)」の手順を実行します。AWS Glue 接続の名前、*connectionName* が必要になります。 例えば、次のようになります。 ``` teradata_write = glueContext.write_dynamic_frame.from_options( frame=dynamicFrame, connection_type= "teradatanos", connection_options={ "connectionName": "connectionName", "dbtable": "tableName", "staging_fs_url": "stagingFsUrl" } ) ``` ## Teradata 接続オプションのリファレンス **接続とオペレーションのオプション：** + `connectionName` — 必須。読み込み/書き込みに使用されます。認証およびネットワークの情報をお使いの接続方法に提供するように設定された AWS Glue Teradata 接続の名前。 + `staging_fs_url` — 必須。読み込み/書き込みに使用されます。Amazon S3 の書き込み可能な場所。Teradata から読み取るときにはアンロードされたデータに使用され、Teradata に書き込むときには Parquet データが Redshift にロードされます。S3 バケットは、AWS Glue ジョブのリージョンと同じリージョンにある必要があります。 + `dbtable` — 書き込みの場合は必須。`query` が指定されていない限り、読み取りの場合は必須。読み込み/書き込みに使用されます。接続メソッドがインタラクションするテーブルの名前。 + `query` — 読み取りに使用。Teradata から読み取るときに何を取得するかを定義する SELECT SQL クエリ。`dbtable` オプションが指定されている場合、パスすることはできません。 + `clean_staging_s3_dir` - オプション。読み込み/書き込みに使用されます。true の場合は、読み取りまたは書き込み後にステージング Amazon S3 オブジェクトをクリーンアップします。デフォルト値は True です。 + `pre_actions` - オプション。書き込みに使用。Spark と Teradata Vantage の間でデータが転送される前に実行される SQL コマンドのセミコロン区切りリスト。 + `post_actions` - オプション。書き込みに使用。Spark と Teradata Vantage の間でデータが転送された後に実行される SQL コマンドのセミコロン区切りリスト。 + `truncate` - オプション。書き込みに使用。true の場合、コネクタは上書きモードで書き込むときにテーブルを切り捨てます。false の場合、コネクタは上書きモードで書き込むときにテーブルをドロップします。デフォルト値は false です。 + `create_table_script` - オプション。書き込みに使用。Teradata Vantage に書き込むときにテーブルを作成する SQL ステートメント。カスタムメタデータ (CREATE MULTISET や SET テーブル、プライマリインデックスの変更など) を使用してテーブルを作成する場合に便利です。テーブル作成スクリプトで使用されるテーブル名は、`dbtable` オプションで指定されたテーブル名と一致する必要があることに注意してください。 + `partition_size_in_mb` - オプション。読み取りに使用されます。ステージング Amazon S3 オブジェクトの読み取り中の Spark パーティションの最大サイズ (メガバイト)。デフォルト値は 128 です。 Teradata ノードを作成する際に、高度なオプションを指定できます。これらのオプションは Spark AWS Glue スクリプトのプログラミング時に使用できるオプションと同じです。 「[Teradata Vantage 接続](aws-glue-programming-etl-connect-teradata-home.md)」を参照してください。 **認可オプション** 以下は、コネクタがステージング Amazon S3 バケットにアクセスするために使用する AWS アカウント認証情報を提供するために使用されるオプションです。(1) 認証オプションを一切提供せず、AWS Glue 実行ロールから生成された一時的な認証情報を使用するか、(2) 作成した認証オブジェクト `auth_object` を提供するか、(3) 長期認証情報を使用する場合は `aws_access_key_id and aws_secret_access_key` を提供するか、または一時的な認証情報を使用する場合は `aws_access_key`、`aws_secret_access_key`、および `aws_session_token` を提供するかを選択できます。 + `auth_object` - オプション。ステージング Amazon S3 バケットへのアクセスに使用されます。Teradata インスタンスで作成された認証オブジェクト文字列。指定すると、コネクタはこの認証オブジェクトを使用してステージング Amazon S3 バケットにアクセスします。指定がなく、`aws_secret_access_key` と AWS Glue も指定されていない場合、一時的な認証情報が `aws_access_key_id` 実行ロールから取得され、コネクタによって使用されます。この認証オブジェクトに関連付けられた AWS アカウントは、AWS Glue ジョブおよびステージング Amazon S3 バケットと同じリージョンにあるか、クロスアカウント信頼が設定されている必要があります。 + `aws_access_key_id` - オプション。ステージング Amazon S3 バケットへのアクセスに使用されます。AWS アカウントセキュリティ認証情報の一部。`auth_object` の指定がなく、 `aws_access_key_id` が `aws_secret_access_key` に提供されている場合、コネクタはそれらを使用してステージング Amazon S3 バケットにアクセスします。このアクセスキーに関連付けられた AWS アカウントは、AWS Glue ジョブおよびステージング Amazon S3 バケットと同じリージョンにあるか、クロスアカウント信頼が設定されている必要があります。 + `aws_secret_access_key` - オプション。ステージング Amazon S3 バケットへのアクセスに使用されます。AWS アカウントセキュリティ認証情報の一部。`auth_object` の指定がなく、 `aws_secret_access_key` が `aws_access_key_id` に設定されている場合、コネクタはそれらを使用してステージング Amazon S3 バケットにアクセスします。このシークレットキーに関連付けられた AWS アカウントは、AWS Glue ジョブとステージング Amazon S3 バケットと同じリージョンにあるか、クロスアカウント信頼が設定されている必要があります。 + `aws_session_token` - オプション。ステージング Amazon S3 バケットへのアクセスに使用されます。一時的な AWS アカウントセキュリティ認証情報の一部。`aws_access_key_id` と `aws_secret_access_key` を指定する必要があります。 ## AWS Glue ビジュアル ETL UI のオプションを指定する ビジュアル ETL ジョブ UI で上記のすべてのオプションを指定できます。connectionName オプションは、Teradata Vantage NOS 接続のドロップダウンリストから選択します。他のすべてのオプションについては、カスタム Teradata Vantage NOS プロパティをキーと値のペアとして指定する必要があります。 ![\[ウィンドウペインで Teradata NOS Vantage 接続が選択されています。\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/images/teradata-nos-vantage-connection-options.png) # Vertica 接続 AWS Glue for Spark を使用して、AWS Glue 4.0 以降のバージョンの Vertica のテーブルからの読み取りとテーブルへの書き込みを行うことができます。SQL クエリを使用して、Vertica から何を読み取るかを定義できます。AWS Glue 接続を介して AWS Secrets Manager で保存されているユーザー名およびパスワードの認証情報を使用して Vertica に接続します。 Vertica の詳細については、[Vertica ドキュメント](https://www.vertica.com/docs/9.3.x/HTML/Content/Authoring/UsingVerticaOnAWS/UsingVerticaOnAWS.htm)を参照してください。 ## Vertica 接続の設定 AWS Glue から Vertica に接続するには、Vertica 認証情報を作成して AWS Secrets Manager シークレットに保存し、そのシークレットを Vertica AWS Glue 接続に関連付ける必要があります。Vertica インスタンスが Amazon VPC 内にある場合は、AWS Glue Vertica 接続にネットワークオプションを提供する必要もあります。データベースの読み取りおよび書き込み時に一時ストレージとして使用する Amazon S3 バケットまたはフォルダが必要です。 AWS Glue から Vertica に接続するには、いくつかの前提条件を満たす必要があります。 + データベースの読み取りおよび書き込み時に一時ストレージとして使用する Amazon S3 バケットまたはフォルダ。*tempS3Path* によって参照されます。 **注記** AWS Glue ジョブデータプレビューで Vertica を使用する場合、一時ファイルは *tempS3Path* から自動的に削除されない場合があります。一時ファイルを確実に削除するには、**[データプレビュー]** ペインで **[セッションの終了]** を選択して、データプレビューセッションを直接終了します。 データプレビューセッションが直接終了することを保証できない場合は、Amazon S3 ライフサイクル構成を設定して古いデータを削除することを検討してください。ジョブの最大実行時間にマージンを加えた値に基づいて、49 時間を超える時間が経過しているデータを削除することをお勧めします。Amazon S3 ライフサイクルの設定の詳細については、Amazon S3 ドキュメントの「[ストレージのライフサイクルの管理](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)」を参照してください。 + AWS Glue ジョブロールに関連付けることができる、Amazon S3 パスに対する適切な許可を持つ IAM ポリシー。 + Vertica インスタンスが Amazon VPC 内にある場合は、トラフィックがパブリックインターネットを経由することなく、AWS Glue ジョブが Vertica インスタンスと通信できるように Amazon VPC を設定します。 Amazon VPC で、AWS Glue がジョブの実行中に使用する **[VPC]**、**[サブネット]**、および **[セキュリティグループ]** を特定または作成します。さらに、Vertica インスタンスとこの場所の間のネットワークトラフィックを許可するように Amazon VPC が設定されているようにする必要があります。ジョブは、Vertica クライアントポート (デフォルトは 5433) との TCP 接続を確立する必要があります。ネットワークレイアウトに基づいて、セキュリティグループルール、ネットワーク ACL、NAT ゲートウェイ、およびピアリング接続の変更が必要になる場合があります。 その後、Vertica で使用できるように AWS Glue を設定する作業に進むことができます。 **Vertica に対する接続を設定するには:** 1. AWS Secrets Manager で、Vertica 認証情報、*verticaUsername* および *verticaPassword* を使用してシークレットを作成します。Secrets Manager でシークレットを作成するには、AWS Secrets Manager ドキュメントの [AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html) にあるチュートリアルに従ってください。シークレットを作成したら、次のステップのためにシークレット名 *secretName* を保存しておきます。 + **[key/value ペア]** を選択する際に、*verticaUsername* という値を持つキー `user` のペアを作成します。 + **[key/value ペア]** を選択する際に、*verticaPassword* という値を持つキー `password` のペアを作成します。 1. AWS Glue コンソールで、「[AWS Glue 接続の追加](console-connections.md)」にあるステップに従って接続を作成します。接続を作成したら、次のステップのために接続名 *connectionName* を保存しておきます。 + **[接続タイプ]** を選択する際に、[Vertica] を選択します。 + **[Vertica ホスト]** を選択する場合は、Vertica インストールのホスト名を入力します。 + **[Vertica ポート]** を選択すると、Vertica インストールを使用できるポートが選択されます。 + **[AWS Secret]** をクリックして、*secretName* を入力します。 1. 次の状況では、追加の設定が必要になる場合があります。 + Amazon VPC の AWS でホストされている Vertica インスタンスの場合 + Vertica セキュリティ認証情報を定義する AWS Glue 接続に、Amazon VPC 接続に関する情報を提供します。接続を作成または更新する際に、**[ネットワークオプション]** で **[VPC]**、**[サブネット]**、および **[セキュリティグループ]** を設定します。 AWS Glue Vertica 接続を作成した後、接続メソッドを呼び出す前に次のステップを実行する必要があります。 + AWS Glue ジョブの許可に関連付けられた IAM ロールを *tempS3Path* に付与します。 + AWS Glue ジョブに関連付けられている IAM ロールに *secretName* を読み取るアクセス許可を付与します。 + AWS Glue ジョブ設定で、**追加のネットワーク接続**として *connectionName* を指定します。 ## Vertica からの読み取り **前提条件:** + 読み取り元とする Vertica テーブル。Vertica データベース名である *dbName* とテーブル名である *tableName* が必要になります。 + 認証情報を提供するように設定された AWS Glue Vertica 接続。認証情報を設定するには、前の手順「*Vertica に対する接続を設定するには*」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 + 前述した一時ストレージに使用する Amazon S3 バケットまたはフォルダ。*tempS3Path* という名前が必要になります。`s3a` プロトコルを使用してこの場所に接続する必要があります。 例えば、次のようになります。 ``` dynamicFrame = glueContext.create_dynamic_frame.from_options( connection_type="vertica", connection_options={ "connectionName": "connectionName", "staging_fs_url": "s3a://tempS3Path", "db": "dbName", "table": "tableName", } ) ``` SELECT SQL クエリを入力して、DynamicFrame に返された結果をフィルタリングしたり、複数のテーブルからデータセットにアクセスしたりすることもできます。 例えば、次のようになります。 ``` dynamicFrame = glueContext.create_dynamic_frame.from_options( connection_type="vertica", connection_options={ "connectionName": "connectionName", "staging_fs_url": "s3a://tempS3Path", "db": "dbName", "query": "select * FROM tableName", }, ) ``` ## Vertica テーブルへの書き込み この例では、既存の DynamicFrame である *dynamicFrame* から Vertica に情報を書き込みます。テーブルに既に情報がある場合、AWS Glue は DynamicFrame からのデータを付加します。 **前提条件:** + 書き込み先とする現在または希望のテーブル名である *tableName*。対応する Vertica データベース名である *dbName* も必要になります。 + 認証情報を提供するように設定された AWS Glue Vertica 接続。認証情報を設定するには、前の手順「*Vertica に対する接続を設定するには*」のステップを実行します。AWS Glue 接続、*connectionName* の名前が必要になります。 + 前述した一時ストレージに使用する Amazon S3 バケットまたはフォルダ。*tempS3Path* という名前が必要になります。`s3a` プロトコルを使用してこの場所に接続する必要があります。 例えば、次のようになります。 ``` glueContext.write_dynamic_frame.from_options( frame=dynamicFrame, connection_type="vertica", connection_options={ "connectionName": "connectionName", "staging_fs_url": "s3a://tempS3Path", "db": "dbName", "table": "tableName", } ) ``` ## Vertica 接続オプションのリファレンス + `connectionName` — 必須。読み込み/書き込みに使用されます。認証およびネットワークの情報を接続方法に提供するように設定された AWS Glue Vertica 接続の名前。 + `db` — 必須。読み込み/書き込みに使用されます。接続方法がインタラクションする Vertica 内のデータベースの名前。 + `dbSchema` — テーブルを識別する必要がある場合は必須です。読み込み/書き込みに使用されます。デフォルト: `public`。接続メソッドがインタラクションするスキーマの名前。 + `table` — 書き込みの場合は必須。`query` が指定されていない限り、読み取りの場合は必須。読み込み/書き込みに使用されます。接続メソッドがインタラクションするテーブルの名前。 + `query` — 読み取りに使用。Teradata から読み取るときに何を取得するかを定義する SELECT SQL クエリ。 + `staging_fs_url` — 必須。読み込み/書き込みに使用されます。有効な値: `s3a` URL。一時ストレージに使用する Amazon S3 バケットまたはフォルダの URL。 ## AWS Glue 5.0 for Spark の ETL の DataFrame オプション DataFrame は、名前の付いた列にまとめられた、テーブルに似たデータセットで、機能スタイル (マップ/リデュース/フィルター/その他) 操作と SQL 操作 (選択、プロジェクト、集計) をサポートしています。 Glue でサポートされているデータソースの DataFrame を作成するには、以下が必要です。 + データソースコネクタ `ClassName` + データソース接続 `Options` 同様に、Glue でサポートされているデータシンクに DataFrame を書き込むときも、同じものが必要です。 + データシンクコネクタ `ClassName` + データシンク接続 `Options` ジョブのブックマークなどの AWS Glue 機能や、`connectionName` などの DynamicFrame オプションは DataFrame ではサポートされていないことに注意してください。DataFrame とサポートされているオペレーションの詳細については、[DataFrame](https://spark.apache.org/docs/3.5.2/api/python/reference/pyspark.sql/dataframe.html) の Spark のドキュメントを参照してください。 ### コネクタ ClassName の指定 データソース/シンクの `ClassName` を指定するには、`.format` オプションを使用して、データソース/シンクを定義するための対応するコネクタ `ClassName` を指定します。 **JDBC コネクタ** JDBC コネクタの場合は、`.format` オプションの値として `jdbc` を指定し、`driver` オプションで JDBC ドライバー `ClassName` を指定します。 ``` df = spark.read.format("jdbc").option("driver", "")... df.write.format("jdbc").option("driver", "")... ``` 次の表は、AWS Glue for DataFrames でサポートされているデータソースの JDBC ドライバー `ClassName` の一覧です。 | データソース | ドライバーの ClassName | | --- |--- | | PostgreSQL | org.postgresql.Driver | | Oracle | oracle.jdbc.driver.OracleDriver | | SQLServer | com.microsoft.sqlserver.jdbc.SQLServerDriver | | MySQL | com.mysql.jdbc.Driver | | SAPHana | com.sap.db.jdbc.Driver | | Teradata | com.teradata.jdbc.TeraDriver | **スパークコネクタ** Spark コネクタの場合は、コネクタの `ClassName` を `.format` オプションの値として指定します。 ``` df = spark.read.format("")... df.write.format("")... ``` 次の表は、AWS Glue for DataFrames でサポートされているデータソースの Spark コネクタ `ClassName` の一覧です。 | データソース | ClassName | | --- |--- | | MongoDB/DocumentDB | glue.spark.mongodb | | Redshift | io.github.spark\$1redshift\$1community.spark.redshift | | AzureCosmos | cosmos.oltp | | AzureSQL | com.microsoft.sqlserver.jdbc.spark | | BigQuery | com.google.cloud.spark.bigquery | | OpenSearch | org.opensearch.spark.sql | | Snowflake | net.snowflake.spark.snowflake | | Vertica | com.vertica.spark.datasource.VerticaSource | ### 接続オプションの指定 データソース/シンクへの接続の `Options` を指定するには、`.option(, )` を使用して個々のオプションを指定するか、`.options()` を使用してキーと値のマップとして複数のオプションを指定します。 各データソース/シンクは、接続 `Options` の独自のセットをサポートします。利用可能な `Options` の詳細については、次の表に記載されている特定のデータソース/シンクの Spark コネクタの公開ドキュメントを参照してください。 + [JDBC](https://spark.apache.org/docs/3.5.2/sql-data-sources-jdbc.html) + [MongoDB/DocumentDB](https://www.mongodb.com/docs/spark-connector/v10.4/) + [Redshift](https://docs.aws.amazon.com/redshift/latest/mgmt/spark-redshift-connector.html) + [AzureCosmos](https://github.com/Azure/azure-cosmosdb-spark) + [AzureSQL](https://learn.microsoft.com/en-us/sql/connect/spark/connector?view=sql-server-ver16) + [BigQuery](https://cloud.google.com/dataproc/docs/tutorials/bigquery-connector-spark-example) + [OpenSearch](https://github.com/opensearch-project/opensearch-hadoop/blob/main/USER_GUIDE.md#apache-spark) + [Snowflake](https://docs.snowflake.com/en/user-guide/spark-connector-use#setting-configuration-options-for-the-connector) + [Vertica](https://github.com/vertica/spark-connector) ### 例 次の例では、PostgreSQL から読み取り、SnowFlake に書き込みます。 **Python** 例: ``` from awsglue.context import GlueContext from pyspark.sql import SparkSession spark = SparkSession.builder.getOrCreate() dataSourceClassName = "jdbc" dataSourceOptions = { "driver": "org.postgresql.Driver", "url": "", "user": "", "password": "", "dbtable": "", } dataframe = spark.read.format(className).options(**options).load() dataSinkClassName = "net.snowflake.spark.snowflake" dataSinkOptions = { "sfUrl": "", "sfUsername": "", "sfPassword": "", "sfDatabase" -> "", "sfSchema" -> "", "sfWarehouse" -> "" } dataframe.write.format(dataSinkClassName).options(**dataSinkOptions).save() ``` **Scala** 例: ``` import org.apache.spark.sql.SparkSession val spark = SparkSession.builder().getOrCreate() val dataSourceClassName = "jdbc" val dataSourceOptions = Map( "driver" -> "org.postgresql.Driver", "url" -> "", "user" -> "", "password" -> "", "dbtable" -> "" ) val dataframe = spark.read.format(dataSourceClassName).options(dataSourceOptions).load() val dataSinkClassName = "net.snowflake.spark.snowflake" val dataSinkOptions = Map( "sfUrl" -> "", "sfUsername" -> "", "sfPassword" -> "", "sfDatabase" -> "", "sfSchema" -> "", "sfWarehouse" -> "" ) dataframe.write.format(dataSinkClassName).options(dataSinkOptions).save() ``` ## カスタムと AWS Marketplace での、connectionType の値 これには以下が含まれます。 + `"connectionType": "marketplace.athena"`: Amazon Athena データストアへの接続を指定します。この接続では、AWS Marketplace が提供するコネクタを使用します。 + `"connectionType": "marketplace.spark"`: Apache Spark データストアへの接続を指定します。この接続では、AWS Marketplace が提供するコネクタを使用します。 + `"connectionType": "marketplace.jdbc"`: JDBC データストアへの接続を指定します。この接続では、AWS Marketplace が提供するコネクタを使用します。 + `"connectionType": "custom.athena"`: Amazon Athena データストアへの接続を指定します。接続には、AWS Glue Studio にアップロードしたカスタムコネクタを使用します。 + `"connectionType": "custom.spark"`: Apache Spark データストアへの接続を指定します。接続には、AWS Glue Studio にアップロードしたカスタムコネクタを使用します。 + `"connectionType": "custom.jdbc"`: JDBC データストアへの接続を指定します。接続には、AWS Glue Studio にアップロードしたカスタムコネクタを使用します。 ### custom.jdbc または marketplace.jdbc 型での接続オプション + `className` – (必須) ドライバクラス名を示す文字列。 + `connectionName` – (必須) コネクタに関連付けられている接続の名前を示す文字列。 + `url` – (必須) データソースへの接続を構築するために使用される、プレースホルダを含む JDBC URL (`${}`) を示す文字列。プレースホルダー `${secretKey}` は、AWS Secrets Manager 内にある同じ名前のシークレットにより置き換えられます。URL の構築の詳細については、データストアのドキュメントを参照してください。 + `secretId` または `user/password` – (必須) URL の認証情報を取得するために使用される文字列。 + `dbTable`または`query` – (必須) データを取得するテーブルまたは SQL クエリを示す文字列。`dbTable` または `query` を指定できます。両方を指定することはできません。 + `partitionColumn` – (オプション) パーティション化に使用される整数カラムの名前を示す文字列。このオプションは、`lowerBound`、`upperBound`、および `numPartitions` に含まれている場合にのみ機能します。このオプションの機能は、Spark SQL JDBC リーダーのものと同様です。詳細については、*Apache Spark SQL, DataFrames and Datasets Guide* の「[JDBC To Other Databases](https://spark.apache.org/docs/latest/sql-data-sources-jdbc.html)」を参照してください。 `lowerBound` および `upperBound` 値は、パーティションのストライドを決定するために使用されます (テーブル内の行のフィルタリングには使用しません)。返されるテーブル内のすべての行は、パーティション化されています。 **注記** テーブル名の代わりにクエリを使用する場合は、指定されたパーティショニング条件でクエリが動作することを確認する必要があります。例: `"SELECT col1 FROM table1"` の形式のクエリでパーティション列を使用する場合、末尾に `WHERE` 句を追加してそのクエリをテストします。 クエリ形式が `SELECT col1 FROM table1 WHERE col2=val"` の場合は、`WHERE` 句を `AND` とパーティション列を使用する式で拡張することで、そのクエリをテストします。 + `lowerBound` – パーティションストライドを決定するために使用される `partitionColumn` の最小値を示す整数 (オプション)。 + `upperBound` – パーティションストライドを決定するために使用される `partitionColumn` の最大値を示す整数 (オプション)。 + `numPartitions` – パーティション数を示す整数 (オプション)。この値は、(範囲に含まれる) `lowerBound` と (範囲に含まれない) `upperBound` とともに使用され、`partitionColumn` の分割で使用するために生成された `WHERE` 句の式のための、パーティションストライドを形成します。 **重要** パーティションが多すぎると、外部データベースシステムで問題が発生する可能性があるため、パーティションの数には注意を払ってください。 + `filterPredicate` – ソースからのデータをフィルタリングする、追加の条件句を示す文字列 (オプション)。例: ``` BillingCity='Mountain View' ``` *table* 名の代わりに *query* を使用した場合は、指定された `filterPredicate` でクエリが動作することを確認します。例: + クエリの形式が `"SELECT col1 FROM table1"` の場合は、フィルタ述語を使用するクエリの末尾に `WHERE` 句を追加して、そのクエリをテストします。 + クエリ形式が `"SELECT col1 FROM table1 WHERE col2=val"` の場合は、`WHERE` 句を `AND` およびフィルター述語を使用する式で拡張して、そのクエリをテストします。 + `dataTypeMapping` – (ディクショナリ、オプション) **JDBC** データ型 から **Glue** データ型に対するマッピングを構築する、カスタムのデータ型マッピング。例えば、オプション `"dataTypeMapping":{"FLOAT":"STRING"}` では、ドライバーの `ResultSet.getString()` メソッドを呼び出すことで、JDBC タイプ `FLOAT` のデータフィールドが Java `String` 型にマッピングされ、それを使用して AWS Glue レコードが構築されます。`ResultSet` オブジェクトは各ドライバによって実装されるため、その動作は使用するドライバにより決定されます。ドライバによる変換の実行方法については、JDBC ドライバのドキュメントを参照してください。 + AWS Glue で現在サポートされているデータ型は次のとおりです。 + DATE + STRING + TIMESTAMP + INT + FLOAT + LONG + BIGDECIMAL + BYTE + SHORT + DOUBLE JDBC データ型としては、[Java8 java.sql.types](https://docs.oracle.com/javase/8/docs/api/java/sql/Types.html) がサポートされています。 デフォルトの (JDBC から AWS Glue への) データ型マッピングは以下のとおりです。 + DATE -> DATE + VARCHAR -> STRING + CHAR -> STRING + LONGNVARCHAR -> STRING + TIMESTAMP -> TIMESTAMP + INTEGER -> INT + FLOAT -> FLOAT + REAL -> FLOAT + BIT -> BOOLEAN + BOOLEAN -> BOOLEAN + BIGINT -> LONG + DECIMAL -> BIGDECIMAL + NUMERIC -> BIGDECIMAL + TINYINT -> SHORT + SMALLINT -> SHORT + DOUBLE -> DOUBLE カスタムのデータタイプマッピングで `dataTypeMapping` オプションを使用すると、デフォルトのデータ型マッピングをオーバーライドできます。この影響を受けるのは、`dataTypeMapping` オプションでリストされた JDBC データ型のみです。他のすべての JDBC データ型に対しては、デフォルトのマッピングが使用されます。必要に応じて、別の JDBC データ型のマッピングを追加することも可能です。デフォルトまたはカスタムのマッピングのいずれにも JDBC データ型が含まれていない場合、データ型はデフォルトで AWS Glue`STRING` データ型に変換されます。 次の Python コード例は、AWS Marketplace のJDBC ドライバーを使用して、JDBC データベースからの読み取りを実行する方法を示しています。ここでは、データベースからの読み取りと、S3 ロケーションへの書き込みの方法を知ることができます。 ``` import sys from awsglue.transforms import * from awsglue.utils import getResolvedOptions from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.job import Job ## @params: [JOB_NAME] args = getResolvedOptions(sys.argv, ['JOB_NAME']) sc = SparkContext() glueContext = GlueContext(sc) spark = glueContext.spark_session job = Job(glueContext) job.init(args['JOB_NAME'], args) ## @type: DataSource ## @args: [connection_type = "marketplace.jdbc", connection_options = {"dataTypeMapping":{"INTEGER":"STRING"},"upperBound":"200","query":"select id, name, department from department where id < 200","numPartitions":"4", "partitionColumn":"id","lowerBound":"0","connectionName":"test-connection-jdbc"}, transformation_ctx = "DataSource0"] ## @return: DataSource0 ## @inputs: [] DataSource0 = glueContext.create_dynamic_frame.from_options(connection_type = "marketplace.jdbc", connection_options = {"dataTypeMapping":{"INTEGER":"STRING"}, "upperBound":"200","query":"select id, name, department from department where id < 200","numPartitions":"4","partitionColumn":"id","lowerBound":"0", "connectionName":"test-connection-jdbc"}, transformation_ctx = "DataSource0") ## @type: ApplyMapping ## @args: [mappings = [("department", "string", "department", "string"), ("name", "string", "name", "string"), ("id", "int", "id", "int")], transformation_ctx = "Transform0"] ## @return: Transform0 ## @inputs: [frame = DataSource0] Transform0 = ApplyMapping.apply(frame = DataSource0, mappings = [("department", "string", "department", "string"), ("name", "string", "name", "string"), ("id", "int", "id", "int")], transformation_ctx = "Transform0") ## @type: DataSink ## @args: [connection_type = "s3", format = "json", connection_options = {"path": "s3:///", "partitionKeys": []}, transformation_ctx = "DataSink0"] ## @return: DataSink0 ## @inputs: [frame = Transform0] DataSink0 = glueContext.write_dynamic_frame.from_options(frame = Transform0, connection_type = "s3", format = "json", connection_options = {"path": "s3:///", "partitionKeys": []}, transformation_ctx = "DataSink0") job.commit() ``` ### custom.athena または marketplace.athena タイプ用の接続オプション + `className` – (必須) ドライバクラス名を示す文字列。Athena-CloudWatch コネクタを使用している場合、このパラメータ値はクラス名にプレフィックスされます (例: `"com.amazonaws.athena.connectors"`)。Athena-CloudWatch コネクタは、メタデータハンドラーとレコードハンドラーの 2 つのクラスで構成されています。共通のプレフィックスを指定することで、API がそのプレフィックスに基づいた適切なクラスをロードします。 + `tableName` – (必須) 読み込む CloudWatch ログストリームの名前を示す文字列。このコードスニペットでは、ビューに特別な名前 `all_log_streams` を使用しています。この場合、返された動的データフレームには、ロググループ内のすべてのログストリームからのデータが含まれます。 + `schemaName` – (必須) 読み取りのソースとなる CloudWatch ロググループの名前を示す文字列。例えば、`/aws-glue/jobs/output`。 + `connectionName` – (必須) コネクタに関連付けられている接続の名前を示す文字列。 このコネクタの追加オプションについては、GitHub の [Amazon Athena CloudWatch Connector README](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch) ファイルを参照してください。 次の Python コード例は、AWS Marketplace コネクタを使用しながら、Athena データストアからの読み取りを実行する方法を示しています。こここでは、Athena からの読み取りと、S3 ロケーションへの書き込みを行う方法を知ることができます。 ``` import sys from awsglue.transforms import * from awsglue.utils import getResolvedOptions from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.job import Job ## @params: [JOB_NAME] args = getResolvedOptions(sys.argv, ['JOB_NAME']) sc = SparkContext() glueContext = GlueContext(sc) spark = glueContext.spark_session job = Job(glueContext) job.init(args['JOB_NAME'], args) ## @type: DataSource ## @args: [connection_type = "marketplace.athena", connection_options = {"tableName":"all_log_streams","schemaName":"/aws-glue/jobs/output", "connectionName":"test-connection-athena"}, transformation_ctx = "DataSource0"] ## @return: DataSource0 ## @inputs: [] DataSource0 = glueContext.create_dynamic_frame.from_options(connection_type = "marketplace.athena", connection_options = {"tableName":"all_log_streams",, "schemaName":"/aws-glue/jobs/output","connectionName": "test-connection-athena"}, transformation_ctx = "DataSource0") ## @type: ApplyMapping ## @args: [mappings = [("department", "string", "department", "string"), ("name", "string", "name", "string"), ("id", "int", "id", "int")], transformation_ctx = "Transform0"] ## @return: Transform0 ## @inputs: [frame = DataSource0] Transform0 = ApplyMapping.apply(frame = DataSource0, mappings = [("department", "string", "department", "string"), ("name", "string", "name", "string"), ("id", "int", "id", "int")], transformation_ctx = "Transform0") ## @type: DataSink ## @args: [connection_type = "s3", format = "json", connection_options = {"path": "s3:///", "partitionKeys": []}, transformation_ctx = "DataSink0"] ## @return: DataSink0 ## @inputs: [frame = Transform0] DataSink0 = glueContext.write_dynamic_frame.from_options(frame = Transform0, connection_type = "s3", format = "json", connection_options = {"path": "s3:///", "partitionKeys": []}, transformation_ctx = "DataSink0") job.commit() ``` ### custom.spark または marketplace.spark タイプ用の接続オプション + `className` – (必須) コネクタのクラス名を支援す文字列。 + `secretId` – (オプション) コネクタ接続の認証情報を取得するために使用される文字列。 + `connectionName` – (必須) コネクタに関連付けられている接続の名前を示す文字列。 + その他のオプションは、データストアによって異なります。例えば、[Elasticsearch for Apache Hadoop](https://www.elastic.co/guide/en/elasticsearch/hadoop/current/configuration.html) ドキュメントの説明にあるように、OpenSearch の設定オプションは「`es`」でプレフィックスされます。Spark から Snowflake への接続では、*Connecting to Snowflake* ガイドの「[Using the Spark Connector](https://docs.snowflake.com/en/user-guide/spark-connector-use.html)」で説明されているように、`sfUser` および `sfPassword` のオプションを使用します。 次の Python コード例に、`marketplace.spark` 接続を使用して、OpenSearch のデータストアからの読み取りを実行する方法を示します。 ``` import sys from awsglue.transforms import * from awsglue.utils import getResolvedOptions from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.job import Job ## @params: [JOB_NAME] args = getResolvedOptions(sys.argv, ['JOB_NAME']) sc = SparkContext() glueContext = GlueContext(sc) spark = glueContext.spark_session job = Job(glueContext) job.init(args['JOB_NAME'], args) ## @type: DataSource ## @args: [connection_type = "marketplace.spark", connection_options = {"path":"test", "es.nodes.wan.only":"true","es.nodes":"https://", "connectionName":"test-spark-es","es.port":"443"}, transformation_ctx = "DataSource0"] ## @return: DataSource0 ## @inputs: [] DataSource0 = glueContext.create_dynamic_frame.from_options(connection_type = "marketplace.spark", connection_options = {"path":"test","es.nodes.wan.only": "true","es.nodes":"https://","connectionName": "test-spark-es","es.port":"443"}, transformation_ctx = "DataSource0") ## @type: DataSink ## @args: [connection_type = "s3", format = "json", connection_options = {"path": "s3:///", "partitionKeys": []}, transformation_ctx = "DataSink0"] ## @return: DataSink0 ## @inputs: [frame = DataSource0] DataSink0 = glueContext.write_dynamic_frame.from_options(frame = DataSource0, connection_type = "s3", format = "json", connection_options = {"path": "s3:///", "partitionKeys": []}, transformation_ctx = "DataSink0") job.commit() ``` ## 汎用オプション このセクションのオプションは `connection_options` として提供されていますが、特定のコネクタには当てはまりません。 以下のパラメータは、ブックマークを設定する際に一般的に使用されます。Amazon S3 または JDBC ワークフローに適用される場合があります。詳細については、「[ジョブのブックマークを使用する](programming-etl-connect-bookmarks.md)」を参照してください。 + `jobBookmarkKeys` - 列名の配列。 + `jobBookmarkKeysSortOrder` — ソート順序に基づいて値を比較する方法を定義する文字列。有効な値: `"asc"`、`"desc"`。 + `useS3ListImplementation` — Amazon S3 バケットの内容を一覧表示する際のメモリパフォーマンスの管理に使用されます。詳しくは、「[Optimize memory management in AWS Glue](https://aws.amazon.com/blogs/big-data/optimize-memory-management-in-aws-glue/)」を参照してください。 # AWS Glue for Spark での入出力のデータ形式に関するオプション これらのページでは、AWS Glue for Spark でサポートされているデータ形式の機能のサポートと設定パラメータについて説明します。この情報の使用と適用可能性の説明については、以下を参照してください。 ## AWS Glue でのデータ形式間の機能のサポート 各データ形式が、異なる AWS Glue の機能をサポートする場合があります。次の一般的な機能は、形式のタイプによってサポートされる場合とサポートされない場合があります。データ形式についてのドキュメントを参照し、当社の機能を活用して要件を満たす方法を理解してください。 | | | | --- |--- | | 読み取り | AWS Glue では、コネクタなどのリソースを追加することなく、データ形式を認識し解釈できます。 | | 書き込み | AWS Glue では、リソースを追加することなく、この形式でデータを書き込むことができます。他の Spark 環境と同様に、サードパーティライブラリをジョブに含め、標準の Apache Spark 関数を使用してデータを書き込むことができます。ライブラリを含める方法の詳細については、「[AWS Glue での Python ライブラリの使用](aws-glue-programming-python-libraries.md)」を参照してください。 | | ストリーミングの読み取り | AWS Glue は、Apache Kafka、Amazon Managed Streaming for Apache Kafka、または Amazon Kinesis メッセージストリームから、このデータ形式を認識して解釈できます。ストリームは一貫した形式でデータを表示することを想定しているため、DataFrames として読み込まれます。 | | 小さなファイルのグループ化 | AWS Glue は、AWS Glue 変換を実行する際にファイルをグループ化し、各ノードに送信されるバッチを処理できます。これにより、大量の小さなファイルを扱うワークロードのパフォーマンスを大幅に向上できます。詳細については、「[大きなグループの入力ファイルの読み取り](grouping-input-files.md)」を参照してください。 | | ジョブのブックマーク | AWS Glue は、ジョブブックマークを使用して、ジョブの実行間で同じデータセットに対して同じ作業を実行する変換の進行状況を追跡できます。これにより、最後のジョブ実行以降の新しいデータに対してのみ作業を行う必要があるデータセットを含むワークロードのパフォーマンスを向上させることができます。詳細については、「[ジョブのブックマークを使用した処理済みデータの追跡](monitor-continuations.md)」を参照してください。 | ## AWS Glue でデータ形式を操作するために使用されるパラメータ 特定の AWS Glue 接続タイプは複数の `format` タイプをサポートしており、`GlueContext.write_dynamic_frame.from_options` のようなメソッドを使用する場合は、`format_options` オブジェクトを使用してデータ形式に関する情報を指定する必要があります。 + `s3` - 詳細については、AWS Glue: [S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) の「Connection types and options for ETL」(ETL の接続タイプとオプション) を参照してください。また、Python でのこの接続タイプを容易にするメソッド [create\$1dynamic\$1frame\$1from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_options) および [write\$1dynamic\$1frame\$1from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-write_dynamic_frame_from_options) と、対応する Scala メソッド [def getSourceWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSourceWithFormat) および [def getSinkWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSinkWithFormat) についてのドキュメントもご覧ください。 + `kinesis` - 詳細については、AWS Glue: [Kinesis 接続パラメータ](aws-glue-programming-etl-connect-kinesis-home.md#aws-glue-programming-etl-connect-kinesis) の「Connection types and options for ETL」(ETL の接続タイプとオプション) を参照してください。また、この接続タイプを容易にするメソッドについてのドキュメント: [create\$1data\$1frame\$1from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create-dataframe-from-options) と、対応する Scala メソッド [def createDataFrameFromOptions](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-createDataFrameFromOptions) についてのドキュメントもご覧ください。 + `kafka` - 詳細については、AWS Glue: [Kafka 接続パラメータ](aws-glue-programming-etl-connect-kafka-home.md#aws-glue-programming-etl-connect-kafka) の「Connection types and options for ETL」(ETL の接続タイプとオプション) を参照してください。また、この接続タイプを容易にするメソッドについてのドキュメント: [create\$1data\$1frame\$1from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create-dataframe-from-options) と、対応する Scala メソッド [def createDataFrameFromOptions](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-createDataFrameFromOptions) についてのドキュメントもご覧ください。 一部の接続タイプでは、`format_options` は必要ありません。例えば、通常の使用においては、リレーショナルデータベースへの JDBC 接続では整合性のある表形式のデータ形式でデータを取得します。したがって、JDBC 接続からの読み取りでは、`format_options` は必要ありません。 Glue でデータを読み書きする一部のメソッドでは、`format_options` が必要です。例えば、AWS Glue クローラーで `GlueContext.create_dynamic_frame.from_catalog` を使用します。クローラーによってデータの形式が決定されます。クローラーを使用する場合、AWS Glue 分類子がデータを調べ、データ形式を表す方法について賢く判断します。次に、データの表現を AWS Glue Data Catalog に保存します。これを AWS Glue ETL スクリプト内で使用し、`GlueContext.create_dynamic_frame.from_catalog` メソッドによってデータを取得できます。クローラーを使用すると、データ形式に関する情報を手動で指定する必要がなくなります。 AWS Lake Formation government table にアクセスするジョブの場合、AWS Glue は Lake Formation のgovernment table でサポートされているすべてのフォーマットの読み書きをサポートします。現在サポートされている AWS Lake Formation government table のフォーマット一覧は、「*AWS Lake Formation デベロッパーガイド*」の「[ガバメントテーブルの注意点と制限事項](https://docs.aws.amazon.com/lake-formation/latest/dg/governed-table-restrictions.html)」を参照してください。 **注記** Apache Parquet を書くために、AWS Glue ETL では、ダイナミックフレーム用に最適化されたカスタム Parquet ライタータイプのオプションを指定することで、管理されたテーブルへの書き込みのみをサポートします。`parquet` フォーマットでガバメントテーブルに書き込む場合は、テーブルパラメータの `useGlueParquetWriter` の値でキー `true` に追加する必要があります。 **Topics** + [AWS Glue でのデータ形式間の機能のサポート](#aws-glue-programming-etl-format-features) + [AWS Glue でデータ形式を操作するために使用されるパラメータ](#aws-glue-programming-etl-format-parameters) + [AWS Glue で CSV 形式を使用する](aws-glue-programming-etl-format-csv-home.md) + [AWS Glue で Parquet 形式を使用する](aws-glue-programming-etl-format-parquet-home.md) + [AWS Glue で XML 形式を使用する](aws-glue-programming-etl-format-xml-home.md) + [AWS Glue で Avro 形式を使用する](aws-glue-programming-etl-format-avro-home.md) + [AWS Glue で grokLog 形式を使用する](aws-glue-programming-etl-format-grokLog-home.md) + [AWS Glue で Ion 形式を使用する](aws-glue-programming-etl-format-ion-home.md) + [AWS Glue で JSON 形式を使用する](aws-glue-programming-etl-format-json-home.md) + [AWS Glue で ORC 形式を使用する](aws-glue-programming-etl-format-orc-home.md) + [AWS Glue ETL ジョブでのデータレイクフレームワークの使用](aws-glue-programming-etl-datalake-native-frameworks.md) + [共有設定リファレンス](#aws-glue-programming-etl-format-shared-reference) # AWS Glue で CSV 形式を使用する AWS Glue はソースからデータを取得し、さまざまなデータ形式で保存および転送されたターゲットにデータを書き込みます。このドキュメントでは、データが CSV データ形式で保存または転送される場合に、AWS Glue でデータを使用する際に利用できる機能について説明します。 AWS Glue は、カンマ区切り値 (CSV) ファイル形式をサポートしています。この形式は、最小限の行をベースにしたデータ形式です。CSV は厳密に基準に準拠していないことがよくありますが、詳細については [RFC 4180](https://tools.ietf.org/html/rfc4180) および [RFC 7111](https://tools.ietf.org/html/rfc7111) を参照してください。 AWS Glue を使用して、Amazon S3 およびストリーミングソースから CSV を読み取ることができ、Amazon S3 に CSV を書き込むこともできます。S3 から、CSV ファイルが含まれる `bzip` および `gzip` アーカイブを読み書きすることができます。このページで説明する設定ではなく、[S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上で圧縮動作を設定します。 次の表は、CSV 形式オプションをサポートする一般的な AWS Glue 機能を示しています。 | 読み込み | 書き込み | ストリーミングの読み取り | 小さなファイルのグループ化 | ジョブのブックマーク | | --- | --- | --- | --- | --- | | サポート対象 | サポート対象 | サポート対象 | サポート対象 | サポート | ## 例: S3 から CSV ファイルまたはフォルダを読み取る **前提条件:** 読み取りたい CSV ファイルまたはフォルダへの S3 パス (`s3path`) が必要です。 **設定:** 関数オプションで `format="csv"` を指定します。`connection_options` で、`paths` キーを使用して `s3path` を指定します。リーダーが S3 とやり取りする方法は、`connection_options` で設定できます。詳細については、AWS Glue: [S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) の「ETL の接続タイプとオプション」を参照してください。リーダーが CSV ファイルを解釈する方法は、`format_options` で設定できます。詳細については、「[CSV 設定リファレンス](#aws-glue-programming-etl-format-csv-reference)」を参照してください。 次の AWS Glue ETL スクリプトは、S3 から CSV ファイルまたはフォルダを読み取るプロセスを示しています。 `optimizePerformance` 設定キーを使用して、一般的なワークフローのパフォーマンスを最適化するカスタム CSV リーダーを提供します。このリーダーがワークロードに適しているかどうかを判断するには、「[ベクトル化された SIMD CSV リーダーで読み取りパフォーマンスを最適化する](#aws-glue-programming-etl-format-simd-csv-reader)」を参照してください。 ------ #### [ Python ] この例では [create\$1dynamic\$1frame.from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_options) メソッドを使用します。 ``` # Example: Read CSV from S3 # For show, we handle a CSV with a header row. Set the withHeader option. # Consider whether optimizePerformance is right for your workflow. from pyspark.context import SparkContext from awsglue.context import GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) spark = glueContext.spark_session dynamicFrame = glueContext.create_dynamic_frame.from_options( connection_type="s3", connection_options={"paths": ["s3://s3path"]}, format="csv", format_options={ "withHeader": True, # "optimizePerformance": True, }, ) ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` dataFrame = spark.read\ .format("csv")\ .option("header", "true")\ .load("s3://s3path") ``` ------ #### [ Scala ] この例では [getSourceWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSourceWithFormat) 操作を使用します。 ``` // Example: Read CSV from S3 // For show, we handle a CSV with a header row. Set the withHeader option. // Consider whether optimizePerformance is right for your workflow. import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.{DynamicFrame, GlueContext} import org.apache.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val dynamicFrame = glueContext.getSourceWithFormat( formatOptions=JsonOptions("""{"withHeader": true}"""), connectionType="s3", format="csv", options=JsonOptions("""{"paths": ["s3://s3path"], "recurse": true}""") ).getDynamicFrame() } } ``` スクリプト (`org.apache.spark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` val dataFrame = spark.read .option("header","true") .format("csv") .load("s3://s3path“) ``` ------ ## 例: CSV ファイルおよびフォルダを S3 に書き込む **前提条件:** 初期化された DataFrame (`dataFrame`) または DynamicFrame (`dynamicFrame`) が必要です。また、予想される S3 出力パスである `s3path` も必要になります。 **設定:** 関数オプションで `format="csv"` を指定します。`connection_options` で、`paths` キーを使用して `s3path` を指定します。ライターが S3 とやり取りする方法は、`connection_options` で設定できます。詳細については、AWS Glue: [S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) の「ETL の接続タイプとオプション」を参照してください。操作によってファイルの内容が `format_options` にどのように書き込まれるかを設定できます。詳細については、「[CSV 設定リファレンス](#aws-glue-programming-etl-format-csv-reference)」を参照してください。次の AWS Glue ETL スクリプトは、S3 に CSV ファイルとフォルダを書き込むプロセスを示しています。 ------ #### [ Python ] この例では [write\$1dynamic\$1frame.from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-write_dynamic_frame_from_options) メソッドを使用します。 ``` # Example: Write CSV to S3 # For show, customize how we write string type values. Set quoteChar to -1 so our values are not quoted. from pyspark.context import SparkContext from awsglue.context import GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) glueContext.write_dynamic_frame.from_options( frame=dynamicFrame, connection_type="s3", connection_options={"path": "s3://s3path"}, format="csv", format_options={ "quoteChar": -1, }, ) ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` dataFrame.write\ .format("csv")\ .option("quote", None)\ .mode("append")\ .save("s3://s3path") ``` ------ #### [ Scala ] この例では [getSinkWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSinkWithFormat) メソッドを使用します。 ``` // Example: Write CSV to S3 // For show, customize how we write string type values. Set quoteChar to -1 so our values are not quoted. import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.{DynamicFrame, GlueContext} import org.apache.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) glueContext.getSinkWithFormat( connectionType="s3", options=JsonOptions("""{"path": "s3://s3path"}"""), format="csv" ).writeDynamicFrame(dynamicFrame) } } ``` スクリプト (`org.apache.spark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` dataFrame.write .format("csv") .option("quote", null) .mode("Append") .save("s3://s3path") ``` ------ ## CSV 設定リファレンス AWS Glue ライブラリが `format="csv"` を指定している場合には、以下の `format_options` を使用することができます。 + `separator` - 区切り文字を指定します。デフォルトはカンマですが、他の任意の文字を指定できます。 + **タイプ:** テキスト、**デフォルト:** `","` + `escaper` - エスケープに使用する文字を指定します。このオプションは、CSV ファイルを書き込む場合ではなく、読み取る場合にのみ使用します。有効にすると、直後の文字はそのまま使用されます。ただし、よく知られている小さいエスケープセット (`\n`、`\r`、`\t`、`\0`) を除きます。 + **タイプ:** テキスト、**デフォルト:** なし + `quoteChar` - 引用に使用する文字を指定します。デフォルト値は二重引用符です。これに `-1` を設定すると、全体的に引用が無効になります。 + **タイプ:** テキスト、**デフォルト:** `'"'` + `multiLine` - 単一のレコードが複数行にまたがることができるかどうかを指定します。これが発生するのは、フィールドに引用符で囲まれた改行文字がある場合などです。複数行にまたがるレコードがある場合は、このオプションを `True` に設定する必要があります。`multiLine` を有効にすると、解析の際にファイル分割をより慎重に行う必要があるため、パフォーマンスが低下する可能性があります。 + **タイプ:** ブール値、**デフォルト:** `false` + `withHeader` - 最初の行をヘッダーとして扱うかどうかを指定します。このオプションは `DynamicFrameReader` クラスで使用できます。 + **タイプ:** ブール値、**デフォルト:** `false` + `writeHeader` - 出力にヘッダーを書き込むかどうかを指定します。このオプションは `DynamicFrameWriter` クラスで使用できます。 + **タイプ:** ブール値、**デフォルト:** `true` + `skipFirst` - 最初のデータ行をスキップするかどうかを指定します。 + **タイプ:** ブール値、**デフォルト:** `false` + `optimizePerformance` - 高度な SIMD CSV リーダーで、Apache Arrow ベースの列指向メモリ形式を使用するかどうかを指定します。これは、AWS Glue 3.0 以降でのみ使用できます。 + **タイプ:** ブール値、**デフォルト:** `false` + `strictCheckForQuoting` – CSV を作成する際、Glue は文字列と解釈した値に引用符を追加することがあります。これは、書き出される内容があいまいにならないようにするためです。Glue は、書き出す内容を決める時間を節約するために、特定の状況では引用符が不要でも引用符を追加することがあります。厳密なチェックを有効にすると、より強力な計算が行われ、厳密に必要な場合にのみ引用符が追加されます。これは、AWS Glue 3.0 以降でのみ使用できます。 + **タイプ:** ブール値、**デフォルト:** `false` ## ベクトル化された SIMD CSV リーダーで読み取りパフォーマンスを最適化する AWS Glue バージョン 3.0 では、行ベースの CSV リーダーと比較して、全体的なジョブパフォーマンスを大幅に高速化できる最適化された CSV リーダーが追加されています。 最適化されたリーダーでは: + CPU SIMD 命令を使用してディスクから読み取ります + レコードを列形式 (Apache Arrow) で即座にメモリに書き込みます + レコードをバッチに分割します これにより、レコードがバッチ処理されるときや、後で列形式に変換されるときの処理時間が節約されます。一例としては、スキーマを変更したり、列ごとにデータを取得したりする場合などが挙げられます。 最適化されたリーダーを使用するには、`format_options` またはテーブルプロパティで `"optimizePerformance"` を `true` に設定します。 ``` glueContext.create_dynamic_frame.from_options( frame = datasource1, connection_type = "s3", connection_options = {"paths": ["s3://s3path"]}, format = "csv", format_options={ "optimizePerformance": True, "separator": "," }, transformation_ctx = "datasink2") ``` **ベクトル化された CSV リーダーでの制限事項** ベクトル化された CSV リーダーには、次の制限があるので注意が必要です。 + `multiLine` および `escaper` 形式オプションはサポートされません。デフォルトの `escaper` として二重引用符文字 `'"'` を使用します。これらのオプションを設定すると、AWS Glue は自動的にフォールバックし、行ベースの CSV リーダーを使用するようになります。 + [ChoiceType](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-crawler-pyspark-extensions-types.html#aws-glue-api-crawler-pyspark-extensions-types-awsglue-choicetype) の DynamicFrame の作成はサポートされません。 + [error records](https://docs.aws.amazon.com/glue/latest/dg/glue-etl-scala-apis-glue-dynamicframe-class.html#glue-etl-scala-apis-glue-dynamicframe-class-defs-errorsAsDynamicFrame) の DynamicFrame の作成はサポートされません。 + 日本語や中国語など、マルチバイト文字を含む CSV ファイルからの読み取りはサポートされません。 # AWS Glue で Parquet 形式を使用する AWS Glue はソースからデータを取得し、さまざまなデータ形式で保存および転送されたターゲットにデータを書き込みます。このドキュメントでは、データが Parquet データ形式で保存または転送される場合に、AWS Glue でデータを使用する際に利用できる機能について説明します。 AWS Glue は Parquet 形式の使用をサポートしています。この形式は、パフォーマンス指向の列ベースのデータ形式です。標準局から発行されている形式の概要については、「[Apache Parquet ドキュメントの概要](https://parquet.apache.org/docs/overview/)」を参照してください。 AWS Glue を使用して、Amazon S3 およびストリーミングソースから Parquet ファイルを読み取ることができ、Amazon S3 に Parquet ファイルを書き込むこともできます。S3 から、Parquet ファイルが含まれる `bzip` および `gzip` アーカイブを読み書きすることができます。このページで説明する設定ではなく、[S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上で圧縮動作を設定します。 次の表は、Parquet 形式オプションをサポートする一般的な AWS Glue 機能を示しています。 | 読み込み | 書き込み | ストリーミングの読み取り | 小さなファイルのグループ化 | ジョブのブックマーク | | --- | --- | --- | --- | --- | | サポート対象 | サポート対象 | サポート | サポートされていません | サポート対象\$1 | \$1 AWS Glue バージョン 1.0\$1 でサポート ## 例: S3 から Parquet ファイルまたはフォルダを読み取る **前提条件:** 読み取りたい Parquet ファイルまたはフォルダへの S3 パス (`s3path`) が必要です。 **設定:** 関数オプションで `format="parquet"` を指定します。`connection_options` で、`paths` キーを使用して `s3path` を指定します。 リーダーが S3 とやり取りする方法は、`connection_options` で設定できます。詳細については、AWS Glue: [S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) の「ETL の接続タイプとオプション」を参照してください。 リーダーが Parquet ファイルを解釈する方法は、`format_options` で設定できます。詳細については、「[Parquet 設定リファレンス](#aws-glue-programming-etl-format-parquet-reference)」を参照してください。 次の AWS Glue ETL スクリプトは、S3 から Parquet ファイルまたはフォルダを読み取るプロセスを示しています。 ------ #### [ Python ] この例では [create\$1dynamic\$1frame.from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_options) メソッドを使用します。 ``` # Example: Read Parquet from S3 from pyspark.context import SparkContext from awsglue.context import GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) spark = glueContext.spark_session dynamicFrame = glueContext.create_dynamic_frame.from_options( connection_type = "s3", connection_options = {"paths": ["s3://s3path/"]}, format = "parquet" ) ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` dataFrame = spark.read.parquet("s3://s3path/") ``` ------ #### [ Scala ] この例では [getSourceWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSourceWithFormat) メソッドを使用します。 ``` // Example: Read Parquet from S3 import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.{DynamicFrame, GlueContext} import org.apache.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val dynamicFrame = glueContext.getSourceWithFormat( connectionType="s3", format="parquet", options=JsonOptions("""{"paths": ["s3://s3path"]}""") ).getDynamicFrame() } } ``` スクリプト (`org.apache.spark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` spark.read.parquet("s3://s3path/") ``` ------ ## 例: Parquet ファイルおよびフォルダを S3 に書き込む **前提条件:** 初期化された DataFrame (`dataFrame`) または DynamicFrame (`dynamicFrame`) が必要です。また、予想される S3 出力パスである `s3path` も必要になります。 **設定:** 関数オプションで `format="parquet"` を指定します。`connection_options` で、`paths` キーを使用して `s3path` を指定します。 ライターが S3 と対話する方法を、`connection_options` でさらに詳しく変更することができます。詳細については、AWS Glue: [S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) の「ETL の接続タイプとオプション」を参照してください。操作によってファイルの内容が `format_options` にどのように書き込まれるかを設定できます。詳細については、「[Parquet 設定リファレンス](#aws-glue-programming-etl-format-parquet-reference)」を参照してください。 次の AWS Glue ETL スクリプトは、S3 に Parquet ファイルとフォルダを書き込むプロセスを示しています。 `useGlueParquetWriter` 設定キーを通して、DynamicFrame のパフォーマンスを最適化するカスタム Parquet ライターを提供します。このライターがワークロードに適しているかどうかを判断するには、「[Glue Parquet Writer](#aws-glue-programming-etl-format-glue-parquet-writer)」を参照してください。 ------ #### [ Python ] この例では [write\$1dynamic\$1frame.from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-write_dynamic_frame_from_options) メソッドを使用します。 ``` # Example: Write Parquet to S3 # Consider whether useGlueParquetWriter is right for your workflow. from pyspark.context import SparkContext from awsglue.context import GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) glueContext.write_dynamic_frame.from_options( frame=dynamicFrame, connection_type="s3", format="parquet", connection_options={ "path": "s3://s3path", }, format_options={ # "useGlueParquetWriter": True, }, ) ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` df.write.parquet("s3://s3path/") ``` ------ #### [ Scala ] この例では [getSinkWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSinkWithFormat) メソッドを使用します。 ``` // Example: Write Parquet to S3 // Consider whether useGlueParquetWriter is right for your workflow. import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.{DynamicFrame, GlueContext} import org.apache.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) glueContext.getSinkWithFormat( connectionType="s3", options=JsonOptions("""{"path": "s3://s3path"}"""), format="parquet" ).writeDynamicFrame(dynamicFrame) } } ``` スクリプト (`org.apache.spark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` df.write.parquet("s3://s3path/") ``` ------ ## Parquet 設定リファレンス AWS Glue ライブラリが `format="parquet"` を指定している場合には、以下の `format_options` を使用することができます。 + `useGlueParquetWriter` - DynamicFrame ワークフローのパフォーマンスを最適化するカスタム Parquet ライターの使用を指定します。使用方法の詳細については、「[Glue Parquet Writer](#aws-glue-programming-etl-format-glue-parquet-writer)」を参照してください。 + **タイプ:** ブール値、**デフォルト:** `false` + `compression` - 使用する圧縮コーデックを指定します。値は `org.apache.parquet.hadoop.metadata.CompressionCodecName` との完全な互換性があります。 + **タイプ:** 列挙型テキスト、**デフォルト:** `"snappy"` + 値: `"uncompressed"`、`"snappy"`、`"gzip"`、`"lzo"` + `blockSize` - メモリにバッファされる行グループのサイズを、バイト数で指定します。これはパフォーマンスのチューニングに使用します。サイズは正確に、メガバイト数で分割する必要があります。 + **タイプ:** 数値、**デフォルト:** `134217728` + デフォルト値は 128 MB です。 + `pageSize` - ページのサイズをバイト数で指定します。これはパフォーマンスのチューニングに使用します。ページは、単一のレコードにアクセスするために完全に読み取らなければならない最小単位です。 + **タイプ:** 数値、**デフォルト:** `1048576` + デフォルト値は 1 MB です。 **注記** 加えて、基盤となる SparkSQL コードで受け入れられるすべてのオプションは、`connection_options` マップパラメータを介し、この形式に渡されます。例えば、[mergeSchema](https://spark.apache.org/docs/latest/sql-data-sources-parquet.html#schema-merging) などの Spark 設定を AWS Glue Spark リーダーに行うことで、すべてのファイルのスキーマをマージすることができます。 ## 書き込みパフォーマンスを AWS Glue Parquet ライターで最適化する **注記** AWS Glue Parquet ライターには、これまで `glueparquet` 形式タイプでアクセスしていました。このアクセス方法は非推奨となりました。代わりに、`useGlueParquetWriter` を有効にして `parquet` タイプを使用してください。 AWS Glue Parquet ライターには、Parquet ファイルの書き込みを高速化できるパフォーマンス強化が組み込まれています。これまでのライターでは、書き込む前にスキーマを計算していました。Parquet 形式では、すぐに取得できる形でスキーマを保存しないため、時間がかかることがありました。AWS Glue Parquet ライターを使用すれば、事前に計算済みのスキーマは必要なくなります。データが到着次第、ライターがスキーマを動的に計算して変更します。 `useGlueParquetWriter` を指定する場合、以下の制限に注意してください。 + ライターは、列の追加や削除などのスキーマの進化のみをサポートし、`ResolveChoice` のように列タイプの変更はサポートしません。 + ライターは、空の DataFrame の書き込み (スキーマのみのファイルを書き込む場合など) をサポートしていません。`enableUpdateCatalog=True` の設定によって AWS Glue データカタログと統合する場合、空の DataFrame を書き込もうとしてもデータカタログは更新されません。これにより、スキーマなしでデータカタログにテーブルが作成されます。 変換時にこれらの制限が必要とならない場合、AWS Glue Parquet ライターをオンにすることで、パフォーマンスが向上するはずです。 # AWS Glue で XML 形式を使用する AWS Glue はソースからデータを取得し、さまざまなデータ形式で保存および転送されたターゲットにデータを書き込みます。このドキュメントでは、データが XML データ形式で保存または転送される場合に、AWS Glue でデータを使用する際に利用できる機能について説明します。 AWS Glue は XML 形式の使用をサポートしています。この形式は、行ベースでも列ベースでもない、非常に設定可能性が高く、厳密に定義されたデータ構造を表します。XML は高度に標準化されています。標準局から発行されている形式の概要については、「[XML エッセンシャル](https://www.w3.org/standards/xml/core)」を参照してください。 AWS Glue を使用して、Amazon S3 から XML ファイルを読み込んだり、XML ファイルが含まれる `bzip` および `gzip` アーカイブを読み込んだりすることができます。このページで説明する設定ではなく、[S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上で圧縮動作を設定します。 次の表は、XML 形式オプションをサポートする一般的な AWS Glue 機能を示しています。 | 読み込み | 書き込み | ストリーミングの読み取り | 小さなファイルのグループ化 | ジョブのブックマーク | | --- | --- | --- | --- | --- | | サポート | サポートされていません | サポートされていません | サポート | サポート | ## 例: S3 から XML を読み込む XML リーダーは XML タグ名を取得します。入力内にあるそのタグを持つ要素を調べてスキーマを推測し、対応する値を DynamicFrame に入力します。AWS Glue XML の機能は、[Apache Spark の XML データソース](https://github.com/databricks/spark-xml)に類似した動作をします。このリーダーをそのプロジェクトのドキュメントと比較することで、基本的な動作に関する洞察が得られる可能性があります。 **前提条件:** 読み取りたい XML ファイルまたはフォルダへの S3 パス (`s3path`) と、XML ファイルに関するいくつかの情報が必要です。また、読み込みたい XML 要素のタグである `xmlTag` が必要です。 **設定:** 関数オプションで `format="xml"` を指定します。`connection_options` で、`paths` キーを使用して `s3path` を指定します。リーダーが S3 とやり取りする方法は、`connection_options` でさらに詳しく設定できます。詳細については、AWS Glue: [S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) の「ETL の接続タイプとオプション」を参照してください。`format_options` で、`rowTag` キーを使用して `xmlTag` を指定します。リーダーが XML ファイルを解釈する方法は、`format_options` でさらに詳しく設定できます。詳細については、「[XML 設定リファレンス](#aws-glue-programming-etl-format-xml-reference)」を参照してください。 次の AWS Glue ETL スクリプトは、S3 から XML ファイルまたはフォルダを読み取るプロセスを示しています。 ------ #### [ Python ] この例では [create\$1dynamic\$1frame.from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_options) メソッドを使用します。 ``` # Example: Read XML from S3 # Set the rowTag option to configure the reader. from awsglue.context import GlueContext from pyspark.context import SparkContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) dynamicFrame = glueContext.create_dynamic_frame.from_options( connection_type="s3", connection_options={"paths": ["s3://s3path"]}, format="xml", format_options={"rowTag": "xmlTag"}, ) ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` dataFrame = spark.read\ .format("xml")\ .option("rowTag", "xmlTag")\ .load("s3://s3path") ``` ------ #### [ Scala ] この例では [getSourceWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSourceWithFormat) 操作を使用します。 ``` // Example: Read XML from S3 // Set the rowTag option to configure the reader. import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.GlueContext import org.apache.spark.sql.SparkSession val glueContext = new GlueContext(SparkContext.getOrCreate()) val sparkSession: SparkSession = glueContext.getSparkSession object GlueApp { def main(sysArgs: Array[String]): Unit = { val dynamicFrame = glueContext.getSourceWithFormat( formatOptions=JsonOptions("""{"rowTag": "xmlTag"}"""), connectionType="s3", format="xml", options=JsonOptions("""{"paths": ["s3://s3path"], "recurse": true}""") ).getDynamicFrame() } ``` スクリプト (`org.apache.spark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` val dataFrame = spark.read .option("rowTag", "xmlTag") .format("xml") .load("s3://s3path“) ``` ------ ## XML 設定リファレンス AWS Glue ライブラリが `format="xml"` を指定している場合には、以下の `format_options` を使用することができます。 + `rowTag` - 行として扱うファイル内の XML タグを指定します。行のタグを自己終了型にすることはできません。 + **タイプ:** テキスト、**必須** + `encoding` - 文字エンコードを指定します。これは、ランタイム環境がサポートする [Charset](https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html) の名前またはエイリアスにすることができます。エンコーディングのサポートに関しては特に保証していませんが、主要なエンコーディングは動作するはずです。 + **タイプ:** テキスト、**デフォルト:** `"UTF-8"` + `excludeAttribute` - 要素の属性を除外するかどうかを指定します。 + **タイプ:** ブール値、**デフォルト:** `false` + `treatEmptyValuesAsNulls` - 空白文字を null 値として扱うかどうかをします。 + **タイプ:** ブール値、**デフォルト:** `false` + `attributePrefix` - 子要素テキストから区別するために属性に付加するプレフィックス。このプレフィックスをフィールド名として使用します。 + **タイプ:** テキスト、**デフォルト:** `"_"` + `valueTag` - 要素内に子を持たない属性がある場合、値に使用するタグ。 + **タイプ:** テキスト、**デフォルト:** `"_VALUE"` + `ignoreSurroundingSpaces` - 値を囲む空白文字を無視するかどうかを指定します。 + **タイプ:** ブール値、**デフォルト:** `false` + `withSchema` - 推論されたスキーマを上書きしたい場合に、期待されるスキーマを含みます。このオプションを使用しない場合は、AWS Glue で XML データからスキーマを推定します。 + **タイプ:** テキスト、**デフォルト:** 該当なし + 値は `StructType` を表す JSON オブジェクトである必要があります。 ## XML スキーマを手動で指定する **手動 XML スキーマの例** これは、XML データ用にスキーマを指定するために、`withSchema` 形式オプションを使用する場合の例です。 ``` from awsglue.gluetypes import * schema = StructType([ Field("id", IntegerType()), Field("name", StringType()), Field("nested", StructType([ Field("x", IntegerType()), Field("y", StringType()), Field("z", ChoiceType([IntegerType(), StringType()])) ])) ]) datasource0 = create_dynamic_frame_from_options( connection_type, connection_options={"paths": ["s3://xml_bucket/someprefix"]}, format="xml", format_options={"withSchema": json.dumps(schema.jsonValue())}, transformation_ctx = "" ) ``` # AWS Glue で Avro 形式を使用する AWS Glue はソースからデータを取得し、さまざまなデータ形式で保存および転送されたターゲットにデータを書き込みます。このドキュメントでは、データが Avro データ形式で保存または転送される場合に、AWS Glue でデータを使用する際に利用できる機能について説明します。 AWS Glue は Avro 形式の使用をサポートしています。この形式は、パフォーマンス指向の行ベースのデータ形式です。標準局による形式の概要については、「[Apache Avro 1.8.2 Documentation](https://avro.apache.org/docs/1.8.2/)」(Apache Avro ドキュメント 1.8.2) を参照してください。 AWS Glue を使用して、Amazon S3 およびストリーミングソースから Avro ファイルを読み取り、Avro ファイルを Amazon S3 に書き込むことができます。S3 から、Avro ファイルが含まれる `bzip2` および `gzip` アーカイブを読み書きすることができます。さらに、Avro ファイルが含まれる `deflate`、`snappy`、`xz` アーカイブを書き込むこともできます。このページで説明する設定ではなく、[S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上で圧縮動作を設定します。 次の表は、Avro 形式のオプションをサポートする一般的な AWS Glue オペレーションを示しています。 | 読み込み | 書き込み | ストリーミングの読み取り | 小さなファイルのグループ化 | ジョブのブックマーク | | --- | --- | --- | --- | --- | | サポート | サポート | サポート対象\$1 | サポートされていません | サポート | 制限付きで、\$1 がサポートされています。詳細については、「[Avro ストリーミングソースに関する注意事項と制約事項](add-job-streaming.md#streaming-avro-notes)」を参照してください。 ## 例: S3 から Avro ファイルまたはフォルダを読み取る **前提条件:** 読み取る Avro ファイルまたはフォルダへの S3 パス (`s3path`) が必要です。 **設定:** 関数オプションで `format="avro"` を指定します。`connection_options` で、`paths` キーを使用して `s3path` を指定します。リーダーが S3 とやり取りする方法は、`connection_options` で設定できます。詳細については、AWS Glue: [Amazon S3 接続のオプションのリファレンス](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) の「ETL の入力および出力のデータ形式オプション」を参照してください。リーダーが Avro ファイルを解釈する方法は、`format_options` で設定できます。詳細については、[Avro 設定リファレンス](#aws-glue-programming-etl-format-avro-reference)を参照してください。 次の AWS Glue ETL スクリプトは、S3 から Avro ファイルまたはフォルダを読み取るプロセスを示しています。 ------ #### [ Python ] この例では [create\$1dynamic\$1frame.from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_options) メソッドを使用します。 ``` from pyspark.context import SparkContext from awsglue.context import GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) dynamicFrame = glueContext.create_dynamic_frame.from_options( connection_type="s3", connection_options={"paths": ["s3://s3path"]}, format="avro" ) ``` ------ #### [ Scala ] この例では [getSourceWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSourceWithFormat) 操作を使用します。 ``` import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.GlueContext import org.apache.spark.sql.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val dynamicFrame = glueContext.getSourceWithFormat( connectionType="s3", format="avro", options=JsonOptions("""{"paths": ["s3://s3path"]}""") ).getDynamicFrame() } ``` ------ ## 例: Avro ファイルおよびフォルダを S3 に書き込む **前提条件:** 初期化された DataFrame (`dataFrame`) または DynamicFrame (`dynamicFrame`) が必要です。また、予想される S3 出力パスである `s3path` も必要になります。 **設定:** 関数オプションで `format="avro"` を指定します。`connection_options` で、`paths` キーを使用して `s3path` を指定します。ライターが S3 と対話する方法を、`connection_options` でさらに詳しく変更することができます。詳細については、AWS Glue: [Amazon S3 接続のオプションのリファレンス](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) の「ETL の入力および出力のデータ形式オプション」を参照してください。リーダーが Avro ファイルを解釈する方法は、`format_options` で変更できます。詳細については、[Avro 設定リファレンス](#aws-glue-programming-etl-format-avro-reference)を参照してください。 次の AWS Glue ETL スクリプトは、S3 に Avro ファイルまたはフォルダを書き込むプロセスを示しています。 ------ #### [ Python ] この例では [write\$1dynamic\$1frame.from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-write_dynamic_frame_from_options) メソッドを使用します。 ``` from pyspark.context import SparkContext from awsglue.context import GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) glueContext.write_dynamic_frame.from_options( frame=dynamicFrame, connection_type="s3", format="avro", connection_options={ "path": "s3://s3path" } ) ``` ------ #### [ Scala ] この例では [getSinkWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSinkWithFormat) メソッドを使用します。 ``` import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.{DynamicFrame, GlueContext} import org.apache.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) glueContext.getSinkWithFormat( connectionType="s3", options=JsonOptions("""{"path": "s3://s3path"}"""), format="avro" ).writeDynamicFrame(dynamicFrame) } } ``` ------ ## Avro 設定リファレンス AWS Glue ライブラリが `format="avro"` を指定する場合は、以下の `format_options` を使用することができます。 + `version` – サポートする Apache Avro リーダー/ライター形式のバージョンを指定します。デフォルト値は「1.7」です。Avro 論理型の読み取りと書き込みを有効にするには、`format_options={"version": “1.8”}` を指定します。詳細については、「[Apache Avro 1.7.7 の仕様](https://avro.apache.org/docs/1.7.7/spec.html)」および「[Apache Avro 1.8.2 の仕様](https://avro.apache.org/docs/1.8.2/spec.html)」を参照してください。 Apache Avro 1.8 コネクタは、次の論理型変換をサポートしています。 リーダーの場合: この表に、Avro リーダー 1.7 と 1.8 について、Avro データ型 (論理型と Avro プリミティブ型) と AWS Glue`DynamicFrame` データ型の間での型変換を示します。 | Avro データ型: 論理型 | Avro データ型: Avro プリミティブ型 | GlueDynamicFrame データ型:Avro リーダー 1.7 | GlueDynamicFrame データ型: Avro リーダー 1.8 | | --- | --- | --- | --- | | 10 進数 | bytes | BINARY | 10 進数 | | 10 進数 | 固定 | BINARY | 10 進数 | | 日付 | int | INT | 日付 | | 時間 (ミリ秒) | int | INT | INT | | 時間 (マイクロ秒) | long | LONG | LONG | | タイムスタンプ (ミリ秒) | long | LONG | Timestamp | | タイムスタンプ (マイクロ秒) | long | LONG | LONG | | 所要時間 (論理型ではない) | 12 で固定 | BINARY | BINARY | ライターの場合: この表に、Avro ライター 1.7 と 1.8 について、データ型と Avro データ型 AWS Glue`DynamicFrame` の間での型変換を示します。 | AWS Glue`DynamicFrame` データ型 | Avro データ型:Avro ライター 1.7 | Avro データ型:Avro タイター 1.8 | | --- | --- | --- | | 10 進数 | 文字列 | decimal | | 日付 | 文字列 | date | | Timestamp | 文字列 | timestamp-micros | ## Avro Spark DataFrame サポート Spark DataFrame API から Avro を使用するには、対応する Spark のバージョン用の Spark Avro プラグインをインストールする必要があります。ジョブで使用できる Spark のバージョンは、AWS Glue のバージョンによって決まります。Spark のバージョンの詳細については、「[AWS Glue バージョン](release-notes.md)」を参照してください。このプラグインは Apache によって管理されており、特定のサポートを保証するものではありません。 AWS Glue 2.0 - Spark Avro プラグインのバージョン 2.4.3 を使用します。この JAR は Maven Central にあります。[org.apache.spark:spark-avro\$12.12:2.4.3](https://search.maven.org/artifact/org.apache.spark/spark-avro_2.12/3.1.1/jar) を参照してください。 AWS Glue 3.0 - Spark Avro プラグインのバージョン 3.1.1 を使用します。この JAR は Maven Central にあります。[org.apache.spark:spark-avro\$12.12:3.1.1](https://search.maven.org/artifact/org.apache.spark/spark-avro_2.12/3.1.1/jar) を参照してください。 AWS Glue の ETL ジョブに追加の JAR を含めるには、`--extra-jars` ジョブパラメータを使用します。ジョブパラメータについては、「[AWS Glue ジョブでジョブパラメータを使用する](aws-glue-programming-etl-glue-arguments.md)」を参照してください。AWS マネジメントコンソール で、このパラメータを設定することもできます。 # AWS Glue で grokLog 形式を使用する AWS Glue はソースからデータを取得し、さまざまなデータ形式で保存および転送されたターゲットにデータを書き込みます。このドキュメントでは、データが大まかに構造化されたプレーンテキスト形式で保存または転送される場合に、AWS Glue でデータを使用する際に利用できる機能を紹介します。 AWS Glue は、Grok パターンの使用をサポートしています。Grok パターンは、正規表現のキャプチャグループに似ています。プレーンテキストファイル内の文字シーケンスのパターンを認識し、タイプと目的を与えます。AWS Glue での主な目的はログを読み取ることです。作成者による Grokの概要については、「[Logstash Reference: Grok filter plugin](https://www.elastic.co/guide/en/logstash/current/plugins-filters-grok.html)」(Logstash リファレンス: Grok フィルタープラグイン) を参照してください。 | 読み込み | 書き込み | ストリーミングの読み取り | 小さなファイルのグループ化 | ジョブのブックマーク | | --- | --- | --- | --- | --- | | サポート | 該当しません | サポート | サポート | サポートされていません | ## grokLog 設定リファレンス `format="grokLog"` には、以下の `format_options` 値を使用できます。 + `logFormat` – ログの形式と一致する Grok パターンを指定します。 + `customPatterns` – ここで使用する追加の Grok パターンを指定します。 + `MISSING` – 欠落した値の識別に使用するシグナルを指定します。デフォルトは `'-'` です。 + `LineCount` – 各ログレコードの行数を指定します。デフォルト値は `'1'` です。現在 1 行のレコードのみがサポートされています。 + `StrictMode` – strict モードを有効にするかどうかを指定するブール値。厳格モードでは、リーダーは自動的な型変換や復旧を行いません。デフォルト値は `"false"` です。 # AWS Glue で Ion 形式を使用する AWS Glue はソースからデータを取得し、さまざまなデータ形式で保存および転送されたターゲットにデータを書き込みます。このドキュメントでは、データが Ion データ形式で保存または転送される場合に、AWS Glue でデータを使用する際に利用できる機能を紹介します。 AWS Glue は Ion 形式の使用をサポートしています。この形式は、データ構造 (行または列ベースではない) を交換可能なバイナリおよびプレーンテキスト形式で表します。作成者による形式の概要については、「[Amazon Ion](https://amzn.github.io/ion-docs/)」を参照してください。詳細については、[Amazon Ion の仕様](https://amzn.github.io/ion-docs/spec.html)に関するドキュメントを参照してください。 AWS Glue を使用して、Amazon S3 から Ion ファイルを読み取ることができます。S3 から、Ion ファイルを含む `bzip` および `gzip` アーカイブを読み取ることができます。このページで説明する設定ではなく、[S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上で圧縮動作を設定します。 次の表は、Ion 形式のオプションをサポートする一般的な AWS Glue オペレーションを示しています。 | 読み込み | 書き込み | ストリーミングの読み取り | 小さなファイルのグループ化 | ジョブのブックマーク | | --- | --- | --- | --- | --- | | サポート | サポートされていません | サポートされていません | サポート | サポートされていません | ## 例: S3 から Ion ファイルとフォルダを読み取る **前提条件:** 読み取る Ion ファイルまたはフォルダへの S3 パス (`s3path`) が必要です。 **設定:** 関数オプションで `format="json"` を指定します。`connection_options` で、`paths` キーを使用して `s3path` を指定します。リーダーが S3 とやり取りする方法は、`connection_options` で設定できます。詳細については、AWS Glue: [Amazon S3 接続のオプションのリファレンス](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) の「ETL の接続タイプとオプション」を参照してください。 次の AWS Glue ETL スクリプトは、S3 から Ion ファイルまたはフォルダを読み取るプロセスを示しています。 ------ #### [ Python ] この例では [create\$1dynamic\$1frame.from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_options) メソッドを使用します。 ``` # Example: Read ION from S3 from pyspark.context import SparkContext from awsglue.context import GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) dynamicFrame = glueContext.create_dynamic_frame.from_options( connection_type="s3", connection_options={"paths": ["s3://s3path"]}, format="ion" ) ``` ------ #### [ Scala ] この例では [getSourceWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSourceWithFormat) 操作を使用します。 ``` // Example: Read ION from S3 import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.GlueContext import org.apache.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val dynamicFrame = glueContext.getSourceWithFormat( connectionType="s3", format="ion", options=JsonOptions("""{"paths": ["s3://s3path"], "recurse": true}""") ).getDynamicFrame() } } ``` ------ ## Ion 設定リファレンス `format="ion"` の `format_options` 値はありません。 # AWS Glue で JSON 形式を使用する AWS Glue はソースからデータを取得し、さまざまなデータ形式で保存および転送されたターゲットにデータを書き込みます。このドキュメントでは、JSON データ形式で保存または転送されているデータを、AWS Glue で使用するために用意されている機能について説明します。 AWS Glue は、JSON 形式の使用をサポートしています。この形式は、行ベースまたは列ベースではなく、形状は一貫しているが内容は柔軟なデータ構造を表します。JSON は、複数の機関が発行する並列した規格で定義されており、そのうちの 1 つが ECMA-404 です。一般的に参照されるソースによる形式の概要については、「[Introducing JSON](https://www.json.org/)」(JSON の概要) を参照してください。 AWS Glue を使用して、JSON ファイルや `bzip` および `gzip` などの圧縮された JSON ファイルを Amazon S3 から 読み取ることができます。このページで説明する設定ではなく、[S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上で圧縮動作を設定します。 | 読み込み | 書き込み | ストリーミングの読み取り | 小さなファイルのグループ化 | ジョブのブックマーク | | --- | --- | --- | --- | --- | | サポート | サポート対象 | サポート対象 | サポート対象 | サポート | ## 例: S3 から JSON ファイルまたはフォルダを読み取る **前提条件:** 読み取る JSON ファイルまたはフォルダへの S3 パス (`s3path`) が必要です。 **設定:** 関数オプションで `format="json"` を指定します。`connection_options` で、`paths` キーを使用して `s3path` を指定します。さらに、接続オプションで、読み取り操作がS3 を通過する方法を変更することができます。詳細については、「[Amazon S3 接続のオプションのリファレンス](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)」を参照してください。リーダーが JSON ファイルを解釈する方法は、`format_options` で設定できます。詳細については、[JSON 設定リファレンス](#aws-glue-programming-etl-format-json-reference)を参照してください。 次の AWS Glue ETL スクリプトは、S3 から JSON ファイルまたはフォルダを読み取るプロセスを示しています。 ------ #### [ Python ] この例では [create\$1dynamic\$1frame.from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_options) メソッドを使用します。 ``` # Example: Read JSON from S3 # For show, we handle a nested JSON file that we can limit with the JsonPath parameter # For show, we also handle a JSON where a single entry spans multiple lines # Consider whether optimizePerformance is right for your workflow. from pyspark.context import SparkContext from awsglue.context import GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) spark = glueContext.spark_session dynamicFrame = glueContext.create_dynamic_frame.from_options( connection_type="s3", connection_options={"paths": ["s3://s3path"]}, format="json", format_options={ "jsonPath": "$.id", "multiline": True, # "optimizePerformance": True, -> not compatible with jsonPath, multiline } ) ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` dataFrame = spark.read\ .option("multiline", "true")\ .json("s3://s3path") ``` ------ #### [ Scala ] この例では [getSourceWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSourceWithFormat) 操作を使用します。 ``` // Example: Read JSON from S3 // For show, we handle a nested JSON file that we can limit with the JsonPath parameter // For show, we also handle a JSON where a single entry spans multiple lines // Consider whether optimizePerformance is right for your workflow. import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.{DynamicFrame, GlueContext} import org.apache.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val dynamicFrame = glueContext.getSourceWithFormat( formatOptions=JsonOptions("""{"jsonPath": "$.id", "multiline": true, "optimizePerformance":false}"""), connectionType="s3", format="json", options=JsonOptions("""{"paths": ["s3://s3path"], "recurse": true}""") ).getDynamicFrame() } } ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` val dataFrame = spark.read .option("multiline", "true") .json("s3://s3path") ``` ------ ## 例: JSON ファイルおよびフォルダを S3 に書き込む **前提条件:** 初期化された DataFrame (`dataFrame`) または DynamicFrame (`dynamicFrame`) が必要です。また、予想される S3 出力パスである `s3path` も必要になります。 **設定:** 関数オプションで `format="json"` を指定します。`connection_options` で、`paths` キーを使用して `s3path` を指定します。ライターが S3 と対話する方法を、`connection_options` でさらに詳しく変更することができます。詳細については、AWS Glue: [Amazon S3 接続のオプションのリファレンス](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) の「ETL の入力および出力のデータ形式オプション」を参照してください。ライターが JSON ファイルを解釈する方法は、`format_options` で設定できます。詳細については、[JSON 設定リファレンス](#aws-glue-programming-etl-format-json-reference)を参照してください。 次の AWS Glue ETL スクリプトは、S3 から JSON ファイルまたはフォルダを書き込むプロセスを示しています。 ------ #### [ Python ] この例では [write\$1dynamic\$1frame.from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-write_dynamic_frame_from_options) メソッドを使用します。 ``` # Example: Write JSON to S3 from pyspark.context import SparkContext from awsglue.context import GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) glueContext.write_dynamic_frame.from_options( frame=dynamicFrame, connection_type="s3", connection_options={"path": "s3://s3path"}, format="json" ) ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` df.write.json("s3://s3path/") ``` ------ #### [ Scala ] この例では [getSinkWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSinkWithFormat) メソッドを使用します。 ``` // Example: Write JSON to S3 import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.{DynamicFrame, GlueContext} import org.apache.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) glueContext.getSinkWithFormat( connectionType="s3", options=JsonOptions("""{"path": "s3://s3path"}"""), format="json" ).writeDynamicFrame(dynamicFrame) } } ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` df.write.json("s3://s3path") ``` ------ ## JSON 設定リファレンス `format="json"` には、以下の `format_options` 値を使用できます。 + `jsonPath` – レコードに読み込むオブジェクトを特定する [JsonPath](https://github.com/json-path/JsonPath) 式。これは、ファイルが外部配列内にネストされたレコードを含む場合に役立ちます。たとえば、次の JsonPath 式のターゲットは、JSON オブジェクトの `id` フィールドです。 ``` format="json", format_options={"jsonPath": "$.id"} ``` + `multiline` — 単一のレコードが複数行にまたがることができるかどうかを指定するブール値。これが発生するのは、フィールドに引用符で囲まれた改行文字がある場合などです。複数行にまたがるレコードがある場合は、このオプションを `"true"` に設定する必要があります。デフォルト値は `"false"` であり、解析時によりアグレッシブなファイル分割を可能にします。 + `optimizePerformance` – 高度な SIMD JSON リーダーで、Apache Arrow ベースの列指向メモリ形式を使用するかどうかを指定するブール値。これは、AWS Glue 3.0 でのみ使用できます。`multiline` または `jsonPath` と互換性がありません。これらのオプションのいずれかを指定すると、AWS Glue は標準のリーダーにフォールバックするように指示されます。 + `withSchema` — 「[XML スキーマを手動で指定する](aws-glue-programming-etl-format-xml-home.md#aws-glue-programming-etl-format-xml-withschema)」で説明されている形式でテーブルスキーマを指定する文字列の値。非カタログ接続から読み取る場合にのみ、`optimizePerformance` で使用されます。 ## Apache Arrow 列指向形式によりベクトル化された SIMD JSON リーダーの使用 AWS Glue バージョン 3.0 では、JSON データ用のベクター化されたリーダーが追加されています。特定の条件下では、標準のリーダーと比較して 2 倍高速に動作します。このリーダーには、このセクションに記載されているように、ユーザーが使用前に知っておく必要のある特定の制限があります。 最適化されたリーダーを使用するには、`format_options` またはテーブルプロパティで `"optimizePerformance"` を True に設定します。カタログを読み取らない限り、`withSchema` を指定する必要もあります。`withSchema` は、「[XML スキーマを手動で指定する](aws-glue-programming-etl-format-xml-home.md#aws-glue-programming-etl-format-xml-withschema)」で説明されている入力を期待します ``` // Read from S3 data source glueContext.create_dynamic_frame.from_options( connection_type = "s3", connection_options = {"paths": ["s3://s3path"]}, format = "json", format_options={ "optimizePerformance": True, "withSchema": SchemaString }) // Read from catalog table glueContext.create_dynamic_frame.from_catalog( database = database, table_name = table, additional_options = { // The vectorized reader for JSON can read your schema from a catalog table property. "optimizePerformance": True, }) ``` AWS Glue ライブラリで *SchemaString* を構築する方法の詳細については、「[PySpark 拡張子型](aws-glue-api-crawler-pyspark-extensions-types.md)」を参照してください。 **ベクトル化された CSV リーダーでの制限事項** 以下の制限事項に留意してください。 + ネストされたオブジェクトまたは配列値を持つ JSON 要素はサポートされていません。指定されている場合、AWS Glue は標準のリーダーにフォールバックします。 + カタログから、または `withSchema` で、スキーマを指定する必要があります。 + `multiline` または `jsonPath` と互換性がありません。これらのオプションのいずれかを指定すると、AWS Glue は標準のリーダーにフォールバックするように指示されます。 + 入力スキーマと一致しない入力レコードを指定すると、リーダーは失敗します。 + [エラーレコード](https://docs.aws.amazon.com/glue/latest/dg/glue-etl-scala-apis-glue-dynamicframe-class.html#glue-etl-scala-apis-glue-dynamicframe-class-defs-errorsAsDynamicFrame)は作成されません。 + マルチバイト文字 (日本語や中国語の文字など) を含む JSON ファイルはサポートされていません。 # AWS Glue で ORC 形式を使用する AWS Glue はソースからデータを取得し、さまざまなデータ形式で保存および転送されたターゲットにデータを書き込みます。このドキュメントでは、データが ORC データ形式で保存または転送される場合に、AWS Glue でデータを使用する際に利用できる機能について説明します。 AWS Glue は、ORC 形式の使用をサポートしています。この形式は、パフォーマンス指向の列ベースのデータ形式です。標準局による形式の概要については、「[Apache Orc](https://orc.apache.org/docs/)」を参照してください。 AWS Glue を使用して、Amazon S3 およびストリーミングソースから ORC ファイルを読み取り、Amazon S3 に ORC ファイルを書き込むことができます。S3 から、ORC ファイルを含む `bzip` および `gzip` アーカイブを読み書きすることができます。このページで説明する設定ではなく、[S3 接続パラメータ](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上で圧縮動作を設定します。 次の表は、ORC 形式のオプションをサポートする一般的な AWS Glue の機能を示しています。 | 読み込み | 書き込み | ストリーミングの読み取り | 小さなファイルのグループ化 | ジョブのブックマーク | | --- | --- | --- | --- | --- | | サポート | サポート対象 | サポート | サポートされていません | サポート対象\$1 | \$1AWS Glue バージョン 1.0\$1 でサポート ## 例: S3 から ORC ファイルまたはフォルダを読み取る **前提条件:** 読み取る ORC ファイルまたはフォルダへの S3 パス (`s3path`) が必要です。 **設定:** 関数オプションで `format="orc"` を指定します。`connection_options` で、`paths` キーを使用して `s3path` を指定します。リーダーが S3 とやり取りする方法は、`connection_options` で設定できます。詳細については、AWS Glue: [Amazon S3 接続のオプションのリファレンス](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) の「ETL の接続タイプとオプション」を参照してください。 次の AWS Glue ETL スクリプトは、S3 から ORC ファイルまたはフォルダを読み取るプロセスを示しています。 ------ #### [ Python ] この例では [create\$1dynamic\$1frame.from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_options) メソッドを使用します。 ``` from pyspark.context import SparkContext from awsglue.context import GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) dynamicFrame = glueContext.create_dynamic_frame.from_options( connection_type="s3", connection_options={"paths": ["s3://s3path"]}, format="orc" ) ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` dataFrame = spark.read\ .orc("s3://s3path") ``` ------ #### [ Scala ] この例では [getSourceWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSourceWithFormat) 操作を使用します。 ``` import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.GlueContext import org.apache.spark.sql.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val dynamicFrame = glueContext.getSourceWithFormat( connectionType="s3", format="orc", options=JsonOptions("""{"paths": ["s3://s3path"]}""") ).getDynamicFrame() } } ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` val dataFrame = spark.read .orc("s3://s3path") ``` ------ ## 例: ORC ファイルおよびフォルダを S3 に書き込む **前提条件:** 初期化された DataFrame (`dataFrame`) または DynamicFrame (`dynamicFrame`) が必要です。また、予想される S3 出力パスである `s3path` も必要になります。 **設定:** 関数オプションで `format="orc"` を指定します。接続オプションでは、`s3path` を指定するための `paths` キーを使用します。ライターが S3 と対話する方法を、`connection_options` でさらに詳しく変更することができます。詳細については、AWS Glue: [Amazon S3 接続のオプションのリファレンス](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) の「ETL の入力および出力のデータ形式オプション」を参照してください。次のコード例は、プロセスを示しています。 ------ #### [ Python ] この例では [write\$1dynamic\$1frame.from\$1options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-write_dynamic_frame_from_options) メソッドを使用します。 ``` from pyspark.context import SparkContext from awsglue.context import GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) glueContext.write_dynamic_frame.from_options( frame=dynamicFrame, connection_type="s3", format="orc", connection_options={ "path": "s3://s3path" } ) ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` df.write.orc("s3://s3path/") ``` ------ #### [ Scala ] この例では [getSinkWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSinkWithFormat) メソッドを使用します。 ``` import com.amazonaws.services.glue.util.JsonOptions import com.amazonaws.services.glue.{DynamicFrame, GlueContext} import org.apache.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) glueContext.getSinkWithFormat( connectionType="s3", options=JsonOptions("""{"path": "s3://s3path"}"""), format="orc" ).writeDynamicFrame(dynamicFrame) } } ``` スクリプト (`pyspark.sql.DataFrame`) では DataFrame を使用することもできます。 ``` df.write.orc("s3://s3path/") ``` ------ ## ORC 設定リファレンス `format="orc"` の `format_options` 値はありません。ただし、基になる SparkSQL コードで受け入れられるオプションは、`connection_options` マップパラメータを介して渡すことができます。 # AWS Glue ETL ジョブでのデータレイクフレームワークの使用 オープンソースのデータレイクフレームワークを使用するいことで、Amazon S3 上に構築されたデータレイクに保存するファイルの増分データ処理を簡素化できます。AWS Glue 3.0 以降で、以下のオープンソースデータレイクフレームワークがサポートされています。 + Apache Hudi + Linux Foundation Delta Lake + Apache Iceberg これらのフレームワークはネイティブにサポートされているので、Amazon S3 に保存するデータに対する読み書きが、一貫性のあるトランザクションにより実行できます。これらのフレームワークを AWS Glue ETLジョブで使用する場合にも、別のコネクタをインストールしたり、追加の構成手順を実行したりする必要はありません。 AWS Glue Data Catalog を介してデータセットを管理していれば、Spark DataFrames を使用してデータレイクテーブルを読み書きする場合に、AWS Glue メソッドを利用できます。また、Spark DataFrame API を使用して、Amazon S3 データを読み書きすることもできます。 このビデオでは、Apache Hudi、Apache Iceberg、Delta Lake の仕組みの基本について学ぶことができます。データレイクにデータを挿入、更新、削除する方法と、これらの各フレームワークの仕組みについて説明します。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/fryfx0Zg7KA/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/fryfx0Zg7KA) **Topics** + [制限](aws-glue-programming-etl-datalake-native-frameworks-limitations.md) + [AWS Glue での Hudi フレームワークの使用](aws-glue-programming-etl-format-hudi.md) + [AWS Glue での Delta Lake フレームワークの使用](aws-glue-programming-etl-format-delta-lake.md) + [AWS Glue での Iceberg フレームワークの使用](aws-glue-programming-etl-format-iceberg.md) # 制限 AWS Glue でデータレイクフレームワークを使用する際には、以下の制限を考慮してください。 + DynamicFrame の次の AWS Glue `GlueContext` メソッドは、データレイクフレームワークテーブルの読み取りと書き込みをサポートしていません。代わりに、DataFrame または Spark DataFrame API については `GlueContext` メソッドを使用します。 + `create_dynamic_frame.from_catalog` + `write_dynamic_frame.from_catalog` + `getDynamicFrame` + `writeDynamicFrame` + DataFrame の次の `GlueContext` メソッドは、Lake Formation の許可のコントロールでサポートされています。 + `create_data_frame.from_catalog` + `write_data_frame.from_catalog` + `getDataFrame` + `writeDataFrame` + [小さなファイルのグループ化](grouping-input-files.md)は、サポートされません。 + [ジョブのブックマーク](monitor-continuations.md)はサポートされません。 + Apache Hudi 0.10.1 for AWS Glue 3.0 では、Hudi Merge on Read (MoR) テーブルはサポートされていません。 + Apache Iceberg 0.13.1 for AWS Glue 3.0 では、`ALTER TABLE … RENAME TO` を使用できません。 ## Lake Formation の許可によって管理されるデータレイク形式のテーブルの制限事項 データレイク形式は、Lake Formation の許可を介して AWS Glue ETL と統合されます。`create_dynamic_frame` を使用した DynamicFrame の作成はサポートされていません。詳細については、次の例を参照してください。 + [例: Lake Formation の許可のコントロールを使用した Iceberg テーブルの読み取りおよび書き込み](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-format-iceberg.html#aws-glue-programming-etl-format-iceberg-read-write-lake-formation-tables) + [例: Lake Formation の許可のコントロールを使用した Hudi テーブルの読み取りおよび書き込み](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-format-hudi.html#aws-glue-programming-etl-format-hudi-read-write-lake-formation-tables) + [例: Lake Formation の許可のコントロールを使用した Delta Lake テーブルの読み取りおよび書き込み](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-format-delta-lake.html#aws-glue-programming-etl-format-delta-lake-read-write-lake-formation-tables) **注記** Apache Hudi、Apache Iceberg、Delta Lake の Lake Formation 許可による AWS Glue ETLとの統合は、AWS Glue バージョン 4.0 でのみサポートされています。 Apache Iceberg は、Lake Formation の許可を介して AWS Glue ETL と最適に統合されています。ほぼすべてのオペレーションをサポートしており、SQL サポートも含まれています。 Hudi は、管理オペレーションを除くほとんどの基本オペレーションをサポートします。これは、これらのオプションが通常、データフレームの書き込みを介して実行され、`additional_options` を介して指定されるためです。SparkSQL はサポートされていないため、オペレーションのために AWS Glue API を使用して DataFrame を作成する必要があります。 Delta Lake は、テーブルデータの読み取り、付加、および上書きのみをサポートします。Delta Lake では、更新などのさまざまなタスクを実行できるように独自のライブラリを使用する必要があります。 次の機能は、Lake Formation の許可によって管理される Iceberg テーブルでは使用できません。 + AWS Glue ETL を使用した圧縮 + AWS Glue ETL を介した Spark SQL サポート Lake Formation の許可によって管理される Hudi テーブルの制限は次のとおりです。 + 孤立したファイルの削除 Lake Formation の許可によって管理される Delta Lake テーブルの制限は次のとおりです。 + Delta Lake テーブルの挿入と読み取り以外のすべての機能。 # AWS Glue での Hudi フレームワークの使用 AWS Glue 3.0 以降では、データレイク向けに Apache Hudi フレームワークが利用できます。Hudi は、増分データ処理とデータパイプラインの開発を簡素化する、オープンソースのデータレイク用ストレージフレームワークです。このトピックでは、AWS Glue 内でデータを Hudi テーブルに転送または保存する際に利用可能な、各機能について説明します。Hudi の詳細については、公式の[Apache Hudi ドキュメント](https://hudi.apache.org/docs/overview/)を参照してください。 AWS Glue により、Amazon S3 内にある Hudi テーブルの読み取りおよび書き込み操作を実行できます。あるいは、AWS Glue データカタログを使用して、Hudi テーブルを操作することも可能です。挿入、更新、および、すべての [Apache Spark オペレーション](https://hudi.apache.org/docs/quick-start-guide/)を含む操作も、追加でサポートされています。 **注記** AWS Glue 5.0 の Apache Hudi 0.15.0 実装は [HUDI-7001](https://github.com/apache/hudi/pull/9936) を内部的に元に戻します。レコードキーが 1 つのフィールドで構成されている場合、Complex Key 生成に関連するリグレッションは表示されません。ただし、この動作は OSS Apache Hudi 0.15.0 とは異なります。 Apache Hudi 0.10.1 for AWS Glue 3.0 では、Hudi Merge on Read (MoR) テーブルはサポートされません。 次の表に、AWS Glue の各バージョンに含まれている、Hudi のバージョンを一覧で示します。 **** | AWS Glue のバージョン | サポートされる Hudi バージョン | | --- | --- | | 5.1 | 1.0.2 | | 5.0 | 0.15.0 | | 4.0 | 0.12.1 | | 3.0 | 0.10.1 | AWS Glue がサポートするデータレイクフレームワークの詳細については、「[AWS Glue ETL ジョブでのデータレイクフレームワークの使用](aws-glue-programming-etl-datalake-native-frameworks.md)」を参照してください。 ## Hudi の有効化 AWS Glue で Hudi を有効化するには、以下のタスクを実行します。 + `hudi` を `--datalake-formats` のジョブパラメータの値として指定します。詳細については、「[AWS Glue ジョブでジョブパラメータを使用する](aws-glue-programming-etl-glue-arguments.md)」を参照してください。 + AWS Glue ジョブ用に、`--conf` という名前でキーを作成し、それに次の値を設定します。または、スクリプトで `SparkConf` を使用して、次の構成を設定することもできます。これらの設定は、Apache Spark が Hudi テーブルを適切に処理するために役立ちます。 ``` spark.serializer=org.apache.spark.serializer.KryoSerializer ``` + Hudi に関する Lake Formation の許可のサポートは、AWS Glue 4.0 のためにデフォルトで有効になっています。Lake Formation に登録された Hudi テーブルの読み取り/書き込みに追加の設定は必要ありません。登録された Hudi テーブルを読み取るには、AWS Glue ジョブの IAM ロールに SELECT 許可が必要です。登録された Hudi テーブルに書き込むには、AWS Glue ジョブの IAM ロールに SUPER 許可が必要です。Lake Formation の許可の管理の詳細については、「[Data Catalog リソースに対する許可の付与と取り消し](https://docs.aws.amazon.com/lake-formation/latest/dg/granting-catalog-permissions.html)」を参照してください。 **別の Hudi バージョンの使用** AWS Glue でサポートされないバージョンの Hudi を使用するには、`--extra-jars` job パラメーターにより独自の Hudi JAR ファイルを指定します。`--datalake-formats` ジョブパラメータの値として、`hudi` は含めないでください。AWS Glue 5.0 以降を使用する場合、`--user-jars-first true` ジョブパラメータを設定する必要があります。 ## 例: Hudi テーブルを Amazon S3 に書き込み、そのテーブルを AWS Glue データカタログに登録する このスクリプト例では、Hudi テーブルを Amazon S3 に書き込み、そのテーブルを AWS Glue データカタログに登録する方法を示します。この例では、テーブルを登録するために、Hudi [Hive Sync ツール](https://hudi.apache.org/docs/syncing_metastore/)を使用します。 **注記** この例では、AWS Glue データカタログを Apache Spark Hive のメタストアとして使用するために、`--enable-glue-datacatalog` ジョブパラメータの設定が必要となります。詳細については[AWS Glue ジョブでジョブパラメータを使用する](aws-glue-programming-etl-glue-arguments.md)を参照してください。 ------ #### [ Python ] ``` # Example: Create a Hudi table from a DataFrame # and register the table to Glue Data Catalog additional_options={ "hoodie.table.name": "", "hoodie.database.name": "", "hoodie.datasource.write.storage.type": "COPY_ON_WRITE", "hoodie.datasource.write.operation": "upsert", "hoodie.datasource.write.recordkey.field": "", "hoodie.datasource.write.precombine.field": "", "hoodie.datasource.write.partitionpath.field": "", "hoodie.datasource.write.hive_style_partitioning": "true", "hoodie.datasource.hive_sync.enable": "true", "hoodie.datasource.hive_sync.database": "", "hoodie.datasource.hive_sync.table": "", "hoodie.datasource.hive_sync.partition_fields": "", "hoodie.datasource.hive_sync.partition_extractor_class": "org.apache.hudi.hive.MultiPartKeysValueExtractor", "hoodie.datasource.hive_sync.use_jdbc": "false", "hoodie.datasource.hive_sync.mode": "hms", "path": "s3://" } dataFrame.write.format("hudi") \ .options(**additional_options) \ .mode("overwrite") \ .save() ``` ------ #### [ Scala ] ``` // Example: Example: Create a Hudi table from a DataFrame // and register the table to Glue Data Catalog val additionalOptions = Map( "hoodie.table.name" -> "", "hoodie.database.name" -> "", "hoodie.datasource.write.storage.type" -> "COPY_ON_WRITE", "hoodie.datasource.write.operation" -> "upsert", "hoodie.datasource.write.recordkey.field" -> "", "hoodie.datasource.write.precombine.field" -> "", "hoodie.datasource.write.partitionpath.field" -> "", "hoodie.datasource.write.hive_style_partitioning" -> "true", "hoodie.datasource.hive_sync.enable" -> "true", "hoodie.datasource.hive_sync.database" -> "", "hoodie.datasource.hive_sync.table" -> "", "hoodie.datasource.hive_sync.partition_fields" -> "", "hoodie.datasource.hive_sync.partition_extractor_class" -> "org.apache.hudi.hive.MultiPartKeysValueExtractor", "hoodie.datasource.hive_sync.use_jdbc" -> "false", "hoodie.datasource.hive_sync.mode" -> "hms", "path" -> "s3://") dataFrame.write.format("hudi") .options(additionalOptions) .mode("append") .save() ``` ------ ## 例: AWS Glue データカタログを使用した Amazon S3 からの Hudi テーブルの読み取り この例では、「[例: Hudi テーブルを Amazon S3 に書き込み、そのテーブルを AWS Glue データカタログに登録する](#aws-glue-programming-etl-format-hudi-write)」で作成した Hudi テーブルを Amazon S3 から読み取ります。 **注記** この例では、AWS Glue データカタログを Apache Spark Hive のメタストアとして使用するために、`--enable-glue-datacatalog` ジョブパラメータの設定が必要となります。詳細については[AWS Glue ジョブでジョブパラメータを使用する](aws-glue-programming-etl-glue-arguments.md)を参照してください。 ------ #### [ Python ] この例では、`GlueContext.create\$1data\$1frame.from\$1catalog()` メソッドを使用します。 ``` # Example: Read a Hudi table from Glue Data Catalog from awsglue.context import GlueContext from pyspark.context import SparkContext sc = SparkContext() glueContext = GlueContext(sc) dataFrame = glueContext.create_data_frame.from_catalog( database = "", table_name = "" ) ``` ------ #### [ Scala ] この例では [getCatalogSource](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getCatalogSource) メソッドを使用します。 ``` // Example: Read a Hudi table from Glue Data Catalog import com.amazonaws.services.glue.GlueContext import org.apache.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val dataFrame = glueContext.getCatalogSource( database = "", tableName = "" ).getDataFrame() } } ``` ------ ## 例: `DataFrame` を更新して、Amazon S3 内にある Hudi テーブルに挿入する この例では、「[例: Hudi テーブルを Amazon S3 に書き込み、そのテーブルを AWS Glue データカタログに登録する](#aws-glue-programming-etl-format-hudi-write)」で作成した Hudi テーブルに対し、AWS Glue データカタログを使用して DataFrame を挿入します。 **注記** この例では、AWS Glue データカタログを Apache Spark Hive のメタストアとして使用するために、`--enable-glue-datacatalog` ジョブパラメータの設定が必要となります。詳細については[AWS Glue ジョブでジョブパラメータを使用する](aws-glue-programming-etl-glue-arguments.md)を参照してください。 ------ #### [ Python ] この例では、`GlueContext.write\$1data\$1frame.from\$1catalog()` メソッドを使用します。 ``` # Example: Upsert a Hudi table from Glue Data Catalog from awsglue.context import GlueContext from pyspark.context import SparkContext sc = SparkContext() glueContext = GlueContext(sc) glueContext.write_data_frame.from_catalog( frame = dataFrame, database = "", table_name = "", additional_options={ "hoodie.table.name": "", "hoodie.database.name": "", "hoodie.datasource.write.storage.type": "COPY_ON_WRITE", "hoodie.datasource.write.operation": "upsert", "hoodie.datasource.write.recordkey.field": "", "hoodie.datasource.write.precombine.field": "", "hoodie.datasource.write.partitionpath.field": "", "hoodie.datasource.write.hive_style_partitioning": "true", "hoodie.datasource.hive_sync.enable": "true", "hoodie.datasource.hive_sync.database": "", "hoodie.datasource.hive_sync.table": "", "hoodie.datasource.hive_sync.partition_fields": "", "hoodie.datasource.hive_sync.partition_extractor_class": "org.apache.hudi.hive.MultiPartKeysValueExtractor", "hoodie.datasource.hive_sync.use_jdbc": "false", "hoodie.datasource.hive_sync.mode": "hms" } ) ``` ------ #### [ Scala ] この例では [getCatalogSink](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getCatalogSink) メソッドを使用します。 ``` // Example: Upsert a Hudi table from Glue Data Catalog import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.util.JsonOptions import org.apacke.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) glueContext.getCatalogSink("", "", additionalOptions = JsonOptions(Map( "hoodie.table.name" -> "", "hoodie.database.name" -> "", "hoodie.datasource.write.storage.type" -> "COPY_ON_WRITE", "hoodie.datasource.write.operation" -> "upsert", "hoodie.datasource.write.recordkey.field" -> "", "hoodie.datasource.write.precombine.field" -> "", "hoodie.datasource.write.partitionpath.field" -> "", "hoodie.datasource.write.hive_style_partitioning" -> "true", "hoodie.datasource.hive_sync.enable" -> "true", "hoodie.datasource.hive_sync.database" -> "", "hoodie.datasource.hive_sync.table" -> "", "hoodie.datasource.hive_sync.partition_fields" -> "", "hoodie.datasource.hive_sync.partition_extractor_class" -> "org.apache.hudi.hive.MultiPartKeysValueExtractor", "hoodie.datasource.hive_sync.use_jdbc" -> "false", "hoodie.datasource.hive_sync.mode" -> "hms" ))) .writeDataFrame(dataFrame, glueContext) } } ``` ------ ## 例: Spark を使用した Amazon S3 からの Hudi テーブルの読み取り この例では、Spark DataFrame API を使用して Amazon S3 から Hudi テーブルを読み取ります。 ------ #### [ Python ] ``` # Example: Read a Hudi table from S3 using a Spark DataFrame dataFrame = spark.read.format("hudi").load("s3://") ``` ------ #### [ Scala ] ``` // Example: Read a Hudi table from S3 using a Spark DataFrame val dataFrame = spark.read.format("hudi").load("s3://") ``` ------ ## 例: スパークを使用した Amazon S3 への Hudi テーブルの書き込み この例では、Spark を使用して Amazon S3 に Hudi テーブルを書き込みます。 ------ #### [ Python ] ``` # Example: Write a Hudi table to S3 using a Spark DataFrame dataFrame.write.format("hudi") \ .options(**additional_options) \ .mode("overwrite") \ .save("s3://) ``` ------ #### [ Scala ] ``` // Example: Write a Hudi table to S3 using a Spark DataFrame dataFrame.write.format("hudi") .options(additionalOptions) .mode("overwrite") .save("s3://") ``` ------ ## 例: Lake Formation の許可のコントロールを使用した Hudi テーブルの読み取りおよび書き込み この例では、Lake Formation の許可のコントロールを使用して Hudi テーブルの読み取りと書き込みを行います。 1. Hudi テーブルを作成して Lake Formation に登録します。 1. Lake Formation の許可のコントロールを有効にするには、まずテーブルの Amazon S3 パスを Lake Formation に登録する必要があります。詳細については、「[Registering an Amazon S3 location](https://docs.aws.amazon.com/lake-formation/latest/dg/register-location.html)」を参照してください。Lake Formation コンソールから、または AWS CLI を使用して登録できます。 ``` aws lakeformation register-resource --resource-arn arn:aws:s3:::/ --use-service-linked-role --region ``` Amazon S3 の場所が登録されると、その場所 (またはその子である場所) をポイントするすべての AWS Glue テーブルが、`GetTable` 呼び出しで `IsRegisteredWithLakeFormation` パラメータの値を true として返します。 1. Spark DataFrame API を介して登録された Amazon S3 パスをポイントする Hudi テーブルを作成します。 ``` hudi_options = { 'hoodie.table.name': table_name, 'hoodie.database.name': database_name, 'hoodie.datasource.write.storage.type': 'COPY_ON_WRITE', 'hoodie.datasource.write.recordkey.field': 'product_id', 'hoodie.datasource.write.table.name': table_name, 'hoodie.datasource.write.operation': 'upsert', 'hoodie.datasource.write.precombine.field': 'updated_at', 'hoodie.datasource.write.hive_style_partitioning': 'true', 'hoodie.upsert.shuffle.parallelism': 2, 'hoodie.insert.shuffle.parallelism': 2, 'path': , 'hoodie.datasource.hive_sync.enable': 'true', 'hoodie.datasource.hive_sync.database': database_name, 'hoodie.datasource.hive_sync.table': table_name, 'hoodie.datasource.hive_sync.use_jdbc': 'false', 'hoodie.datasource.hive_sync.mode': 'hms' } df_products.write.format("hudi") \ .options(**hudi_options) \ .mode("overwrite") \ .save() ``` 1. AWS Glue ジョブ IAM ロールに Lake Formation の許可を付与します。Lake Formation コンソールから、または AWS CLI を使用して許可を付与できます。詳細については、「[Lake Formation コンソールと名前付きリソース方式を使用したテーブル許可の付与](https://docs.aws.amazon.com/lake-formation/latest/dg/granting-table-permissions.html)」を参照してください。 1. Lake Formation に登録されている Hudi テーブルを読み取ります。このコードは、未登録の Hudi テーブルを読み取る場合と同じです。読み取りを成功させるには、AWS Glue ジョブの IAM ロールに SELECT 許可が必要であることに留意してください。 ``` val dataFrame = glueContext.getCatalogSource( database = "", tableName = "" ).getDataFrame() ``` 1. Lake Formation に登録されている Hudi テーブルに書き込みます。このコードは、未登録の Hudi テーブルに書き込む場合と同じです。書き込みを成功させるには、AWS Glue ジョブの IAM ロールに SUPER 許可が必要であることに留意してください。 ``` glueContext.getCatalogSink("", "", additionalOptions = JsonOptions(Map( "hoodie.table.name" -> "", "hoodie.database.name" -> "", "hoodie.datasource.write.storage.type" -> "COPY_ON_WRITE", "hoodie.datasource.write.operation" -> "", "hoodie.datasource.write.recordkey.field" -> "", "hoodie.datasource.write.precombine.field" -> "", "hoodie.datasource.write.partitionpath.field" -> "", "hoodie.datasource.write.hive_style_partitioning" -> "true", "hoodie.datasource.hive_sync.enable" -> "true", "hoodie.datasource.hive_sync.database" -> "", "hoodie.datasource.hive_sync.table" -> "", "hoodie.datasource.hive_sync.partition_fields" -> "", "hoodie.datasource.hive_sync.partition_extractor_class" -> "org.apache.hudi.hive.MultiPartKeysValueExtractor", "hoodie.datasource.hive_sync.use_jdbc" -> "false", "hoodie.datasource.hive_sync.mode" -> "hms" ))) .writeDataFrame(dataFrame, glueContext) ``` # AWS Glue での Delta Lake フレームワークの使用 AWS Glue 3.0 以降では、Linux Foundation Delta Lake フレームワークを利用できます。Delta Lake は、ACID トランザクションの実行、メタデータ処理のスケーリング、さらにストリーミングとバッチデータ処理の統合を支援する、オープンソースのデータレイクストレージフレームワークです。このトピックでは、Delta Lake テーブルに転送または保存するデータに対して、AWS Glue 内で利用可能な機能について説明します。Delta Lake の詳細については、公式の [Delta Lake のドキュメント](https://docs.delta.io/latest/delta-intro.html)を参照してください。 Amazon S3 内にある Delta Lake テーブルに対する読み取りおよび書き込みの操作は、AWS Glue を使用して実行できます。あるいは、AWS Glue データカタログにより Delta Lake テーブルを操作することもできます。挿入、更新、および[テーブルに対する一括での読み取りと書き込み](https://docs.delta.io/0.7.0/api/python/index.html)など、その他の操作もサポートされています。Delta Lake テーブルを使用する場合、Delta Lake Python ライブラリに備わったメソッド (例えば、`DeltaTable.forPath`) も使用可能です。Delta Lake Python ライブラリの詳細については、「Delta Lake の Python ドキュメント」を参照してください。 次の表に、AWS Glue の各バージョンに含まれている Delta Lake のバージョンを一覧で示します。 **** | AWS Glue のバージョン | サポートされている Delta Lake バージョン | | --- | --- | | 5.1 | 3.3.2 | | 5.0 | 3.3.0 | | 4.0 | 2.1.0 | | 3.0 | 1.0.0 | AWS Glue がサポートするデータレイクフレームワークの詳細については、「[AWS Glue ETL ジョブでのデータレイクフレームワークの使用](aws-glue-programming-etl-datalake-native-frameworks.md)」を参照してください。 ## AWS Glue のための Delta Lake の有効化 AWS Glue で Delta Lake を有効化するには、以下のタスクを実行します。 + `delta` を `--datalake-formats` のジョブパラメータの値として指定します。詳細については、「[AWS Glue ジョブでジョブパラメータを使用する](aws-glue-programming-etl-glue-arguments.md)」を参照してください。 + AWS Glue ジョブ用に、`--conf` という名前でキーを作成し、それに次の値を設定します。または、スクリプトで `SparkConf` を使用して、次の構成を設定することもできます。これらの設定は、Apache Spark が Delta Lake テーブルを適切に処理するために役立ちます。 ``` spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension --conf spark.sql.catalog.spark_catalog=org.apache.spark.sql.delta.catalog.DeltaCatalog --conf spark.delta.logStore.class=org.apache.spark.sql.delta.storage.S3SingleDriverLogStore ``` + Delta テーブルに関する Lake Formation の許可のサポートは、AWS Glue 4.0 のためにデフォルトで有効になっています。Lake Formation に登録された Delta テーブルの読み取り/書き込みに追加の設定は必要ありません。登録された Delta テーブルを読み取るには、AWS Glue ジョブの IAM ロールに SELECT 許可が必要です。登録された Delta テーブルに書き込むには、AWS Glue ジョブの IAM ロールに SUPER 許可が必要です。Lake Formation の許可の管理の詳細については、「[Data Catalog リソースに対する許可の付与と取り消し](https://docs.aws.amazon.com/lake-formation/latest/dg/granting-catalog-permissions.html)」を参照してください。 **別のバージョンの Delta Lake を使用する** AWS Glue でサポートされないバージョンの Delta Lake を使用するには、`--extra-jars` ジョブパラメータにより、独自の Delta Lake JAR ファイルを指定します。`--datalake-formats` ジョブパラメータの値として、`delta` は含めないでください。AWS Glue 5.0 以降を使用する場合、`--user-jars-first true` ジョブパラメータを設定する必要があります。この場合、Delta Lake Python ライブラリを使用するには、`--extra-py-files` ジョブパラメータにより、ライブラリの JAR ファイルを指定する必要があります。Python ライブラリは、Delta Lake JAR ファイルにパッケージ化されています。 ## 例: Delta Lake テーブルを Amazon S3 に書き込んで、そのテーブルを AWS Glue データカタログに登録する 次の AWS Glue ETL スクリプトは、Delta Lake テーブルを Amazon S3 に書き込み、そのテーブルを AWS Glue データカタログに登録する方法を示しています。 ------ #### [ Python ] ``` # Example: Create a Delta Lake table from a DataFrame # and register the table to Glue Data Catalog additional_options = { "path": "s3://" } dataFrame.write \ .format("delta") \ .options(**additional_options) \ .mode("append") \ .partitionBy("") \ .saveAsTable(".") ``` ------ #### [ Scala ] ``` // Example: Example: Create a Delta Lake table from a DataFrame // and register the table to Glue Data Catalog val additional_options = Map( "path" -> "s3://" ) dataFrame.write.format("delta") .options(additional_options) .mode("append") .partitionBy("") .saveAsTable(".") ``` ------ ## 例: AWS Glue データカタログを使用して Amazon S3 から Delta Lake テーブルを読み取る 次の AWS Glue ETL スクリプトでは、「[例: Delta Lake テーブルを Amazon S3 に書き込んで、そのテーブルを AWS Glue データカタログに登録する](#aws-glue-programming-etl-format-delta-lake-write)」で作成した Delta Lake テーブルの読み取りを実行します。 ------ #### [ Python ] この例では [create\$1data\$1frame.from\$1catalog](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create-dataframe-from-catalog) メソッドを使用します。 ``` # Example: Read a Delta Lake table from Glue Data Catalog from awsglue.context import GlueContext from pyspark.context import SparkContext sc = SparkContext() glueContext = GlueContext(sc) df = glueContext.create_data_frame.from_catalog( database="", table_name="", additional_options=additional_options ) ``` ------ #### [ Scala ] この例では [getCatalogSource](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getCatalogSource) メソッドを使用します。 ``` // Example: Read a Delta Lake table from Glue Data Catalog import com.amazonaws.services.glue.GlueContext import org.apacke.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val df = glueContext.getCatalogSource("", "", additionalOptions = additionalOptions) .getDataFrame() } } ``` ------ ## 例: AWS Glue データカタログを使用して Amazon S3 内にある Delta Lake テーブルに `DataFrame` を挿入する この例では、「[例: Delta Lake テーブルを Amazon S3 に書き込んで、そのテーブルを AWS Glue データカタログに登録する](#aws-glue-programming-etl-format-delta-lake-write)」で作成した Delta Lake テーブルにデータを挿入します。 **注記** この例では、AWS Glue データカタログを Apache Spark Hive のメタストアとして使用するために、`--enable-glue-datacatalog` ジョブパラメータの設定が必要となります。詳細については[AWS Glue ジョブでジョブパラメータを使用する](aws-glue-programming-etl-glue-arguments.md)を参照してください。 ------ #### [ Python ] この例では、[write\$1data\$1frame.from\$1catalog](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-write_data_frame_from_catalog) メソッドを使用します。 ``` # Example: Insert into a Delta Lake table in S3 using Glue Data Catalog from awsglue.context import GlueContext from pyspark.context import SparkContext sc = SparkContext() glueContext = GlueContext(sc) glueContext.write_data_frame.from_catalog( frame=dataFrame, database="", table_name="", additional_options=additional_options ) ``` ------ #### [ Scala ] この例では [getCatalogSink](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getCatalogSink) メソッドを使用します。 ``` // Example: Insert into a Delta Lake table in S3 using Glue Data Catalog import com.amazonaws.services.glue.GlueContext import org.apacke.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) glueContext.getCatalogSink("", "", additionalOptions = additionalOptions) .writeDataFrame(dataFrame, glueContext) } } ``` ------ ## 例: Spark API を使用して Amazon S3 から Delta Lake テーブルを読み取る この例では、Spark API を使用して Amazon S3 から Delta Lake を読み取ります。 ------ #### [ Python ] ``` # Example: Read a Delta Lake table from S3 using a Spark DataFrame dataFrame = spark.read.format("delta").load("s3://") ``` ------ #### [ Scala ] ``` // Example: Read a Delta Lake table from S3 using a Spark DataFrame val dataFrame = spark.read.format("delta").load("s3://") ``` ------ ## 例: Spark を使用した Amazon S3 への Delta Lake テーブルの書き込み この例では、Spark を使用して Amazon S3 に Delta Lake テーブルを書き込みます。 ------ #### [ Python ] ``` # Example: Write a Delta Lake table to S3 using a Spark DataFrame dataFrame.write.format("delta") \ .options(**additional_options) \ .mode("overwrite") \ .partitionBy("") .save("s3://") ``` ------ #### [ Scala ] ``` // Example: Write a Delta Lake table to S3 using a Spark DataFrame dataFrame.write.format("delta") .options(additionalOptions) .mode("overwrite") .partitionBy("") .save("s3://") ``` ------ ## 例: Lake Formation の許可のコントロールを使用した Delta Lake テーブルの読み取りおよび書き込み この例では、Lake Formation の許可のコントロールを使用して Delta Lake テーブルの読み取りと書き込みを行います。 1. Delta テーブルを作成して Lake Formation に登録する 1. Lake Formation の許可のコントロールを有効にするには、まずテーブルの Amazon S3 パスを Lake Formation に登録する必要があります。詳細については、「[Registering an Amazon S3 location](https://docs.aws.amazon.com/lake-formation/latest/dg/register-location.html)」を参照してください。Lake Formation コンソールから、または AWS CLI を使用して登録できます。 ``` aws lakeformation register-resource --resource-arn arn:aws:s3:::/ --use-service-linked-role --region ``` Amazon S3 の場所が登録されると、その場所 (またはその子である場所) をポイントするすべての AWS Glue テーブルが、`GetTable` 呼び出しで `IsRegisteredWithLakeFormation` パラメータの値を true として返します。 1. Spark を介して登録された Amazon S3 パスをポイントする Delta テーブルを作成します。 **注記** 次に Python の例を示します。 ``` dataFrame.write \ .format("delta") \ .mode("overwrite") \ .partitionBy("") \ .save("s3://") ``` データが Amazon S3 に書き込まれた後、AWS Glue クローラーを使用して新しい Delta カタログテーブルを作成します。詳細については、「[AWS Glue クローラーによるネイティブデータレイクテーブルサポートの紹介](https://aws.amazon.com/blogs/big-data/introducing-native-delta-lake-table-support-with-aws-glue-crawlers/)」を参照してください。 AWS Glue `CreateTable` API を通じてテーブルを手動で作成することもできます。 1. AWS Glue ジョブ IAM ロールに Lake Formation の許可を付与します。Lake Formation コンソールから、または AWS CLI を使用して許可を付与できます。詳細については、「[Lake Formation コンソールと名前付きリソース方式を使用したテーブル許可の付与](https://docs.aws.amazon.com/lake-formation/latest/dg/granting-table-permissions.html)」を参照してください。 1. Lake Formation に登録されている Delta テーブルを読み取ります。このコードは、未登録の Delta テーブルを読み取る場合と同じです。読み取りを成功させるには、AWS Glue ジョブの IAM ロールに SELECT 許可が必要であることに留意してください。 ``` # Example: Read a Delta Lake table from Glue Data Catalog df = glueContext.create_data_frame.from_catalog( database="", table_name="", additional_options=additional_options ) ``` 1. Lake Formation に登録されている Delta テーブルに書き込みます。このコードは、未登録の Delta テーブルに書き込む場合と同じです。書き込みを成功させるには、AWS Glue ジョブの IAM ロールに SUPER 許可が必要であることに留意してください。 デフォルトでは、AWS Glue は saveMode として `Append` を使用します。これを変更するには、`additional_options` で saveMode オプションを設定します。Delta テーブルでの saveMode サポートの詳細については、「[テーブルに書き込む](https://docs.delta.io/latest/delta-batch.html#write-to-a-table)」を参照してください。 ``` glueContext.write_data_frame.from_catalog( frame=dataFrame, database="", table_name="", additional_options=additional_options ) ``` # AWS Glue での Iceberg フレームワークの使用 AWS Glue 3.0 以降では、データレイク向けに Apache Iceberg フレームワークがサポートされています。Iceberg により、SQL テーブルと同様な機能を持つ、高性能なテーブルフォーマットが提供されます。このトピックでは、AWS Glue 内でデータを Iceberg テーブルに転送または保存する際に利用可能な、機能について説明します。Iceberg の詳細については、公式の[Apache Iceberg ドキュメント](https://iceberg.apache.org/docs/latest/)を参照してください。 Amazon S3 内の Iceberg テーブルに対する読み取りと書き込みの操作は、AWS Glue を使用して実行することができます。あるいは、AWS Glue データカタログを使用して Iceberg テーブルを操作することも可能です。挿入に加え、「[Spark クエリ](https://iceberg.apache.org/docs/latest/spark-queries/)」 や 「[Spark 書き込み](https://iceberg.apache.org/docs/latest/spark-writes/)」 のすべての操作も、追加でサポートされています。更新は Iceberg テーブルではサポートされていません。 **注記** Apache Iceberg 0.13.1 for AWS Glue 3.0 では、`ALTER TABLE … RENAME TO` はサポートされません。 次の表に、AWS Glue の各バージョンに含まれる Iceberg のバージョンを一覧で示します。 **** | AWS Glue のバージョン | サポートされる Iceberg バージョン | | --- | --- | | 5.1 | 1.10.0 | | 5.0 | 1.7.1 | | 4.0 | 1.0.0 | | 3.0 | 0.13.1 | AWS Glue がサポートするデータレイクフレームワークの詳細については、「[AWS Glue ETL ジョブでのデータレイクフレームワークの使用](aws-glue-programming-etl-datalake-native-frameworks.md)」を参照してください。 ## Iceberg フレームワークの有効化 AWS Glue で Iceberg を有効化するには、以下のタスクを実行します。 + `iceberg` を `--datalake-formats` のジョブパラメータの値として指定します。詳細については、「[AWS Glue ジョブでジョブパラメータを使用する](aws-glue-programming-etl-glue-arguments.md)」を参照してください。 + AWS Glue ジョブ用に、`--conf` という名前でキーを作成し、それに次の値を設定します。または、スクリプトで `SparkConf` を使用して、次の構成を設定することもできます。これらの設定は、Apache Spark が Iceberg テーブルを適切に処理する際に役立ちます。 ``` spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions --conf spark.sql.catalog.glue_catalog=org.apache.iceberg.spark.SparkCatalog --conf spark.sql.catalog.glue_catalog.warehouse=s3:/// --conf spark.sql.catalog.glue_catalog.catalog-impl=org.apache.iceberg.aws.glue.GlueCatalog --conf spark.sql.catalog.glue_catalog.io-impl=org.apache.iceberg.aws.s3.S3FileIO ``` Lake Formation に登録されている Iceberg テーブルを読み書きする場合は、AWS Glue 5.0 以降の [AWS Glue と AWS Lake Formation を併用したきめ細かなアクセスコントロール](security-lf-enable.md) のガイダンスに従ってください。AWS Glue 4.0 で、次の設定を追加して Lake Formation のサポートを有効にします。 ``` --conf spark.sql.catalog.glue_catalog.glue.lakeformation-enabled=true --conf spark.sql.catalog.glue_catalog.glue.id= ``` AWS Glue 3.0 で Iceberg 0.13.1 を使用する場合には、Amazon DynamoDB ロックマネージャーを使用して確実なアトミックトランザクションを行うために、次の追加事項を設定する必要があります。 AWSGlue 4.0 以降では、デフォルトで楽観的ロックが使用されます。詳細については、公式の Apache Iceberg ドキュメントで「[Iceberg と AWS の統合](https://iceberg.apache.org/docs/latest/aws/#dynamodb-lock-manager)」を参照してください。 ``` --conf spark.sql.catalog.glue_catalog.lock-impl=org.apache.iceberg.aws.glue.DynamoLockManager --conf spark.sql.catalog.glue_catalog.lock.table= ``` **別バージョンの Iceberg の使用** AWS Glue でサポートされないバージョンの Iceberg を使用するには、`--extra-jars` ジョブパラメータを使用して独自の Iceberg JAR ファイルを指定します。`--datalake-formats` パラメータの値として、`iceberg` を含めないようにしてください。AWS Glue 5.0 以降を使用する場合、`--user-jars-first true` ジョブパラメータを設定する必要があります。 **Iceberg テーブルの暗号化を有効にする** **注記** Iceberg テーブルにはサーバー側の暗号化を有効にする独自のメカニズムがあります。AWS Glue のセキュリティ設定に加えて、これらの設定を有効にする必要があります。 Iceberg テーブルでサーバー側の暗号化を有効にするには、「[Iceberg ドキュメント](https://iceberg.apache.org/docs/latest/aws/#s3-server-side-encryption)」のガイダンスを確認してください。 **Iceberg クロスリージョンに Spark 設定を追加する** AWS Glue Data Catalog および AWS Lake Formation を使用して Iceberg クロスリージョンテーブルアクセスの Spark 設定を追加するには、以下の手順に従います。 1. [マルチリージョンアクセスポイント](https://docs.aws.amazon.com/AmazonS3/latest/userguide/multi-region-access-point-create-examples.html)を作成します。 1. 以下の Spark パラメータを設定します。 ``` ----- --conf spark.sql.catalog.my_catalog.s3.use-arn-region-enabled=true \ --conf spark.sql.catalog.{CATALOG}.s3.access-points.bucket1", "arn:aws:s3:::accesspoint/.mrap \ --conf spark.sql.catalog.{CATALOG}.s3.access-points.bucket2", "arn:aws:s3:::accesspoint/.mrap ----- ``` ## 例: Amazon S3 に Iceberg テーブルを書き込み、そのテーブルを AWS Glue データカタログに登録する このスクリプト例は、Amazon S3 に Iceberg テーブルを書き込む方法を示しています。この例では、[Iceberg と AWS の統合](https://iceberg.apache.org/docs/latest/aws/)を使用して、テーブルを AWS Glue データカタログに登録しています。 ------ #### [ Python ] ``` # Example: Create an Iceberg table from a DataFrame # and register the table to Glue Data Catalog dataFrame.createOrReplaceTempView("tmp_") query = f""" CREATE TABLE glue_catalog.. USING iceberg TBLPROPERTIES ("format-version"="2") AS SELECT * FROM tmp_ """ spark.sql(query) ``` ------ #### [ Scala ] ``` // Example: Example: Create an Iceberg table from a DataFrame // and register the table to Glue Data Catalog dataFrame.createOrReplaceTempView("tmp_") val query = """CREATE TABLE glue_catalog.. USING iceberg TBLPROPERTIES ("format-version"="2") AS SELECT * FROM tmp_ """ spark.sql(query) ``` ------ または、Spark メソッドを使用して Amazon S3 とデータカタログに Iceberg テーブルを書き込むこともできます。 前提条件: Iceberg ライブラリが使用するカタログを用意する必要があります。AWS Glue データカタログを使う場合、AWS Glue を使えば簡単です。AWS Glue データカタログは、`glue_catalog` として Spark ライブラリで使用できるように事前に設定されています。データカタログテーブルは、*atabaseName* と*tableName* で識別されます。AWS Glue データカタログの詳細については、「[AWS Glue でのデータ検出とカタログ化](catalog-and-crawler.md)」を参照してください AWS Glue データカタログを使用していない場合は、Spark API を使用してカタログをプロビジョニングする必要があります。詳細については、Spark ドキュメントの「[Spark の設定](https://iceberg.apache.org/docs/latest/spark-configuration/)」を参照してください。 この例では、Spark を使用して Amazon S3 と データカタログに Iceberg テーブルを書き込みます。 ------ #### [ Python ] ``` # Example: Write an Iceberg table to S3 on the Glue Data Catalog # Create (equivalent to CREATE TABLE AS SELECT) dataFrame.writeTo("glue_catalog.databaseName.tableName") \ .tableProperty("format-version", "2") \ .create() # Append (equivalent to INSERT INTO) dataFrame.writeTo("glue_catalog.databaseName.tableName") \ .tableProperty("format-version", "2") \ .append() ``` ------ #### [ Scala ] ``` // Example: Write an Iceberg table to S3 on the Glue Data Catalog // Create (equivalent to CREATE TABLE AS SELECT) dataFrame.writeTo("glue_catalog.databaseName.tableName") .tableProperty("format-version", "2") .create() // Append (equivalent to INSERT INTO) dataFrame.writeTo("glue_catalog.databaseName.tableName") .tableProperty("format-version", "2") .append() ``` ------ ## 例: AWS Glue データカタログを使用した Amazon S3 からの Iceberg テーブルの読み込み この例では、「[例: Amazon S3 に Iceberg テーブルを書き込み、そのテーブルを AWS Glue データカタログに登録する](#aws-glue-programming-etl-format-iceberg-write)」で作成した Iceberg テーブルを読み取っています。 ------ #### [ Python ] この例では、`GlueContext.create\$1data\$1frame.from\$1catalog()` メソッドを使用します。 ``` # Example: Read an Iceberg table from Glue Data Catalog from awsglue.context import GlueContext from pyspark.context import SparkContext sc = SparkContext() glueContext = GlueContext(sc) df = glueContext.create_data_frame.from_catalog( database="", table_name="", additional_options=additional_options ) ``` ------ #### [ Scala ] この例では [getCatalogSource](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getCatalogSource) メソッドを使用します。 ``` // Example: Read an Iceberg table from Glue Data Catalog import com.amazonaws.services.glue.GlueContext import org.apacke.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val df = glueContext.getCatalogSource("", "", additionalOptions = additionalOptions) .getDataFrame() } } ``` ------ ## 例: AWS Glue データカタログを使用した Amazon S3 にある Iceberg テーブルへの `DataFrame` の挿入 この例では、「[例: Amazon S3 に Iceberg テーブルを書き込み、そのテーブルを AWS Glue データカタログに登録する](#aws-glue-programming-etl-format-iceberg-write)」で作成した Iceberg テーブルにデータを挿入します。 **注記** この例では、AWS Glue データカタログを Apache Spark Hive のメタストアとして使用するために、`--enable-glue-datacatalog` ジョブパラメータの設定が必要となります。詳細については[AWS Glue ジョブでジョブパラメータを使用する](aws-glue-programming-etl-glue-arguments.md)を参照してください。 ------ #### [ Python ] この例では、`GlueContext.write\$1data\$1frame.from\$1catalog()` メソッドを使用します。 ``` # Example: Insert into an Iceberg table from Glue Data Catalog from awsglue.context import GlueContext from pyspark.context import SparkContext sc = SparkContext() glueContext = GlueContext(sc) glueContext.write_data_frame.from_catalog( frame=dataFrame, database="", table_name="", additional_options=additional_options ) ``` ------ #### [ Scala ] この例では [getCatalogSink](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getCatalogSink) メソッドを使用します。 ``` // Example: Insert into an Iceberg table from Glue Data Catalog import com.amazonaws.services.glue.GlueContext import org.apacke.spark.SparkContext object GlueApp { def main(sysArgs: Array[String]): Unit = { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) glueContext.getCatalogSink("", "", additionalOptions = additionalOptions) .writeDataFrame(dataFrame, glueContext) } } ``` ------ ## 例: Spark を使用した Iceberg テーブルの Amazon S3 からの読み取り 前提条件: Iceberg ライブラリが使用するカタログを用意する必要があります。AWS Glue データカタログを使う場合、AWS Glue を使えば簡単です。AWS Glue データカタログは、`glue_catalog` として Spark ライブラリで使用できるように事前に設定されています。データカタログテーブルは、*atabaseName* と*tableName* で識別されます。AWS Glue データカタログの詳細については、「[AWS Glue でのデータ検出とカタログ化](catalog-and-crawler.md)」を参照してください AWS Glue データカタログを使用していない場合は、Spark API を使用してカタログをプロビジョニングする必要があります。詳細については、Spark ドキュメントの「[Spark の設定](https://iceberg.apache.org/docs/latest/spark-configuration/)」を参照してください。 この例では、Spark を使用してデータカタログから Amazon S3 の Iceberg テーブルを読み取ります。 ------ #### [ Python ] ``` # Example: Read an Iceberg table on S3 as a DataFrame from the Glue Data Catalog dataFrame = spark.read.format("iceberg").load("glue_catalog.databaseName.tableName") ``` ------ #### [ Scala ] ``` // Example: Read an Iceberg table on S3 as a DataFrame from the Glue Data Catalog val dataFrame = spark.read.format("iceberg").load("glue_catalog.databaseName.tableName") ``` ------ ## 例: Lake Formation の許可のコントロールを使用した Iceberg テーブルの読み取りおよび書き込み この例では、Lake Formation の許可のコントロールを使用して Iceberg テーブルの読み取りと書き込みを行います。 **注記** この例は、AWS Glue 4.0 でのみ動作します。AWS Glue 5.0 以降では、「[AWS Glue と AWS Lake Formation を併用したきめ細かなアクセスコントロール](security-lf-enable.md)」のガイダンスに従ってください。 1. Iceberg テーブルを作成して Lake Formation に登録します: 1. Lake Formation の許可のコントロールを有効にするには、まずテーブルの Amazon S3 パスを Lake Formation に登録する必要があります。詳細については、「[Registering an Amazon S3 location](https://docs.aws.amazon.com/lake-formation/latest/dg/register-location.html)」を参照してください。Lake Formation コンソールから、または AWS CLI を使用して登録できます。 ``` aws lakeformation register-resource --resource-arn arn:aws:s3:::/ --use-service-linked-role --region ``` Amazon S3 の場所が登録されると、その場所 (またはその子である場所) をポイントするすべての AWS Glue テーブルが、`GetTable` 呼び出しで `IsRegisteredWithLakeFormation` パラメータの値を true として返します。 1. Spark SQL を介して登録されたパスをポイントする Iceberg テーブルを作成します。 **注記** 次に Python の例を示します。 ``` dataFrame.createOrReplaceTempView("tmp_") query = f""" CREATE TABLE glue_catalog.. USING iceberg AS SELECT * FROM tmp_ """ spark.sql(query) ``` AWS Glue `CreateTable` API を通じてテーブルを手動で作成することもできます。詳細については、「[Apache Iceberg テーブルの作成](https://docs.aws.amazon.com/lake-formation/latest/dg/creating-iceberg-tables.html)」を参照してください。 **注記** `UpdateTable` API は現在、 オペレーションへの入力として Iceberg テーブル形式をサポートしていません。 1. ジョブ IAM ロールに Lake Formation の許可を付与します。Lake Formation コンソールから、または AWS CLI を使用して許可を付与できます。詳細については、次を参照してください: https://docs.aws.amazon.com/lake-formation/latest/dg/granting-table-permissions.html 1. Lake Formation に登録されている Iceberg テーブルを読み取ります。このコードは、未登録の Iceberg テーブルを読み取る場合と同じです。読み取りを成功させるには、AWS Glue ジョブの IAM ロールに SELECT 許可が必要であることに留意してください。 ``` # Example: Read an Iceberg table from the AWS Glue Data Catalog from awsglue.context import GlueContextfrom pyspark.context import SparkContext sc = SparkContext() glueContext = GlueContext(sc) df = glueContext.create_data_frame.from_catalog( database="", table_name="", additional_options=additional_options ) ``` 1. Lake Formation に登録されている Iceberg テーブルに書き込みます。このコードは、未登録の Iceberg テーブルに書き込む場合と同じです。書き込みを成功させるには、AWS Glue ジョブの IAM ロールに SUPER 許可が必要であることに留意してください。 ``` glueContext.write_data_frame.from_catalog( frame=dataFrame, database="", table_name="", additional_options=additional_options ) ``` ## 共有設定リファレンス 形式タイプには次の `format_options` 値を使用できます。 + `attachFilename` — 列名として使用する適切な形式の文字列。このオプションを指定すると、レコードのソースファイルの名前がレコードに追加されます。パラメータ値は列名として使用されます。 + `attachTimestamp` — 列名として使用する適切な形式の文字列。このオプションを指定すると、レコードのソースファイルの変更時刻がレコードに追加されます。パラメータ値は列名として使用されます。 # Spark SQL ジョブ用の AWS Glue Data Catalog のサポート AWS Glue の Data Catalog は、Apache Hive メタストア互換のカタログです。Data Catalog を外部の Apache Hive メタストアとして使用するように、ジョブと開発エンドポイント AWS Glueを設定できます。その後、Data Catalog に格納されたテーブルに対して Apache Spark SQL クエリを直接実行することができます。AWS Glue ダイナミックフレームは、デフォルトで Data Catalogと 統合されています。また、この機能により Spark SQL ジョブは、Data Catalog を外部の Hive メタストアとして使用できるようになります。 この機能には、AWS Glue API エンドポイントへのネットワークアクセスが必要です。ネットワークアクセスを提供する場合、プライベートサブネットに接続がある AWS Glue ジョブでは VPC エンドポイントまたは NAT ゲートウェイを構成する必要があります。VPCエンドポイントの設定については、「[データストアへのネットワークアクセスを設定する](start-connecting.md)」を参照してください。NAT ゲートウェイを作成するには、*Amazon VPC ユーザーガイド*の「[NAT ゲートウェイ](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)」を参照してください。 ジョブ引数と開発エンドポイント引数にそれぞれ `"--enable-glue-datacatalog": ""` 引数を追加することで、AWS Glue ジョブと開発エンドポイントを設定できます。この引数を渡すことで、Spark が外部 Hive メタストアとして Data Catalog にアクセスできるようにする、特定の設定が構成されます。同時に、`SparkSession` オブジェクトにある AWS Glue ジョブまたは開発エンドポイント内で作成された [Hive のサポートを有効化](https://spark.apache.org/docs/latest/api/java/org/apache/spark/sql/SparkSession.Builder.html#enableHiveSupport--)します。 データ カタログへのアクセスを有効にするには、コンソールの［**ジョブの追加**］または［**エンドポイントの追加**］ページの**カタログオプション** グループで［**Hive メタストアとして AWS Glue データ カタログを使用**］のチェックボックスをオンにします。ジョブまたは開発エンドポイントに使用される IAM ロールには `glue:CreateDatabase` アクセス許可が必要です。存在しない場合、「`default`」というデータベースが Data Catalog に作成されます。 Spark SQL ジョブでこの機能の使用方法の例を見てみましょう。次の例では、`s3://awsglue-datasets/examples/us-legislators` にある米国国会議員のデータセットをクロールしたと想定しています。 AWS Glue Data Catalog で定義されたテーブルからデータをシリアル化/逆シリアル化するには、Spark ジョブのクラスパスにある AWS Glue Data Catalog で定義された形式の [Hive SerDe](https://cwiki.apache.org/confluence/display/Hive/SerDe) クラスが、Spark SQL に必要です。 特定の一般的なフォーマットの SerDes は AWS Glue によって配布されています。以下はこれらへの Amazon S3 リンクです。 + [JSON](https://s3.us-west-2.amazonaws.com/crawler-public/json/serde/json-serde.jar) + [XML](https://s3.us-west-2.amazonaws.com/crawler-public/xml/serde/hivexmlserde-1.0.5.3.jar) + [Grok](https://s3.us-west-2.amazonaws.com/crawler-public/grok/serde/AWSGlueHiveGrokSerDe-1.0-super.jar) JSON SerDe を[追加の JAR として開発エンドポイント](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-dev-endpoint.html#aws-glue-api-dev-endpoint-DevEndpointCustomLibraries)に追加します。ジョブでは、引数フィールドで `--extra-jars` 引数を使用して SerDe を追加できます。詳細については、 を参照してください。[AWS Glue ジョブでジョブパラメータを使用する](aws-glue-programming-etl-glue-arguments.md) ここに、Spark SQL 用に Data Catalog を有効にして開発エンドポイントを作成するための入力 JSON の例を示します。 ``` { "EndpointName": "Name", "RoleArn": "role_ARN", "PublicKey": "public_key_contents", "NumberOfNodes": 2, "Arguments": { "--enable-glue-datacatalog": "" }, "ExtraJarsS3Path": "s3://crawler-public/json/serde/json-serde.jar" } ``` Spark SQL を使用して、米国国会議員のデータセットから作成されたテーブルにクエリを実行します。 ``` >>> spark.sql("use legislators") DataFrame[] >>> spark.sql("show tables").show() +-----------+------------------+-----------+ | database| tableName|isTemporary| +-----------+------------------+-----------+ |legislators| areas_json| false| |legislators| countries_json| false| |legislators| events_json| false| |legislators| memberships_json| false| |legislators|organizations_json| false| |legislators| persons_json| false| +-----------+------------------+-----------+ >>> spark.sql("describe memberships_json").show() +--------------------+---------+-----------------+ | col_name|data_type| comment| +--------------------+---------+-----------------+ | area_id| string|from deserializer| | on_behalf_of_id| string|from deserializer| | organization_id| string|from deserializer| | role| string|from deserializer| | person_id| string|from deserializer| |legislative_perio...| string|from deserializer| | start_date| string|from deserializer| | end_date| string|from deserializer| +--------------------+---------+-----------------+ ``` 形式の SerDe クラスがジョブのクラスパスで使用できない場合は、以下に示すようなエラーが表示されます。 ``` >>> spark.sql("describe memberships_json").show() Caused by: MetaException(message:java.lang.ClassNotFoundException Class org.openx.data.jsonserde.JsonSerDe not found) at org.apache.hadoop.hive.metastore.MetaStoreUtils.getDeserializer(MetaStoreUtils.java:399) at org.apache.hadoop.hive.ql.metadata.Table.getDeserializerFromMetaStore(Table.java:276) ... 64 more ``` `memberships` テーブルとは異なる `organization_id` だけを表示するには、次の SQL クエリを実行します。 ``` >>> spark.sql("select distinct organization_id from memberships_json").show() +--------------------+ | organization_id| +--------------------+ |d56acebe-8fdc-47b...| |8fa6c3d2-71dc-478...| +--------------------+ ``` 動的フレームで同じ手順を実行する必要がある場合は、以下を実行してください。 ``` >>> memberships = glueContext.create_dynamic_frame.from_catalog(database="legislators", table_name="memberships_json") >>> memberships.toDF().createOrReplaceTempView("memberships") >>> spark.sql("select distinct organization_id from memberships").show() +--------------------+ | organization_id| +--------------------+ |d56acebe-8fdc-47b...| |8fa6c3d2-71dc-478...| +--------------------+ ``` DynamicFrame は ETL オペレーション用に最適化されていますが、Spark SQL が Data Catalog に直接アクセスできるようにすることで、複雑な SQL ステートメントの実行や、既存のアプリケーションの移植が簡素化されます。 # ジョブのブックマークを使用する Spark 用の AWS Glue はジョブのブックマークを使用して処理済みのデータを追跡します。ジョブのブックマーク機能の概要とサポート内容については、「[ジョブのブックマークを使用した処理済みデータの追跡](monitor-continuations.md)」を参照してください。ブックマークを使用して AWS Glue ジョブをプログラミングすると、ビジュアルジョブでは実現できない柔軟性が得られます。 + JDBC から読み込む場合、AWS Glue スクリプトのブックマークキーとして使用する列を指定できます。 + 各メソッド呼び出しに適用する `transformation_ctx` を選択できます。 常に適切に設定されたパラメータでスクリプトの先頭に `job.init` を呼び出して、末尾に `job.commit` を呼び出します。これら 2 つの関数は、ブックマークサービスを初期化し、サービスの状態変化を更新します。ブックマークは呼び出さないと機能しません。 ## ブックマークキーの指定 JDBC ワークフローの場合、ブックマークはキーフィールドの値をブックマークされた値と比較することで、ジョブがどの行を読み込んたかを追跡します。これは Amazon S3 ワークフローには必要ありませんし、適用可能でもありません。ビジュアルエディタを使用せずに AWS Glue スクリプトを記述する場合、どの列をブックマークで追跡するかを指定できます。複数の列を指定することもできます。ユーザー定義のブックマークキーを指定する場合、値の順序にギャップがあってもかまいません。 **警告** ユーザー定義のブックマークキーを使用する場合、キーはそれぞれ厳密に一定間隔で増減する必要があります。複合キーに追加のフィールドを選択しても、「マイナーバージョン」や「リビジョン番号」などの概念のフィールドは、値がデータセット全体で再利用されるため、この基準を満たしません。 `jobBookmarkKeys` および `jobBookmarkKeysSortOrder` は以下の方法で指定できます。 + `create_dynamic_frame.from_catalog` — `additional_options` を使用する。 + `create_dynamic_frame.from_options` — `connection_options` を使用する。 ## 変換コンテキスト AWS Glue PySpark の動的フレームの多くのメソッドには、`transformation_ctx` というオプションのパラメータが含まれています。このパラメータは ETL 演算子インスタンスの一意の識別子です。`transformation_ctx` パラメータは指定された演算子に対するジョブのブックマーク内の状態情報を識別するために使用されます。具体的には、AWS Glue では `transformation_ctx` を使用してブックマーク状態に対するキーにインデックスを付けます。 **警告** `transformation_ctx` は、スクリプト内の特定のソースのブックマーク状態を検索するためのキーとして機能します。ブックマークを正しく機能させるためには、ソースと関連する `transformation_ctx` の一貫性を常に保つ必要があります。ソースプロパティを変更したり、`transformation_ctx` の名前を変更したりすると、前のブックマークが無効になり、タイムスタンプベースのフィルタリングで正しい結果が得られない場合があります。 ジョブのブックマークが正しく機能するように、ジョブのブックマークのパラメータを有効にし、`transformation_ctx` パラメータを設定します。`transformation_ctx` パラメータを渡さない場合、メソッドで使用されている動的フレームやテーブルに対してジョブのブックマークは有効になりません。例えば、ETL ジョブで 2 つの Amazon S3 ソースを読み取って結合する場合、ブックマークを有効にするメソッドに対してのみ `transformation_ctx` パラメータを渡すことができます。1 つのジョブについてジョブのブックマークをリセットした場合、`transformation_ctx` の使用には関係なく、このジョブに関連付けられているすべての変換がリセットされます。 `DynamicFrameReader` クラスの詳細については、「[DynamicFrameReader クラス](aws-glue-api-crawler-pyspark-extensions-dynamic-frame-reader.md)」を参照してください。PySpark 拡張の詳細については、「[AWS Glue PySpark 拡張機能リファレンス](aws-glue-programming-python-extensions.md)」を参照してください ## 例 **Example** Amazon S3 データソース用に生成されたスクリプトの例を次に示します。ジョブのブックマークを使用するために必要なスクリプトの部分は、斜体で表示されています。これらの要素の詳細については、[GlueContext クラス](aws-glue-api-crawler-pyspark-extensions-glue-context.md) API および [DynamicFrameWriter クラス](aws-glue-api-crawler-pyspark-extensions-dynamic-frame-writer.md) API を参照してください。 ``` # Sample Script import sys from awsglue.transforms import * from awsglue.utils import getResolvedOptions from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.job import Job args = getResolvedOptions(sys.argv, ['JOB_NAME']) sc = SparkContext() glueContext = GlueContext(sc) spark = glueContext.spark_session job = Job(glueContext) job.init(args['JOB_NAME'], args) datasource0 = glueContext.create_dynamic_frame.from_catalog( database = "database", table_name = "relatedqueries_csv", transformation_ctx = "datasource0" ) applymapping1 = ApplyMapping.apply( frame = datasource0, mappings = [("col0", "string", "name", "string"), ("col1", "string", "number", "string")], transformation_ctx = "applymapping1" ) datasink2 = glueContext.write_dynamic_frame.from_options( frame = applymapping1, connection_type = "s3", connection_options = {"path": "s3://input_path"}, format = "json", transformation_ctx = "datasink2" ) job.commit() ``` **Example** JDBC ソース用に生成されたスクリプトの例を以下に示します。ソーステーブルは、`empno` 列がプライマリキーである従業員テーブルです。デフォルトでは、ブックマークキーが指定されていない場合、ジョブはブックマークキーとしてシーケンシャルプライマリキーを使用しますが、`empno` は必ずしもシーケンシャルではなく、値にギャップがある可能性があるため、デフォルトのブックマークキーとして適切ではありません。したがって、スクリプトは `empno` を明示的にブックマークキーとして指定します。コードのその部分は、斜体で表示されます。 ``` import sys from awsglue.transforms import * from awsglue.utils import getResolvedOptions from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.job import Job args = getResolvedOptions(sys.argv, ['JOB_NAME']) sc = SparkContext() glueContext = GlueContext(sc) spark = glueContext.spark_session job = Job(glueContext) job.init(args['JOB_NAME'], args) datasource0 = glueContext.create_dynamic_frame.from_catalog( database = "hr", table_name = "emp", transformation_ctx = "datasource0", additional_options = {"jobBookmarkKeys":["empno"],"jobBookmarkKeysSortOrder":"asc"} ) applymapping1 = ApplyMapping.apply( frame = datasource0, mappings = [("ename", "string", "ename", "string"), ("hrly_rate", "decimal(38,0)", "hrly_rate", "decimal(38,0)"), ("comm", "decimal(7,2)", "comm", "decimal(7,2)"), ("hiredate", "timestamp", "hiredate", "timestamp"), ("empno", "decimal(5,0)", "empno", "decimal(5,0)"), ("mgr", "decimal(5,0)", "mgr", "decimal(5,0)"), ("photo", "string", "photo", "string"), ("job", "string", "job", "string"), ("deptno", "decimal(3,0)", "deptno", "decimal(3,0)"), ("ssn", "decimal(9,0)", "ssn", "decimal(9,0)"), ("sal", "decimal(7,2)", "sal", "decimal(7,2)")], transformation_ctx = "applymapping1" ) datasink2 = glueContext.write_dynamic_frame.from_options( frame = applymapping1, connection_type = "s3", connection_options = {"path": "s3://hr/employees"}, format = "csv", transformation_ctx = "datasink2" ) job.commit() ``` # AWS Glue Studio 外での機密データ検出の使用 AWS Glue Studio では機密データを検出することができますが、AWS Glue Studio 外でこの機密データ検出機能を使用することも可能です。 マネージド機密データタイプの全リストについては、「[Managed data types](https://docs.aws.amazon.com/glue/latest/dg/sensitive-data-managed-data-types.html)」を参照してください。 ## AWS マネージド PII タイプを使用した機密データの検出 AWS Glue は、AWS Glue ETL ジョブで 2 つの API を提供します。これらは、`detect()` および `classifyColumns()` です。 ``` detect(frame: DynamicFrame, entityTypesToDetect: Seq[String], outputColumnName: String = "DetectedEntities", detectionSensitivity: String = "LOW"): DynamicFrame detect(frame: DynamicFrame, detectionParameters: JsonOptions, outputColumnName: String = "DetectedEntities", detectionSensitivity: String = "LOW"): DynamicFrame classifyColumns(frame: DynamicFrame, entityTypesToDetect: Seq[String], sampleFraction: Double = 0.1, thresholdFraction: Double = 0.1, detectionSensitivity: String = "LOW") ``` AWS マネージド PII タイプとカスタムエンティティタイプを識別するには、`detect()` API を使用できます。検出結果が含まれる新しい列が自動的に作成されます。`classifyColumns()` API は、キーが列名で値が検出されたエンティティタイプのリストになっているマップを返します。`SampleFraction` は、PII エンティティをスキャンしているときにサンプリングするためのデータの割合を示し、`ThresholdFraction` は、列が PII データとして識別されるために満たされる必要があるデータの割合を示します。 ### 行レベルの検出 この例では、ジョブが `detect()` と `classifyColumns()` API を使用して以下のアクションを実行しています。 + Amazon S3 バケットからデータを読み込み、dynamicFrame に変換する + dynamicFrame 内にある「Email」と「Credit Card」のインスタンスを検出する + 元の値と、各行の検出結果が網羅された 1 つの列が含まれる dynamicFrame を返す + 返された dynamicFrame を別の Amazon S3 パスに書き込む ``` import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.MappingSpec import com.amazonaws.services.glue.errors.CallSite import com.amazonaws.services.glue.util.GlueArgParser import com.amazonaws.services.glue.util.Job import com.amazonaws.services.glue.util.JsonOptions import org.apache.spark.SparkContext import scala.collection.JavaConverters._ import com.amazonaws.services.glue.ml.EntityDetector object GlueApp { def main(sysArgs: Array[String]) { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) val frame= glueContext.getSourceWithFormat(formatOptions=JsonOptions("""{"quoteChar": "\"", "withHeader": true, "separator": ","}"""), connectionType="s3", format="csv", options=JsonOptions("""{"paths": ["s3://pathToSource"], "recurse": true}"""), transformationContext="AmazonS3_node1650160158526").getDynamicFrame() val frameWithDetectedPII = EntityDetector.detect(frame, Seq("EMAIL", "CREDIT_CARD")) glueContext.getSinkWithFormat(connectionType="s3", options=JsonOptions("""{"path": "s3://pathToOutput/", "partitionKeys": []}"""), transformationContext="someCtx", format="json").writeDynamicFrame(frameWithDetectedPII) Job.commit() } } ``` ### 詳細なアクションによる行レベルの検出 この例では、ジョブが `detect()` API を使用して次のアクションを実行しています。 + Amazon S3 バケットからデータを読み取り、dynamicFrame に変換する + dynamicFrame 内の「USA\$1PTIN」、「BANK\$1ACCOUNT]、「USA\$1SSN」、「USA\$1PASSPORT\$1NUMBER」、および「PHONE\$1NUMBER」の機密データタイプの検出 + 変更およびマスキングされた値と、各行の検出結果が網羅された 1 つの列が含まれる dynamicFrame を返す + 返された dynamicFrame を別の Amazon S3 パスに書き込む 上記の `detect()` API とは対照的に、これはエンティティタイプを検出するための詳細なアクションを使用します。詳細については、「[`detect()` を使用する検出パラメータ](#sensitive-data-detect-parameters-fine-grained-actions)」を参照してください。 ``` import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.MappingSpec import com.amazonaws.services.glue.errors.CallSite import com.amazonaws.services.glue.util.GlueArgParser import com.amazonaws.services.glue.util.Job import com.amazonaws.services.glue.util.JsonOptions import org.apache.spark.SparkContext import scala.collection.JavaConverters._ import com.amazonaws.services.glue.ml.EntityDetector object GlueApp { def main(sysArgs: Array[String]) { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) val frame = glueContext.getSourceWithFormat(formatOptions=JsonOptions("""{"quoteChar": "\"", "withHeader": true, "separator": ","}"""), connectionType="s3", format="csv", options=JsonOptions("""{"paths": ["s3://pathToSource"], "recurse": true}"""), transformationContext="AmazonS3_node_source").getDynamicFrame() val detectionParameters = JsonOptions( """ { "USA_DRIVING_LICENSE": [{ "action": "PARTIAL_REDACT", "sourceColumns": ["Driving License"], "actionOptions": { "matchPattern": "[0-9]", "redactChar": "*" } }], "BANK_ACCOUNT": [{ "action": "DETECT", "sourceColumns": ["*"] }], "USA_SSN": [{ "action": "SHA256_HASH", "sourceColumns": ["SSN"] }], "IP_ADDRESS": [{ "action": "REDACT", "sourceColumns": ["IP Address"], "actionOptions": {"redactText": "*****"} }], "PHONE_NUMBER": [{ "action": "PARTIAL_REDACT", "sourceColumns": ["Phone Number"], "actionOptions": { "numLeftCharsToExclude": 1, "numRightCharsToExclude": 0, "redactChar": "*" } }] } """ ) val frameWithDetectedPII = EntityDetector.detect(frame, detectionParameters, "DetectedEntities", "HIGH") glueContext.getSinkWithFormat(connectionType="s3", options=JsonOptions("""{"path": "s3://pathToOutput/", "partitionKeys": []}"""), transformationContext="AmazonS3_node_target", format="json").writeDynamicFrame(frameWithDetectedPII) Job.commit() } } ``` ### 列レベルの検出 この例では、ジョブが `classifyColumns()` API を使用して次のアクションを実行しています。 + Amazon S3 バケットからデータを読み取り、dynamicFrame に変換する + dynamicFrame 内にある「Email」と「Credit Card」のインスタンスを検出する + 列の 100% をサンプリングし、エンティティがセルの 10% にある場合に検出済みとしてマークするとともに、感度が [低] になるようにパラメータを設定します + キーが列名、値が検出されたエンティティタイプのリストであるマップを返します + 返された dynamicFrame を別の Amazon S3 パスに書き込む ``` import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.MappingSpec import com.amazonaws.services.glue.errors.CallSite import com.amazonaws.services.glue.util.GlueArgParser import com.amazonaws.services.glue.util.Job import com.amazonaws.services.glue.util.JsonOptions import org.apache.spark.SparkContext import scala.collection.JavaConverters._ import com.amazonaws.services.glue.DynamicFrame import com.amazonaws.services.glue.ml.EntityDetector object GlueApp { def main(sysArgs: Array[String]) { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) val frame = glueContext.getSourceWithFormat(formatOptions=JsonOptions("""{"quoteChar": "\"", "withHeader": true, "separator": ",", "optimizePerformance": false}"""), connectionType="s3", format="csv", options=JsonOptions("""{"paths": ["s3://pathToSource"], "recurse": true}"""), transformationContext="frame").getDynamicFrame() import glueContext.sparkSession.implicits._ val detectedDataFrame = EntityDetector.classifyColumns( frame, entityTypesToDetect = Seq("CREDIT_CARD", "PHONE_NUMBER"), sampleFraction = 1.0, thresholdFraction = 0.1, detectionSensitivity = "LOW" ) val detectedDF = (detectedDataFrame).toSeq.toDF("columnName", "entityTypes") val DetectSensitiveData_node = DynamicFrame(detectedDF, glueContext) glueContext.getSinkWithFormat(connectionType="s3", options=JsonOptions("""{"path": "s3://pathToOutput", "partitionKeys": []}"""), transformationContext="someCtx", format="json").writeDynamicFrame(DetectSensitiveData_node) Job.commit() } } ``` ## AWS CustomEntityType PII タイプを使用した機密データの検出 カスタムエンティティは AWS Studio を使用して定義できますが、AWS Studio 外でこの機能を使用するには、まずカスタムエンティティタイプを定義してから、定義されたカスタムエンティティタイプを `entityTypesToDetect` のリストに追加する必要があります。 データ内に特定の機密データタイプ (「Employee Id」など) がある場合は、`CreateCustomEntityType()` API を呼び出してカスタムエンティティを作成することができます。以下の例では、リクエストパラメータを使用して `CreateCustomEntityType()` API にカスタムエンティティタイプ「EMPLOYEE\$1ID」を定義します。 ``` { "name": "EMPLOYEE_ID", "regexString": "\d{4}-\d{3}", "contextWords": ["employee"] } ``` 次に、カスタムエンティティタイプ (EMPLOYEE\$1ID) を`EntityDetector()` API に追加することで、新しいカスタム機密データタイプを使用するようにジョブを変更します。 ``` import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.MappingSpec import com.amazonaws.services.glue.errors.CallSite import com.amazonaws.services.glue.util.GlueArgParser import com.amazonaws.services.glue.util.Job import com.amazonaws.services.glue.util.JsonOptions import org.apache.spark.SparkContext import scala.collection.JavaConverters._ import com.amazonaws.services.glue.ml.EntityDetector object GlueApp { def main(sysArgs: Array[String]) { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) val frame= glueContext.getSourceWithFormat(formatOptions=JsonOptions("""{"quoteChar": "\"", "withHeader": true, "separator": ","}"""), connectionType="s3", format="csv", options=JsonOptions("""{"paths": ["s3://pathToSource"], "recurse": true}"""), transformationContext="AmazonS3_node1650160158526").getDynamicFrame() val frameWithDetectedPII = EntityDetector.detect(frame, Seq("EMAIL", "CREDIT_CARD", "EMPLOYEE_ID")) glueContext.getSinkWithFormat(connectionType="s3", options=JsonOptions("""{"path": "s3://pathToOutput/", "partitionKeys": []}"""), transformationContext="someCtx", format="json").writeDynamicFrame(frameWithDetectedPII) Job.commit() } } ``` **注記** カスタム機密データタイプが既存マネージドエンティティタイプと同じ名前で定義されている場合は、カスタム機密データタイプが優先され、マネージドエンティティタイプのロジックが上書きされます。 ## `detect()` を使用する検出パラメータ このメソッドは、DynamicFrame 内のエンティティを検出するために使用されます。元の値を含む新しい DataFrame と、PII 検出メタデータを含む追加の列の outputColumnName を返します。この DynamicFrame が AWS Glue スクリプト内で返された後にカスタムマスキングを実行することも、詳細なアクション API を備えた detect() を代わりに使用することもできます。 ``` detect(frame: DynamicFrame, entityTypesToDetect: Seq[String], outputColumnName: String = "DetectedEntities", detectionSensitivity: String = "LOW"): DynamicFrame ``` パラメータ : + **frame** – (タイプ: `DynamicFrame`) 処理されるデータを含む入力 DynamicFrame。 + **entityTypesToDetect** – (タイプ: `[Seq[String]`) 検出するエンティティタイプのリスト。マネージドエンティティタイプまたはカスタムエンティティタイプのいずれかになります。 + **outputColumnName** – (タイプ: `String`、デフォルト:「DetectedEntities」) 検出されたエンティティが保存される列の名前。指定しない場合、デフォルトの列名は「DetectedEntities」となります。 + **detectionSensitivity** – (タイプ: `String`、オプション: [低] または [高]、デフォルト: [低]) 検出プロセスの感度を指定します。有効なオプションは [低] または [高] です。指定しない場合、デフォルトの感度は [低] に設定されます。 `outputColumnName` の設定: 検出されたエンティティが保存される列の名前。指定しない場合、デフォルトの列名は「DetectedEntities」となります。出力列の各行について、補足列には、次の key-value ペアを含む、検出されたエンティティメタデータに対する列名のマップが含まれます。 + **entityType** – 検出されたエンティティタイプ。 + **start** – 元のデータ内の検出されたエンティティの開始場所。 + **end** – 元のデータ内の検出されたエンティティの終了場所。 + **actionUsed** – 検出されたエンティティに対して実行されたアクション (例:「DETECT」、「REDACT」、「PARTIAL\$1REDACT」、「SHA256\$1HASH」)。 例: ``` { "DetectedEntities":{ "SSN Col":[ { "entityType":"USA_SSN", "actionUsed":"DETECT", "start":4, "end":15 } ], "Random Data col":[ { "entityType":"BANK_ACCOUNT", "actionUsed":"PARTIAL_REDACT", "start":4, "end":13 }, { "entityType":"IP_ADDRESS", "actionUsed":"REDACT", "start":4, "end":13 } ] } } ``` **詳細なアクションの `detect()` の検出パラメータ** このメソッドは、指定されたパラメータを使用して DynamicFrame 内のエンティティを検出するために使用されます。元の値がマスキングされた機密データに置き換えられた新しい DataFrame と、PII 検出メタデータを含む追加の列 `outputColumnName` が返されます。 ``` detect(frame: DynamicFrame, detectionParameters: JsonOptions, outputColumnName: String = "DetectedEntities", detectionSensitivity: String = "LOW"): DynamicFrame ``` パラメータ : + **frame** – (タイプ: `DynamicFrame`): 処理されるデータを含む入力 DynamicFrame。 + **detectionParameters** – (タイプ: `JsonOptions`): 検出プロセスのパラメータを指定する JSON オプション。 + **outputColumnName** – (タイプ: `String`、デフォルト:「DetectedEntities」): 検出されたエンティティが保存される列の名前。指定しない場合、デフォルトの列名は「DetectedEntities」となります。 + **detectionSensitivity** – (タイプ: `String`、オプション: [低] または [高]、デフォルト: [低]): 検出プロセスの感度を指定します。有効なオプションは [低] または [高] です。指定しない場合、デフォルトの感度は [低] に設定されます。 `detectionParameters` の設定 設定が含まれていない場合は、デフォルト値が使用されます。 + **action** – (タイプ: `String`、オプション:「DETECT」、「REDACT」、「PARTIAL\$1REDACT」、「SHA256\$1HASH」) エンティティに対して実行するアクションを指定します。必須。マスキングを実行するアクション (「DETECT」を除くすべて) は、列ごとに 1 つのアクションしか実行できないことに留意してください。これは、合体したエンティティをマスキングするための予防措置です。 + **sourceColumns** – (タイプ: `List[String]`、デフォルト: [“\$1”]) エンティティの検出を実行するソース列名のリスト。存在しない場合は、デフォルトで [“\$1”] に設定されます。無効な列名が使用された場合に `IllegalArgumentException` を発生させます。 + **sourceColumnsToExclude** – (タイプ: `List[String]`) エンティティの検出を実行するソース列名のリスト。`sourceColumns` または `sourceColumnsToExclude` のいずれかを使用します。無効な列名が使用された場合に `IllegalArgumentException` を発生させます。 + **actionOptions** – 指定されたアクションに基づく追加オプション: + 「DETECT」および「SHA256\$1HASH」の場合、いかなるオプションも使用できません。 + 「REDACT」の場合: + **redactText** – (タイプ: `String`、デフォルト:「\$1\$1\$1\$1\$1」) 検出されたエンティティを置き換えるテキスト。 + 「PARTIAL\$1REDACT」の場合: + **redactChar** – (タイプ: `String`、デフォルト:「\$1」) エンティティ内で検出された各文字を置き換える文字。 + **matchPattern** – (タイプ: `String`) 部分的なマスキングの正規表現パターン。numLeftCharsToExclude または `numRightCharsToExclude` と組み合わせることはできません。 + **numLeftCharsToExclude** – (タイプ: `String, integer`) 除外する左側の文字の数。matchPattern と組み合わせることはできませんが、`numRightCharsToExclude` と組み合わせて使用することはできます。 + **numRightCharsToExclude** – (タイプ: `String, integer`) 除外する右側の文字の数。matchPattern と組み合わせることはできませんが、`numRightCharsToExclude` と組み合わせて使用することはできます。 `outputColumnName` の設定 [outputColumnName の設定を参照してください](#sensitive-data-detect-parameters-fine-grained-actions) ## `classifyColumns()` の検出パラメータ このメソッドは、DynamicFrame 内のエンティティを検出するために使用されます。キーが列名、値が検出されたエンティティタイプのリストであるマップを返します。これが AWS Glue スクリプト内で返された後、カスタムマスキングを実行できます。 ``` classifyColumns(frame: DynamicFrame, entityTypesToDetect: Seq[String], sampleFraction: Double = 0.1, thresholdFraction: Double = 0.1, detectionSensitivity: String = "LOW") ``` パラメータ : + **frame** – (タイプ: `DynamicFrame`) 処理されるデータを含む入力 DynamicFrame。 + **entityTypesToDetect** – (タイプ: `Seq[String]`) 検出するエンティティタイプのリスト。マネージドエンティティタイプまたはカスタムエンティティタイプのいずれかになります。 + **sampleFraction** – (タイプ: `Double`、デフォルト: 10%) PII エンティティをスキャンする際にサンプリングするデータの割合。 + **thresholdFraction** – (タイプ: `Double`、デフォルト: 10%): 列が PII データとして識別されるために満たす必要があるデータの割合。 + **detectionSensitivity** – (タイプ: `String`、オプション: [低] または [高]、デフォルト: [低]) 検出プロセスの感度を指定します。有効なオプションは [低] または [高] です。指定しない場合、デフォルトの感度は [低] に設定されます。 # 管理対象の機密データタイプ **グローバルエンティティ** | データタイプ | Category | 説明 | | --- | --- | --- | | PERSON\$1NAME | Universal | その人物の名前 | | EMAIL | 個人 | E メールアドレス | | IP\$1ADDRESS | [コンピュータ] | IP アドレス | | MAC\$1ADDRESS | 個人 | MAC アドレス | **米国のデータタイプ** | データタイプ | 説明 | | --- | --- | | BANK\$1ACCOUNT | 銀行口座番号。国や地域に固有のものではありませんが、米国とカナダの口座形式のみが検出されます。 | | CREDIT\$1CARD | クレジットカード番号。 | | PHONE\$1NUMBER | 電話番号。国や地域に固有のものではありませんが、現時点では米国とカナダの電話番号のみが検出されます。 | | USA\$1ATIN | 内国歳入庁 (IRS、Internal Revenue Service) が発行する米国養子縁組納税者番号 (ATIN、Adoption Taxpayer Identification Number)。 | | USA\$1CPT\$1CODE | CPT コード (米国のみ)。 | | USA\$1DEA\$1NUMBER | DEA 番号 (米国のみ)。 | | USA\$1DRIVING\$1LICENSE | 運転免許証番号 (米国のみ)。 | | USA\$1HCPCS\$1CODE | HCPCS コード (米国のみ)。 | | USA\$1HEALTH\$1INSURANCE\$1CLAIM\$1NUMBER | 健康保険請求番号 (米国のみ)。 | | USA\$1ITIN | ITIN (米国人または法人の場合)。 | | USA\$1MEDICARE\$1BENEFICIARY\$1IDENTIFIER | メディケア受益者識別子 (米国のみ)。 | | USA\$1NATIONAL\$1DRUG\$1CODE | NDC コード (米国のみ)。 | | USA\$1NATIONAL\$1PROVIDER\$1IDENTIFIER | 米国医療従事者識別子番号 (米国のみ)。 | | USA\$1PASSPORT\$1NUMBER | パスポート番号 (米国人の場合)。 | | USA\$1PTIN | 内国歳入庁が発行する米国申告書作成者番号 (PTIN、Preparer Tax Identification Number)。 | | USA\$1SSN | 社会保障番号 (米国人の場合)。 | **アルゼンチンのデータタイプ** | データタイプ | 説明 | | --- | --- | | ARGENTINA\$1TAX\$1IDENTIFICATION\$1NUMBER | アルゼンチンの納税者番号。CUIT または CUIL とも呼ばれます。 | **オーストラリアのデータタイプ** | データタイプ | 説明 | | --- | --- | | AUSTRALIA\$1BUSINESS\$1NUMBER | オーストラリア事業者番号 (ABN、Australia Business Number)。オーストラリア事業者登記所 (ABR、Australian Business Register) が発行する固有の識別番号で、政府や地域社会が事業者を識別します。 | | AUSTRALIA\$1COMPANY\$1NUMBER | オーストラリア企業番号 (ACN、Australia Company Number)。オーストラリア証券投資委員会 (ASIC、Australian Securities and Investments Commission) が発行する固有の識別番号。 | | AUSTRALIA\$1DRIVING\$1LICENSE | オーストラリアの運転免許証番号。 | | AUSTRALIA\$1MEDICARE\$1NUMBER | オーストラリアの健康保険番号。オーストラリア健康保険委員会 (Australian Health Insurance Commission) が発行する個人識別番号。 | | AUSTRALIA\$1PASSPORT\$1NUMBER | オーストラリアのパスポート番号。 | | AUSTRALIA\$1TAX\$1FILE\$1NUMBER | オーストラリアのタックスファイルナンバー (TFN、Tax File Number)。オーストラリア税務局 (ATO、Australian Taxation Office) が納税者 (個人、会社など) に税務取引を行うために発行します。 | **オーストリアのデータタイプ** | データタイプ | 説明 | | --- | --- | | AUSTRIA\$1DRIVING\$1LICENSE | 運転免許証番号 (オーストリアのみ)。 | | AUSTRIA\$1PASSPORT\$1NUMBER | パスポート番号 (オーストリアのみ)。 | | AUSTRIA\$1SSN | 社会保障番号 (オーストリア人の場合)。 | | AUSTRIA\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (オーストリアのみ)。 | | AUSTRIA\$1VALUE\$1ADDED\$1TAX | 付加価値税 (オーストリアのみ)。 | **バルカン諸国のデータタイプ** | データタイプ | 説明 | | --- | --- | | BOSNIA\$1UNIQUE\$1MASTER\$1CITIZEN\$1NUMBER | ボスニア・ヘルツェゴビナ市民の固有マスター市民番号 (JMBG、Unique master citizen number)。 | | KOSOVO\$1UNIQUE\$1MASTER\$1CITIZEN\$1NUMBER | コソボの固有マスター市民番号 (JMBG)。 | | MACEDONIA\$1UNIQUE\$1MASTER\$1CITIZEN\$1NUMBER | マケドニアの固有マスター市民番号。 | | MONTENEGRO\$1UNIQUE\$1MASTER\$1CITIZEN\$1NUMBER | モンテネグロの固有マスター市民番号 (JMBG)。 | | SERBIA\$1UNIQUE\$1MASTER\$1CITIZEN\$1NUMBER | セルビアの固有マスター市民番号 (JMBG)。 | | SERBIA\$1VALUE\$1ADDED\$1TAX | 付加価値税 (セルビアのみ)。 | | VOJVODINA\$1UNIQUE\$1MASTER\$1CITIZEN\$1NUMBER | ヴォイヴォディナの固有マスター市民番号 (JMBG)。 | **ベルギーのデータタイプ** | データタイプ | 説明 | | --- | --- | | BELGIUM\$1DRIVING\$1LICENSE | 運転免許証番号 (ベルギーのみ)。 | | BELGIUM\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | ベルギー国民番号 (BNN、Belgian National Number)。 | | BELGIUM\$1PASSPORT\$1NUMBER | パスポート番号 (ベルギーのみ)。 | | BELGIUM\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (ベルギーのみ)。 | | BELGIUM\$1VALUE\$1ADDED\$1TAX | 付加価値税 (ベルギーのみ)。 | **ブラジルのデータタイプ** | データタイプ | 説明 | | --- | --- | | BRAZIL\$1BANK\$1ACCOUNT | 銀行口座番号 (ブラジルのみ)。 | | BRAZIL\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (ブラジルのみ)。 | | BRAZIL\$1NATIONAL\$1REGISTRY\$1OF\$1LEGAL\$1ENTITIES\$1NUMBER | 企業に発行される識別番号 (ブラジルのみ)。CNPJ とも呼ばれます。 | | BRAZIL\$1NATURAL\$1PERSON\$1REGISTRY\$1NUMBER | CPF とも呼ばれる自然人登録番号 (Natural Person Registry Number)。 | **ブルガリアのデータタイプ** | データタイプ | 説明 | | --- | --- | | BULGARIA\$1DRIVING\$1LICENSE | 運転免許証番号 (ブルガリアのみ)。 | | BULGARIA\$1UNIFORM\$1CIVIL\$1NUMBER | 国民識別番号として機能する統一市民番号 (EGN、Unified Civil Number)。 | | BULGARIA\$1VALUE\$1ADDED\$1TAX | 付加価値税 (ブルガリアのみ)。 | **カナダのデータタイプ** | データタイプ | 説明 | | --- | --- | | CANADA\$1DRIVING\$1LICENSE | 運転免許証番号 (カナダのみ)。 | | CANADA\$1GOVERNMENT\$1IDENTIFICATION\$1CARD\$1NUMBER | 国民識別番号 (カナダのみ)。 | | CANADA\$1PASSPORT\$1NUMBER | パスポート番号 (カナダのみ)。 | | CANADA\$1PERMANENT\$1RESIDENCE\$1NUMBER | 永住者番号 (PR カード番号)。 | | CANADA\$1PERSONAL\$1HEALTH\$1NUMBER | ヘルスケアの固有識別番号 (PHN 番号)。 | | CANADA\$1SOCIAL\$1INSURANCE\$1NUMBER | カナダの社会保険番号 (SIN)。 | **チリのデータタイプ** | データタイプ | 説明 | | --- | --- | | CHILE\$1DRIVING\$1LICENSE | 運転免許証番号 (チリのみ)。 | | CHILE\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | チリの国民識別番号。RUT または RUN とも呼ばれます。 | **中国、香港、マカオ、台湾のデータタイプ** | データタイプ | 説明 | | --- | --- | | CHINA\$1IDENTIFICATION | 中国の識別子。 | | CHINA\$1LICENSE\$1PLATE\$1NUMBER | 運転免許証番号 (中国のみ)。 | | CHINA\$1MAINLAND\$1TRAVEL\$1PERMIT\$1ID\$1HONG\$1KONG\$1MACAU | 香港とマカオの居住者向けの本土旅行許可証。 | | CHINA\$1MAINLAND\$1TRAVEL\$1PERMIT\$1ID\$1TAIWAN | 中華人民共和国 (PRC) 政府が発行する台湾居住者向けの本土旅行許可証。 | | CHINA\$1PASSPORT\$1NUMBER | パスポート番号 (中国のみ)。 | | CHINA\$1PHONE\$1NUMBER | 電話番号 (中国のみ)。 | | HONG\$1KONG\$1IDENTITY\$1CARD | 香港入国管理局が発行する公式の身分証明書。 | | MACAU\$1RESIDENT\$1IDENTITY\$1CARD | マカオ居住者 ID カード (BIR) は、マカオの ID サービス局 (Identification Services Bureau) が発行する公式の ID カードです。 | | TAIWAN\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (台湾のみ)。 | | TAIWAN\$1PASSPORT\$1NUMBER | パスポート番号 (台湾のみ)。 | **コロンビアのデータタイプ** | データタイプ | 説明 | | --- | --- | | COLOMBIA\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 出生時にコロンビア人に割り当てられる固有の識別番号。 | | COLOMBIA\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (コロンビアのみ)。 | **クロアチアのデータタイプ** | データタイプ | 説明 | | --- | --- | | CROATIA\$1DRIVING\$1LICENSE | 運転免許証番号 (クロアチアのみ)。 | | CROATIA\$1IDENTITY\$1NUMBER | 国民識別番号 (クロアチアのみ)。 | | CROATIA\$1PASSPORT\$1NUMBER | パスポート番号 (クロアチアのみ)。 | | CROATIA\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別番号 (OIB)。 | **キプロスのデータタイプ** | データタイプ | 説明 | | --- | --- | | CYPRUS\$1DRIVING\$1LICENSE | 運転免許証番号 (キプロスのみ)。 | | CYPRUS\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | キプロスの身分証明書。 | | CYPRUS\$1PASSPORT\$1NUMBER | パスポート番号 (キプロスのみ)。 | | CYPRUS\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (キプロスのみ)。 | | CYPRUS\$1VALUE\$1ADDED\$1TAX | 付加価値税 (キプロスのみ)。 | **チェコのデータタイプ** | データタイプ | 説明 | | --- | --- | | CZECHIA\$1DRIVING\$1LICENSE | 運転免許証番号 (チェコのみ)。 | | CZECHIA\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別番号 (チェコのみ)。 | | CZECHIA\$1VALUE\$1ADDED\$1TAX | 付加価値税 (チェコのみ)。 | **デンマークのデータタイプ** | データタイプ | 説明 | | --- | --- | | DENMARK\$1DRIVING\$1LICENSE | 運転免許証番号 (デンマークのみ)。 | | DENMARK\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別番号 (デンマークのみ)。 | | DENMARK\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (デンマークのみ)。 | | DENMARK\$1VALUE\$1ADDED\$1TAX | 付加価値税 (デンマークのみ)。 | **エストニアのデータタイプ** | データタイプ | 説明 | | --- | --- | | ESTONIA\$1DRIVING\$1LICENSE | 運転免許証番号 (エストニアのみ)。 | | ESTONIA\$1PASSPORT\$1NUMBER | パスポート番号 (エストニアのみ)。 | | ESTONIA\$1PERSONAL\$1IDENTIFICATION\$1CODE | 個人識別番号 (エストニアのみ)。 | | ESTONIA\$1VALUE\$1ADDED\$1TAX | 付加価値税 (エストニアのみ)。 | **フィンランドのデータタイプ** | データタイプ | 説明 | | --- | --- | | FINLAND\$1DRIVING\$1LICENSE | 運転免許証番号 (フィンランドのみ)。 | | FINLAND\$1HEALTH\$1INSURANCE\$1NUMBER | 健康保険番号 (フィンランドのみ)。 | | FINLAND\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (フィンランドのみ)。 | | FINLAND\$1PASSPORT\$1NUMBER | パスポート番号 (フィンランドのみ)。 | | FINLAND\$1VALUE\$1ADDED\$1TAX | 付加価値税 (フィンランドのみ)。 | **フランスのデータタイプ** | データタイプ | 説明 | | --- | --- | | FRANCE\$1BANK\$1ACCOUNT | 銀行口座番号 (フランスのみ)。 | | FRANCE\$1DRIVING\$1LICENSE | 運転免許証番号 (フランスのみ)。 | | FRANCE\$1HEALTH\$1INSURANCE\$1NUMBER | フランスの健康保険番号。 | | FRANCE\$1INSEE\$1CODE | フランスの社会保障 (SSN または NIR) 番号。 | | FRANCE\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | フランス国民識別番号 (CNI)。 | | FRANCE\$1PASSPORT\$1NUMBER | パスポート番号 (フランスのみ)。 | | FRANCE\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (フランスのみ)。 | | FRANCE\$1VALUE\$1ADDED\$1TAX | 付加価値税 (フランスのみ)。 | **ドイツのデータタイプ** | データタイプ | 説明 | | --- | --- | | GERMANY\$1BANK\$1ACCOUNT | 銀行口座番号 (ドイツのみ)。 | | GERMANY\$1DRIVING\$1LICENSE | 運転免許証番号 (ドイツのみ)。 | | GERMANY\$1PASSPORT\$1NUMBER | パスポート番号 (ドイツのみ)。 | | GERMANY\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別番号 (ドイツのみ)。 | | GERMANY\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (ドイツのみ)。 | | GERMANY\$1VALUE\$1ADDED\$1TAX | 付加価値税 (ドイツのみ)。 | **ギリシャのデータタイプ** | データタイプ | 説明 | | --- | --- | | GREECE\$1DRIVING\$1LICENSE | 運転免許証番号 (ギリシャのみ)。 | | GREECE\$1PASSPORT\$1NUMBER | パスポート番号 (ギリシャのみ)。 | | GREECE\$1SSN | 社会保障番号 (ギリシャ人の場合)。 | | GREECE\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (ギリシャのみ)。 | | GREECE\$1VALUE\$1ADDED\$1TAX | 付加価値税 (ギリシャのみ)。 | **ハンガリーのデータタイプ** | データタイプ | 説明 | | --- | --- | | HUNGARY\$1DRIVING\$1LICENSE | 運転免許証番号 (ハンガリーのみ)。 | | HUNGARY\$1PASSPORT\$1NUMBER | パスポート番号 (ハンガリーのみ)。 | | HUNGARY\$1SSN | 社会保障番号 (ハンガリー人の場合)。 | | HUNGARY\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (ハンガリーのみ)。 | | HUNGARY\$1VALUE\$1ADDED\$1TAX | 付加価値税 (ハンガリーのみ)。 | **アイスランドのデータタイプ** | データタイプ | 説明 | | --- | --- | | ICELAND\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (アイスランドのみ)。 | | ICELAND\$1PASSPORT\$1NUMBER | パスポート番号 (アイスランドのみ)。 | | ICELAND\$1VALUE\$1ADDED\$1TAX | 付加価値税 (アイスランドのみ)。 | **インドのデータタイプ** | データタイプ | 説明 | | --- | --- | | INDIA\$1AADHAAR\$1NUMBER | インドの固有 ID 局 (Unique Identification Authority) が発行する Aadhaar 識別番号。 | | INDIA\$1PERMANENT\$1ACCOUNT\$1NUMBER | インドの納税者番号 (PAN、Permanent Account Number)。 | **インドネシアのデータタイプ** | データタイプ | 説明 | | --- | --- | | INDONESIA\$1IDENTITY\$1CARD\$1NUMBER | 国民識別番号 (インドネシアのみ)。 | **アイルランドのデータタイプ** | データタイプ | 説明 | | --- | --- | | IRELAND\$1DRIVING\$1LICENSE | 運転免許証番号 (アイルランドのみ)。 | | IRELAND\$1PASSPORT\$1NUMBER | パスポート番号 (アイルランドのみ)。 | | IRELAND\$1PERSONAL\$1PUBLIC\$1SERVICE\$1NUMBER | アイルランド個人公共サービス (PPS、Personal Public Service) 番号。 | | IRELAND\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (アイルランドのみ)。 | | IRELAND\$1VALUE\$1ADDED\$1TAX | 付加価値税 (アイルランドのみ)。 | **イスラエルのデータタイプ** | データタイプ | 説明 | | --- | --- | | ISRAEL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (イスラエルのみ)。 | **イタリアのデータタイプ** | データタイプ | 説明 | | --- | --- | | ITALY\$1BANK\$1ACCOUNT | 銀行口座番号 (イタリアのみ)。 | | ITALY\$1DRIVING\$1LICENSE | 運転免許証番号 (イタリアのみ)。 | | ITALY\$1FISCAL\$1CODE | 識別番号。Italian Codice Fiscale (イタリアの納税者コード) としても知られています。 | | ITALY\$1PASSPORT\$1NUMBER | パスポート番号 (イタリアのみ)。 | | ITALY\$1VALUE\$1ADDED\$1TAX | 付加価値税 (イタリアのみ)。 | **日本のデータタイプ** | データタイプ | 説明 | | --- | --- | | JAPAN\$1BANK\$1ACCOUNT | 日本の銀行口座。 | | JAPAN\$1DRIVING\$1LICENSE | 日本の運転免許証番号。 | | JAPAN\$1MY\$1NUMBER | 国税行政、年金行政、災害対応に使用される日本の国民または法人のための固有の識別子 | | JAPAN\$1PASSPORT\$1NUMBER | 日本のパスポート番号。 | **韓国のデータタイプ** | データタイプ | 説明 | | --- | --- | | KOREA\$1PASSPORT\$1NUMBER | パスポート番号 (韓国のみ)。 | | KOREA\$1RESIDENCE\$1REGISTRATION\$1NUMBER\$1FOR\$1CITIZENS | 居住者の韓国居住登録者番号。 | | KOREA\$1RESIDENCE\$1REGISTRATION\$1NUMBER\$1FOR\$1FOREIGNERS | 外国人の韓国居住登録者番号。 | **ラトビアのデータタイプ** | データタイプ | 説明 | | --- | --- | | LATVIA\$1DRIVING\$1LICENSE | 運転免許証番号 (ラトビアのみ)。 | | LATVIA\$1PASSPORT\$1NUMBER | パスポート番号 (ラトビアのみ)。 | | LATVIA\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別番号 (ラトビアのみ)。 | | LATVIA\$1VALUE\$1ADDED\$1TAX | 付加価値税 (ラトビアのみ)。 | **リヒテンシュタインのデータタイプ** | データタイプ | 説明 | | --- | --- | | LIECHTENSTEIN\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (リヒテンシュタインのみ)。 | | LIECHTENSTEIN\$1PASSPORT\$1NUMBER | パスポート番号 (リヒテンシュタインのみ)。 | | LIECHTENSTEIN\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (リヒテンシュタインのみ)。 | **リトアニアのデータタイプ** | データタイプ | 説明 | | --- | --- | | LITHUANIA\$1DRIVING\$1LICENSE | 運転免許証番号 (リトアニアのみ)。 | | LITHUANIA\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別番号 (リトアニアのみ)。 | | LITHUANIA\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (リトアニアのみ)。 | | LITHUANIA\$1VALUE\$1ADDED\$1TAX | 付加価値税 (リトアニアのみ)。 | **ルクセンブルクのデータタイプ** | データタイプ | 説明 | | --- | --- | | LUXEMBOURG\$1DRIVING\$1LICENSE | 運転免許証番号 (ルクセンブルクのみ)。 | | LUXEMBOURG\$1NATIONAL\$1INDIVIDUAL\$1NUMBER | 国民識別番号 (ルクセンブルクのみ)。 | | LUXEMBOURG\$1PASSPORT\$1NUMBER | パスポート番号 (ルクセンブルクのみ)。 | | LUXEMBOURG\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (ルクセンブルクのみ)。 | | LUXEMBOURG\$1VALUE\$1ADDED\$1TAX | 付加価値税 (ルクセンブルクのみ)。 | **マレーシアのデータタイプ** | データタイプ | 説明 | | --- | --- | | MALAYSIA\$1MYKAD\$1NUMBER | 国民識別番号 (マレーシアのみ)。 | | MALAYSIA\$1PASSPORT\$1NUMBER | パスポート番号 (マレーシアのみ)。 | **マルタのデータタイプ** | データタイプ | 説明 | | --- | --- | | MALTA\$1DRIVING\$1LICENSE | 運転免許証番号 (マルタのみ)。 | | MALTA\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (マルタのみ)。 | | MALTA\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (マルタのみ)。 | | MALTA\$1VALUE\$1ADDED\$1TAX | 付加価値税 (マルタのみ)。 | **メキシコのデータタイプ** | データタイプ | 説明 | | --- | --- | | MEXICO\$1CLABE\$1NUMBER | メキシコ CLABE (Clave Bancaria Estandarizada) 銀行番号。 | | MEXICO\$1DRIVING\$1LICENSE | 運転免許証番号 (メキシコのみ)。 | | MEXICO\$1PASSPORT\$1NUMBER | パスポート番号 (メキシコのみ)。 | | MEXICO\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (メキシコのみ)。 | | MEXICO\$1UNIQUE\$1POPULATION\$1REGISTRY\$1CODE | メキシコの Clave Única de Registro de Población (CURP) 固有識別コード。 | **オランダのデータタイプ** | データタイプ | 説明 | | --- | --- | | NETHERLANDS\$1CITIZEN\$1SERVICE\$1NUMBER | オランダ市民番号 (BSN、burgerservicenummer)。 | | NETHERLANDS\$1DRIVING\$1LICENSE | 運転免許証番号 (オランダのみ)。 | | NETHERLANDS\$1PASSPORT\$1NUMBER | パスポート番号 (オランダのみ)。 | | NETHERLANDS\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (オランダのみ)。 | | NETHERLANDS\$1VALUE\$1ADDED\$1TAX | 付加価値税 (オランダのみ)。 | | NETHERLANDS\$1BANK\$1ACCOUNT | 銀行口座番号 (オランダのみ)。 | **ニュージーランドのデータタイプ** | データタイプ | 説明 | | --- | --- | | NEW\$1ZEALAND\$1DRIVING\$1LICENSE | 運転免許証番号 (ニュージーランドのみ)。 | | NEW\$1ZEALAND\$1NATIONAL\$1HEALTH\$1INDEX\$1NUMBER | ニュージーランドの国民健康指標番号 (National Health Index Number)。 | | NEW\$1ZEALAND\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号。内国歳入番号 (Inland Revenue Number) とも呼ばれます (ニュージーランドのみ)。 | **ノルウェーのデータタイプ** | データタイプ | 説明 | | --- | --- | | NORWAY\$1BIRTH\$1NUMBER | ノルウェーの国民識別番号。 | | NORWAY\$1DRIVING\$1LICENSE | 運転免許証番号 (ノルウェーのみ)。 | | NORWAY\$1HEALTH\$1INSURANCE\$1NUMBER | ノルウェーの健康保険番号。 | | NORWAY\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (ノルウェーのみ)。 | | NORWAY\$1VALUE\$1ADDED\$1TAX | 付加価値税 (ノルウェーのみ)。 | **フィリピンのデータタイプ** | データタイプ | 説明 | | --- | --- | | PHILIPPINES\$1DRIVING\$1LICENSE | 運転免許証番号 (フィリピンのみ)。 | | PHILIPPINES\$1PASSPORT\$1NUMBER | パスポート番号 (フィリピンのみ)。 | **ポーランドのデータタイプ** | データタイプ | 説明 | | --- | --- | | POLAND\$1DRIVING\$1LICENSE | 運転免許証番号 (ポーランドのみ)。 | | POLAND\$1IDENTIFICATION\$1NUMBER | ポーランドの識別番号。 | | POLAND\$1PASSPORT\$1NUMBER | パスポート番号 (ポーランドのみ)。 | | POLAND\$1REGON\$1NUMBER | REGON 識別番号。統計識別番号 (Statistical Identification Number) とも呼ばれます。 | | POLAND\$1SSN | 社会保障番号 (ポーランド人の場合)。 | | POLAND\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (ポーランドのみ)。 | | POLAND\$1VALUE\$1ADDED\$1TAX | 付加価値税 (ポーランドのみ)。 | **ポルトガルのデータタイプ** | データタイプ | 説明 | | --- | --- | | PORTUGAL\$1DRIVING\$1LICENSE | 運転免許証番号 (ポルトガルのみ)。 | | PORTUGAL\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (ポルトガルのみ)。 | | PORTUGAL\$1PASSPORT\$1NUMBER | パスポート番号 (ポルトガルのみ)。 | | PORTUGAL\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (ポルトガルのみ)。 | | PORTUGAL\$1VALUE\$1ADDED\$1TAX | 付加価値税 (ポルトガルのみ)。 | **ルーマニアのデータタイプ** | データタイプ | 説明 | | --- | --- | | ROMANIA\$1DRIVING\$1LICENSE | 運転免許証番号 (ルーマニアのみ)。 | | ROMANIA\$1NUMERICAL\$1PERSONAL\$1CODE | 個人識別番号 (ルーマニアのみ)。 | | ROMANIA\$1PASSPORT\$1NUMBER | パスポート番号 (ルーマニアのみ)。 | | ROMANIA\$1VALUE\$1ADDED\$1TAX | 付加価値税 (ルーマニアのみ)。 | **シンガポールのデータタイプ** | データタイプ | 説明 | | --- | --- | | SINGAPORE\$1DRIVING\$1LICENSE | 運転免許証番号 (シンガポールのみ)。 | | SINGAPORE\$1NATIONAL\$1REGISTRY\$1IDENTIFICATION\$1NUMBER | シンガポールの国民登録 ID カード。 | | SINGAPORE\$1PASSPORT\$1NUMBER | パスポート番号 (シンガポールのみ)。 | | SINGAPORE\$1UNIQUE\$1ENTITY\$1NUMBER | シンガポールの個別企業登録番号 (UEN)。 | **スロバキアのデータタイプ** | データタイプ | 説明 | | --- | --- | | SLOVAKIA\$1DRIVING\$1LICENSE | 運転免許証番号 (スロバキアのみ)。 | | SLOVAKIA\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (スロバキアのみ)。 | | SLOVAKIA\$1PASSPORT\$1NUMBER | パスポート番号 (スロバキアのみ)。 | | SLOVAKIA\$1VALUE\$1ADDED\$1TAX | 付加価値税 (スロバキアのみ)。 | **スロベニアのデータタイプ** | データタイプ | 説明 | | --- | --- | | SLOVENIA\$1DRIVING\$1LICENSE | 運転免許証番号 (スロベニアのみ)。 | | SLOVENIA\$1PASSPORT\$1NUMBER | パスポート番号 (スロベニアのみ)。 | | SLOVENIA\$1TAX\$1IDENTIFICATION\$1NUMBER | 納税者番号 (スロベニアのみ)。 | | SLOVENIA\$1UNIQUE\$1MASTER\$1CITIZEN\$1NUMBER | スロベニア市民の固有マスター市民番号 (JMBG、Unique master citizen number)。 | | SLOVENIA\$1VALUE\$1ADDED\$1TAX | 付加価値税 (スロベニアのみ)。 | **南アフリカのデータタイプ** | データタイプ | 説明 | | --- | --- | | SOUTH\$1AFRICA\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別番号 (南アフリカのみ)。 | **スペインのデータタイプ** | データタイプ | 説明 | | --- | --- | | SPAIN\$1BANK\$1ACCOUNT | 銀行口座番号 (スペインのみ)。 | | SPAIN\$1DNI | スペインの国民 ID カード (Documento Nacional de Identidad)。 | | SPAIN\$1DRIVING\$1LICENSE | 運転免許証番号 (スペインのみ)。 | | SPAIN\$1NIE | NIE とも呼ばれる外国人 ID 番号 (スペインのみ)。 | | SPAIN\$1NIF | NIF とも呼ばれる納税者番号 (スペインのみ)。 | | SPAIN\$1PASSPORT\$1NUMBER | パスポート番号 (スペインのみ)。 | | SPAIN\$1SSN | 社会保障番号 (スペイン人の場合)。 | | SPAIN\$1VALUE\$1ADDED\$1TAX | 付加価値税 (スペインのみ)。 | **スリランカのデータタイプ** | データタイプ | 説明 | | --- | --- | | SRI\$1LANKA\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (スリランカのみ)。 | **スウェーデンのデータタイプ** | データタイプ | 説明 | | --- | --- | | SWEDEN\$1DRIVING\$1LICENSE | 運転免許証番号 (スウェーデンのみ)。 | | SWEDEN\$1PASSPORT\$1NUMBER | パスポート番号 (スウェーデンのみ)。 | | SWEDEN\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (スウェーデンのみ)。 | | SWEDEN\$1TAX\$1IDENTIFICATION\$1NUMBER | スウェーデンの納税者番号 (personnummer)。 | | SWEDEN\$1VALUE\$1ADDED\$1TAX | 付加価値税 (スウェーデンのみ)。 | **スイスのデータタイプ** | データタイプ | 説明 | | --- | --- | | SWITZERLAND\$1AHV | スイス人の社会保障番号 (AHV)。 | | SWITZERLAND\$1HEALTH\$1INSURANCE\$1NUMBER | スイスの健康保険番号。 | | SWITZERLAND\$1PASSPORT\$1NUMBER | パスポート番号 (スイスのみ)。 | | SWITZERLAND\$1VALUE\$1ADDED\$1TAX | 付加価値税 (スイスのみ)。 | **タイのデータタイプ** | データタイプ | 説明 | | --- | --- | | THAILAND\$1PASSPORT\$1NUMBER | パスポート番号 (タイのみ)。 | | THAILAND\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別番号 (タイのみ)。 | **トルコのデータタイプ** | データタイプ | 説明 | | --- | --- | | TURKEY\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (トルコのみ)。 | | TURKEY\$1PASSPORT\$1NUMBER | パスポート番号 (トルコのみ)。 | | TURKEY\$1VALUE\$1ADDED\$1TAX | 付加価値税 (トルコのみ)。 | **ウクライナのデータタイプ** | データタイプ | 説明 | | --- | --- | | UKRAINE\$1INDIVIDUAL\$1IDENTIFICATION\$1NUMBER | 固有識別番号 (ウクライナのみ)。 | | UKRAINE\$1PASSPORT\$1NUMBER\$1DOMESTIC | 国内パスポート番号 (ウクライナのみ)。 | | UKRAINE\$1PASSPORT\$1NUMBER\$1INTERNATIONAL | 国際パスポート番号 (ウクライナのみ)。 | **アラブ首長国連邦 (UAE) のデータタイプ** | データタイプ | 説明 | | --- | --- | | UNITED\$1ARAB\$1EMIRATES\$1PERSONAL\$1NUMBER | 個人識別番号 (UAE のみ)。 | **英国のデータタイプ** | データタイプ | 説明 | | --- | --- | | UK\$1BANK\$1ACCOUNT | 英国 (UK) の銀行口座。 | | UK\$1BANK\$1SORT\$1CODE | 英国 (UK) の銀行ソートコード。ソートコードは、各国の銀行間で、それぞれの決済機関を通じて送金をルーティングするために使用される銀行コードです。 | | UK\$1DRIVING\$1LICENSE | グレートブリテンおよび北アイルランド連合王国の運転免許証番号 (英国固有) | | UK\$1ELECTORAL\$1ROLL\$1NUMBER | 選挙人名簿番号 (ERN) は、英国の選挙登録のために個人に発行される識別番号です。この番号の形式は、英国内閣府の英国政府基準によって定められています。 | | UK\$1NATIONAL\$1HEALTH\$1SERVICE\$1NUMBER | 国民保険サービス (NHS) 番号は、英国の公衆衛生サービスの登録ユーザーに割り当てられる固有の番号です。 | | UK\$1NATIONAL\$1INSURANCE\$1NUMBER | 国民保険番号 (NINO) は、国民保険プログラムまたは社会保障システムで個人を識別するために英国で使用される番号です。この番号は、NI No または NINO と呼ばれることもあります。 | | UK\$1PASSPORT\$1NUMBER | 英国 (UK) パスポート番号。 | | UK\$1UNIQUE\$1TAXPAYER\$1REFERENCE\$1NUMBER | 英国 (UK) 納税者固有番号 (UTR) 番号。英国政府が課税システムを管理するために使用する識別子。 | | UK\$1VALUE\$1ADDED\$1TAX | VAT は最終消費者が負担する消費税です。VAT は、製造および流通プロセスの各取引に対して支払われます。英国の場合、VAT 番号は事業が設立された地域の VAT 事務所によって発行されます。 | | UK\$1PHONE\$1NUMBER | 英国 (UK) の電話番号。 | **ベネズエラのデータタイプ** | データタイプ | 説明 | | --- | --- | | VENEZUELA\$1DRIVING\$1LICENSE | 運転免許証番号 (ベネズエラのみ)。 | | VENEZUELA\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 国民識別番号 (ベネズエラのみ)。 | | VENEZUELA\$1VALUE\$1ADDED\$1TAX | 付加価値税 (ベネズエラのみ)。 | # 詳細な機密データ検出の使用 **注記** 詳細なアクションは AWS Glue 3.0 および 4.0 でのみ使用できます。これには AWS Glue Studio エクスペリエンスも含まれます。永続的な監査ログの変更も 2.0 では使用できません。 すべての AWS Glue Studio 3.0 および 4.0 のビジュアルジョブでは、詳細なアクション API を自動的に使用するスクリプトが作成されます。 Detect Sensitive Data は、定義したエンティティ、または AWS Glue によって事前定義されたエンティティを検出、マスキング、削除する機能を提供します。さらに、詳細なアクションを使用することで、エンティティごとに特定のアクションを適用できます。その他の利点には次が含まれます。 + データが検出されるとすぐにアクションが適用されるようになり、パフォーマンスが改善されました。 + 特定の列を含めるか、または除外するオプション。 + 部分的なマスキングを使用する機能。これにより、文字列全体をマスキングするのではなく、検出された機密データエンティティを部分的にマスキングできます。オフセットを含むシンプルなパラメータと正規表現の両方がサポートされます。 次のセクションで参照するサンプルジョブで使用される機密データ検出 API と詳細なアクションのコードスニペットを次に示します。 **detect API** – 詳細なアクションは、新しい `detectionParameters` パラメータを使用します。 ``` def detect( frame: DynamicFrame, detectionParameters: JsonOptions, outputColumnName: String = "DetectedEntities", detectionSensitivity: String = "LOW" ): DynamicFrame = {} ``` ## 詳細なアクションで機密データ検出 API を使用する **detect** を使用する機密データ検出 API は、指定されたデータを分析し、行または列が機密データエンティティタイプであるかどうかを判断して、エンティティタイプごとにユーザーが指定したアクションを実行します。 ### 詳細なアクションでの detect API の使用 **detect** API を使用して、`outputColumnName` と ` detectionParameters` を指定します。 ``` object GlueApp { def main(sysArgs: Array[String]) { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) // @params: [JOB_NAME] val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) // Script generated for node S3 bucket. Creates DataFrame from data stored in S3. val S3bucket_node1 = glueContext.getSourceWithFormat(formatOptions=JsonOptions("""{"quoteChar": "\"", "withHeader": true, "separator": ",", "optimizePerformance": false}"""), connectionType="s3", format="csv", options=JsonOptions("""{"paths": ["s3://189657479688-ddevansh-pii-test-bucket/tiny_pii.csv"], "recurse": true}"""), transformationContext="S3bucket_node1").getDynamicFrame() // Script generated for node Detect Sensitive Data. Will run detect API for the DataFrame // detectionParameter contains information on which EntityType are being detected // and what actions are being applied to them when detected. val DetectSensitiveData_node2 = EntityDetector.detect( frame = S3bucket_node1, detectionParameters = JsonOptions( """ { "PHONE_NUMBER": [ { "action": "PARTIAL_REDACT", "actionOptions": { "numLeftCharsToExclude": "3", "numRightCharsToExclude": "4", "redactChar": "#" }, "sourceColumnsToExclude": [ "Passport No", "DL NO#" ] } ], "USA_PASSPORT_NUMBER": [ { "action": "SHA256_HASH", "sourceColumns": [ "Passport No" ] } ], "USA_DRIVING_LICENSE": [ { "action": "REDACT", "actionOptions": { "redactText": "USA_DL" }, "sourceColumns": [ "DL NO#" ] } ] } """ ), outputColumnName = "DetectedEntities" ) // Script generated for node S3 bucket. Store Results of detect to S3 location val S3bucket_node3 = glueContext.getSinkWithFormat(connectionType="s3", options=JsonOptions("""{"path": "s3://amzn-s3-demo-bucket/test-output/", "partitionKeys": []}"""), transformationContext="S3bucket_node3", format="json").writeDynamicFrame(DetectSensitiveData_node2) Job.commit() } ``` 上記のスクリプトは、Amazon S3 内の場所から DataFrame を作成し、`detect` API を実行します。`detect` API ではフィールド `detectionParameters` (エンティティに使用されるすべてのアクション設定のリストに対するエンティティ名のマップ) が AWS Glue の `JsonOptions` オブジェクトによって表されるため、API の機能を拡張することもできます。 エンティティごとに指定された各アクションについて、エンティティ/アクションの組み合わせを適用するすべての列名のリストを入力します。これにより、エンティティをカスタマイズしてデータセット内のすべての列を検出したり、特定の列に存在しないことがわかっているエンティティをスキップしたりできます。また、これらのエンティティを呼び出す不要な検出を実行しないことでジョブのパフォーマンスが改善し、各列とエンティティの組み合わせに固有のアクションを実行できるようになります。 `detectionParameters` を詳しく見てみると、サンプルジョブには 3 つのエンティティタイプがあることがわかります。これらは、`Phone Number`、`USA_PASSPORT_NUMBER`、`USA_DRIVING_LICENSE` です。これらの各エンティティタイプについて、AWS Glue は、異なるアクション (`PARTIAL_REDACT`、`SHA256_HASH`、`REDACT`、`DETECT` のいずれか) を実行します。各エンティティタイプには、適用する `sourceColumns` および/または `sourceColumnsToExclude` (検出された場合) があります。 **注記** 列ごとに使用できるその場編集アクション (`PARTIAL_REDACT`、`SHA256_HASH`、または `REDACT`) は 1 つだけですが、`DETECT` アクションはこれらのアクションのいずれかと併用できます。 `detectionParameters` フィールドのレイアウトは以下のとおりです。 ``` ENTITY_NAME -> List[Actions] { "ENTITY_NAME": [{ Action, // required ColumnSpecs, ActionOptionsMap }], "ENTITY_NAME2": [{ ... }] } ``` タイプ `actions` および `actionOptions` は以下のとおりです。 ``` DETECT { # Required "action": "DETECT", # Optional, depending on action chosen "actionOptions": { // There are no actionOptions for DETECT }, # 1 of below required, both can also used "sourceColumns": [ "COL_1", "COL_2", ..., "COL_N" ], "sourceColumnsToExclude": [ "COL_5" ] } SHA256_HASH { # Required "action": "SHA256_HASH", # Required or optional, depending on action chosen "actionOptions": { // There are no actionOptions for SHA256_HASH }, # 1 of below required, both can also used "sourceColumns": [ "COL_1", "COL_2", ..., "COL_N" ], "sourceColumnsToExclude": [ "COL_5" ] } REDACT { # Required "action": "REDACT", # Required or optional, depending on action chosen "actionOptions": { // The text that is being replaced "redactText": "USA_DL" }, # 1 of below required, both can also used "sourceColumns": [ "COL_1", "COL_2", ..., "COL_N" ], "sourceColumnsToExclude": [ "COL_5" ] } PARTIAL_REDACT { # Required "action": "PARTIAL_REDACT", # Required or optional, depending on action chosen "actionOptions": { // number of characters to not redact from the left side "numLeftCharsToExclude": "3", // number of characters to not redact from the right side "numRightCharsToExclude": "4", // the partial redact will be made with this redacted character "redactChar": "#", // regex pattern for partial redaction "matchPattern": "[0-9]" }, # 1 of below required, both can also used "sourceColumns": [ "COL_1", "COL_2", ..., "COL_N" ], "sourceColumnsToExclude": [ "COL_5" ] } ``` スクリプトが実行されると、指定された Amazon S3 の場所に結果が出力されます。Amazon S3 でデータを表示することはできますが、選択したアクションに基づいて、選択したエンティティタイプの感度が高くなります。この場合、行は次のようになります。 ``` { "Name": "Colby Schuster", "Address": "39041 Antonietta Vista, South Rodgerside, Nebraska 24151", "Car Owned": "Fiat", "Email": "Kitty46@gmail.com", "Company": "O'Reilly Group", "Job Title": "Dynamic Functionality Facilitator", "ITIN": "991-22-2906", "Username": "Cassandre.Kub43", "SSN": "914-22-2906", "DOB": "2020-08-27", "Phone Number": "1-2#######1718", "Bank Account No": "69741187", "Credit Card Number": "6441-6289-6867-2162-2711", "Passport No": "94f311e93a623c72ccb6fc46cf5f5b0265ccb42c517498a0f27fd4c43b47111e", "DL NO#": "USA_DL" } ``` 上記のスクリプトでは、`Phone Number` は部分的に `#` でマスキングされています。`Passport No` は SHA256 ハッシュに変更されました。`DL NO# ` は米国の運転免許証番号として検出され、`detectionParameters` で記述されているように「USA\$1DL」でマスキングされました。 **注記** classifyColumns API は、API の性質上、詳細なアクションでは使用できません。この API は、列サンプリング (ユーザーによる調整が可能ですが、デフォルト値が設定されています) を実行して、検出をより迅速に実行します。このため、詳細なアクションでは、すべての値に対してイテレーションを実行する必要があります。 ### 永続的な監査ログ 詳細なアクションで導入された新機能 (ただし、通常の API を使用する場合にも使用可能) は、永続的な監査ログです。現在、detect API を実行すると、PII 検出メタデータを含む追加の列 (`DetectedEntities` にデフォルト設定されていますが、`outputColumnName` を通じてカスタマイズ可能です) パラメータが追加されます。これには、「actionUsed」メタデータキーが追加されました。これは、`DETECT`、`PARTIAL_REDACT`、`SHA256_HASH`、`REDACT` のいずれかです。 ``` "DetectedEntities": { "Credit Card Number": [ { "entityType": "CREDIT_CARD", "actionUsed": "DETECT", "start": 0, "end": 19 } ], "Phone Number": [ { "entityType": "PHONE_NUMBER", "actionUsed": "REDACT", "start": 0, "end": 14 } ] } ``` `detect(entityTypesToDetect, outputColumnName)` などの詳細なアクションなしで API を使用しているお客様でも、結果として得られるデータフレームでこの永続的な監査ログを確認できます。 詳細なアクションが設定されている API を使用しているお客様は、マスキングされているかどうかにかかわらず、すべてのアクションを表示できます。例: ``` +---------------------+----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Credit Card Number | Phone Number | DetectedEntities | +---------------------+----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 622126741306XXXX | +12#####7890 | {"Credit Card Number":[{"entityType":"CREDIT_CARD","actionUsed":"PARTIAL_REDACT","start":0,"end":16}],"Phone Number":[{"entityType":"PHONE_NUMBER","actionUsed":"PARTIAL_REDACT","start":0,"end":12}]}} | | 6221 2674 1306 XXXX | +12#######7890 | {"Credit Card Number":[{"entityType":"CREDIT_CARD","actionUsed":"PARTIAL_REDACT","start":0,"end":19}],"Phone Number":[{"entityType":"PHONE_NUMBER","actionUsed":"PARTIAL_REDACT","start":0,"end":14}]}} | | 6221-2674-1306-XXXX | 22#######7890 | {"Credit Card Number":[{"entityType":"CREDIT_CARD","actionUsed":"PARTIAL_REDACT","start":0,"end":19}],"Phone Number":[{"entityType":"PHONE_NUMBER","actionUsed":"PARTIAL_REDACT","start":0,"end":14}]}} | +---------------------+----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ``` **[DetectedEntities]** 列を表示したくない場合、必要なのは、カスタムスクリプトに追加の列をドロップすることだけです。 # AWS Glue ビジュアルジョブ API AWS Glue は ビジュアルステップワークフローを表す JSON オブジェクトから AWS Glue APIを使用して、お客様がデータ統合ジョブを作成できるようにする API を提供します。　 お客様は AWS Glue Studio のビジュアルエディターを使って、これらのジョブを処理することができます。 Visual Job API データ型の詳細については、「[Visual Job API](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-visual-job-api.html)」(ビジュアル Job API) を参照してください。 **Topics** + [API 設計と CRUD API](#visual-job-api-design) + [開始方法](#getting-started-visual-job-api) + [ビジュアルジョブの制限](#visual-job-limitations) ## API 設計と CRUD API CreateJobAPI と UpdateJob の [API](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-jobs-job.html) は、追加のオプションパラメータとして codeGenConfigurationNodes をサポートするようになりました。このフィールドに空でない JSON 構造を指定すると、作成されたジョブの AWS Glue Studio に対して DAG が登録され、関連するコードが生成されます。ジョブ作成時のこのフィールドの NULL 値または空の文字列は無視されます。 codeGenConfigurationNodes フィールドの更新は、CreateJob と同様の方法で UpdateJob AWS Glue API で行われます。DAG が必要に応じて変更された UpdateJob でフィールド全体を指定する必要があります。指定された NULL 値は無視され、DAG への更新は実行されません。空の構造体または文字列を指定すると、CodeGenConfigurationNodes が空に設定され、以前の DAG が削除されます。GetJob API は DAG が存在する場合、DAG を返します。DeleteJob API では、関連する DAG も削除されます。 ## 開始方法 ジョブを作成するには、[CreateJob アクション](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-jobs-job.html#aws-glue-api-jobs-job-CreateJob)を使用します。`CreateJob` リクエストの入力には、JSON で DAG オブジェクトを指定できる追加のフィールド 「CodeGenConfigurationNodes」があります。 留意すべきこと: + 「CodeGenConfigurationNodes」フィールドは、ノードへの nodeID のマップです。 + 各ノードは、ノードの種類を識別するキーで始まります。 + ノードには 1 つのタイプしか指定できないため、キーは 1 つしか指定できません。 + 入力フィールドには、現在のノードの親ノードが含まれます。 以下は、**CreateJob** 入力の JSON 表現です。 ``` { "node-1": { "S3CatalogSource": { "Table": "csvFormattedTable", "PartitionPredicate": "", "Name": "S3 bucket", "AdditionalOptions": {}, "Database": "myDatabase" } }, "node-3": { "S3DirectTarget": { "Inputs": ["node-2"], "PartitionKeys": [], "Compression": "none", "Format": "json", "SchemaChangePolicy": { "EnableUpdateCatalog": false }, "Path": "", "Name": "S3 bucket" } }, "node-2": { "ApplyMapping": { "Inputs": ["node-1"], "Name": "ApplyMapping", "Mapping": [ { "FromType": "long", "ToType": "long", "Dropped": false, "ToKey": "myheader1", "FromPath": ["myheader1"] }, { "FromType": "long", "ToType": "long", "Dropped": false, "ToKey": "myheader2", "FromPath": ["myheader2"] }, { "FromType": "long", "ToType": "long", "Dropped": false, "ToKey": "myheader3", "FromPath": ["myheader3"] } ] } } } ``` **ジョブの更新と取得** *[Updating jobs]* (ジョブの更新) に 'codeGenConfigurationNodes'フィールドがあるため、入力形式は同じになります。「[UpdateJob](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-jobs-job.html#aws-glue-api-jobs-job-UpdateJob)」アクションを参照してください。 *GetJob* アクションは、同じ形式の「CodeGenConfigurationNodes」フィールドも返します。「[GetJob](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-jobs-job.html#aws-glue-api-jobs-job-GetJob)」アクションを参照してください。 ## ビジュアルジョブの制限 既存の API に「CodeGenConfigurationNodes」パラメータが追加されているため、これらの API の制限はすべて継承されます。さらに、CodeGenConfigurationNodes および一部のノードのサイズは制限されます。詳細については、次の「[ジョブ構造](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-jobs-job.html#aws-glue-api-jobs-job-Job)」を参照してください。