本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Spark 指令碼程式設計 AWS Glue 可讓您輕鬆撰寫或自動產生擷取、轉換和載入 (ETL) 指令碼，以及進行測試和執行指令碼。本節說明 AWS Glue 推出的 Apache Spark 擴充功能，並提供範例，來示範以 Python 和 Scala 撰寫程式碼和執行 ETL 指令碼的方法。 **重要** 不同版本的 AWS Glue 支援不同版本的 Apache Spark。您的自訂指令碼必須與支援的 Apache Spark 版本相容。如需 AWS Glue 版本的相關資訊，請參閱 [Glue version job property](add-job.md#glue-version-table)。 **Topics** + [教學課程：撰寫 Glue for Spark AWS 指令碼](aws-glue-programming-intro-tutorial.md) + [在 PySpark 中程式設計 AWS Glue ETL 指令碼](aws-glue-programming-python.md) + [在 Scala 中進行 AWS Glue ETL 指令碼程式設計](aws-glue-programming-scala.md) + [AWS Glue for Spark ETL 指令碼程式設計的功能和最佳化](aws-glue-programming-general.md) # 教學課程：撰寫 Glue for Spark AWS 指令碼 本教學課程向您介紹撰寫 Glue AWS 指令碼的程序。您可以按照任務的排程執行指令碼，也可以與互動式工作階段互動執行。如需任務的詳細資訊，請參閱[建置視覺化的 ETL 任務](author-job-glue.md)。如需互動式工作階段的詳細資訊，請參閱[AWS Glue 互動式工作階段概觀](interactive-sessions-chapter.md#interactive-sessions-overview)。 Glue Studio AWS 視覺化編輯器提供圖形化、無程式碼的界面，用於建置 AWS Glue 任務。 AWS Glue 指令碼會傳回視覺化任務。您可透過這些指令碼存取一組經過擴增的工具，這些工具能與 Apache Spark 程式搭配運作。您可以存取原生 Spark APIs，以及促進從 AWS Glue 指令碼內擷取、轉換和載入 (ETL) 工作流程的 AWS Glue 程式庫。 本教學課程中，您會擷取、轉換及載入違停罰單資料集。執行此工作的指令碼與 AWS 大數據部落格上的 [AWS Glue Studio 所產生 ETL 的](https://aws.amazon.com/blogs/big-data/making-etl-easier-with-aws-glue-studio/)格式和函數相同，該部落格介紹 AWS 了 Glue Studio 視覺化編輯器。透過在任務中執行此指令碼，您可以將其與視覺化任務進行比較，並查看 AWS Glue ETL 指令碼的運作方式。如此一來，您就可以做好準備，以便日後使用目前視覺化任務尚未提供的其他功能。 在本教學課程中，您將使用 Python 語言和程式庫。類似的功能在 Scala 中可用。完成本教學課程後，您應該能夠產生並檢查範例 Scala 指令碼，以了解如何執行 Scala AWS Glue ETL 指令碼撰寫程序。 ## 先決條件 本教學課程具備下列先決條件： + 與 AWS Glue Studio 部落格文章相同的先決條件，它會指示您執行 CloudFormation 範本。 此範本使用 AWS Glue Data Catalog 來管理 中可用的停車票證資料集`s3://aws-bigdata-blog/artifacts/gluestudio/`。它建立將被引用以下資源： + **AWS Glue StudioRole**：要執行 AWS Glue 任務的 IAM 角色 + **AWS Glue StudioAmazon S3Bucket**：儲存部落格相關檔案的 Amazon S3 儲存貯體名稱 + **AWS Glue StudioTicketsYYZDB**：AWS Glue Data Catalog 資料庫 + **AWS Glue StudioTableTickets**：用作來源的 Data Catalog 資料表 + **AWS Glue StudioTableTrials**：用作來源的 Data Catalog 資料表 + **AWS Glue StudioParkingTicketCount**：用作目的地的 Data Catalog 資料表 + Glue Studio AWS 部落格文章中產生的指令碼。如果部落格文章變更，指令碼在下列文字中同樣可用。 ### 產生範例指令碼 您可以使用 AWS Glue Studio 視覺化編輯器做為強大的程式碼產生工具，為您要寫入的指令碼建立 scaffold。您將使用此工具建立範例指令碼。 如果您想跳過這些步驟，系統會提供指令碼。 #### 教學課程範例指令碼 ``` 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) # Script generated for node S3 bucket S3bucket_node1 = glueContext.create_dynamic_frame.from_catalog( database="yyz-tickets", table_name="tickets", transformation_ctx="S3bucket_node1" ) # Script generated for node ApplyMapping ApplyMapping_node2 = ApplyMapping.apply( frame=S3bucket_node1, mappings=[ ("tag_number_masked", "string", "tag_number_masked", "string"), ("date_of_infraction", "string", "date_of_infraction", "string"), ("ticket_date", "string", "ticket_date", "string"), ("ticket_number", "decimal", "ticket_number", "float"), ("officer", "decimal", "officer_name", "decimal"), ("infraction_code", "decimal", "infraction_code", "decimal"), ("infraction_description", "string", "infraction_description", "string"), ("set_fine_amount", "decimal", "set_fine_amount", "float"), ("time_of_infraction", "decimal", "time_of_infraction", "decimal"), ], transformation_ctx="ApplyMapping_node2", ) # Script generated for node S3 bucket S3bucket_node3 = glueContext.write_dynamic_frame.from_options( frame=ApplyMapping_node2, connection_type="s3", format="glueparquet", connection_options={"path": "s3://DOC-EXAMPLE-BUCKET", "partitionKeys": []}, format_options={"compression": "gzip"}, transformation_ctx="S3bucket_node3", ) job.commit() ``` **產生範例指令碼** 1. 完成 AWS Glue Studio 教學課程。若要完成本教學課程，請參閱[從範例任務在 Glue Studio AWS 中建立任務](https://docs.aws.amazon.com/glue/latest/dg/edit-nodes-chapter.html#create-jobs-start.html)。 1. 導覽至任務頁面上的 **Script** (指令碼) 索引標籤，如以下螢幕擷取畫面所示： ![\[Glue AWS 任務的指令碼標籤。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/programming-intro-generated-script.png) 1. 複製 **Script** (指令碼) 索引標籤中的完整內容。透過在 **Job details** (任務詳細資訊) 中設定指令碼語言，您可以在產生 Python 程式碼或 Scala 程式碼之間來回切換。 ## 步驟 1. 建立任務並貼上指令碼 在此步驟中，您會在 中建立 AWS Glue 任務 AWS 管理主控台。這會設定允許 AWS Glue 執行指令碼的組態。此操作還會為您建立一個存放和編輯指令碼的地方。 **建立任務** 1. 在 中 AWS 管理主控台，導覽至 AWS Glue 登陸頁面。 1. 在側邊的導覽窗格中，選擇 **Jobs** (任務)。 1. 在 **Create job** (建立任務) 中選擇 **Spark script editor** (Spark 指令碼編輯器)，接著選擇 **Create** (建立)。 1. **選用** – 將指令碼的完整文字貼入 **Script** (指令碼) 窗格中。或者，您可以按照教學課程進行操作。 ## 步驟 2. 匯入 AWS Glue 程式庫 您需要設定指令碼，使其與在指令碼外部定義的程式碼和組態互動。此工作會在 Glue Studio AWS 的幕後完成。 在此步驟中，您會執行下列動作。 + 匯入並初始化 `GlueContext` 物件。從指令碼編寫的角度來看，這是最重要的匯入。這會公開定義來源和目標資料集所使用的標準方法，也就是任何 ETL 指令碼的起點。若要進一步了解 `GlueContext` 類別，請參閱 [GlueContext 類別](aws-glue-api-crawler-pyspark-extensions-glue-context.md)。 + 初始化 `SparkContext` 和 `SparkSession`。這些可讓您設定 Glue 任務中可用的 Spark AWS 引擎。您不需要直接在 Glue AWS 指令碼簡介中使用這些指令碼。 + 呼叫 `getResolvedOptions`，準備您的任務參數以在指令碼內使用。如需有關解析任務參數的詳細資訊，請參閱 [使用 `getResolvedOptions` 存取參數](aws-glue-api-crawler-pyspark-extensions-get-resolved-options.md)。 + 初始化 `Job`。`Job` 物件會設定組態並追蹤各種選用 Glue AWS 功能的狀態。您的指令碼可以在沒有 `Job` 物件的情況下執行，但最佳實務是將其初始化，以免之後整合這些功能時造成混淆。 其中一項功能是任務書籤，您可以在此教學課程中選擇性地設定該功能。您可以在以下章節中了解有關任務書籤的資訊：[選用 – 啟用任務書籤](#aws-glue-programming-intro-tutorial-create-job-bookmarks)。 在此程序中，您需編寫下列程式碼。此程式碼是產生的範例指令碼的一部分。 ``` 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) ``` **匯入 AWS Glue 程式庫** + 複製此段程式碼並貼入 **Script** (指令碼) 編輯器中。 **注意** 您或許會認為，複製程式碼是一種不好的工程實務。在本教學課程中，我們建議您一致地命名所有 Glue ETL AWS 指令碼的核心變數。 ## 步驟 3。從來源擷取資料 在任何 ETL 程序中，您都需要先定義要變更的來源資料集。在 AWS Glue Studio 視覺化編輯器中，您可以透過建立**來源**節點來提供此資訊。 在此步驟中，您需為 `create_dynamic_frame.from_catalog` 方法提供 `database` 和 `table_name`，以便從 AWS Glue 資料目錄所設定的來源擷取資料。 在先前的步驟中，您已初始化 `GlueContext` 物件。您可以使用此物件來尋找設定來源所需使用的方法，例如 `create_dynamic_frame.from_catalog`。 在此程序中，您需使用 `create_dynamic_frame.from_catalog` 編寫下列程式碼。此程式碼是產生的範例指令碼的一部分。 ``` S3bucket_node1 = glueContext.create_dynamic_frame.from_catalog( database="yyz-tickets", table_name="tickets", transformation_ctx="S3bucket_node1" ) ``` **從來源擷取資料** 1. 檢查 文件，在 上尋找從 Glue Data Catalog AWS 中定義的來源`GlueContext`擷取資料的方法。這些方法記錄於 [GlueContext 類別](aws-glue-api-crawler-pyspark-extensions-glue-context.md)。選擇 [create\$1dynamic\$1frame.from\$1catalog](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_catalog) 方法。在 `glueContext` 上呼叫此方法。 1. 檢查 `create_dynamic_frame.from_catalog` 的文件。此方法需要 `database` 和 `table_name` 參數。為 `create_dynamic_frame.from_catalog` 提供必要的參數。 Glue Data Catalog AWS 會儲存來源資料的位置和格式相關資訊，並在先決條件區段中設定。您不必直接為指令碼提供該資訊。 1. **選用** – 為該方法提供 `transformation_ctx` 參數，以支援任務書籤。您可以在以下章節中了解有關任務書籤的資訊：[選用 – 啟用任務書籤](#aws-glue-programming-intro-tutorial-create-job-bookmarks)。 **注意** **擷取資料的常用方法** [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) 用於連接到 Glue Data Catalog AWS 中的資料表。 如果您需要直接為任務提供描述來源結構和位置的組態，請參閱 [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) 方法。您需要提供比使用 `create_dynamic_frame.from_catalog` 時更詳細的參數以描述您的資料。 請參閱有關 `format_options` 和 `connection_parameters` 的補充文件來識別所需參數。有關如何提供關於來源資料格式的指令碼資訊的說明，請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md)。有關如何提供關於來源資料位置的指令碼資訊的說明，請參閱 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 如果您要從串流來源讀取資訊，您可以透過 [create\$1data\$1frame\$1from\$1catalog](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create-dataframe-from-catalog) 或 [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) 方法為任務提供來源資訊。請注意，這些方法會傳回 Apache Spark `DataFrames`。 儘管參考文件參考的是 `create_dynamic_frame_from_catalog`，但產生的程式碼會呼叫 `create_dynamic_frame.from_catalog`。這些方法最終會呼叫相同的程式碼，並包含在內，以便您可以編寫更簡潔的程式碼。您可以檢視 Python 包裝函式的來源，藉以確認這一點，該包裝函式可在 [https://github.com/awslabs/aws-glue-libs/blob/master/awsglue/context.py](https://github.com/awslabs/aws-glue-libs/blob/master/awsglue/context.py) 找到。 ## 步驟 4. 使用 Glue AWS 轉換資料 在 ETL 程序中擷取來源資料後，您需要說明要如何變更資料。您可以在 Glue Studio AWS 視覺化編輯器中建立**轉換**節點，以提供此資訊。 在此步驟中，您需為 `ApplyMapping` 方法提供目前所需欄位名稱和類型的映射，以轉換您的 `DynamicFrame`。 執行以下轉換。 + 捨棄這四個 `location` 和 `province` 索引鍵。 + 將 `officer` 的名稱變更為 `officer_name`。 + 將 `ticket_number` 和 `set_fine_amount` 的類型變更為 `float`。 `create_dynamic_frame.from_catalog` 將為您提供 `DynamicFrame` 物件。`DynamicFrame` 代表 Glue AWS 中的資料集。 AWS Glue 轉換是變更 的操作`DynamicFrames`。 **注意** 什麼是 `DynamicFrame`？ `DynamicFrame` 是一種抽象，允許您連接資料集，該資料集中包含資料中項目的名稱和類型的描述。Apache Spark 中存在類似的抽象，稱為 DataFrame。如需 DataFrame 的說明，請參閱 [Spark SQL Guide](https://spark.apache.org/docs/latest/sql-programming-guide.html) (Spark SQL 指南)。 `DynamicFrames` 可讓您動態描述資料集結構描述。考慮具有價格欄的資料集，其中某些項目將價格儲存為字串，而其他項目則將價格儲存為雙重。 AWS Glue on-the-fly運算結構描述，它會為每個資料列建立自我描述記錄。 不一致的欄位 (如價格) 在框架結構描述中用類型 (`ChoiceType`) 明確表示。您可以使用 `DropFields` 捨棄不一致的欄位，或使用 `ResolveChoice` 來解析欄位，藉以處理欄位不一致的問題。這些轉換可從 `DynamicFrame` 取得。然後，您可以使用 `writeDynamicFrame` 將資料寫回資料湖。 您可以從 `DynamicFrame` 類別上的方法呼叫許多相同的轉換，這樣可以得到更具可讀性的指令碼。如需 `DynamicFrame` 的相關資訊，請參閱 [DynamicFrame 類別](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md)。 在此程序中，您需使用 `ApplyMapping` 編寫下列程式碼。此程式碼是產生的範例指令碼的一部分。 ``` ApplyMapping_node2 = ApplyMapping.apply( frame=S3bucket_node1, mappings=[ ("tag_number_masked", "string", "tag_number_masked", "string"), ("date_of_infraction", "string", "date_of_infraction", "string"), ("ticket_date", "string", "ticket_date", "string"), ("ticket_number", "decimal", "ticket_number", "float"), ("officer", "decimal", "officer_name", "decimal"), ("infraction_code", "decimal", "infraction_code", "decimal"), ("infraction_description", "string", "infraction_description", "string"), ("set_fine_amount", "decimal", "set_fine_amount", "float"), ("time_of_infraction", "decimal", "time_of_infraction", "decimal"), ], transformation_ctx="ApplyMapping_node2", ) ``` **使用 Glue AWS 轉換資料** 1. 檢查文件以識別要變更和捨棄欄位的轉換。如需詳細資訊，請參閱[GlueTransform base 類別](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md)。選擇 `ApplyMapping` 轉換。如需 `ApplyMapping` 的相關資訊，請參閱 [ApplyMapping 類別](aws-glue-api-crawler-pyspark-transforms-ApplyMapping.md)。在 `ApplyMapping` 轉換物件上呼叫 `apply`。 **注意** 什麼是 `ApplyMapping`？ `ApplyMapping` 採用 `DynamicFrame` 並對其進行轉換。這需使用代表欄位轉換的元組清單，亦即「映射」。前兩個元組元素 (欄位名稱和類型) 用於識別框架中的欄位。第二對參數同樣是欄位名稱和類型。 ApplyMapping 會以其傳回的新 `DynamicFrame`，將來源欄位轉換為目標名稱和類型。未提供的欄位會在傳回值中遭到捨棄。 您可以呼叫與 `DynamicFrame` 上的 `apply_mapping` 方法相同的轉換 (而不必呼叫 `apply`) 來建立更流暢、更易讀的程式碼。如需詳細資訊，請參閱[apply\$1mapping](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-apply_mapping)。 1. 檢查 `ApplyMapping` 的文件以識別所需參數。請參閱 [ApplyMapping 類別](aws-glue-api-crawler-pyspark-transforms-ApplyMapping.md)。您會發現此方法需要 `frame` 和 `mappings` 參數。為 `ApplyMapping` 提供必要的參數。 1. **選用** – 為該方法提供 `transformation_ctx`，以支援任務書籤。您可以在以下章節中了解有關任務書籤的資訊：[選用 – 啟用任務書籤](#aws-glue-programming-intro-tutorial-create-job-bookmarks)。 **注意** **Apache Spark 功能** 我們提供轉換以簡化您任務中的 ETL 工作流程。您還可以存取任務中 Spark 程式所提供的程式庫，這些程式庫專為更廣泛的用途而建立。如要使用這些程式庫，您需在 `DynamicFrame` 和 `DataFrame` 之間轉換。 您可以使用 [toDF](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-toDF) 建立 `DataFrame`。接著，您可以使用 DataFrame 所提供的方法來轉換資料集。如需這些方法的詳細資訊，請參閱 [DataFrame](https://spark.apache.org/docs/3.1.1/api/python/reference/api/pyspark.sql.DataFrame.html)。然後，您可以使用 向後轉換 [fromDF](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-fromDF) ，以使用 AWS Glue 操作將影格載入目標。 ## 步驟 5. 將資料載入目標 轉換資料之後，通常需將轉換後的資料存放在與來源不同的地方。您可以在 Glue Studio AWS 視覺化編輯器中建立**目標**節點來執行此操作。 在此步驟中，您需為 `write_dynamic_frame.from_options` 方法提供 `connection_type`、`connection_options`、`format` 和 `format_options`，將資料載入 Amazon S3 中的目標儲存貯體。 在步驟 1 中，您初始化了 `GlueContext` 物件。在 AWS Glue 中，您可以找到用來設定目標的方法，就像來源一樣。 在此程序中，您需使用 `write_dynamic_frame.from_options` 編寫下列程式碼。此程式碼是產生的範例指令碼的一部分。 ``` S3bucket_node3 = glueContext.write_dynamic_frame.from_options( frame=ApplyMapping_node2, connection_type="s3", format="glueparquet", connection_options={"path": "s3://amzn-s3-demo-bucket", "partitionKeys": []}, format_options={"compression": "gzip"}, transformation_ctx="S3bucket_node3", ) ``` **將資料載入目標** 1. 檢查文件，查找將資料載入目標 Amazon S3 儲存貯體的方法。這些方法記錄於 [GlueContext 類別](aws-glue-api-crawler-pyspark-extensions-glue-context.md)。選擇 [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) 方法。在 `glueContext` 上呼叫此方法。 **注意** **常用資料載入方法** `write_dynamic_frame.from_options` 是最常用的資料載入方法，它支援 Glue AWS 中提供的所有目標。 如果您要寫入 Glue AWS 連線中定義的 JDBC 目標，請使用 [write\$1dynamic\$1frame\$1from\$1jdbc\$1conf](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-write_dynamic_frame_from_jdbc_conf)方法。 AWS Glue 連線會儲存有關如何連線至資料來源的資訊。如此一來，您就不需在 `connection_options` 提供該資訊，不過您仍然需要使用 `connection_options` 來提供 `dbtable`。 `write_dynamic_frame.from_catalog` 不是常用的資料載入方法。此方法會在不更新基礎資料集的情況下更新 AWS Glue Data Catalog，並與其他變更基礎資料集的程序結合使用。如需詳細資訊，請參閱[使用 AWS Glue ETL 任務，在 Data Catalog 中更新結構描述並新增新的分區](update-from-job.md)。 1. 檢查 [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) 的文件。此方法需要 `frame`、`connection_type`、`format`、`connection_options` 和 `format_options`。在 `glueContext` 上呼叫此方法。 1. 請參閱有關 `format_options` 和 `format` 的補充文件以識別您需要的參數。如需資料格式的說明，請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md)。 1. 請參閱有關 `connection_type` 和 `connection_options` 的補充文件以識別您需要的參數。如需連線的說明，請參閱 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 1. 為 `write_dynamic_frame.from_options` 提供必要的參數。此方法的組態與 `create_dynamic_frame.from_options` 類似。 1. **選用** – 向 `write_dynamic_frame.from_options` 提供 `transformation_ctx`，以支援任務書籤。您可以在以下章節中了解有關任務書籤的資訊：[選用 – 啟用任務書籤](#aws-glue-programming-intro-tutorial-create-job-bookmarks)。 ## 步驟 6. 遞交 `Job` 物件 您在步驟 1 中初始化了 `Job` 物件。如果某些選用功能需要此功能才能正常運作 (例如在使用任務書籤時)，您可能需要在指令碼結尾處手動斷定其生命週期。此工作會在 Glue Studio AWS 的幕後完成。 在此步驟中，在 `Job` 物件上呼叫 `commit` 方法。 在此程序中，您需編寫下列程式碼。此程式碼是產生的範例指令碼的一部分。 ``` job.commit() ``` **遞交 `Job` 物件** 1. 如果您尚未執行此操作，請執行先前章節中概述的選用步驟，將 `transformation_ctx` 納入其中。 1. 呼叫 `commit`。 ## 選用 – 啟用任務書籤 之前的每個步驟都已經指示您設定 `transformation_ctx` 參數。這與名為任務書籤的功能有關。 藉由任務書籤，您可針對資料集定期執行任務，達到節省時間和金錢的目的，同時還能輕鬆追蹤先前的工作。任務書籤會追蹤從先前執行跨資料集的 AWS Glue 轉換進度。透過追蹤先前執行的結束位置， AWS Glue 可以將工作限制為之前未處理的資料列。如需任務書籤的詳細資訊，請參閱 [使用任務書籤追蹤處理的資料](monitor-continuations.md)。 若要啟用任務書籤，請先新增 `transformation_ctx` 陳述式至我們所提供的函數，如之前的範例所述。任務書籤狀態會在執行期間維持不變，而 `transformation_ctx` 參數是存取該狀態所需的索引鍵。這些陳述式自身不會執行任何操作。您還需要在任務的組態中啟用該功能。 在此程序中，您會使用 AWS 管理主控台啟用任務書籤。 **啟用任務書籤** 1. 導覽至相應任務的 **Job details** (任務詳細資訊) 一節。 1. 將 **Job bookmark** (任務書籤) 設定為 **Enable** (啟用)。 ## 步驟 7. 將程式碼作為任務執行 在此步驟中，您需執行任務以確認您是否已成功完成本教學課程。按一下按鈕即可完成此操作，如 Glue Studio AWS 視覺化編輯器所示。 **將程式碼作為任務執行** 1. 在標題列上選擇 **Untitled job** (未命名任務) 以編輯和設定您的任務名稱。 1. 導覽至 **Job details** (任務詳細資訊) 索引標籤。為您的任務指派 **IAM Role** (IAM 角色)。您可以在 AWS Glue Studio 教學課程的先決條件中使用 CloudFormation 範本建立的 。如果您已完成該教學課程，則該角色應可用，名為 `AWS Glue StudioRole`。 1. 選擇 **Save** (儲存) 以儲存您的指令碼。 1. 選擇 **Run** (執行) 以執行您的任務。 1. 導覽至 **Runs** (執行) 索引標籤，以確認您的任務已完成。 1. 導覽至 *amzn-s3-demo-bucket* (`write_dynamic_frame.from_options` 的目標)。確認輸出符合您的期望。 如需有關設定和管理任務的詳細資訊，請參閱 [提供您的自訂指令碼](console-custom-created.md)。 ## 其他資訊 Apache Spark 程式庫和方法可在 Glue AWS 指令碼中使用。您可以查看 Spark 文件以了解您可以使用這些包含的程式庫來做什麼。如需詳細資訊，請參閱 [Spark 來源儲存庫的範例區段](https://github.com/apache/spark/tree/master/examples/src/main/python)。 AWS Glue 2.0\$1 預設包含數個常見的 Python 程式庫。也有機制可將您自己的相依性載入 Scala 或 Python 環境中的 AWS Glue 任務。如需 Python 相依性的相關資訊，請參閱 [搭配 Glue 使用 Python AWS 程式庫](aws-glue-programming-python-libraries.md)。 如需如何在 Python 中使用 AWS Glue 功能的詳細資訊，請參閱 [AWS Glue Python 程式碼範例](aws-glue-programming-python-samples.md)。Scala 和 Python 任務具有相同的功能，所以我們的 Python 範例應能為您提供以 Scala 執行類似工作的些許想法。 # 在 PySpark 中程式設計 AWS Glue ETL 指令碼 您可以在 GitHub AWS 網站上的 Glue [AWS 範例儲存庫中找到 Glue](https://github.com/awslabs/aws-glue-samples) 的 Python 程式碼範例和公用程式。 ## 將 Python 與 AWS Glue 搭配使用 AWS Glue 支援 PySpark Python 方言的延伸，用於指令碼擷取、轉換和載入 (ETL) 任務。本節說明如何在 ETL 指令碼和 Glue API AWS 中使用 Python。 + [設定以 AWS Glue 使用 Python](aws-glue-programming-python-setup.md) + [在 Python 中呼叫 AWS Glue API](aws-glue-programming-python-calling.md) + [搭配 Glue 使用 Python AWS 程式庫](aws-glue-programming-python-libraries.md) + [AWS Glue Python 程式碼範例](aws-glue-programming-python-samples.md) ## AWS Glue PySpark 延伸模組 AWS Glue 已建立 PySpark Python 方言的下列延伸。 + [使用 `getResolvedOptions` 存取參數](aws-glue-api-crawler-pyspark-extensions-get-resolved-options.md) + [PySpark 延伸模組類型](aws-glue-api-crawler-pyspark-extensions-types.md) + [DynamicFrame 類別](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md) + [DynamicFrameCollection 類別](aws-glue-api-crawler-pyspark-extensions-dynamic-frame-collection.md) + [DynamicFrameWriter 類別](aws-glue-api-crawler-pyspark-extensions-dynamic-frame-writer.md) + [DynamicFrameReader 類別](aws-glue-api-crawler-pyspark-extensions-dynamic-frame-reader.md) + [GlueContext 類別](aws-glue-api-crawler-pyspark-extensions-glue-context.md) ## AWS Glue PySpark 轉換 AWS Glue 已建立下列轉換類別以用於 PySpark ETL 操作。 + [GlueTransform base 類別](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md) + [ApplyMapping 類別](aws-glue-api-crawler-pyspark-transforms-ApplyMapping.md) + [DropFields 類別](aws-glue-api-crawler-pyspark-transforms-DropFields.md) + [DropNullFields 類別](aws-glue-api-crawler-pyspark-transforms-DropNullFields.md) + [ErrorsAsDynamicFrame 類別](aws-glue-api-crawler-pyspark-transforms-ErrorsAsDynamicFrame.md) + [FillMissingValues 類別](aws-glue-api-crawler-pyspark-transforms-fillmissingvalues.md) + [Filter 類別](aws-glue-api-crawler-pyspark-transforms-filter.md) + [FindIncrementalMatches 類別](aws-glue-api-crawler-pyspark-transforms-findincrementalmatches.md) + [FindMatches 類別](aws-glue-api-crawler-pyspark-transforms-findmatches.md) + [FlatMap 類別](aws-glue-api-crawler-pyspark-transforms-flat-map.md) + [Join 類別](aws-glue-api-crawler-pyspark-transforms-join.md) + [Map 類別](aws-glue-api-crawler-pyspark-transforms-map.md) + [MapToCollection 類別](aws-glue-api-crawler-pyspark-transforms-MapToCollection.md) + [mergeDynamicFrame](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-merge) + [Relationalize 類別](aws-glue-api-crawler-pyspark-transforms-Relationalize.md) + [RenameField 類別](aws-glue-api-crawler-pyspark-transforms-RenameField.md) + [ResolveChoice 類別](aws-glue-api-crawler-pyspark-transforms-ResolveChoice.md) + [SelectFields 類別](aws-glue-api-crawler-pyspark-transforms-SelectFields.md) + [SelectFromCollection 類別](aws-glue-api-crawler-pyspark-transforms-SelectFromCollection.md) + [Spigot 類別](aws-glue-api-crawler-pyspark-transforms-spigot.md) + [SplitFields 類別](aws-glue-api-crawler-pyspark-transforms-SplitFields.md) + [SplitRows 類別](aws-glue-api-crawler-pyspark-transforms-SplitRows.md) + [Unbox 類別](aws-glue-api-crawler-pyspark-transforms-Unbox.md) + [UnnestFrame 類別](aws-glue-api-crawler-pyspark-transforms-UnnestFrame.md) # 設定以 AWS Glue 使用 Python 使用 Python 開發 Spark 任務的 ETL 指令碼。ETL 任務支援的 Python 版本取決於任務的 AWS Glue 版本。如需有關 AWS Glue 版本的詳細資訊，請參閱 [Glue version job property](add-job.md#glue-version-table)。 **設定您的系統以 AWS Glue 使用 Python** 依照以下步驟安裝 Python 以及能夠呼叫 AWS Glue API。 1. 如果您尚未安裝 Python，請至 [Python.org 下載頁面](https://www.python.org/downloads/)下載及安裝。 1. 安裝 AWS Command Line Interface (AWS CLI)，如 [AWS CLI 文件](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)所述。 使用 Python AWS CLI 不需要直接使用 。不過，安裝和設定它是一種使用 AWS 您的帳戶登入資料進行設定並驗證它們是否有效的便利方式。 1. 安裝適用於 Python 的 AWS SDK (Boto 3)，如 [Boto3 Quickstart](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) 所述。 AWS Glue 尚未提供 Boto 3 資源 API。目前，只能使用 Boto 3 用戶端 API。 如需有關 Boto 3 的詳細資訊，請參閱[AWS SDK for Python (Boto3) 入門](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)。 您可以在 GitHub 網站上的 [AWS Glue 範例儲存庫](https://github.com/awslabs/aws-glue-samples)中，找到適用於 AWS Glue 的 Python 程式碼範例與公用程式。 # 在 Python 中呼叫 AWS Glue API 請注意，AWS Glue 尚未提供 Boto 3 資源 API。目前，只能使用 Boto 3 用戶端 API。 ## Python 中的 AWS Glue API 名稱 AWS Java 和其他程式設計語言的 Glue API 名稱通常為 CamelCased。但是，從 Python 呼叫時，這些一般名稱會變更為小寫字母，並以底線字元區隔名稱的部分，使其更為「Pythonic」。在 [AWS Glue API](aws-glue-api.md) 參考文件中，這些 Pythonic 名稱會列在一般 CamelCased 名稱後面的刮號中。 但是，雖然 AWS Glue API 名稱本身會轉換為小寫字母，但其參數名稱仍維持大寫字母。請務必記住這一點，因為如下所述，在呼叫 AWS Glue API 時，應以名稱傳遞參數。 ## 在 AWS Glue 中傳遞和存取 Python 參數 在 Python 中呼叫 AWS Glue API，最好以名稱明確傳遞參數。例如： ``` job = glue.create_job(Name='sample', Role='Glue_DefaultRole', Command={'Name': 'glueetl', 'ScriptLocation': 's3://my_script_bucket/scripts/my_etl_script.py'}) ``` 這可協助您了解 Python 建立字典的名稱/值元組，讓您在 [Job 結構](aws-glue-api-jobs-job.md#aws-glue-api-jobs-job-Job) 或 [JobRun 結構](aws-glue-api-jobs-runs.md#aws-glue-api-jobs-runs-JobRun) 中將其指定為 ETL 指令碼的引數。Boto 3 會透過 REST API 呼叫，以 JSON 格式將它們傳送到 AWS Glue。這表示您在指令碼中存取這些引數時，無法倚賴引數的排序。 例如，假設您在 Python Lambda 處理常式函式中起始 `JobRun`，而且要指定幾個參數。您的程式碼看起來類似如下： ``` from datetime import datetime, timedelta client = boto3.client('glue') def lambda_handler(event, context): last_hour_date_time = datetime.now() - timedelta(hours = 1) day_partition_value = last_hour_date_time.strftime("%Y-%m-%d") hour_partition_value = last_hour_date_time.strftime("%-H") response = client.start_job_run( JobName = 'my_test_Job', Arguments = { '--day_partition_key': 'partition_0', '--hour_partition_key': 'partition_1', '--day_partition_value': day_partition_value, '--hour_partition_value': hour_partition_value } ) ``` 若要在您的 ETL 指令碼中可靠地存取這些參數，請使用 AWS Glue 的 `getResolvedOptions` 指定其名稱，然後從產生的字典存取這些參數： ``` import sys from awsglue.utils import getResolvedOptions args = getResolvedOptions(sys.argv, ['JOB_NAME', 'day_partition_key', 'hour_partition_key', 'day_partition_value', 'hour_partition_value']) print "The day partition key is: ", args['day_partition_key'] print "and the day partition value is: ", args['day_partition_value'] ``` 如果想傳遞一個巢狀 JSON 字串的引數，以在將參數值傳遞給 AWS Glue ETL 任務時保留參數值，則您必須在開始任務執行之前對參數字串進行編碼，然後在任務指令碼參考其之前對參數字串進行解碼。例如，請試想有下列引數字串： ``` glue_client.start_job_run(JobName = "gluejobname", Arguments={ "--my_curly_braces_string": '{"a": {"b": {"c": [{"d": {"e": 42}}]}}}' }) ``` 若要正確傳遞此參數，您應該將引數編碼為 Base64 編碼的字串。 ``` import base64 ... sample_string='{"a": {"b": {"c": [{"d": {"e": 42}}]}}}' sample_string_bytes = sample_string.encode("ascii") base64_bytes = base64.b64encode(sample_string_bytes) base64_string = base64_bytes.decode("ascii") ... glue_client.start_job_run(JobName = "gluejobname", Arguments={ "--my_curly_braces_string": base64_bytes}) ... sample_string_bytes = base64.b64decode(base64_bytes) sample_string = sample_string_bytes.decode("ascii") print(f"Decoded string: {sample_string}") ... ``` ## 範例：建立和執行任務 以下範例顯示如何使用 Python 呼叫 AWS Glue API，以建立和執行 ETL 任務。 **建立和執行任務** 1. 建立 AWS Glue 用戶端執行個體： ``` import boto3 glue = boto3.client(service_name='glue', region_name='us-east-1', endpoint_url='https://glue.us-east-1.amazonaws.com') ``` 1. 建立任務。您必須使用 `glueetl` 做為 ETL 命令的名稱，如以下程式碼所示： ``` myJob = glue.create_job(Name='sample', Role='Glue_DefaultRole', Command={'Name': 'glueetl', 'ScriptLocation': 's3://my_script_bucket/scripts/my_etl_script.py'}) ``` 1. 為您在上個步驟建立的任務啟動新的執行： ``` myNewJobRun = glue.start_job_run(JobName=myJob['Name']) ``` 1. 取得任務狀態： ``` status = glue.get_job_run(JobName=myJob['Name'], RunId=myNewJobRun['JobRunId']) ``` 1. 列印任務執行的目前狀態： ``` print(status['JobRun']['JobRunState']) ``` # 搭配 Glue 使用 Python AWS 程式庫 您可以安裝其他 Python 模組和程式庫，以與 Glue ETL AWS 搭配使用。對於 AWS Glue 2.0 及更高版本， AWS Glue 使用 Python 套件安裝程式 (pip3) 來安裝 AWS Glue ETL 使用的其他模組。 AWS Glue 提供多種選項，可將其他 Python 模組帶入您的 AWS Glue 任務環境。您可以使用 `--additional-python-modules` 參數，使用包含綁定 Python wheel 的 zip 檔案 （也稱為 "zip of wheel"，適用於 AWS Glue 5.0 及更高版本）、個別 Python wheel 檔案、需求檔案 (requirements.txt，適用於 AWS Glue 5.0 及更高版本） 或逗號分隔 Python 模組清單來引入新模組。它也可以用來變更 Glue 環境中提供的 Python AWS 模組版本 （如需詳細資訊[Python 模組已在 Glue AWS 中提供](#glue-modules-provided)，請參閱 )。 **Topics** + [在 AWS Glue 2.0 或更新版本中使用 pip 安裝其他 Python 模組](#addl-python-modules-support) + [包括 Python 檔案與 PySpark 原生功能](#extra-py-files-support) + [使用視覺化轉換的程式設計指令碼](#aws-glue-programming-with-cvt) + [壓縮程式庫以加入](#aws-glue-programming-python-libraries-zipping) + [在 Glue Studio AWS 筆記本中載入 Python 程式庫](#aws-glue-programming-python-libraries-notebooks) + [在 Glue 0.9/1.0 的開發端點中載入 Python AWS 程式庫](#aws-glue-programming-python-libraries-dev-endpoint) + [在任務或 JobRun 使用 Python 程式庫](#aws-glue-programming-python-libraries-job) + [主動分析 Python 相依項](#aws-glue-programming-analyzing-python-dependencies) + [Python 模組已在 Glue AWS 中提供](#glue-modules-provided) + [附錄 A：建立輪子壓縮成品](#glue-python-library-zip-of-wheels-appendix) + [附錄 B： AWS Glue 環境詳細資訊](#glue-python-libraries-environment-details) ## 在 AWS Glue 2.0 或更新版本中使用 pip 安裝其他 Python 模組 AWS Glue 使用 Python 套件安裝程式 (pip3) 來安裝 AWS Glue ETL 要使用的其他模組。您可以使用 `--additional-python-modules` 參數與逗號分隔的 Python 模組清單來新增新模組或變更現有模組的版本。您可以將檔案上傳到 Amazon S3，然後在模組清單中包含 Amazon S3 物件的路徑，透過轉輪壓縮或獨立轉輪成品來安裝建置的車輪成品。如需設定任務參數的詳細資訊，請參閱[在 Glue AWS 任務中使用任務參數](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-glue-arguments.html)。 您可以使用 `--python-modules-installer-option` 參數將其他選項傳遞給 pip3。例如，您可以傳遞 `--only-binary` ，強制 pip 僅為 指定的套件安裝預先建置的成品`--additional-python-modules`。如需更多範例，請參閱[使用 Glue 2.0 從 Spark ETL AWS 工作負載的 wheel 建置 Python 模組。 ](https://aws.amazon.com/blogs/big-data/building-python-modules-from-a-wheel-for-spark-etl-workloads-using-aws-glue-2-0/) ### Python 相依性管理的最佳實務 對於生產工作負載， AWS Glue 建議將所有 Python 相依性封裝為單一 zip 成品中的 wheel 檔案。此方法提供： + **確定性執行**：精確控制已安裝的套件版本 + **可靠性**：任務執行期間不依賴外部套件儲存庫 + **效能**：單一下載操作而非多個網路呼叫 + **離線安裝**：可在沒有網際網路存取的私有 VPC 環境中運作 #### 重要考量 在[AWS 共同責任模型](https://aws.amazon.com/compliance/shared-responsibility-model/)下，您負責管理其他 Python 模組、程式庫及其相依性。其中包含： + **安全性更新**：定期更新套件以解決安全性漏洞 + **版本相容性**：確保套件與您的 Glue AWS 版本相容 + **測試**：驗證您的封裝相依性在 Glue 環境中是否正常運作 如果您有最少的相依性，您可以考慮改用個別的 wheel 檔案。 ### （建議） 使用 Zip of Wheels AWS 在 Glue 5.0 或更高版本中安裝其他 Python 程式庫 AWS Glue 5.0 及更高版本支援將多個車輪檔案封裝到包含綁定 Python 車輪的單一 zip 成品中，以實現更可靠和決定性的相依性管理。若要使用此方法，請使用`.gluewheels.zip`尾碼建立包含所有車輪相依性及其傳輸相依性的 zip 檔案，將其上傳至 Amazon S3，然後使用 `--additional-python-modules` 參數加以參考。請務必將 `--no-index` 新增至`--python-modules-installer-option`任務參數。透過此組態，輪子檔案的壓縮基本上可做為 pip 的本機索引，以解決執行時間的相依性。這消除了任務執行期間 PyPI 等外部套件儲存庫的相依性，為生產工作負載提供更高的穩定性和一致性。例如： ``` --additional-python-modules s3://amzn-s3-demo-bucket/path/to/zip-of-wheels-1.0.0.gluewheels.zip --python-modules-installer-option --no-index ``` 如需如何建立 wheel 檔案 zip 的說明，請參閱 [附錄 A：建立輪子壓縮成品](#glue-python-library-zip-of-wheels-appendix)。 ### 使用 Wheel 安裝其他 Python 程式庫 AWS Glue 支援使用存放在 Amazon S3 中的 wheel (.whl) 檔案安裝自訂 Python 套件。若要在 Glue AWS 任務中包含輪子檔案，請將儲存在 s3 中的輪子檔案逗號分隔清單提供給`--additional-python-modules`任務參數。例如： ``` --additional-python-modules s3://amzn-s3-demo-bucket/path/to/package-1.0.0-py3-none-any.whl,s3://your-bucket/path/to/another-package-2.1.0-cp311-cp311-linux_x86_64.whl ``` 當您需要自訂發行版本，或具有原生相依項的套件已針對正確的作業系統預先編譯時，此方法也支援。如需更多範例，請參閱[使用 Glue 2.0 從 Spark ETL 工作負載的 wheel AWS 建置 Python 模組。](https://aws.amazon.com/blogs/big-data/building-python-modules-from-a-wheel-for-spark-etl-workloads-using-aws-glue-2-0/) ### 使用 requirements.txt AWS 在 Glue 5.0 或更高版本中安裝其他 Python 程式庫 在 AWS Glue 5.0\$1 中，您可以提供 defacto 標準`requirements.txt`來管理 Python 程式庫相依性。若要這樣做，請提供下列兩個任務參數： + 索引鍵：`--python-modules-installer-option` 值：`-r` + 索引鍵：`--additional-python-modules` 值：`s3://path_to_requirements.txt` AWS Glue 5.0 節點一開始會載入 中指定的 Python 程式庫`requirements.txt`。 以下是範例 requirements.txt： ``` awswrangler==3.9.1 elasticsearch==8.15.1 PyAthena==3.9.0 PyMySQL==1.1.1 PyYAML==6.0.2 pyodbc==5.2.0 pyorc==0.9.0 redshift-connector==2.1.3 scipy==1.14.1 scikit-learn==1.5.2 SQLAlchemy==2.0.36 ``` **重要** 請謹慎使用此選項，尤其是在生產工作負載中。在執行時間從 PyPI 提取相依性具有高風險，因為您無法確定要解析什麼成品 pip。使用未鎖定的程式庫版本特別有風險，因為它會提取最新版本的 python 模組，這可能會導致突破性的變更或帶來不相容的 python 模組。這可能會導致任務失敗，因為 AWS Glue 任務環境中的 Python 安裝失敗。雖然鎖定程式庫版本可提高穩定性，但 pip 解析度仍未完全確定，因此可能會出現類似的問題。最佳實務是， AWS Glue 建議使用凍結的成品，例如輪子的壓縮或個別的輪子檔案 （如需詳細資訊[（建議） 使用 Zip of Wheels AWS 在 Glue 5.0 或更高版本中安裝其他 Python 程式庫](#glue-python-library-installing-zip-of-wheels)，請參閱 )。 **重要** 如果您未鎖定傳輸相依性的版本，則主要相依性可能會提取不相容的傳輸相依性版本。最佳實務是，所有程式庫版本都應固定，以提高 Glue AWS 任務的一致性。更好的是， AWS Glue 建議將您的相依性封裝到 wheel 壓縮檔中，以確保生產工作負載的最大一致性和可靠性。 ### 直接將其他 Python 程式庫設定為逗號分隔清單 若要更新 或 新增 Python 模組 AWS Glue，允許使用逗號分隔 Python 模組的清單做為值傳遞`--additional-python-modules`參數。例如，若要更新或新增 scikit-learn 模組，請使用下列金鑰/值：`"--additional-python-modules", "scikit-learn==0.21.3"`。您有兩個選項可以直接設定 python 模組。 + **固定 Python 模組** `"--additional-python-modules", "scikit-learn==0.21.3,ephem==4.1.6"` + **未固定的 Python 模組：(不建議用於生產工作負載)** `"--additional-python-modules", "scikit-learn>==0.20.0,ephem>=4.0.0"` 或 `"--additional-python-modules", "scikit-learn,ephem"` **重要** 請謹慎使用此選項，尤其是在生產工作負載中。在執行時間從 PyPI 提取相依性具有高風險，因為您無法確定要解析什麼成品 pip。使用未鎖定的程式庫版本特別有風險，因為它會提取最新版本的 python 模組，這可能會導致突破性的變更或帶來不相容的 python 模組。這可能會導致任務失敗，因為 AWS Glue 任務環境中的 Python 安裝失敗。雖然鎖定程式庫版本可提高穩定性，但 pip 解析度仍未完全確定，因此可能會出現類似的問題。最佳實務是， AWS Glue 建議使用凍結的成品，例如輪子的壓縮或個別的輪子檔案 （如需詳細資訊[（建議） 使用 Zip of Wheels AWS 在 Glue 5.0 或更高版本中安裝其他 Python 程式庫](#glue-python-library-installing-zip-of-wheels)，請參閱 )。 **重要** 如果您未鎖定傳輸相依性的版本，則主要相依性可能會提取不相容的傳輸相依性版本。最佳實務是，所有程式庫版本都應固定，以提高 Glue AWS 任務的一致性。更好的是， AWS Glue 建議將您的相依性封裝到 wheel 壓縮檔中，以確保生產工作負載的最大一致性和可靠性。 ## 包括 Python 檔案與 PySpark 原生功能 AWS Glue 使用 PySpark 在 Glue ETL AWS 任務中包含 Python 檔案。您需使用可用的 `--additional-python-modules` 管理相依性。您可以使用 `--extra-py-files` 任務參數來包含 Python 檔案。相依性必須在 Amazon S3 中託管，且引數值應為以逗號分隔的 Amazon S3 路徑清單，並不含空格。此功能的行為類似於您搭配 Spark 使用的 Python 相依性管理。有關 Spark 中 Python 相依性管理的詳細資訊，請參閱 Apache Spark 文件中的 [Using PySpark Native Features](https://spark.apache.org/docs/latest/api/python/tutorial/python_packaging.html#using-pyspark-native-features) (使用 PySpark 原生功能) 頁面。在未封裝其他程式碼的情況下，或者當您使用現有工具鏈移轉 Spark 程式以管理相依性時，`--extra-py-files` 非常有用。為了使您的相依性工具可維護，您必須在提交之前綁定相依性。 ## 使用視覺化轉換的程式設計指令碼 當您使用 AWS Glue Studio 視覺化界面建立 Glue AWS 任務時，您可以使用受管資料轉換節點和自訂視覺化轉換來轉換資料。如需有關受管資料轉換節點的詳細資訊，請參閱[使用 AWS Glue 受管轉換來轉換資料](edit-jobs-transforms.md)。如需有關自訂視覺化轉換的詳細資訊，請參閱[使用自訂視覺化轉換來轉換資料](custom-visual-transform.md)。只有在任務**語言**設定為使用 Python 時，才能使用視覺化轉換產生指令碼。 使用視覺化轉換產生 AWS Glue 任務時， AWS Glue Studio 會使用任務組態中的 `--extra-py-files` 參數，將這些轉換包含在執行時間環境中。如需有關任務參數的詳細資訊，請參閱 [在 Glue AWS 任務中使用任務參數](aws-glue-programming-etl-glue-arguments.md)。對產生的指令碼或執行時期環境進行變更時，您需要保留此任務組態，指令碼才能成功執行。 ## 壓縮程式庫以加入 除非程式庫包含在單一的 `.py` 檔案裡，否則應封裝於 `.zip` 封存中。套件目錄應位於封存的根目錄，且套件必須包含一個 `__init__.py` 檔案。接著 Python 就可以正常匯入套件。 如果程式庫僅由一個 `.py` 檔案裡的單一 Python 模組組成，則不必將其置於 `.zip` 檔案。 ## 在 Glue Studio AWS 筆記本中載入 Python 程式庫 若要在 Glue Studio AWS 筆記本中指定 Python 程式庫，請參閱[安裝其他 Python 模組。 ](https://docs.aws.amazon.com/glue/latest/dg/manage-notebook-sessions.html#specify-default-modules) ## 在 Glue 0.9/1.0 的開發端點中載入 Python AWS 程式庫 若要將不同的程式庫集用於不同的 ETL 指令碼，您可以為各程式庫集設定個別的開發端點，或是覆寫每次切換指令碼時開發端點載入的程式庫 `.zip` 檔案。 在建立開發端點時，您可以使用主控台為其指定一或多個程式庫 .zip 檔案。指派名稱和 IAM 角色後，請選擇 **Script Libraries and job parameters (optional)** [指令碼程式庫與任務參數 (選用)]，並在 `.zip`Python library path** (Python 程式庫路徑) 方塊中輸入程式庫 ** 檔案的完整 Amazon S3 路徑。例如： ``` s3://bucket/prefix/site-packages.zip ``` 您也可以為檔案指定多個完整路徑，以逗號但不含空格的方式隔開，例如： ``` s3://bucket/prefix/lib_A.zip,s3://bucket_B/prefix/lib_X.zip ``` 如果您在後來更新這些 `.zip` 檔案，您可以使用主控台將檔案重新匯入開發端點。導覽至該開發端點，從 **Action** (動作) 選單選擇 **Update ETL libraries** (更新 ETL 程式庫)。 以類似的方式，您可以使用 Glue APIs AWS 指定程式庫檔案。呼叫 [CreateDevEndpoint 動作 (Python: create\$1dev\$1endpoint)](aws-glue-api-dev-endpoint.md#aws-glue-api-dev-endpoint-CreateDevEndpoint) 以建立開發端點時，您可以在 `ExtraPythonLibsS3Path` 參數中為程式庫指定一個或多個完整路徑，而呼叫的格式如下： ``` dep = glue.create_dev_endpoint( EndpointName="testDevEndpoint", RoleArn="arn:aws:iam::123456789012", SecurityGroupIds="sg-7f5ad1ff", SubnetId="subnet-c12fdba4", PublicKey="ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCtp04H/y...", NumberOfNodes=3, ExtraPythonLibsS3Path="s3://bucket/prefix/lib_A.zip,s3://bucket_B/prefix/lib_X.zip") ``` 更新開發端點時，您也可以更新其載入的程式庫，方式是使用 [DevEndpointCustomLibraries](aws-glue-api-dev-endpoint.md#aws-glue-api-dev-endpoint-DevEndpointCustomLibraries) 物件，並在呼叫 [UpdateDevEndpoint (update\$1dev\$1endpoint)](aws-glue-api-dev-endpoint.md#aws-glue-api-dev-endpoint-UpdateDevEndpoint) 時將 `UpdateEtlLibraries ` 參數設定為 `True`。 ## 在任務或 JobRun 使用 Python 程式庫 在主控台建立新任務時，您可以指定一個或多個程式庫 .zip 檔案，方式是選擇 **Script Libraries and job parameters (optional) (指令碼程式庫與任務參數 (選用))**，並以與建立開發端點相同的方式輸入完整 Amazon S3 路徑： ``` s3://bucket/prefix/lib_A.zip,s3://bucket_B/prefix/lib_X.zip ``` 若要呼叫 [CreateJob (create\$1job)](aws-glue-api-jobs-job.md#aws-glue-api-jobs-job-CreateJob)，您可以使用 `--extra-py-files` 預設參數來為預設程式庫指定一個或多個完整路徑，如下所示： ``` job = glue.create_job(Name='sampleJob', Role='Glue_DefaultRole', Command={'Name': 'glueetl', 'ScriptLocation': 's3://my_script_bucket/scripts/my_etl_script.py'}, DefaultArguments={'--extra-py-files': 's3://bucket/prefix/lib_A.zip,s3://bucket_B/prefix/lib_X.zip'}) ``` 接著，啟動 JobRun 時，您可以用不同的內容覆寫預設程式庫設定： ``` runId = glue.start_job_run(JobName='sampleJob', Arguments={'--extra-py-files': 's3://bucket/prefix/lib_B.zip'}) ``` ## 主動分析 Python 相依項 若要在部署至 Glue AWS 之前主動識別潛在的相依性問題，您可以使用相依性分析工具，針對目標 Glue 環境驗證 Python AWS 套件。 AWS 提供專為 Glue 環境設計的開放原始碼 Python AWS 相依性分析器工具。此工具可在 AWS Glue 範例儲存庫中使用，並可在本機用來在部署之前驗證您的相依性。 此分析有助於確保您的相依項遵循固定所有程式庫版本以實現一致生產部署的建議實務。如需詳細資訊，請參閱工具的 [README](https://github.com/aws-samples/aws-glue-samples/tree/master/utilities/glue_python_dependency_analyzer)。 ### 使用 AWS Glue 相依性分析器 AWS Glue Python 相依性分析器透過使用符合您目標 Glue AWS 環境的平台特定限制來模擬 pip 安裝，協助識別未鎖定的相依性和版本衝突。 ``` # Analyze a single Glue job python glue_dependency_analyzer.py -j my-glue-job # Analyze multiple jobs with specific AWS configuration python glue_dependency_analyzer.py -j job1 -j job2 --aws-profile production --aws-region us-west-2 ``` 工具會標記： + 可跨任務執行安裝不同版本的未固定相依項 + 套件之間的版本衝突 + 您的目標 Glue AWS 環境無法使用相依性 ## 使用 Amazon Q Developer 分析和修正因 Python 相依項造成的任務失敗 Amazon Q Developer 是生成式人工智慧 (AI) 支援的對話式助理，可協助您了解、建置、擴展和操作 AWS 應用程式。您可以遵循 Amazon Q 入門指南中的指示進行下載。 Amazon Q Developer 可用於分析和修正因 python 相依項而導致的任務失敗。我們建議您使用下列提示，將任務 預留位置取代為您的 Glue 任務名稱。 ``` I have an AWS Glue job named that has failed due to Python module installation conflicts. Please assist in diagnosing and resolving this issue using the following systematic approach. Proceed once sufficient information is available. Objective: Implement a fix that addresses the root cause module while minimizing disruption to the existing working environment. Step 1: Root Cause Analysis • Retrieve the most recent failed job run ID for the specified Glue job • Extract error logs from CloudWatch Logs using the job run ID as a log stream prefix • Analyze the logs to identify: • The recently added or modified Python module that triggered the dependency conflict • The specific dependency chain causing the installation failure • Version compatibility conflicts between required and existing modules Step 2: Baseline Configuration Identification • Locate the last successful job run ID prior to the dependency failure • Document the Python module versions that were functioning correctly in that baseline run • Establish the compatible version constraints for conflicting dependencies Step 3: Targeted Resolution Implementation • Apply pinning by updating the job's additional_python_modules parameter • Pin only the root cause module and its directly conflicting dependencies to compatible versions, and do not remove python modules unless necessary • Preserve flexibility for non-conflicting modules by avoiding unnecessary version constraints • Deploy the configuration changes with minimal changes to the existing configuration and execute a validation test run. Do not change the Glue versions. Implementation Example: Scenario: Recently added pandas==2.0.0 to additional_python_modules Error: numpy version conflict (pandas 2.0.0 requires numpy>=1.21, but existing job code requires numpy<1.20) Resolution: Update additional_python_modules to "pandas==1.5.3,numpy==1.19.5" Rationale: Use pandas 1.5.3 (compatible with numpy 1.19.5) and pin numpy to last known working version Expected Outcome: Restore job functionality with minimal configuration changes while maintaining system stability. ``` 提示指示 Q 執行下列動作： 1. 擷取最近失敗的任務執行 ID 1. 尋找關聯的日誌和詳細資訊 1. 尋找成功的任務執行，以偵測任何變更的 Python 套件 1. 進行任何組態修正並觸發另一個測試執行 ## Python 模組已在 Glue AWS 中提供 若要變更這些已提供模組的版本，請提供帶有 `--additional-python-modules` 任務參數的新版本。 ------ #### [ AWS Glue version 5.1 ] AWS Glue 5.1 版包含以下立即可用的 Python 模組： + aiobotocore==2.25.1 + aiohappyeyeballs==2.6.1 + aiohttp==3.13.2 + aioitertools==0.12.0 + aiosignal==1.4.0 + appdirs==1.4.4 + attrs==25.4.0 + boto3==1.40.61 + botocore==1.40.61 + certifi==2025.10.5 + charset-normalizer==3.4.4 + 編排人員==1.2.0 + contourpy==1.3.3 + cycler==0.12.1 + distlib==0.4.0 + filelock==3.20.0 + fonttools==4.60.1 + frozenlist==1.8.0 + fsspec==2025.10.0 + idna==3.11 + iniconfig==2.3.0 + jmespath==1.0.1 + kaleido==1.2.0 + kiwisolver==1.4.9 + logistro==2.0.1 + matplotlib==3.10.7 + multidict==6.7.0 + narwhals==2.10.2 + numpy==2.3.4 + orjson==3.11.4 + packaging==25.0 + pandas==2.3.3 + blocked=12.0.0 + pip==24.0 + platformdirs==4.5.0 + plotly==6.4.0 + pluggy==1.6.0 + propcache==0.4.1 + pyarrow==22.0.0 + Pygments==2.19.2 + pyparsing==3.2.5 + pytest-timeout==2.4.0 + pytest==8.4.2 + python-dateutil==2.9.0.post0 + pytz==2025.2 + 請求==2.32.5 + s3fs==2025.10.0 + s3transfer==0.14.0 + seaborn==0.13.2 + setuptools==79.0.1 + simplejson==3.20.2 + 六==1.17.0 + 韌性==9.1.2 + type\$1extensions==4.15.0 + tzdata==2025.2 + urllib3==2.5.0 + uv==0.9.7 + virtualenv==20.35.4 + wrapt==1.17.3 + yarl==1.22.0 ------ #### [ AWS Glue version 5.0 ] AWS Glue 5.0 版包含以下立即可用的 Python 模組： + aiobotocore==2.13.1 + aiohappyeyeballs==2.3.5 + aiohttp==3.10.1 + aioitertools==0.11.0 + aiosignal==1.3.1 + appdirs==1.4.4 + attrs==24.2.0 + boto3==1.34.131 + botocore==1.34.131 + certifi==2024.7.4 + charset-normalizer==3.3.2 + contourpy==1.2.1 + cycler==0.12.1 + fonttools==4.53.1 + frozenlist==1.4.1 + fsspec==2024.6.1 + idna==2.10 + jmespath==0.10.0 + kaleido==0.2.1 + kiwisolver==1.4.5 + matplotlib==3.9.0 + multidict==6.0.5 + numpy==1.26.4 + packaging==24.1 + pandas==2.2.2 + blocked==10.4.0 + pip==23.0.1 + plotly==5.23.0 + pyarrow==17.0.0 + pyparsing==3.1.2 + python-dateutil==2.9.0.post0 + pytz==2024.1 + requests==2.32.2 + s3fs==2024.6.1 + s3transfer==0.10.2 + seaborn==0.13.2 + setuptools==59.6.0 + six==1.16.0 + tenacity==9.0.0 + tzdata==2024.1 + urllib3==1.25.10 + virtualenv==20.4.0 + wrapt==1.16.0 + yarl==1.9.4 ------ #### [ AWS Glue version 4.0 ] AWS Glue 4.0 版包含以下立即可用的 Python 模組： + aiobotocore==2.4.1 + aiohttp==3.8.3 + aioitertools==0.11.0 + aiosignal==1.3.1 + async-timeout==4.0.2 + asynctest==0.13.0 + attrs==22.2.0 + avro-python3==1.10.2 + boto3==1.24.70 + botocore==1.27.59 + certifi==2021.5.30 + chardet==3.0.4 + charset-normalizer==2.1.1 + click==8.1.3 + cycler==0.10.0 + Cython==0.29.32 + fsspec==2021.8.1 + idna==2.10 + importlib-metadata==5.0.0 + jmespath==0.10.0 + joblib==1.0.1 + kaleido==0.2.1 + kiwisolver==1.4.4 + matplotlib==3.4.3 + mpmath==1.2.1 + multidict==6.0.4 + nltk==3.7 + numpy==1.23.5 + packaging==23.0 + pandas==1.5.1 + patsy==0.5.1 + Pillow==9.4.0 + pip==23.0.1 + plotly==5.16.0 + pmdarima==2.0.1 + ptvsd==4.3.2 + pyarrow==10.0.0 + pydevd==2.5.0 + pyhocon==0.3.58 + PyMySQL==1.0.2 + pyparsing==2.4.7 + python-dateutil==2.8.2 + pytz==2021.1 + PyYAML==6.0.1 + regex==2022.10.31 + requests==2.23.0 + s3fs==2022.11.0 + s3transfer==0.6.0 + scikit-learn==1.1.3 + scipy==1.9.3 + setuptools==49.1.3 + six==1.16.0 + statsmodels==0.13.5 + subprocess32==3.5.4 + sympy==1.8 + tbats==1.1.0 + threadpoolctl==3.1.0 + tqdm==4.64.1 + typing\$1extensions==4.4.0 + urllib3==1.25.11 + wheel==0.37.0 + wrapt==1.14.1 + yarl==1.8.2 + zipp==3.10.0 ------ #### [ AWS Glue version 3.0 ] AWS Glue 3.0 版包含以下立即可用的 Python 模組： + aiobotocore==1.4.2 + aiohttp==3.8.3 + aioitertools==0.11.0 + aiosignal==1.3.1 + async-timeout==4.0.2 + asynctest==0.13.0 + attrs==22.2.0 + avro-python3==1.10.2 + boto3==1.18.50 + botocore==1.21.50 + certifi==2021.5.30 + chardet==3.0.4 + charset-normalizer==2.1.1 + click==8.1.3 + cycler==0.10.0 + Cython==0.29.4 + docutils==0.17.1 + enum34==1.1.10 + frozenlist==1.3.3 + fsspec==2021.8.1 + idna==2.10 + importlib-metadata==6.0.0 + jmespath==0.10.0 + joblib==1.0.1 + kiwisolver==1.3.2 + matplotlib==3.4.3 + mpmath==1.2.1 + multidict==6.0.4 + nltk==3.6.3 + numpy==1.19.5 + packaging==23.0 + pandas==1.3.2 + patsy==0.5.1 + Pillow==9.4.0 + pip==23.0 + pmdarima==1.8.2 + ptvsd==4.3.2 + pyarrow==5.0.0 + pydevd==2.5.0 + pyhocon==0.3.58 + PyMySQL==1.0.2 + pyparsing==2.4.7 + python-dateutil==2.8.2 + pytz==2021.1 + PyYAML==5.4.1 + regex==2022.10.31 + requests==2.23.0 + s3fs==2021.8.1 + s3transfer==0.5.0 + scikit-learn==0.24.2 + scipy==1.7.1 + six==1.16.0 + Spark==1.0 + statsmodels==0.12.2 + subprocess32==3.5.4 + sympy==1.8 + tbats==1.1.0 + threadpoolctl==3.1.0 + tqdm==4.64.1 + typing\$1extensions==4.4.0 + urllib3==1.25.11 + wheel==0.37.0 + wrapt==1.14.1 + yarl==1.8.2 + zipp==3.12.0 ------ #### [ AWS Glue version 2.0 ] AWS Glue 2.0 版包含以下立即可用的 Python 模組： + avro-python3==1.10.0 + awscli==1.27.60 + boto3==1.12.4 + botocore==1.15.4 + certifi==2019.11.28 + chardet==3.0.4 + click==8.1.3 + colorama==0.4.4 + cycler==0.10.0 + Cython==0.29.15 + docutils==0.15.2 + enum34==1.1.9 + fsspec==0.6.2 + idna==2.9 + importlib-metadata==6.0.0 + jmespath==0.9.4 + joblib==0.14.1 + kiwisolver==1.1.0 + matplotlib==3.1.3 + mpmath==1.1.0 + nltk==3.5 + numpy==1.18.1 + pandas==1.0.1 + patsy==0.5.1 + pmdarima==1.5.3 + ptvsd==4.3.2 + pyarrow==0.16.0 + pyasn1==0.4.8 + pydevd==1.9.0 + pyhocon==0.3.54 + PyMySQL==0.9.3 + pyparsing==2.4.6 + python-dateutil==2.8.1 + pytz==2019.3 + PyYAML==5.3.1 + regex==2022.10.31 + requests==2.23.0 + rsa==4.7.2 + s3fs==0.4.0 + s3transfer==0.3.3 + scikit-learn==0.22.1 + scipy==1.4.1 + setuptools==45.2.0 + six==1.14.0 + Spark==1.0 + statsmodels==0.11.1 + subprocess32==3.5.4 + sympy==1.5.1 + tbats==1.0.9 + tqdm==4.64.1 + typing-extensions==4.4.0 + urllib3==1.25.8 + wheel==0.35.1 + zipp==3.12.0 ------ ## 附錄 A：建立輪子壓縮成品 我們示範如何建立輪子成品的壓縮。顯示的範例會將套件 `cryptography`和 下載`scipy`到輪子成品的壓縮中，並將輪子的壓縮複製到 Amazon S3 位置。 1. 您必須執行命令，以在類似 Glue 環境的 Amazon Linux 環境中建立輪子的壓縮。請參閱 [附錄 B： AWS Glue 環境詳細資訊](#glue-python-libraries-environment-details)。Glue 5.1 使用 AL2023 搭配 python 3.11 版。建立將建置此環境的 Dockerfile： ``` FROM --platform=linux/amd64 public.ecr.aws/amazonlinux/amazonlinux:2023-minimal # Install Python 3.11, pip, and zip utility RUN dnf install -y python3.11 pip zip && \ dnf clean all WORKDIR /build ``` 1. 建立 requirements.txt 檔案 ``` cryptography scipy ``` 1. 建置和啟動 Docker 容器 ``` # Build docker image docker build --platform linux/amd64 -t glue-wheel-builder . # Spin up container docker run --platform linux/amd64 -v $(pwd)/requirements.txt:/input/requirements.txt:ro -v $(pwd):/output -it glue-wheel-builder bash ``` 1. 在 docker 映像中執行下列命令 ``` # Create a directory for the wheels mkdir wheels # Copy requirements.txt into wheels directory cp /input/requirements.txt wheels/ # Download the wheels with the correct platform and Python version pip3 download \ -r wheels/requirements.txt \ --dest wheels/ \ --platform manylinux2014_x86_64 \ --python-version 311 \ --only-binary=:all: # Package the wheels into a zip archive with the .gluewheels.zip suffix zip -r mylibraries-1.0.0.gluewheels.zip wheels/ # Copy zip to output cp mylibraries-1.0.0.gluewheels.zip /output/ # Exit the container exit ``` 1. 將輪子的壓縮上傳到 Amazon S3 位置 ``` aws s3 cp mylibraries-1.0.0.gluewheels.zip s3://amzn-s3-demo-bucket/example-prefix/ ``` 1. 選用清除 ``` rm mylibraries-1.0.0.gluewheels.zip rm Dockerfile rm requirements.txt ``` 1. 使用以下任務引數執行 Glue 任務： ``` --additional-python-modules s3://amzn-s3-demo-bucket/example-prefix/mylibraries-1.0.0.gluewheels.zip --python-modules-installer-option --no-index ``` ## 附錄 B： AWS Glue 環境詳細資訊 **Glue 版本相容性和安裝方法** | AWS Glue 版本 | Python 版本 | 基礎映像 | glibc 版本 | 相容平台標籤 | | --- | --- | --- | --- | --- | | 5.1 | 3.11 | [Amazon Linux 2023 (AL2023)](https://aws.amazon.com/linux/amazon-linux-2023/) | 2.34 | manylinux\$12\$134\$1x86\$164 manylinux\$12\$128\$1x86\$164 manylinux2014\$1x86\$164 | | 5.0 | 3.11 | [Amazon Linux 2023 (AL2023)](https://aws.amazon.com/linux/amazon-linux-2023/) | 2.34 | manylinux\$12\$134\$1x86\$164 manylinux\$12\$128\$1x86\$164 manylinux2014\$1x86\$164 | | 4.0 | 3.10 | [Amazon Linux 2 (AL2)](https://aws.amazon.com/amazon-linux-2/) | 2.26 | manylinux2014\$1x86\$164 | | 3.0 | 3.7 | [Amazon Linux 2 (AL2)](https://aws.amazon.com/amazon-linux-2/) | 2.26 | manylinux2014\$1x86\$164 | | 2.0 | 3.7 | [Amazon Linux AMI (AL1)](https://aws.amazon.com/amazon-linux-ami/) | 2.17 | manylinux2014\$1x86\$164 | 在[AWS 共同責任模型](https://aws.amazon.com/compliance/shared-responsibility-model/)下，您負責管理與 Glue ETL 任務搭配使用的其他 Python AWS 模組、程式庫及其相依性。這包括套用更新和安全性修補程式。 AWS Glue 不支援在任務環境中編譯原生程式碼。不過， AWS Glue 任務會在 Amazon 受管 Linux 環境中執行。透過 Python wheel 檔案，您也許能夠以編譯形式提供原生相依項。如需 Glue AWS 版本相容性詳細資訊，請參閱上表。 **重要** 使用不相容的相依項可能會導致執行時期問題，尤其是對於必須與目標環境的架構和系統庫相符的原生延伸模組的程式庫。每個 AWS Glue 版本都會在具有預先安裝程式庫和系統組態的特定 Python 版本上執行。 # AWS Glue Python 程式碼範例 + [程式碼範例：加入和關聯化資料](aws-glue-programming-python-samples-legislators.md) + [程式碼範例：使用 ResolveChoice、Lambda 和 ApplyMapping 的資料準備](aws-glue-programming-python-samples-medicaid.md) # 程式碼範例：加入和關聯化資料 本範例使用從 [http://everypolitician.org/](http://everypolitician.org/) 下載至 Amazon Simple Storage Service (Amazon S3) 的 `sample-dataset` 儲存貯體的資料集：`s3://awsglue-datasets/examples/us-legislators/all`。資料集包含美國國會議員和他們在美國眾議院和參議院內座位的 JSON 格式的資料，已針對教學用途稍作修改，並透過公有 Amazon S3 儲存貯體提供。 您可在 GitHub 網站 [AWS Glue 儲存庫範例](https://github.com/awslabs/aws-glue-samples)的 `join_and_relationalize.py` 檔案中找到此範例的原始程式碼。 本指南將利用這項資料告訴您如何執行下列動作： + 使用AWS Glue爬蟲程式來分類存放在公有 Amazon S3 儲存貯體中的物件，並將其結構描述儲存至 AWS Glue Data Catalog。 + 檢查爬蟲程式所產生的資料表中繼資料和結構描述。 + 編寫 Python 擷取、傳輸和載入 (ETL) 指令碼，使用 Data Catalog 中的中繼資料執行下列動作： + 將來自不同原始檔案的資料加入到單一資料表 (也就是將資料去正規化)。 + 篩選加入的資料表，依國會議員類型放入不同的資料表。 + 將產生的資料寫入到單獨的 Apache Parquet 檔案中，供以後分析之用。 在 上執行時偵錯 Python 或 PySpark 指令碼的偏好方法是 AWS 在 [Glue Studio AWS 上使用筆記本](https://docs.aws.amazon.com/glue/latest/ug/notebooks-chapter.html)。 ## 步驟 1：在 Amazon S3 儲存貯體中網路爬取資料 1. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/) 開啟 AWS Glue主控台。 1. 遵循 中的步驟[設定編目程式](define-crawler.md)，建立新的爬蟲程式，可將`s3://awsglue-datasets/examples/us-legislators/all`資料集編目到 Glue Data Catalog `legislators`中名為 AWS 的資料庫。範例資料已放在這個公有 Amazon S3 儲存貯體中。 1. 執行新的爬蟲程式，接著查看 `legislators` 資料庫。 爬蟲程式建立下列中繼資料資料表： + `persons_json` + `memberships_json` + `organizations_json` + `events_json` + `areas_json` + `countries_r_json` 這是一個包含國會議員和其歷史的半標準化資料表集合。 ## 步驟 2：新增樣板指令碼至開發端點筆記本 將以下樣板指令碼貼至開發端點以匯入您需要的 AWS Glue 程式庫，並且設定單一的 `GlueContext`： ``` 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 glueContext = GlueContext(SparkContext.getOrCreate()) ``` ## 步驟 3：從資料目錄中的資料檢查結構描述 接下來，您可以從 Glue Data Catalog AWS 輕鬆建立檢查 DynamicFrame，並檢查資料的結構描述。例如，若要查看 `persons_json` 資料表的結構描述，請將下列內容新增到筆記本： ``` persons = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="persons_json") print "Count: ", persons.count() persons.printSchema() ``` 以下為列印呼叫的輸出： ``` Count: 1961 root |-- family_name: string |-- name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- gender: string |-- image: string |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- other_names: array | |-- element: struct | | |-- note: string | | |-- name: string | | |-- lang: string |-- sort_name: string |-- images: array | |-- element: struct | | |-- url: string |-- given_name: string |-- birth_date: string |-- id: string |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string |-- death_date: string ``` 資料表中的每個人都是美國國會的成員。 若要檢視 `memberships_json` 資料表的結構描述，請輸入如下命令： ``` memberships = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="memberships_json") print "Count: ", memberships.count() memberships.printSchema() ``` 其輸出如下： ``` Count: 10439 root |-- area_id: string |-- on_behalf_of_id: string |-- organization_id: string |-- role: string |-- person_id: string |-- legislative_period_id: string |-- start_date: string |-- end_date: string ``` `organizations` 為政黨和參議院與眾議院這兩個議會殿堂。若要檢視 `organizations_json` 資料表的結構描述，請輸入如下命令： ``` orgs = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="organizations_json") print "Count: ", orgs.count() orgs.printSchema() ``` 其輸出如下： ``` Count: 13 root |-- classification: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- image: string |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- other_names: array | |-- element: struct | | |-- lang: string | | |-- note: string | | |-- name: string |-- id: string |-- name: string |-- seats: int |-- type: string ``` ## 步驟 4：篩選資料 接著，保留需要的欄位，將 `id` 重新命名為 `org_id`。資料集很小，可以從整體來檢視。 `toDF()` 會將 `DynamicFrame` 轉換為 Apache Spark `DataFrame`，因此您可套用 Apache Spark SQL 中現有的轉換： ``` orgs = orgs.drop_fields(['other_names', 'identifiers']).rename_field( 'id', 'org_id').rename_field( 'name', 'org_name') orgs.toDF().show() ``` 以下將顯示輸出： ``` +--------------+--------------------+--------------------+--------------------+-----+-----------+--------------------+ |classification| org_id| org_name| links|seats| type| image| +--------------+--------------------+--------------------+--------------------+-----+-----------+--------------------+ | party| party/al| AL| null| null| null| null| | party| party/democrat| Democrat|[[website,http://...| null| null|https://upload.wi...| | party|party/democrat-li...| Democrat-Liberal|[[website,http://...| null| null| null| | legislature|d56acebe-8fdc-47b...|House of Represen...| null| 435|lower house| null| | party| party/independent| Independent| null| null| null| null| | party|party/new_progres...| New Progressive|[[website,http://...| null| null|https://upload.wi...| | party|party/popular_dem...| Popular Democrat|[[website,http://...| null| null| null| | party| party/republican| Republican|[[website,http://...| null| null|https://upload.wi...| | party|party/republican-...|Republican-Conser...|[[website,http://...| null| null| null| | party| party/democrat| Democrat|[[website,http://...| null| null|https://upload.wi...| | party| party/independent| Independent| null| null| null| null| | party| party/republican| Republican|[[website,http://...| null| null|https://upload.wi...| | legislature|8fa6c3d2-71dc-478...| Senate| null| 100|upper house| null| +--------------+--------------------+--------------------+--------------------+-----+-----------+--------------------+ ``` 輸入以下以檢視出現在 `memberships` 的 `organizations`： ``` memberships.select_fields(['organization_id']).toDF().distinct().show() ``` 以下將顯示輸出： ``` +--------------------+ | organization_id| +--------------------+ |d56acebe-8fdc-47b...| |8fa6c3d2-71dc-478...| +--------------------+ ``` ## 步驟 5：全部整合為一 現在，使用 AWS Glue 加入這些關聯式表格，並建立一份關於國會議員 `memberships` 及其對應的 `organizations` 的完整歷史記錄資料表。 1. 首先，加入 `persons` 和 `memberships` 的 `id` 和 `person_id`。 1. 接著，將結果加入到 `orgs` 的 `org_id` 和 `organization_id`。 1. 然後，捨棄冗餘欄位 `person_id` 和 `org_id`。 您可以在同一 (延伸) 指令碼行執行所有這些操作： ``` l_history = Join.apply(orgs, Join.apply(persons, memberships, 'id', 'person_id'), 'org_id', 'organization_id').drop_fields(['person_id', 'org_id']) print "Count: ", l_history.count() l_history.printSchema() ``` 其輸出如下： ``` Count: 10439 root |-- role: string |-- seats: int |-- org_name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- type: string |-- sort_name: string |-- area_id: string |-- images: array | |-- element: struct | | |-- url: string |-- on_behalf_of_id: string |-- other_names: array | |-- element: struct | | |-- note: string | | |-- name: string | | |-- lang: string |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string |-- name: string |-- birth_date: string |-- organization_id: string |-- gender: string |-- classification: string |-- death_date: string |-- legislative_period_id: string |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- image: string |-- given_name: string |-- family_name: string |-- id: string |-- start_date: string |-- end_date: string ``` 您現在取得最終的資料表，可用於分析。您可以用精巧、有效率的格式編寫，以用於分析 (也就是 Parquet)，在 AWS Glue、Amazon Athena 或 Amazon Redshift Spectrum 上執行 SQL。 以下呼叫將資料表編寫到多個檔案，在稍後執行分析時支援快速平行讀取： ``` glueContext.write_dynamic_frame.from_options(frame = l_history, connection_type = "s3", connection_options = {"path": "s3://glue-sample-target/output-dir/legislator_history"}, format = "parquet") ``` 若要將所有歷史記錄資料合併成單一檔案，您必須將其轉換為資料框架、分割並編寫： ``` s_history = l_history.toDF().repartition(1) s_history.write.parquet('s3://glue-sample-target/output-dir/legislator_single') ``` 或者，如果您希望將其分為參議院和眾議院： ``` l_history.toDF().write.parquet('s3://glue-sample-target/output-dir/legislator_part', partitionBy=['org_name']) ``` ## 步驟 6：轉換關聯式資料庫的資料 AWS Glue 可讓您輕鬆地將資料寫入關聯式資料庫，例如 Amazon Redshift，即使是半結構化資料。其提供轉換 `relationalize`，可將 `DynamicFrames` 扁平化，無論框架中的物件多複雜。 使用本範例中的 `l_history` `DynamicFrame`，以根資料表 (`hist_root`) 的名稱和暫時任務路徑傳送至 `relationalize`。將傳回 `DynamicFrameCollection`。然後，您可以將 `DynamicFrames` 的名稱列在該集合中： ``` dfc = l_history.relationalize("hist_root", "s3://glue-sample-target/temp-dir/") dfc.keys() ``` 以下為 `keys` 呼叫的輸出： ``` [u'hist_root', u'hist_root_contact_details', u'hist_root_links', u'hist_root_other_names', u'hist_root_images', u'hist_root_identifiers'] ``` `Relationalize` 將歷史記錄資料表分成六個新資料表：根資料表包含在 `DynamicFrame` 中的各物件記錄，和陣列的輔助資料表。關聯式資料庫中的陣列處理通常為次最佳化，尤其在這些陣列變得龐大時。將陣列分成不同的資料表，可加快查詢速度。 接著，檢查 `contact_details` 以查看分隔： ``` l_history.select_fields('contact_details').printSchema() dfc.select('hist_root_contact_details').toDF().where("id = 10 or id = 75").orderBy(['id','index']).show() ``` 以下為 `show` 呼叫的輸出： ``` root |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string +---+-----+------------------------+-------------------------+ | id|index|contact_details.val.type|contact_details.val.value| +---+-----+------------------------+-------------------------+ | 10| 0| fax| | | 10| 1| | 202-225-1314| | 10| 2| phone| | | 10| 3| | 202-225-3772| | 10| 4| twitter| | | 10| 5| | MikeRossUpdates| | 75| 0| fax| | | 75| 1| | 202-225-7856| | 75| 2| phone| | | 75| 3| | 202-225-2711| | 75| 4| twitter| | | 75| 5| | SenCapito| +---+-----+------------------------+-------------------------+ ``` `contact_details` 欄位為原始 `DynamicFrame` 中結構的陣列。這些陣列的每個元素都是輔助資料表中的單獨資料列，以 `index` 編製索引。此處的 `id` 是 `hist_root` 資料表的外部金鑰，金鑰為 `contact_details`： ``` dfc.select('hist_root').toDF().where( "contact_details = 10 or contact_details = 75").select( ['id', 'given_name', 'family_name', 'contact_details']).show() ``` 以下為其輸出： ``` +--------------------+----------+-----------+---------------+ | id|given_name|family_name|contact_details| +--------------------+----------+-----------+---------------+ |f4fc30ee-7b42-432...| Mike| Ross| 10| |e3c60f34-7d1b-4c0...| Shelley| Capito| 75| +--------------------+----------+-----------+---------------+ ``` 請注意，這些命令將使用 `toDF()`，然後是 `where` 表達式，來篩選您想要查看的資料列。 因此，加入 `hist_root` 資料表與輔助資料表可執行下列動作： + 無需陣列支援便能將資料載入到資料庫。 + 使用 SQL 查詢陣列中的每個個別項目。 使用 AWS Glue 連線以安全存放和存取您的 Amazon Redshift 憑證。有關如何建立自己的連線的詳細資訊，請參閱 [連線至資料](glue-connections.md)。 您現已準備好透過一次循環一個 `DynamicFrames` 來將資料寫入連接器： ``` for df_name in dfc.keys(): m_df = dfc.select(df_name) print "Writing to table: ", df_name glueContext.write_dynamic_frame.from_jdbc_conf(frame = m_df, connection settings here) ``` 您的連接器設定將因您的關聯式資料庫類型而異： + 如需有關寫入 Amazon Redshift 的指示，請參閱[Redshift 連線](aws-glue-programming-etl-connect-redshift-home.md)。 + 若為其他資料庫，請參閱 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 ## 結論 整體而言，AWS Glue 極具彈性。它讓您用幾行程式碼便能完成通常要好幾天才能完成撰寫的任務。您可在 GitHub [AWS Glue 範例](https://github.com/awslabs/aws-glue-samples)的 Python 檔案 `join_and_relationalize.py` 中找到完整從來源到目標的 ETL 指令碼。 # 程式碼範例：使用 ResolveChoice、Lambda 和 ApplyMapping 的資料準備 此範例使用的資料集，包含從兩個 [Data.CMS.gov](https://data.cms.gov) 資料集下載的美國聯邦醫療保險 (Medicare) 供應商付款資料：「住院患者預期付款系統供應商前 100 大診斷相關群組摘要 - FY2011」和「住院患者費用資料 FY 2011」。下載資料之後，我們修改了資料集，以在檔案結尾處引入幾個錯誤記錄。上述經修改的檔案位於公有 Amazon S3 儲存貯體，位置在 `s3://awsglue-datasets/examples/medicare/Medicare_Hospital_Provider.csv`。 您可以在 `data_cleaning_and_lambda.py`[ examplesAWS Glue GitHub 儲存庫的 ](https://github.com/awslabs/aws-glue-samples) 檔案中找到此範例的原始碼。 在 上執行時偵錯 Python 或 PySpark 指令碼的偏好方法是 AWS 在 [Glue Studio AWS 上使用筆記本](https://docs.aws.amazon.com/glue/latest/ug/notebooks-chapter.html)。 ## 步驟 1：在 Amazon S3 儲存貯體中網路爬取資料 1. 登入 AWS 管理主控台 並在 https：//[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/) 開啟 AWS Glue主控台。 1. 遵循 中所述的程序[設定編目程式](define-crawler.md)，建立新的爬蟲程式，該爬蟲程式可以編目`s3://awsglue-datasets/examples/medicare/Medicare_Hospital_Provider.csv`檔案，並將產生的中繼資料放入 Glue Data Catalog `payments`中名為 AWS 的資料庫。 1. 執行新的爬蟲程式，接著查看 `payments` 資料庫。在讀取檔案開頭，確定其格式和分隔符號後，爬蟲程式應會於資料庫建立一個命名為 `medicare` 的中繼資料資料表。 新 `medicare` 資料表的結構描述如下： ``` Column name Data type ================================================== drg definition string provider id bigint provider name string provider street address string provider city string provider state string provider zip code bigint hospital referral region description string total discharges bigint average covered charges string average total payments string average medicare payments string ``` ## 步驟 2：新增樣板指令碼至開發端點筆記本 將以下樣板指令碼貼至開發端點以匯入您需要的 AWS Glue 程式庫，並且設定單一的 `GlueContext`： ``` 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 glueContext = GlueContext(SparkContext.getOrCreate()) ``` ## 步驟 3：比較不同的結構描述剖析 接著，您可以查看 Apache Spark `DataFrame` 辨識出的結構描述是否跟 AWS Glue 爬蟲程式所記錄的相同。執行此程式碼： ``` medicare = spark.read.format( "com.databricks.spark.csv").option( "header", "true").option( "inferSchema", "true").load( 's3://awsglue-datasets/examples/medicare/Medicare_Hospital_Provider.csv') medicare.printSchema() ``` 以下為 `printSchema` 呼叫的輸出： ``` root |-- DRG Definition: string (nullable = true) |-- Provider Id: string (nullable = true) |-- Provider Name: string (nullable = true) |-- Provider Street Address: string (nullable = true) |-- Provider City: string (nullable = true) |-- Provider State: string (nullable = true) |-- Provider Zip Code: integer (nullable = true) |-- Hospital Referral Region Description: string (nullable = true) |-- Total Discharges : integer (nullable = true) |-- Average Covered Charges : string (nullable = true) |-- Average Total Payments : string (nullable = true) |-- Average Medicare Payments: string (nullable = true) ``` 接著，查看 AWS Glue `DynamicFrame` 產生的結構描述： ``` medicare_dynamicframe = glueContext.create_dynamic_frame.from_catalog( database = "payments", table_name = "medicare") medicare_dynamicframe.printSchema() ``` `printSchema` 的輸出如下： ``` root |-- drg definition: string |-- provider id: choice | |-- long | |-- string |-- provider name: string |-- provider street address: string |-- provider city: string |-- provider state: string |-- provider zip code: long |-- hospital referral region description: string |-- total discharges: long |-- average covered charges: string |-- average total payments: string |-- average medicare payments: string ``` 在 `DynamicFrame` 產生的結構描述中，`provider id` 可以是 `long` 或 `string` 類型。`DataFrame` 結構描述將 `Provider Id` 列為 `string` 類型， Data Catalog 則是將 `provider id` 列為 `bigint` 類型。 何者正確？ 在檔案的最後有兩筆記錄 (總共 160,000 筆記錄)，且該欄位中有 `string` 值。這些就是之前引入以示範產生問題的錯誤記錄。 為了解決這種問題，AWS Glue`DynamicFrame` 採用 *choice (選擇)* 類型的概念。在此例中，`DynamicFrame` 展示了 `long` 和 `string` 值都會在該欄出現。AWS Glue 爬蟲程式遺漏了 `string` 值，原因是只考量到資料的前 2 MB。Apache Spark `DataFrame` 會考量整個資料集，但被強制將最普遍的類型指派給該欄位，亦即 `string`。事實上，Spark 在遇到複雜類型或不熟悉的變化時，通常都會採取最普遍的作法。 要查詢 `provider id` 欄，請先解決選擇類型。您可以使用 `DynamicFrame` 中的 `resolveChoice` 轉換方法，藉由以下的 `cast:long` 選項將 `string` 值轉換為 `long` 值。 ``` medicare_res = medicare_dynamicframe.resolveChoice(specs = [('provider id','cast:long')]) medicare_res.printSchema() ``` `printSchema` 輸出就會是： ``` root |-- drg definition: string |-- provider id: long |-- provider name: string |-- provider street address: string |-- provider city: string |-- provider state: string |-- provider zip code: long |-- hospital referral region description: string |-- total discharges: long |-- average covered charges: string |-- average total payments: string |-- average medicare payments: string ``` 如果有無法轉換的 `string` 值，AWS Glue 會插入 `null`。 另一個選項是將選擇類型轉換為 `struct`，這會保留兩種類型的值。 接著，查看異常的資料列。 ``` medicare_res.toDF().where("'provider id' is NULL").show() ``` 您會見到以下情況： ``` +--------------------+-----------+---------------+-----------------------+-------------+--------------+-----------------+------------------------------------+----------------+-----------------------+----------------------+-------------------------+ | drg definition|provider id| provider name|provider street address|provider city|provider state|provider zip code|hospital referral region description|total discharges|average covered charges|average total payments|average medicare payments| +--------------------+-----------+---------------+-----------------------+-------------+--------------+-----------------+------------------------------------+----------------+-----------------------+----------------------+-------------------------+ |948 - SIGNS & SYM...| null| INC| 1050 DIVISION ST| MAUSTON| WI| 53948| WI - Madison| 12| $11961.41| $4619.00| $3775.33| |948 - SIGNS & SYM...| null| INC- ST JOSEPH| 5000 W CHAMBERS ST| MILWAUKEE| WI| 53210| WI - Milwaukee| 14| $10514.28| $5562.50| $4522.78| +--------------------+-----------+---------------+-----------------------+-------------+--------------+-----------------+------------------------------------+----------------+-----------------------+----------------------+-------------------------+ ``` 現在移除兩筆不正確的記錄，如下所示： ``` medicare_dataframe = medicare_res.toDF() medicare_dataframe = medicare_dataframe.where("'provider id' is NOT NULL") ``` ## 步驟 4：映射資料並使用 Apache Spark Lambda 函數 AWS Glue 尚未直接支援 Lambda 函式，亦即使用者定義的函式。但是您隨時可以從 Apache Spark `DataFrame` 來回轉換 `DynamicFrame`，以利用除了 `DynamicFrames` 特殊功能之外的 Spark 功能。 接著，將付款資訊轉為數字，讓 Amazon Redshift 或 Amazon Athena 等分析引擎可以更快處理。 ``` from pyspark.sql.functions import udf from pyspark.sql.types import StringType chop_f = udf(lambda x: x[1:], StringType()) medicare_dataframe = medicare_dataframe.withColumn( "ACC", chop_f( medicare_dataframe["average covered charges"])).withColumn( "ATP", chop_f( medicare_dataframe["average total payments"])).withColumn( "AMP", chop_f( medicare_dataframe["average medicare payments"])) medicare_dataframe.select(['ACC', 'ATP', 'AMP']).show() ``` `show` 呼叫的輸出如下： ``` +--------+-------+-------+ | ACC| ATP| AMP| +--------+-------+-------+ |32963.07|5777.24|4763.73| |15131.85|5787.57|4976.71| |37560.37|5434.95|4453.79| |13998.28|5417.56|4129.16| |31633.27|5658.33|4851.44| |16920.79|6653.80|5374.14| |11977.13|5834.74|4761.41| |35841.09|8031.12|5858.50| |28523.39|6113.38|5228.40| |75233.38|5541.05|4386.94| |67327.92|5461.57|4493.57| |39607.28|5356.28|4408.20| |22862.23|5374.65|4186.02| |31110.85|5366.23|4376.23| |25411.33|5282.93|4383.73| | 9234.51|5676.55|4509.11| |15895.85|5930.11|3972.85| |19721.16|6192.54|5179.38| |10710.88|4968.00|3898.88| |51343.75|5996.00|4962.45| +--------+-------+-------+ only showing top 20 rows ``` 資料仍然全是字串。我們可以使用強大的 `apply_mapping` 轉換方法來捨棄、重新命名、轉換、巢套資料，讓其他資料程式設計語言和系統能夠輕易存取： ``` from awsglue.dynamicframe import DynamicFrame medicare_tmp_dyf = DynamicFrame.fromDF(medicare_dataframe, glueContext, "nested") medicare_nest_dyf = medicare_tmp_dyf.apply_mapping([('drg definition', 'string', 'drg', 'string'), ('provider id', 'long', 'provider.id', 'long'), ('provider name', 'string', 'provider.name', 'string'), ('provider city', 'string', 'provider.city', 'string'), ('provider state', 'string', 'provider.state', 'string'), ('provider zip code', 'long', 'provider.zip', 'long'), ('hospital referral region description', 'string','rr', 'string'), ('ACC', 'string', 'charges.covered', 'double'), ('ATP', 'string', 'charges.total_pay', 'double'), ('AMP', 'string', 'charges.medicare_pay', 'double')]) medicare_nest_dyf.printSchema() ``` `printSchema` 輸出如下： ``` root |-- drg: string |-- provider: struct | |-- id: long | |-- name: string | |-- city: string | |-- state: string | |-- zip: long |-- rr: string |-- charges: struct | |-- covered: double | |-- total_pay: double | |-- medicare_pay: double ``` 將資料轉回 Spark `DataFrame` 後，您就可以顯示其樣貌： ``` medicare_nest_dyf.toDF().show() ``` 其輸出如下： ``` +--------------------+--------------------+---------------+--------------------+ | drg| provider| rr| charges| +--------------------+--------------------+---------------+--------------------+ |039 - EXTRACRANIA...|[10001,SOUTHEAST ...| AL - Dothan|[32963.07,5777.24...| |039 - EXTRACRANIA...|[10005,MARSHALL M...|AL - Birmingham|[15131.85,5787.57...| |039 - EXTRACRANIA...|[10006,ELIZA COFF...|AL - Birmingham|[37560.37,5434.95...| |039 - EXTRACRANIA...|[10011,ST VINCENT...|AL - Birmingham|[13998.28,5417.56...| |039 - EXTRACRANIA...|[10016,SHELBY BAP...|AL - Birmingham|[31633.27,5658.33...| |039 - EXTRACRANIA...|[10023,BAPTIST ME...|AL - Montgomery|[16920.79,6653.8,...| |039 - EXTRACRANIA...|[10029,EAST ALABA...|AL - Birmingham|[11977.13,5834.74...| |039 - EXTRACRANIA...|[10033,UNIVERSITY...|AL - Birmingham|[35841.09,8031.12...| |039 - EXTRACRANIA...|[10039,HUNTSVILLE...|AL - Huntsville|[28523.39,6113.38...| |039 - EXTRACRANIA...|[10040,GADSDEN RE...|AL - Birmingham|[75233.38,5541.05...| |039 - EXTRACRANIA...|[10046,RIVERVIEW ...|AL - Birmingham|[67327.92,5461.57...| |039 - EXTRACRANIA...|[10055,FLOWERS HO...| AL - Dothan|[39607.28,5356.28...| |039 - EXTRACRANIA...|[10056,ST VINCENT...|AL - Birmingham|[22862.23,5374.65...| |039 - EXTRACRANIA...|[10078,NORTHEAST ...|AL - Birmingham|[31110.85,5366.23...| |039 - EXTRACRANIA...|[10083,SOUTH BALD...| AL - Mobile|[25411.33,5282.93...| |039 - EXTRACRANIA...|[10085,DECATUR GE...|AL - Huntsville|[9234.51,5676.55,...| |039 - EXTRACRANIA...|[10090,PROVIDENCE...| AL - Mobile|[15895.85,5930.11...| |039 - EXTRACRANIA...|[10092,D C H REGI...|AL - Tuscaloosa|[19721.16,6192.54...| |039 - EXTRACRANIA...|[10100,THOMAS HOS...| AL - Mobile|[10710.88,4968.0,...| |039 - EXTRACRANIA...|[10103,BAPTIST ME...|AL - Birmingham|[51343.75,5996.0,...| +--------------------+--------------------+---------------+--------------------+ only showing top 20 rows ``` ## 步驟 5：寫入資料至 Apache Parquet AWS Glue 可讓您輕鬆以關聯式資料庫能有效取用的格式 (例如 Apache Parquet) 撰寫資料： ``` glueContext.write_dynamic_frame.from_options( frame = medicare_nest_dyf, connection_type = "s3", connection_options = {"path": "s3://glue-sample-target/output-dir/medicare_parquet"}, format = "parquet") ``` # AWS Glue PySpark 延伸模組參考 AWS Glue 已建立 PySpark Python 方言的下列延伸。 + [使用 `getResolvedOptions` 存取參數](aws-glue-api-crawler-pyspark-extensions-get-resolved-options.md) + [PySpark 延伸模組類型](aws-glue-api-crawler-pyspark-extensions-types.md) + [DynamicFrame 類別](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md) + [DynamicFrameCollection 類別](aws-glue-api-crawler-pyspark-extensions-dynamic-frame-collection.md) + [DynamicFrameWriter 類別](aws-glue-api-crawler-pyspark-extensions-dynamic-frame-writer.md) + [DynamicFrameReader 類別](aws-glue-api-crawler-pyspark-extensions-dynamic-frame-reader.md) + [GlueContext 類別](aws-glue-api-crawler-pyspark-extensions-glue-context.md) # 使用 `getResolvedOptions` 存取參數 AWS Glue `getResolvedOptions(args, options)` 公用程式功能可讓您存取執行任務時傳送到指令碼的引數。若要使用此功能，請先從 AWS Glue `utils` 模組與 `sys` 模組一起匯入： ``` import sys from awsglue.utils import getResolvedOptions ``` **`getResolvedOptions(args, options)`** + `args` - `sys.argv` 所含的引數清單。 + `options` - 想要擷取之引數名稱的 Python 陣列。 **Example 擷取傳送到 JobRun 的引數** 假設您在指令碼內建立 JobRun，或許在 Lambda 函數內： ``` response = client.start_job_run( JobName = 'my_test_Job', Arguments = { '--day_partition_key': 'partition_0', '--hour_partition_key': 'partition_1', '--day_partition_value': day_partition_value, '--hour_partition_value': hour_partition_value } ) ``` 若要擷取傳送的引數，您可以使用 `getResolvedOptions` 函數，如下所示： ``` import sys from awsglue.utils import getResolvedOptions args = getResolvedOptions(sys.argv, ['JOB_NAME', 'day_partition_key', 'hour_partition_key', 'day_partition_value', 'hour_partition_value']) print "The day-partition key is: ", args['day_partition_key'] print "and the day-partition value is: ", args['day_partition_value'] ``` 請注意，每個引數的定義開頭形式為兩個連字號，在指令碼中參考的引數則不含連字號。引數只使用底線，不使用連字號。您的引數需要遵循此慣例才能被解析。 # PySpark 延伸模組類型 AWS Glue PySpark 延伸模組所使用的類型。 ## DataType 其他 Glue AWS 類型的基底類別。 **`__init__(properties={})`** + `properties` – 資料類型的屬性 (選用)。   **`typeName(cls)`** 傳回 AWS Glue 類型類別的類型 (亦即從尾端移除「Type」的類別名稱)。 + `cls` – 從 AWS Glue 衍生而來的 `DataType` 類別執行個體。   `jsonValue( )` 傳回 JSON 物件，其中包含類別的資料類型和屬性： ``` { "dataType": typeName, "properties": properties } ``` ## AtomicType 和 simple 衍生性產品 繼承自及延伸 [DataType](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-datatype) 類別，並做為所有 AWS Glue 不可部分完成資料類型的基本類別。 **`fromJsonValue(cls, json_value)`** 以來自 JSON 物件的值，初始化類別執行個體。 + `cls` – 要初始化的 AWS Glue 類別執行個體。 + `json_value` – 用於載入金鑰/值對的來源 JSON 物件。   以下類型為 [AtomicType](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-atomictype) 類別的簡單衍生產品： + `BinaryType` – 二進位資料。 + `BooleanType` – 布林值。 + `ByteType` – 位元組值。 + `DateType` – 日期時間值。 + `DoubleType` – 浮點雙精度值。 + `IntegerType` – 整數值。 + `LongType` – 長整數值。 + `NullType` – null 值。 + `ShortType` – 短整數值。 + `StringType` – 文字字串。 + `TimestampType` – 時間戳記值 (單位通常為 1970/1/1 起的秒數)。 + `UnknownType` – 無法識別類型的值。 ## DecimalType(AtomicType) 沿用自和延伸 [AtomicType](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-atomictype) 類別來代表十進位數字 (以十進位數字表示，而非二進位 base-2 數字)。 **`__init__(precision=10, scale=2, properties={})`** + `precision` – 十進位數字的位數 (選用，預設為 10)。 + `scale` – 小數點右邊的位數 (選用，預設為 2)。 + `properties` – 十進位數字段屬性 (選用)。 ## EnumType(AtomicType) 繼承自和延伸 [AtomicType](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-atomictype) 類別，以表示有效選項的列舉。 **`__init__(options)`** + `options` – 列舉的選項清單。 ##  集合類型 + [ArrayType(DataType)](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-arraytype) + [ChoiceType(DataType)](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-choicetype) + [MapType(DataType)](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-maptype) + [Field(Object)](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-field) + [StructType(DataType)](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-structtype) + [EntityType(DataType)](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-entitytype) ## ArrayType(DataType) **`__init__(elementType=UnknownType(), properties={})`** + `elementType` – 陣列中的元素類型 (選用，預設為 UnknownType)。 + `properties` – 陣列的屬性 (選用)。 ## ChoiceType(DataType) **`__init__(choices=[], properties={})`** + `choices` – 可能的選項清單 (選用)。 + `properties` – 這些選項的屬性 (選用)。   **`add(new_choice)`** 將選項新增至可能的選項清單。 + `new_choice` – 要加入至可能選項清單的選項。   **`merge(new_choices)`** 合併新選項的清單與現有的選項清單。 + `new_choices` – 合併新選項與現有選項的清單。 ## MapType(DataType) **`__init__(valueType=UnknownType, properties={})`** + `valueType` – 映射中的值類型 (選用，預設為 UnknownType)。 + `properties` – 映射的屬性 (選用)。 ## Field(Object) 從衍生自 [DataType](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-datatype) 的物件建立欄位物件。 **`__init__(name, dataType, properties={})`** + `name` – 要指派到欄位的名稱。 + `dataType` – 要從中建立欄位的物件。 + `properties` – 欄位的屬性 (選用)。 ## StructType(DataType) 定義資料結構 (`struct`)。 **`__init__(fields=[], properties={})`** + `fields` – 要包含在結構中的欄位 (`Field` 類型) 清單 (選用)。 + `properties` – 結構的屬性 (選用)。   **`add(field)`** + `field` – 要新增到架構的物件類型 `Field`。   **`hasField(field)`** 如果此結構有相同名稱的欄位，將傳回 `True`，否則將傳回 `False`。 + `field` – 欄位名稱，或名稱已使用的物件類型 `Field`。   **`getField(field)`** + `field` – 欄位名稱，或使用其名稱的物件類型 `Field`。如果結構有相同名稱的欄位，將會傳回。 ## EntityType(DataType) `__init__(entity, base_type, properties)` 此類別尚未實作。 ##  其他類型 + [DataSource(object)](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-data-source) + [DataSink(object)](#aws-glue-api-crawler-pyspark-extensions-types-awsglue-data-sink) ## DataSource(object) **`__init__(j_source, sql_ctx, name)`** + `j_source` – 資料來源。 + `sql_ctx` – SQL 內容。 + `name` – 資料來源名稱。   **`setFormat(format, **options)`** + `format` – 要用於設定資料來源的格式。 + `options` – 要用於設定資料來源的選項集合。如需有關格式選項的詳細資訊，請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md)。   `getFrame()` 傳回資料來源的 `DynamicFrame`。 ## DataSink(object) **`__init__(j_sink, sql_ctx)`** + `j_sink` – 要建立的目的地。 + `sql_ctx` – 資料目的地的 SQL 內容。   **`setFormat(format, **options)`** + `format` – 要用於設定資料目的地的格式。 + `options` – 要用於設定資料目的地的選項集合。如需有關格式選項的詳細資訊，請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md)。   **`setAccumulableSize(size)`** + `size` – 要設定的 accumulable 大小 (以位元組為單位)。   **`writeFrame(dynamic_frame, info="")`** + `dynamic_frame` – 所要撰寫的 `DynamicFrame`。 + `info` – 有關 `DynamicFrame` 的資訊 (選用)。   **`write(dynamic_frame_or_dfc, info="")`** 撰寫 `DynamicFrame` 或 `DynamicFrameCollection`。 + `dynamic_frame_or_dfc` – 要撰寫的 `DynamicFrame` 物件或 `DynamicFrameCollection` 物件。 + `info` – 有關要撰寫的 `DynamicFrame` 或 `DynamicFrames` 的資訊 (選用)。 # DynamicFrame 類別 Apache Spark 其中一個主要抽象為 SparkSQL `DataFrame`，其與 R 和 pandas 中找到的 `DataFrame` 結構類似。`DataFrame` 類似於資料表並支援功能樣式 (對應/減少/篩選/等) 操作和 SQL 操作 (選擇、專案、彙總)。 `DataFrames` 功能強大，受到廣泛採用，但其在擷取、轉換和載入 (ETL) 操作上受到限制。最重要的是，其需要指定結構描述，才能載入任何資料。SparkSQL 可解決此問題，其進行兩次資料傳送，第一個推斷結構描述，第二個則載入資料。不過，此推斷相當有限，無法滿足龐大資料的實際需求。例如，相同的欄位在不同的記錄內可能為不同的類型。Apache Spark 通常讓出並使用原始欄位文字回報類型為 `string`。這可能不正確，而且您可能需要更精確控制如何解決結構描述的差異。此外，對於大型資料集，額外傳送來源資料的代價可能使人卻步地高昂。 為了解決這些限制， AWS Glue 推出了 `DynamicFrame`。`DynamicFrame` 類似 `DataFrame`，但每筆記錄均為自我描述，且開始時不需結構描述。反之，AWS Glue 僅在必要時隨時計算結構描述，並使用所選 (或聯合) 類型明確編碼結構描述的不一致。您可以解決這些不一致，讓您的資料集相容於需要固定結構描述的資料存放區。 同樣地，`DynamicRecord` 代表 `DynamicFrame` 內的邏輯記錄。其類似 Spark `DataFrame` 中的資料列，除了它是自我描述的，以及可用於不符合固定結構描述的資料。搭配 PySpark 使用 AWS Glue 時，您通常不會操作獨立 `DynamicRecords`。相反地，您可以透過其 `DynamicFrame` 一起轉換資料集。 您可以在解決任何結構描述不一致後反覆轉換 `DynamicFrames` 和 `DataFrames`。 ##  — construction — + [\$1\$1init\$1\$1](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-__init__) + [fromDF](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-fromDF) + [toDF](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-toDF) ## \$1\$1init\$1\$1 **`__init__(jdf, glue_ctx, name)`** + `jdf` – Java 虛擬機器 (JVM) 中資料框架的參考。 + `glue_ctx` – [GlueContext 類別](aws-glue-api-crawler-pyspark-extensions-glue-context.md) 物件。 + `name` – 選用名稱字串，預設是空的。 ## fromDF **`fromDF(dataframe, glue_ctx, name)`** 將 `DataFrame` 欄位轉換為 `DynamicFrame` 欄位，藉此將 `DataFrame` 轉換為 `DynamicRecord`。傳回新的 `DynamicFrame`。 `DynamicRecord` 代表 `DynamicFrame` 中的邏輯記錄。它類似 Spark `DataFrame` 中的一列，除了它是自我描述的，以及可用於不符合固定結構描述的資料。 此函數會預期 `DataFrame` 中具有重複名稱的資料欄已受到解析。 + `dataframe` – 要轉換的 Apache Spark SQL `DataFrame` (必要)。 + `glue_ctx` – 指定轉換內容的 [GlueContext 類別](aws-glue-api-crawler-pyspark-extensions-glue-context.md) 物件 (必要)。 + `name` – 產生的名稱 `DynamicFrame`（自 Glue 3.0 AWS 起為選用）。 ## toDF **`toDF(options)`** 將 `DynamicRecords` 轉換為 `DataFrame` 欄位，藉此將 `DynamicFrame` 轉換為 Apache Spark `DataFrame`。傳回新的 `DataFrame`。 `DynamicRecord` 代表 `DynamicFrame` 中的邏輯記錄。它類似 Spark `DataFrame` 中的一列，除了它是自我描述的，以及可用於不符合固定結構描述的資料。 + `options` – `ResolveOption` 物件清單，指定如何在轉換期間解析選擇類型。此參數用於處理結構描述不一致，而不是 CSV 剖析等格式選項。 對於 CSV 剖析和其他格式選項，請在建立 DynamicFrame 時於 `from_options` 方法中指定這些選項，而不是在 `toDF`方法中。 以下是處理 CSV 格式選項的正確方式範例： ``` from awsglue.context import GlueContext from awsglue.dynamicframe import DynamicFrame from pyspark.context import SparkContext sc = SparkContext() glueContext = GlueContext(sc) # Correct: Specify format options in from_options csv_dyf = glueContext.create_dynamic_frame.from_options( connection_type="s3", connection_options={"paths": ["s3://my-bucket/path/to/csv/"]}, format="csv", format_options={ "withHeader": True, "separator": ",", "inferSchema": True } ) # Convert to DataFrame (no format options needed here) csv_df = csv_dyf.toDF() ``` 中的 `options` 參數`toDF`專門用於解析選擇類型。如果您選擇 `Project` 和 `Cast` 動作類型，請指定目標類型。範例如下。 ``` >>>toDF([ResolveOption("a.b.c", "KeepAsStruct")]) >>>toDF([ResolveOption("a.b.c", "Project", DoubleType())]) ``` ##  — information — + [count](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-count) + [結構描述](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-schema) + [printSchema](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-printSchema) + [顯示](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-show) + [repartition](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-repartition) + [coalesce](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-coalesce) ## count `count( )` – 傳回基礎 `DataFrame` 中的資料列數量。 ## 結構描述 `schema( )` – 傳回此 `DynamicFrame` 的結構描述，或者，假如不可用，則傳回基礎 `DataFrame` 的結構描述。 如需有關組成此結構描述的 `DynamicFrame` 類型的詳細資訊，請參閱 [PySpark 延伸模組類型](aws-glue-api-crawler-pyspark-extensions-types.md)。 ## printSchema `printSchema( )` – 列印基礎 `DataFrame` 的結構描述。 ## 顯示 `show(num_rows)` – 列印基礎 `DataFrame` 的指定資料列數量。 ## repartition `repartition(numPartitions)` – 傳回包含 `numPartitions` 個分割區的新 `DynamicFrame`。 ## coalesce `coalesce(numPartitions)` – 傳回包含 `numPartitions` 個分割區的新 `DynamicFrame`。 ##  — transforms — + [apply\$1mapping](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-apply_mapping) + [drop\$1fields](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-drop_fields) + [篩選條件](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-filter) + [join](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-join) + [map](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-map) + [mergeDynamicFrame](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-merge) + [關聯化](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-relationalize) + [rename\$1field](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-rename_field) + [resolveChoice](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-resolveChoice) + [select\$1fields](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-select_fields) + [spigot](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-spigot) + [split\$1fields](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-split_fields) + [split\$1rows](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-split_rows) + [unbox](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-unbox) + [聯集](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-union) + [解巢狀](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-unnest) + [unnest\$1ddb\$1json](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-unnest_ddb_json) + [write](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-write) ## apply\$1mapping **`apply_mapping(mappings, transformation_ctx="", info="", stageThreshold=0, totalThreshold=0)`** 套用宣告映射至 `DynamicFrame`，並傳回將這些映射套用至您指定欄位的新 `DynamicFrame`。未指定的欄位將從新的 `DynamicFrame` 中省略。 + `mappings` –映射元組的清單 (必要)。每個清單包括：(來源欄、來源類型、目標欄、目標類型)。 如果來源資料欄的名稱中有一個小點 "`.`"，則您必須在其前後加上反引號 "````"。例如，若要將 `this.old.name` (字串) 對應至 `thisNewName`，會使用以下元組： ``` ("`this.old.name`", "string", "thisNewName", "string") ``` + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `totalThreshold` –直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 ### 範例：使用 apply\$1map 來重新命名欄位並變更欄位類型 以下程式碼顯示使用 `apply_mapping` 方法重新命名所選欄位和更改欄位類型的方法。 **注意** 若要存取此範例中使用的資料集，請參閱 [程式碼範例：加入和關聯化資料](aws-glue-programming-python-samples-legislators.md) 並依照 [步驟 1：在 Amazon S3 儲存貯體中網路爬取資料](aws-glue-programming-python-samples-legislators.md#aws-glue-programming-python-samples-legislators-crawling) 中的說明進行。 ``` # Example: Use apply_mapping to reshape source data into # the desired column names and types as a new DynamicFrame from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Create a DynamicFrame and view its schema persons = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="persons_json" ) print("Schema for the persons DynamicFrame:") persons.printSchema() # Select and rename fields, change field type print("Schema for the persons_mapped DynamicFrame, created with apply_mapping:") persons_mapped = persons.apply_mapping( [ ("family_name", "String", "last_name", "String"), ("name", "String", "first_name", "String"), ("birth_date", "String", "date_of_birth", "Date"), ] ) persons_mapped.printSchema() ``` #### Output ``` Schema for the persons DynamicFrame: root |-- family_name: string |-- name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- gender: string |-- image: string |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- other_names: array | |-- element: struct | | |-- lang: string | | |-- note: string | | |-- name: string |-- sort_name: string |-- images: array | |-- element: struct | | |-- url: string |-- given_name: string |-- birth_date: string |-- id: string |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string |-- death_date: string Schema for the persons_mapped DynamicFrame, created with apply_mapping: root |-- last_name: string |-- first_name: string |-- date_of_birth: date ``` ## drop\$1fields **`drop_fields(paths, transformation_ctx="", info="", stageThreshold=0, totalThreshold=0)`** 呼叫 [FlatMap 類別](aws-glue-api-crawler-pyspark-transforms-flat-map.md) 轉換，從 `DynamicFrame` 移除欄位。傳回捨棄了指定欄位的新 `DynamicFrame`。 + `paths` – 字串清單。各包含您想捨棄的欄位節點的完整路徑。您可以使用點標記法來指定巢狀欄位。例如，如果欄位 `first` 是樹狀結構中的子欄位 `name`，您可以指定 `"name.first"` 為路徑。 如果欄位節點的名稱中有常值 `.`，您必須以反引號將名稱括起 (```)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `totalThreshold` –直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 ### 範例：使用 drop\$1fields 從 `DynamicFrame` 中移除欄位 此程式碼範例使用 `drop_fields` 方法從 `DynamicFrame` 中移除選取的頂層和巢狀欄位。 **範例資料集** 此範例使用下列資料集，該資料集由程式碼中的 `EXAMPLE-FRIENDS-DATA` 表格表示： ``` {"name": "Sally", "age": 23, "location": {"state": "WY", "county": "Fremont"}, "friends": []} {"name": "Varun", "age": 34, "location": {"state": "NE", "county": "Douglas"}, "friends": [{"name": "Arjun", "age": 3}]} {"name": "George", "age": 52, "location": {"state": "NY"}, "friends": [{"name": "Fred"}, {"name": "Amy", "age": 15}]} {"name": "Haruki", "age": 21, "location": {"state": "AK", "county": "Denali"}} {"name": "Sheila", "age": 63, "friends": [{"name": "Nancy", "age": 22}]} ``` **範例程式碼** ``` # Example: Use drop_fields to remove top-level and nested fields from a DynamicFrame. # Replace MY-EXAMPLE-DATABASE with your Glue Data Catalog database name. # Replace EXAMPLE-FRIENDS-DATA with your table name. from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Create a DynamicFrame from Glue Data Catalog glue_source_database = "MY-EXAMPLE-DATABASE" glue_source_table = "EXAMPLE-FRIENDS-DATA" friends = glueContext.create_dynamic_frame.from_catalog( database=glue_source_database, table_name=glue_source_table ) print("Schema for friends DynamicFrame before calling drop_fields:") friends.printSchema() # Remove location.county, remove friends.age, remove age friends = friends.drop_fields(paths=["age", "location.county", "friends.age"]) print("Schema for friends DynamicFrame after removing age, county, and friend age:") friends.printSchema() ``` #### Output ``` Schema for friends DynamicFrame before calling drop_fields: root |-- name: string |-- age: int |-- location: struct | |-- state: string | |-- county: string |-- friends: array | |-- element: struct | | |-- name: string | | |-- age: int Schema for friends DynamicFrame after removing age, county, and friend age: root |-- name: string |-- location: struct | |-- state: string |-- friends: array | |-- element: struct | | |-- name: string ``` ## 篩選條件 **`filter(f, transformation_ctx="", info="", stageThreshold=0, totalThreshold=0)`** 傳回新的 `DynamicFrame`，其中包含所有 `DynamicRecords`，其滿足輸入 `DynamicFrame` 且指定的述詞函數 `f`。 + `f` – 要套用至 `DynamicFrame` 的述詞函數。此函數必須以 `DynamicRecord` 做為引數並傳回 True，如果 `DynamicRecord` 符合篩選條件要求，否則將傳回 False (必要)。 `DynamicRecord` 代表 `DynamicFrame` 中的邏輯記錄。它類似 Spark `DataFrame` 中的一列，除了它是自我描述的，以及可用於不符合固定結構描述的資料。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `totalThreshold` –直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 ### 範例：使用篩選條件取得已篩選的欄位選取 此範例使用`filter`方法來建立新的`DynamicFrame`，其中包括對另一個 `DynamicFrame` 的欄位的已篩選選取。 跟 `map` 方法一樣，`filter` 需要一個函數作為引數，該引數應用於原始 `DynamicFrame` 中的每個記錄。該函數需要一個記錄作為輸入，並傳回一個布林值。如果傳回值為 true，記錄會包含在所產生的 `DynamicFrame` 中。如果傳回值為 false，記錄會被排除在外。 **注意** 若要存取此範例中使用的資料集，請參閱 [程式碼範例：使用 ResolveChoice、Lambda 和 ApplyMapping 的資料準備](aws-glue-programming-python-samples-medicaid.md) 並依照 [步驟 1：在 Amazon S3 儲存貯體中網路爬取資料](aws-glue-programming-python-samples-medicaid.md#aws-glue-programming-python-samples-medicaid-crawling) 中的說明進行。 ``` # Example: Use filter to create a new DynamicFrame # with a filtered selection of records from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Create DynamicFrame from Glue Data Catalog medicare = glueContext.create_dynamic_frame.from_options( "s3", { "paths": [ "s3://awsglue-datasets/examples/medicare/Medicare_Hospital_Provider.csv" ] }, "csv", {"withHeader": True}, ) # Create filtered DynamicFrame with custom lambda # to filter records by Provider State and Provider City sac_or_mon = medicare.filter( f=lambda x: x["Provider State"] in ["CA", "AL"] and x["Provider City"] in ["SACRAMENTO", "MONTGOMERY"] ) # Compare record counts print("Unfiltered record count: ", medicare.count()) print("Filtered record count: ", sac_or_mon.count()) ``` #### Output ``` Unfiltered record count: 163065 Filtered record count: 564 ``` ## join **`join(paths1, paths2, frame2, transformation_ctx="", info="", stageThreshold=0, totalThreshold=0)`** 執行與其他 `DynamicFrame` 的對等性加入，並傳回產生的 `DynamicFrame`。 + `paths1` – 要加入的此框架中的金鑰清單。 + `paths2` – 要加入的其他框架中的金鑰清單。 + `frame2` – 要加入的其他 `DynamicFrame`。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `totalThreshold` –直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 ### 範例：使用聯結合併 `DynamicFrames` 此範例使用 `join`方法來對三個 執行聯結`DynamicFrames`。 AWS Glue 會根據您提供的欄位金鑰執行聯結。產生的 `DynamicFrame` 包含兩個原始影格的列，其中指定之索引鍵相符。 請注意，`join` 轉換會保持所有欄位不變。這表示您指定要比對的欄位會出現在產生的 DynamicFrame 中，即使這些欄位是多餘且包含相同的索引鍵。在此範例中，我們使用 `drop_fields` 在聯結後移除這些多餘的索引鍵。 **注意** 若要存取此範例中使用的資料集，請參閱 [程式碼範例：加入和關聯化資料](aws-glue-programming-python-samples-legislators.md) 並依照 [步驟 1：在 Amazon S3 儲存貯體中網路爬取資料](aws-glue-programming-python-samples-legislators.md#aws-glue-programming-python-samples-legislators-crawling) 中的說明進行。 ``` # Example: Use join to combine data from three DynamicFrames from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Load DynamicFrames from Glue Data Catalog persons = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="persons_json" ) memberships = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="memberships_json" ) orgs = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="organizations_json" ) print("Schema for the persons DynamicFrame:") persons.printSchema() print("Schema for the memberships DynamicFrame:") memberships.printSchema() print("Schema for the orgs DynamicFrame:") orgs.printSchema() # Join persons and memberships by ID persons_memberships = persons.join( paths1=["id"], paths2=["person_id"], frame2=memberships ) # Rename and drop fields from orgs # to prevent field name collisions with persons_memberships orgs = ( orgs.drop_fields(["other_names", "identifiers"]) .rename_field("id", "org_id") .rename_field("name", "org_name") ) # Create final join of all three DynamicFrames legislators_combined = orgs.join( paths1=["org_id"], paths2=["organization_id"], frame2=persons_memberships ).drop_fields(["person_id", "org_id"]) # Inspect the schema for the joined data print("Schema for the new legislators_combined DynamicFrame:") legislators_combined.printSchema() ``` #### Output ``` Schema for the persons DynamicFrame: root |-- family_name: string |-- name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- gender: string |-- image: string |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- other_names: array | |-- element: struct | | |-- lang: string | | |-- note: string | | |-- name: string |-- sort_name: string |-- images: array | |-- element: struct | | |-- url: string |-- given_name: string |-- birth_date: string |-- id: string |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string |-- death_date: string Schema for the memberships DynamicFrame: root |-- area_id: string |-- on_behalf_of_id: string |-- organization_id: string |-- role: string |-- person_id: string |-- legislative_period_id: string |-- start_date: string |-- end_date: string Schema for the orgs DynamicFrame: root |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- other_names: array | |-- element: struct | | |-- lang: string | | |-- note: string | | |-- name: string |-- id: string |-- classification: string |-- name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- image: string |-- seats: int |-- type: string Schema for the new legislators_combined DynamicFrame: root |-- role: string |-- seats: int |-- org_name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- type: string |-- sort_name: string |-- area_id: string |-- images: array | |-- element: struct | | |-- url: string |-- on_behalf_of_id: string |-- other_names: array | |-- element: struct | | |-- note: string | | |-- name: string | | |-- lang: string |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string |-- name: string |-- birth_date: string |-- organization_id: string |-- gender: string |-- classification: string |-- legislative_period_id: string |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- image: string |-- given_name: string |-- start_date: string |-- family_name: string |-- id: string |-- death_date: string |-- end_date: string ``` ## map **`map(f, transformation_ctx="", info="", stageThreshold=0, totalThreshold=0)`** 傳回套用指定映射函數至原始 `DynamicFrame` 中所有記錄而產生的新 `DynamicFrame`。 + `f` – 套用到 `DynamicFrame` 中所有記錄的映射函數。此函數必須以 `DynamicRecord` 做為引數，並傳回新的 `DynamicRecord` (必要)。 `DynamicRecord` 代表 `DynamicFrame` 中的邏輯記錄。它類似 Apache Spark `DataFrame` 中的一列，除了它是自我描述的，以及可用於不符合固定結構描述的資料。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 ### 範例：使用 map 將函數套用至 `DynamicFrame` 中的每個記錄 此範例示範如何使用 `map` 方法將函數套用至 `DynamicFrame` 的每個記錄。具體來說，此範例套用名為 `MergeAddress` 函數至每個記錄，以便將多個地址欄位合併為一個 `struct` 類型。 **注意** 若要存取此範例中使用的資料集，請參閱 [程式碼範例：使用 ResolveChoice、Lambda 和 ApplyMapping 的資料準備](aws-glue-programming-python-samples-medicaid.md) 並依照 [步驟 1：在 Amazon S3 儲存貯體中網路爬取資料](aws-glue-programming-python-samples-medicaid.md#aws-glue-programming-python-samples-medicaid-crawling) 中的說明進行。 ``` # Example: Use map to combine fields in all records # of a DynamicFrame from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Create a DynamicFrame and view its schema medicare = glueContext.create_dynamic_frame.from_options( "s3", {"paths": ["s3://awsglue-datasets/examples/medicare/Medicare_Hospital_Provider.csv"]}, "csv", {"withHeader": True}) print("Schema for medicare DynamicFrame:") medicare.printSchema() # Define a function to supply to the map transform # that merges address fields into a single field def MergeAddress(rec): rec["Address"] = {} rec["Address"]["Street"] = rec["Provider Street Address"] rec["Address"]["City"] = rec["Provider City"] rec["Address"]["State"] = rec["Provider State"] rec["Address"]["Zip.Code"] = rec["Provider Zip Code"] rec["Address"]["Array"] = [rec["Provider Street Address"], rec["Provider City"], rec["Provider State"], rec["Provider Zip Code"]] del rec["Provider Street Address"] del rec["Provider City"] del rec["Provider State"] del rec["Provider Zip Code"] return rec # Use map to apply MergeAddress to every record mapped_medicare = medicare.map(f = MergeAddress) print("Schema for mapped_medicare DynamicFrame:") mapped_medicare.printSchema() ``` #### Output ``` Schema for medicare DynamicFrame: root |-- DRG Definition: string |-- Provider Id: string |-- Provider Name: string |-- Provider Street Address: string |-- Provider City: string |-- Provider State: string |-- Provider Zip Code: string |-- Hospital Referral Region Description: string |-- Total Discharges: string |-- Average Covered Charges: string |-- Average Total Payments: string |-- Average Medicare Payments: string Schema for mapped_medicare DynamicFrame: root |-- Average Total Payments: string |-- Average Covered Charges: string |-- DRG Definition: string |-- Average Medicare Payments: string |-- Hospital Referral Region Description: string |-- Address: struct | |-- Zip.Code: string | |-- City: string | |-- Array: array | | |-- element: string | |-- State: string | |-- Street: string |-- Provider Id: string |-- Total Discharges: string |-- Provider Name: string ``` ## mergeDynamicFrame **`mergeDynamicFrame(stage_dynamic_frame, primary_keys, transformation_ctx = "", options = {}, info = "", stageThreshold = 0, totalThreshold = 0)`** 根據指定的主索引鍵來合併此 `DynamicFrame` 與暫存 `DynamicFrame` 以識別記錄。重複的記錄 (具有相同主索引鍵的記錄) 不會被刪除重複資料。如果暫存影格中沒有相符的記錄，則會保留來源中的所有記錄 (包括重複項)。如果暫存影格具有相符的記錄，則暫存影格中的記錄會覆寫 AWS Glue 中來源的記錄。 + `stage_dynamic_frame` – 要合併的暫存 `DynamicFrame`。 + `primary_keys` - 要從來源和暫存動態影格比對記錄的主索引鍵欄位清單。 + `transformation_ctx` - 用來擷取目前轉換之中繼資料的唯一字串 (選用)。 + `options` - JSON 名稱值組的字串，可提供此轉換的額外資料。目前未使用此引數。 + `info` – `String`。與轉換中的錯誤相關的任何字串。 + `stageThreshold` – `Long`。在給定轉換中的錯誤數量，其處理需要輸出錯誤。 + `totalThreshold` – `Long`。在此轉換之前 (包括在此轉換中) 的錯誤總數，其處理需要輸出錯誤。 此方法會傳回透過將此 `DynamicFrame` 與暫存 `DynamicFrame` 合併而取得的新 `DynamicFrame`。 在下列情況下，傳回的 `DynamicFrame` 包含記錄 A： + 如果 `A` 同時存在於來源影格和暫存影格，則會傳回暫存影格中的 `A`。 + 如果 `A` 位於來源資料表中而 `A.primaryKeys` 不在 `stagingDynamicFrame` 中，則 `A` 不會在暫存資料表中更新。 來源影格和暫存影格不需要具有相同的結構描述。 ### 範例：使用 mergeDynamicFrame 根據主索引鍵來合併兩個 `DynamicFrames`。 下列程式碼範例示範如何使用 `mergeDynamicFrame` 方法，根據主索引鍵 `id` 將 `DynamicFrame` 與「暫存」`DynamicFrame` 合併。 **範例資料集** 該範例使用稱為 `split_rows_collection` 的來自 `DynamicFrameCollection` 的兩個 `DynamicFrames`。以下是 `split_rows_collection` 中的索引鍵清單。 ``` dict_keys(['high', 'low']) ``` **範例程式碼** ``` # Example: Use mergeDynamicFrame to merge DynamicFrames # based on a set of specified primary keys from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.transforms import SelectFromCollection # Inspect the original DynamicFrames frame_low = SelectFromCollection.apply(dfc=split_rows_collection, key="low") print("Inspect the DynamicFrame that contains rows where ID < 10") frame_low.toDF().show() frame_high = SelectFromCollection.apply(dfc=split_rows_collection, key="high") print("Inspect the DynamicFrame that contains rows where ID > 10") frame_high.toDF().show() # Merge the DynamicFrames based on the "id" primary key merged_high_low = frame_high.mergeDynamicFrame( stage_dynamic_frame=frame_low, primary_keys=["id"] ) # View the results where the ID is 1 or 20 print("Inspect the merged DynamicFrame that contains the combined rows") merged_high_low.toDF().where("id = 1 or id= 20").orderBy("id").show() ``` #### Output ``` Inspect the DynamicFrame that contains rows where ID < 10 +---+-----+------------------------+-------------------------+ | id|index|contact_details.val.type|contact_details.val.value| +---+-----+------------------------+-------------------------+ | 1| 0| fax| 202-225-3307| | 1| 1| phone| 202-225-5731| | 2| 0| fax| 202-225-3307| | 2| 1| phone| 202-225-5731| | 3| 0| fax| 202-225-3307| | 3| 1| phone| 202-225-5731| | 4| 0| fax| 202-225-3307| | 4| 1| phone| 202-225-5731| | 5| 0| fax| 202-225-3307| | 5| 1| phone| 202-225-5731| | 6| 0| fax| 202-225-3307| | 6| 1| phone| 202-225-5731| | 7| 0| fax| 202-225-3307| | 7| 1| phone| 202-225-5731| | 8| 0| fax| 202-225-3307| | 8| 1| phone| 202-225-5731| | 9| 0| fax| 202-225-3307| | 9| 1| phone| 202-225-5731| | 10| 0| fax| 202-225-6328| | 10| 1| phone| 202-225-4576| +---+-----+------------------------+-------------------------+ only showing top 20 rows Inspect the DynamicFrame that contains rows where ID > 10 +---+-----+------------------------+-------------------------+ | id|index|contact_details.val.type|contact_details.val.value| +---+-----+------------------------+-------------------------+ | 11| 0| fax| 202-225-6328| | 11| 1| phone| 202-225-4576| | 11| 2| twitter| RepTrentFranks| | 12| 0| fax| 202-225-6328| | 12| 1| phone| 202-225-4576| | 12| 2| twitter| RepTrentFranks| | 13| 0| fax| 202-225-6328| | 13| 1| phone| 202-225-4576| | 13| 2| twitter| RepTrentFranks| | 14| 0| fax| 202-225-6328| | 14| 1| phone| 202-225-4576| | 14| 2| twitter| RepTrentFranks| | 15| 0| fax| 202-225-6328| | 15| 1| phone| 202-225-4576| | 15| 2| twitter| RepTrentFranks| | 16| 0| fax| 202-225-6328| | 16| 1| phone| 202-225-4576| | 16| 2| twitter| RepTrentFranks| | 17| 0| fax| 202-225-6328| | 17| 1| phone| 202-225-4576| +---+-----+------------------------+-------------------------+ only showing top 20 rows Inspect the merged DynamicFrame that contains the combined rows +---+-----+------------------------+-------------------------+ | id|index|contact_details.val.type|contact_details.val.value| +---+-----+------------------------+-------------------------+ | 1| 0| fax| 202-225-3307| | 1| 1| phone| 202-225-5731| | 20| 0| fax| 202-225-5604| | 20| 1| phone| 202-225-6536| | 20| 2| twitter| USRepLong| +---+-----+------------------------+-------------------------+ ``` ## 關聯化 **`relationalize(root_table_name, staging_path, options, transformation_ctx="", info="", stageThreshold=0, totalThreshold=0)`** 將 `DynamicFrame` 轉換為適合關聯式資料庫的表單。當您想要將資料從 DynamoDB 等 NoSQL 環境移動到 MySQL 等關聯式資料庫時，關聯化 `DynamicFrame` 特別有用。 透過對巢狀化欄解除巢狀化並將陣列欄直轉橫，可產生框架清單。使用在解除巢狀化階段中所產生的聯結鍵，將直轉橫的陣列欄聯結至根資料表。 + `root_table_name` – 根資料表的名稱。 + `staging_path` – 該方法用來以 CSV 格式存放直轉橫資料表分區的路徑 (選用)。直轉橫資料表從這個路徑讀回。 + `options` – 選用參數的字典。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `totalThreshold` –直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 ### 範例：使用 relationalize 來壓平合併 `DynamicFrame` 中的巢狀化結構描述 此程式碼範例使用 `relationalize` 方法，將巢狀化結構描述壓平合併為適合關聯式資料庫的表單。 **範例資料集** 此範例會將稱為 `legislators_combined` 的 `DynamicFrame` 與下列結構描述搭配使用。`legislators_combined` 具有多個巢狀化欄位，例如 `links`、`images` 和 `contact_details`，這些欄位將由 `relationalize` 轉換進行壓平合併。 ``` root |-- role: string |-- seats: int |-- org_name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- type: string |-- sort_name: string |-- area_id: string |-- images: array | |-- element: struct | | |-- url: string |-- on_behalf_of_id: string |-- other_names: array | |-- element: struct | | |-- note: string | | |-- name: string | | |-- lang: string |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string |-- name: string |-- birth_date: string |-- organization_id: string |-- gender: string |-- classification: string |-- legislative_period_id: string |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- image: string |-- given_name: string |-- start_date: string |-- family_name: string |-- id: string |-- death_date: string |-- end_date: string ``` **範例程式碼** ``` # Example: Use relationalize to flatten # a nested schema into a format that fits # into a relational database. # Replace DOC-EXAMPLE-S3-BUCKET/tmpDir with your own location. from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Apply relationalize and inspect new tables legislators_relationalized = legislators_combined.relationalize( "l_root", "s3://DOC-EXAMPLE-BUCKET/tmpDir" ) legislators_relationalized.keys() # Compare the schema of the contact_details # nested field to the new relationalized table that # represents it legislators_combined.select_fields("contact_details").printSchema() legislators_relationalized.select("l_root_contact_details").toDF().where( "id = 10 or id = 75" ).orderBy(["id", "index"]).show() ``` #### Output 下列輸出可讓您將稱為 `contact_details` 的巢狀化欄位結構描述與 `relationalize` 轉換所建立的資料表進行比較。請注意，資料表記錄使用稱為 `id` 的外部索引鍵和代表陣列位置的 `index` 資料欄連結回主資料表。 ``` dict_keys(['l_root', 'l_root_images', 'l_root_links', 'l_root_other_names', 'l_root_contact_details', 'l_root_identifiers']) root |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string +---+-----+------------------------+-------------------------+ | id|index|contact_details.val.type|contact_details.val.value| +---+-----+------------------------+-------------------------+ | 10| 0| fax| 202-225-4160| | 10| 1| phone| 202-225-3436| | 75| 0| fax| 202-225-6791| | 75| 1| phone| 202-225-2861| | 75| 2| twitter| RepSamFarr| +---+-----+------------------------+-------------------------+ ``` ## rename\$1field **`rename_field(oldName, newName, transformation_ctx="", info="", stageThreshold=0, totalThreshold=0)`** 重新命名此 `DynamicFrame` 中的欄位，並傳回欄位重新命名的新 `DynamicFrame`。 + `oldName` – 要重新命名之節點的完整路徑。 如果舊名稱內有小點，`RenameField` 無法正常運作，除非在前後加上反引號 (```)。例如，若要將 `this.old.name` 換成 `thisNewName`，可以用下列方式呼叫 rename\$1field。 ``` newDyF = oldDyF.rename_field("`this.old.name`", "thisNewName") ``` + `newName` – 新的名稱，做為完整路徑。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `totalThreshold` –直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 ### 範例：使用 rename\$1field 重新命名 `DynamicFrame` 中的欄位 此程式碼範例會使用 `rename_field` 方法重新命名 `DynamicFrame` 中的欄位。請注意，此範例使用方法鏈結同時重新命名多個欄位。 **注意** 若要存取此範例中使用的資料集，請參閱 [程式碼範例：加入和關聯化資料](aws-glue-programming-python-samples-legislators.md) 並依照 [步驟 1：在 Amazon S3 儲存貯體中網路爬取資料](aws-glue-programming-python-samples-legislators.md#aws-glue-programming-python-samples-legislators-crawling) 中的說明進行。 **範例程式碼** ``` # Example: Use rename_field to rename fields # in a DynamicFrame from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Inspect the original orgs schema orgs = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="organizations_json" ) print("Original orgs schema: ") orgs.printSchema() # Rename fields and view the new schema orgs = orgs.rename_field("id", "org_id").rename_field("name", "org_name") print("New orgs schema with renamed fields: ") orgs.printSchema() ``` #### Output ``` Original orgs schema: root |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- other_names: array | |-- element: struct | | |-- lang: string | | |-- note: string | | |-- name: string |-- id: string |-- classification: string |-- name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- image: string |-- seats: int |-- type: string New orgs schema with renamed fields: root |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- other_names: array | |-- element: struct | | |-- lang: string | | |-- note: string | | |-- name: string |-- classification: string |-- org_id: string |-- org_name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- image: string |-- seats: int |-- type: string ``` ## resolveChoice **`resolveChoice(specs = None, choice = "" , database = None , table_name = None , transformation_ctx="", info="", stageThreshold=0, totalThreshold=0, catalog_id = None)`** 在此 `DynamicFrame` 中解析所選類型，並傳回新的 `DynamicFrame`。 + `specs` – 要解析的特定模棱兩可項目的清單，形式皆為 tuple：`(field_path, action)`。 有兩種方式可以使用 `resolveChoice`。第一種是使用 `specs` 引數指定一系列的特定的欄以及解析它們的方式。`resolveChoice` 的其他模式是使用 `choice` 引數為所有 `ChoiceTypes` 指定單一解析度。 `specs` 的值指定為由 `(field_path, action)` 對組成的元組。`field_path` 值代表模棱兩可的特定元素，`action` 值則代表對應的解析動作。可行的動作如下： + `cast:type` - 嘗試將所有值轉換至指定類型。例如：`cast:int`。 + `make_cols` - 將每個不同的類型轉換為具有 `columnName_type` 名稱的欄。透過將資料壓平合併來解析可能的模棱兩可項目。例如，如果 `columnA` 可能是 `int` 或 `string`，則在得出的 `DynamicFrame` 中，解析動作會產生名為 `columnA_int` 和 `columnA_string` 的兩個欄。 + `make_struct` – 藉由使用 `struct` 表示資料，來解決可能的模棱兩可項目。舉例來說，如果欄中的資料可能是 `int` 或 `string`，則 `make_struct` 動作會在產生的 `DynamicFrame` 中產生結構欄。每個結構都包含 `int` 和 `string`。 + `project:type` - 藉由將所有資料預測為一種可能的資料類型，來解決可能的模棱兩可項目。舉例來說，如果欄中的資料可能是 `int` 或 `string`，則使用 `project:string` 動作會在結果的 `DynamicFrame` 中產生欄，其中所有的 `int` 值皆轉換為字串。 若 `field_path` 識別到陣列，在陣列的名稱後放置空白的方括號以避免模棱兩可的狀況。例如，假設您使用如下結構化的資料： ``` "myList": [ { "price": 100.00 }, { "price": "$100.00" } ] ``` 您可以選取數值而不是價格字串版本，方法是將 `field_path` 設定為 `"myList[].price"`，且將 `action` 設定為 `"cast:double"`。 **注意** 您只能使用 `specs` 和 `choice` 參數的其中一項。如果 `specs` 參數不是 `None`，則 `choice` 參數必須為空字串。相反地，如果 `choice` 不是空字串，則 `specs` 參數必須為 `None`。 + `choice` – 為所有 `ChoiceTypes` 指定單一解析度。您可以在 `ChoiceTypes` 的完整清單在執行時間之前是未知的情況下使用此模式。除了以上列出的 `specs` 動作，此引數也支援下列動作： + `match_catalog` – 嘗試將每個 `ChoiceType` 投射至指定 Data Catalog 資料表中的對應類型。 + `database` – 搭配 `match_catalog` 動作使用的 Data Catalog 資料庫。 + `table_name` – 搭配 `match_catalog` 動作使用的 Data Catalog 資料表。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `totalThreshold` – 直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設為零，表示流程不會錯誤輸出。 + `catalog_id` – 要存取之 Data Catalog 的目錄 ID ( Data Catalog 的帳戶 ID)。當設定為 `None` (預設值) 時，它會使用呼叫帳戶的目錄 ID。 ### 範例：使用 resolveChoice 來處理包含多種類型的資料欄 此程式碼範例會使用 `resolveChoice` 方法來指定如何處理包含多種類型值的 `DynamicFrame` 資料欄。該範例演示了處理具有不同類型欄的兩種常見方法： + 將資料欄轉換為單一資料類型。 + 將所有類型保留在單獨的欄中。 **範例資料集** **注意** 若要存取此範例中使用的資料集，請參閱 [程式碼範例：使用 ResolveChoice、Lambda 和 ApplyMapping 的資料準備](aws-glue-programming-python-samples-medicaid.md) 並依照 [步驟 1：在 Amazon S3 儲存貯體中網路爬取資料](aws-glue-programming-python-samples-medicaid.md#aws-glue-programming-python-samples-medicaid-crawling) 中的說明進行。 此範例將稱為 `medicare` 的 `DynamicFrame` 與下列結構描述搭配使用： ``` root |-- drg definition: string |-- provider id: choice | |-- long | |-- string |-- provider name: string |-- provider street address: string |-- provider city: string |-- provider state: string |-- provider zip code: long |-- hospital referral region description: string |-- total discharges: long |-- average covered charges: string |-- average total payments: string |-- average medicare payments: string ``` **範例程式碼** ``` # Example: Use resolveChoice to handle # a column that contains multiple types from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Load the input data and inspect the "provider id" column medicare = glueContext.create_dynamic_frame.from_catalog( database="payments", table_name="medicare_hospital_provider_csv" ) print("Inspect the provider id column:") medicare.toDF().select("provider id").show() # Cast provider id to type long medicare_resolved_long = medicare.resolveChoice(specs=[("provider id", "cast:long")]) print("Schema after casting provider id to type long:") medicare_resolved_long.printSchema() medicare_resolved_long.toDF().select("provider id").show() # Create separate columns # for each provider id type medicare_resolved_cols = medicare.resolveChoice(choice="make_cols") print("Schema after creating separate columns for each type:") medicare_resolved_cols.printSchema() medicare_resolved_cols.toDF().select("provider id_long", "provider id_string").show() ``` #### Output ``` Inspect the 'provider id' column: +-----------+ |provider id| +-----------+ | [10001,]| | [10005,]| | [10006,]| | [10011,]| | [10016,]| | [10023,]| | [10029,]| | [10033,]| | [10039,]| | [10040,]| | [10046,]| | [10055,]| | [10056,]| | [10078,]| | [10083,]| | [10085,]| | [10090,]| | [10092,]| | [10100,]| | [10103,]| +-----------+ only showing top 20 rows Schema after casting 'provider id' to type long: root |-- drg definition: string |-- provider id: long |-- provider name: string |-- provider street address: string |-- provider city: string |-- provider state: string |-- provider zip code: long |-- hospital referral region description: string |-- total discharges: long |-- average covered charges: string |-- average total payments: string |-- average medicare payments: string +-----------+ |provider id| +-----------+ | 10001| | 10005| | 10006| | 10011| | 10016| | 10023| | 10029| | 10033| | 10039| | 10040| | 10046| | 10055| | 10056| | 10078| | 10083| | 10085| | 10090| | 10092| | 10100| | 10103| +-----------+ only showing top 20 rows Schema after creating separate columns for each type: root |-- drg definition: string |-- provider id_string: string |-- provider id_long: long |-- provider name: string |-- provider street address: string |-- provider city: string |-- provider state: string |-- provider zip code: long |-- hospital referral region description: string |-- total discharges: long |-- average covered charges: string |-- average total payments: string |-- average medicare payments: string +----------------+------------------+ |provider id_long|provider id_string| +----------------+------------------+ | 10001| null| | 10005| null| | 10006| null| | 10011| null| | 10016| null| | 10023| null| | 10029| null| | 10033| null| | 10039| null| | 10040| null| | 10046| null| | 10055| null| | 10056| null| | 10078| null| | 10083| null| | 10085| null| | 10090| null| | 10092| null| | 10100| null| | 10103| null| +----------------+------------------+ only showing top 20 rows ``` ## select\$1fields **`select_fields(paths, transformation_ctx="", info="", stageThreshold=0, totalThreshold=0)`** 傳回包含所選欄位的新 `DynamicFrame`。 + `paths` – 字串清單。每個字串清單均為您想要選擇的最上層節點的路徑。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `totalThreshold` –直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 ### 範例：使用 select\$1fields 來用所選欄位建立新的 `DynamicFrame` 以下程式碼範例顯示如何使用 `select_fields` 方法建立新的 `DynamicFrame`，其具有從現有 `DynamicFrame` 中選取的欄位清單。 **注意** 若要存取此範例中使用的資料集，請參閱 [程式碼範例：加入和關聯化資料](aws-glue-programming-python-samples-legislators.md) 並依照 [步驟 1：在 Amazon S3 儲存貯體中網路爬取資料](aws-glue-programming-python-samples-legislators.md#aws-glue-programming-python-samples-legislators-crawling) 中的說明進行。 ``` # Example: Use select_fields to select specific fields from a DynamicFrame from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Create a DynamicFrame and view its schema persons = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="persons_json" ) print("Schema for the persons DynamicFrame:") persons.printSchema() # Create a new DynamicFrame with chosen fields names = persons.select_fields(paths=["family_name", "given_name"]) print("Schema for the names DynamicFrame, created with select_fields:") names.printSchema() names.toDF().show() ``` #### Output ``` Schema for the persons DynamicFrame: root |-- family_name: string |-- name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- gender: string |-- image: string |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- other_names: array | |-- element: struct | | |-- lang: string | | |-- note: string | | |-- name: string |-- sort_name: string |-- images: array | |-- element: struct | | |-- url: string |-- given_name: string |-- birth_date: string |-- id: string |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string |-- death_date: string Schema for the names DynamicFrame: root |-- family_name: string |-- given_name: string +-----------+----------+ |family_name|given_name| +-----------+----------+ | Collins| Michael| | Huizenga| Bill| | Clawson| Curtis| | Solomon| Gerald| | Rigell| Edward| | Crapo| Michael| | Hutto| Earl| | Ertel| Allen| | Minish| Joseph| | Andrews| Robert| | Walden| Greg| | Kazen| Abraham| | Turner| Michael| | Kolbe| James| | Lowenthal| Alan| | Capuano| Michael| | Schrader| Kurt| | Nadler| Jerrold| | Graves| Tom| | McMillan| John| +-----------+----------+ only showing top 20 rows ``` ## simplify\$1ddb\$1json **`simplify_ddb_json(): DynamicFrame`** 簡化專屬於 DynamoDB JSON 結構中 `DynamicFrame` 內的巢狀資料欄，並傳回新的簡化 `DynamicFrame`。如果 List 類型中有多種類型或 Map 類型，則 List 中的元素不會進行簡化。請注意，這是一種特定類型的轉換，其行為與常規 `unnest` 轉換不同，且資料必須已位於 DynamoDB JSON 結構中。如需詳細資訊，請參閱 [DynamoDB JSON](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataExport.Output.html#DataExport.Output.Data)。 例如，讀取 DynamoDB JSON 結構的匯出結構描述與以下類似： ``` 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 ``` `simplify_ddb_json()` 轉換會將此轉換為： ``` 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 ``` ### 範例：使用 simplify\$1ddb\$1json 來調用 DynamoDB JSON 簡化 此程式碼範例使用 `simplify_ddb_json`方法使用 AWS Glue DynamoDB 匯出連接器、叫用 DynamoDB JSON 簡化，以及列印分割區數量。 **範例程式碼** ``` from pyspark.context import SparkContext from awsglue.context import GlueContext sc = SparkContext() glueContext = GlueContext(sc) dynamicFrame = glueContext.create_dynamic_frame.from_options( connection_type = "dynamodb", connection_options = { 'dynamodb.export': 'ddb', 'dynamodb.tableArn': '', 'dynamodb.s3.bucket': '', 'dynamodb.s3.prefix': '', 'dynamodb.s3.bucketOwner': '' } ) simplified = dynamicFrame.simplify_ddb_json() print(simplified.getNumPartitions()) ``` ## spigot **`spigot(path, options={})`** 將範例記錄寫入指定的目的地，以協助您驗證任務執行的轉換。 + `path` - 要寫入的目的地路徑 (必要)。 + `options` – 指定選項的索引鍵/值對 (選用)。`"topk"` 選項指定應寫入第一個 `k` 記錄。`"prob"` 選項指定選擇任何給定記錄的概率 (小數)。您可以使用其來選擇要寫入的記錄。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 ### 範例：使用 spigot 將範例欄位從 `DynamicFrame` 寫入到 Amazon S3 此程式碼範例會在套用 `select_fields` 轉換後，使用 `spigot` 方法將範例記錄寫入 Amazon S3 儲存貯體。 **範例資料集** **注意** 若要存取此範例中使用的資料集，請參閱 [程式碼範例：加入和關聯化資料](aws-glue-programming-python-samples-legislators.md) 並依照 [步驟 1：在 Amazon S3 儲存貯體中網路爬取資料](aws-glue-programming-python-samples-legislators.md#aws-glue-programming-python-samples-legislators-crawling) 中的說明進行。 此範例將稱為 `persons` 的 `DynamicFrame` 與下列結構描述搭配使用： ``` root |-- family_name: string |-- name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- gender: string |-- image: string |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- other_names: array | |-- element: struct | | |-- lang: string | | |-- note: string | | |-- name: string |-- sort_name: string |-- images: array | |-- element: struct | | |-- url: string |-- given_name: string |-- birth_date: string |-- id: string |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string |-- death_date: string ``` **範例程式碼** ``` # Example: Use spigot to write sample records # to a destination during a transformation # from pyspark.context import SparkContext. # Replace DOC-EXAMPLE-BUCKET with your own location. from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Load table data into a DynamicFrame persons = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="persons_json" ) # Perform the select_fields on the DynamicFrame persons = persons.select_fields(paths=["family_name", "given_name", "birth_date"]) # Use spigot to write a sample of the transformed data # (the first 10 records) spigot_output = persons.spigot( path="s3://DOC-EXAMPLE-BUCKET", options={"topk": 10} ) # Example: Use spigot to write sample records # to a destination during a transformation # from pyspark.context import SparkContext. # Replace DOC-EXAMPLE-BUCKET with your own location. from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Load table data into a DynamicFrame persons = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="persons_json" ) # Perform the select_fields on the DynamicFrame persons = persons.select_fields(paths=["family_name", "given_name", "birth_date"]) # Use spigot to write a sample of the transformed data # (the first 10 records) spigot_output = persons.spigot( path="s3://DOC-EXAMPLE-BUCKET", options={"topk": 10} ) ``` #### Output 以下是 `spigot` 寫入 Amazon S3 的資料範例。由於範例程式碼指定了 `options={"topk": 10}`，範例資料會包含前 10 筆記錄。 ``` {"family_name":"Collins","given_name":"Michael","birth_date":"1944-10-15"} {"family_name":"Huizenga","given_name":"Bill","birth_date":"1969-01-31"} {"family_name":"Clawson","given_name":"Curtis","birth_date":"1959-09-28"} {"family_name":"Solomon","given_name":"Gerald","birth_date":"1930-08-14"} {"family_name":"Rigell","given_name":"Edward","birth_date":"1960-05-28"} {"family_name":"Crapo","given_name":"Michael","birth_date":"1951-05-20"} {"family_name":"Hutto","given_name":"Earl","birth_date":"1926-05-12"} {"family_name":"Ertel","given_name":"Allen","birth_date":"1937-11-07"} {"family_name":"Minish","given_name":"Joseph","birth_date":"1916-09-01"} {"family_name":"Andrews","given_name":"Robert","birth_date":"1957-08-04"} ``` ## split\$1fields **`split_fields(paths, name1, name2, transformation_ctx="", info="", stageThreshold=0, totalThreshold=0)`** 傳回新的 `DynamicFrameCollection`，其包含兩個 `DynamicFrames`。第一個 `DynamicFrame` 包含分割的所有節點，第二個包含其餘節點。 + `paths` – 字串清單，其各自為想要分割到新 `DynamicFrame` 的節點的完整路徑。 + `name1` – 分割的 `DynamicFrame` 的名稱字串。 + `name2` – 分割指定節點後剩餘的 `DynamicFrame` 的名稱字串。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `totalThreshold` –直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 ### 範例：使用 split\$1fields 將選取的欄位分割為單獨的 `DynamicFrame` 此程式碼範例會使用 `split_fields` 方法，將指定欄位的清單分割為單獨的 `DynamicFrame`。 **範例資料集** 該範例使用稱為 `l_root_contact_details` 的 `DynamicFrame`，其來自名為 `legislators_relationalized` 的集合。 `l_root_contact_details` 具有以下結構描述和項目。 ``` root |-- id: long |-- index: int |-- contact_details.val.type: string |-- contact_details.val.value: string +---+-----+------------------------+-------------------------+ | id|index|contact_details.val.type|contact_details.val.value| +---+-----+------------------------+-------------------------+ | 1| 0| phone| 202-225-5265| | 1| 1| twitter| kathyhochul| | 2| 0| phone| 202-225-3252| | 2| 1| twitter| repjackyrosen| | 3| 0| fax| 202-225-1314| | 3| 1| phone| 202-225-3772| ... ``` **範例程式碼** ``` # Example: Use split_fields to split selected # fields into a separate DynamicFrame from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Load the input DynamicFrame and inspect its schema frame_to_split = legislators_relationalized.select("l_root_contact_details") print("Inspect the input DynamicFrame schema:") frame_to_split.printSchema() # Split id and index fields into a separate DynamicFrame split_fields_collection = frame_to_split.split_fields(["id", "index"], "left", "right") # Inspect the resulting DynamicFrames print("Inspect the schemas of the DynamicFrames created with split_fields:") split_fields_collection.select("left").printSchema() split_fields_collection.select("right").printSchema() ``` #### Output ``` Inspect the input DynamicFrame's schema: root |-- id: long |-- index: int |-- contact_details.val.type: string |-- contact_details.val.value: string Inspect the schemas of the DynamicFrames created with split_fields: root |-- id: long |-- index: int root |-- contact_details.val.type: string |-- contact_details.val.value: string ``` ## split\$1rows **`split_rows(comparison_dict, name1, name2, transformation_ctx="", info="", stageThreshold=0, totalThreshold=0)`** 將 `DynamicFrame` 中一個或多個欄分割成新的 `DynamicFrame`。 該方法傳回新的 `DynamicFrameCollection`，其包含兩個 `DynamicFrames`。第一個 `DynamicFrame` 包含分割的所有列，第二個包含其餘節列。 + `comparison_dict` – 一個字典，其中索引鍵為欄位的路徑，而對於與欄位數值相比較的數值而言，此數值為另一種字典映射比較運算子。例如，`{"age": {">": 10, "<": 20}}` 分割所有資料列，其年齡欄中的值大於 10 且小於 20。 + `name1` – 分割的 `DynamicFrame` 的名稱字串。 + `name2` – 分割指定節點後剩餘的 `DynamicFrame` 的名稱字串。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `totalThreshold` –直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 ### 範例：使用 split\$1rows 來分割 `DynamicFrame` 中的列 此程式碼範例使用 `split_rows` 方法，根據 `id` 欄位值來分割 `DynamicFrame` 中的列。 **範例資料集** 該範例使用稱為 `l_root_contact_details` 的 `DynamicFrame`，其選自名為 `legislators_relationalized` 的集合。 `l_root_contact_details` 具有以下結構描述和項目。 ``` root |-- id: long |-- index: int |-- contact_details.val.type: string |-- contact_details.val.value: string +---+-----+------------------------+-------------------------+ | id|index|contact_details.val.type|contact_details.val.value| +---+-----+------------------------+-------------------------+ | 1| 0| phone| 202-225-5265| | 1| 1| twitter| kathyhochul| | 2| 0| phone| 202-225-3252| | 2| 1| twitter| repjackyrosen| | 3| 0| fax| 202-225-1314| | 3| 1| phone| 202-225-3772| | 3| 2| twitter| MikeRossUpdates| | 4| 0| fax| 202-225-1314| | 4| 1| phone| 202-225-3772| | 4| 2| twitter| MikeRossUpdates| | 5| 0| fax| 202-225-1314| | 5| 1| phone| 202-225-3772| | 5| 2| twitter| MikeRossUpdates| | 6| 0| fax| 202-225-1314| | 6| 1| phone| 202-225-3772| | 6| 2| twitter| MikeRossUpdates| | 7| 0| fax| 202-225-1314| | 7| 1| phone| 202-225-3772| | 7| 2| twitter| MikeRossUpdates| | 8| 0| fax| 202-225-1314| +---+-----+------------------------+-------------------------+ ``` **範例程式碼** ``` # Example: Use split_rows to split up # rows in a DynamicFrame based on value from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Retrieve the DynamicFrame to split frame_to_split = legislators_relationalized.select("l_root_contact_details") # Split up rows by ID split_rows_collection = frame_to_split.split_rows({"id": {">": 10}}, "high", "low") # Inspect the resulting DynamicFrames print("Inspect the DynamicFrame that contains IDs < 10") split_rows_collection.select("low").toDF().show() print("Inspect the DynamicFrame that contains IDs > 10") split_rows_collection.select("high").toDF().show() ``` #### Output ``` Inspect the DynamicFrame that contains IDs < 10 +---+-----+------------------------+-------------------------+ | id|index|contact_details.val.type|contact_details.val.value| +---+-----+------------------------+-------------------------+ | 1| 0| phone| 202-225-5265| | 1| 1| twitter| kathyhochul| | 2| 0| phone| 202-225-3252| | 2| 1| twitter| repjackyrosen| | 3| 0| fax| 202-225-1314| | 3| 1| phone| 202-225-3772| | 3| 2| twitter| MikeRossUpdates| | 4| 0| fax| 202-225-1314| | 4| 1| phone| 202-225-3772| | 4| 2| twitter| MikeRossUpdates| | 5| 0| fax| 202-225-1314| | 5| 1| phone| 202-225-3772| | 5| 2| twitter| MikeRossUpdates| | 6| 0| fax| 202-225-1314| | 6| 1| phone| 202-225-3772| | 6| 2| twitter| MikeRossUpdates| | 7| 0| fax| 202-225-1314| | 7| 1| phone| 202-225-3772| | 7| 2| twitter| MikeRossUpdates| | 8| 0| fax| 202-225-1314| +---+-----+------------------------+-------------------------+ only showing top 20 rows Inspect the DynamicFrame that contains IDs > 10 +---+-----+------------------------+-------------------------+ | id|index|contact_details.val.type|contact_details.val.value| +---+-----+------------------------+-------------------------+ | 11| 0| phone| 202-225-5476| | 11| 1| twitter| RepDavidYoung| | 12| 0| phone| 202-225-4035| | 12| 1| twitter| RepStephMurphy| | 13| 0| fax| 202-226-0774| | 13| 1| phone| 202-225-6335| | 14| 0| fax| 202-226-0774| | 14| 1| phone| 202-225-6335| | 15| 0| fax| 202-226-0774| | 15| 1| phone| 202-225-6335| | 16| 0| fax| 202-226-0774| | 16| 1| phone| 202-225-6335| | 17| 0| fax| 202-226-0774| | 17| 1| phone| 202-225-6335| | 18| 0| fax| 202-226-0774| | 18| 1| phone| 202-225-6335| | 19| 0| fax| 202-226-0774| | 19| 1| phone| 202-225-6335| | 20| 0| fax| 202-226-0774| | 20| 1| phone| 202-225-6335| +---+-----+------------------------+-------------------------+ only showing top 20 rows ``` ## unbox **`unbox(path, format, transformation_ctx="", info="", stageThreshold=0, totalThreshold=0, **options)`** 將 `DynamicFrame` 中的字串欄位拆箱 (重新格式化)，並傳回包含拆箱的 `DynamicRecords` 的新 `DynamicFrame`。 `DynamicRecord` 代表 `DynamicFrame` 中的邏輯記錄。它類似 Apache Spark `DataFrame` 中的一列，除了它是自我描述的，以及可用於不符合固定結構描述的資料。 + `path` – 要拆箱之字串節點的完整路徑。 + `format` – 格式化規格 (選用)。您可將其用於 Amazon S3 或支援多種格式的 AWS Glue 連線。如需了解受支援的格式，請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `totalThreshold` –直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `options` – 下列一或多個： + `separator` – 包含分隔符號字元的字串。 + `escaper` – 包含逸出字元的字串。 + `skipFirst` – 布林值，指出是否略過第一個執行個體。 + `withSchema`：包含節點結構描述的 JSON 表示法的字串。結構描述的 JSON 表示法的格式由 `StructType.json()` 的輸出定義。 + `withHeader` – 布林值，指出是否包含標頭。 ### 範例：使用 unbox 將字串欄位拆箱到結構中 此程式碼範例使用 `unbox` 方法，將 `DynamicFrame` 中的字串欄位*拆箱*或重新格式化為結構類型的欄位。 **範例資料集** 此範例搭配使用稱為 `mapped_with_string` 的 `DynamicFrame` 與下列結構描述和項目。 請注意名為 `AddressString` 的欄位。這是範例拆箱為結構的欄位。 ``` root |-- Average Total Payments: string |-- AddressString: string |-- Average Covered Charges: string |-- DRG Definition: string |-- Average Medicare Payments: string |-- Hospital Referral Region Description: string |-- Address: struct | |-- Zip.Code: string | |-- City: string | |-- Array: array | | |-- element: string | |-- State: string | |-- Street: string |-- Provider Id: string |-- Total Discharges: string |-- Provider Name: string +----------------------+--------------------+-----------------------+--------------------+-------------------------+------------------------------------+--------------------+-----------+----------------+--------------------+ |Average Total Payments| AddressString|Average Covered Charges| DRG Definition|Average Medicare Payments|Hospital Referral Region Description| Address|Provider Id|Total Discharges| Provider Name| +----------------------+--------------------+-----------------------+--------------------+-------------------------+------------------------------------+--------------------+-----------+----------------+--------------------+ | $5777.24|{"Street": "1108 ...| $32963.07|039 - EXTRACRANIA...| $4763.73| AL - Dothan|[36301, DOTHAN, [...| 10001| 91|SOUTHEAST ALABAMA...| | $5787.57|{"Street": "2505 ...| $15131.85|039 - EXTRACRANIA...| $4976.71| AL - Birmingham|[35957, BOAZ, [25...| 10005| 14|MARSHALL MEDICAL ...| | $5434.95|{"Street": "205 M...| $37560.37|039 - EXTRACRANIA...| $4453.79| AL - Birmingham|[35631, FLORENCE,...| 10006| 24|ELIZA COFFEE MEMO...| | $5417.56|{"Street": "50 ME...| $13998.28|039 - EXTRACRANIA...| $4129.16| AL - Birmingham|[35235, BIRMINGHA...| 10011| 25| ST VINCENT'S EAST| ... ``` **範例程式碼** ``` # Example: Use unbox to unbox a string field # into a struct in a DynamicFrame from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) unboxed = mapped_with_string.unbox("AddressString", "json") unboxed.printSchema() unboxed.toDF().show() ``` #### Output ``` root |-- Average Total Payments: string |-- AddressString: struct | |-- Street: string | |-- City: string | |-- State: string | |-- Zip.Code: string | |-- Array: array | | |-- element: string |-- Average Covered Charges: string |-- DRG Definition: string |-- Average Medicare Payments: string |-- Hospital Referral Region Description: string |-- Address: struct | |-- Zip.Code: string | |-- City: string | |-- Array: array | | |-- element: string | |-- State: string | |-- Street: string |-- Provider Id: string |-- Total Discharges: string |-- Provider Name: string +----------------------+--------------------+-----------------------+--------------------+-------------------------+------------------------------------+--------------------+-----------+----------------+--------------------+ |Average Total Payments| AddressString|Average Covered Charges| DRG Definition|Average Medicare Payments|Hospital Referral Region Description| Address|Provider Id|Total Discharges| Provider Name| +----------------------+--------------------+-----------------------+--------------------+-------------------------+------------------------------------+--------------------+-----------+----------------+--------------------+ | $5777.24|[1108 ROSS CLARK ...| $32963.07|039 - EXTRACRANIA...| $4763.73| AL - Dothan|[36301, DOTHAN, [...| 10001| 91|SOUTHEAST ALABAMA...| | $5787.57|[2505 U S HIGHWAY...| $15131.85|039 - EXTRACRANIA...| $4976.71| AL - Birmingham|[35957, BOAZ, [25...| 10005| 14|MARSHALL MEDICAL ...| | $5434.95|[205 MARENGO STRE...| $37560.37|039 - EXTRACRANIA...| $4453.79| AL - Birmingham|[35631, FLORENCE,...| 10006| 24|ELIZA COFFEE MEMO...| | $5417.56|[50 MEDICAL PARK ...| $13998.28|039 - EXTRACRANIA...| $4129.16| AL - Birmingham|[35235, BIRMINGHA...| 10011| 25| ST VINCENT'S EAST| | $5658.33|[1000 FIRST STREE...| $31633.27|039 - EXTRACRANIA...| $4851.44| AL - Birmingham|[35007, ALABASTER...| 10016| 18|SHELBY BAPTIST ME...| | $6653.80|[2105 EAST SOUTH ...| $16920.79|039 - EXTRACRANIA...| $5374.14| AL - Montgomery|[36116, MONTGOMER...| 10023| 67|BAPTIST MEDICAL C...| | $5834.74|[2000 PEPPERELL P...| $11977.13|039 - EXTRACRANIA...| $4761.41| AL - Birmingham|[36801, OPELIKA, ...| 10029| 51|EAST ALABAMA MEDI...| | $8031.12|[619 SOUTH 19TH S...| $35841.09|039 - EXTRACRANIA...| $5858.50| AL - Birmingham|[35233, BIRMINGHA...| 10033| 32|UNIVERSITY OF ALA...| | $6113.38|[101 SIVLEY RD, H...| $28523.39|039 - EXTRACRANIA...| $5228.40| AL - Huntsville|[35801, HUNTSVILL...| 10039| 135| HUNTSVILLE HOSPITAL| | $5541.05|[1007 GOODYEAR AV...| $75233.38|039 - EXTRACRANIA...| $4386.94| AL - Birmingham|[35903, GADSDEN, ...| 10040| 34|GADSDEN REGIONAL ...| | $5461.57|[600 SOUTH THIRD ...| $67327.92|039 - EXTRACRANIA...| $4493.57| AL - Birmingham|[35901, GADSDEN, ...| 10046| 14|RIVERVIEW REGIONA...| | $5356.28|[4370 WEST MAIN S...| $39607.28|039 - EXTRACRANIA...| $4408.20| AL - Dothan|[36305, DOTHAN, [...| 10055| 45| FLOWERS HOSPITAL| | $5374.65|[810 ST VINCENT'S...| $22862.23|039 - EXTRACRANIA...| $4186.02| AL - Birmingham|[35205, BIRMINGHA...| 10056| 43|ST VINCENT'S BIRM...| | $5366.23|[400 EAST 10TH ST...| $31110.85|039 - EXTRACRANIA...| $4376.23| AL - Birmingham|[36207, ANNISTON,...| 10078| 21|NORTHEAST ALABAMA...| | $5282.93|[1613 NORTH MCKEN...| $25411.33|039 - EXTRACRANIA...| $4383.73| AL - Mobile|[36535, FOLEY, [1...| 10083| 15|SOUTH BALDWIN REG...| | $5676.55|[1201 7TH STREET ...| $9234.51|039 - EXTRACRANIA...| $4509.11| AL - Huntsville|[35609, DECATUR, ...| 10085| 27|DECATUR GENERAL H...| | $5930.11|[6801 AIRPORT BOU...| $15895.85|039 - EXTRACRANIA...| $3972.85| AL - Mobile|[36608, MOBILE, [...| 10090| 27| PROVIDENCE HOSPITAL| | $6192.54|[809 UNIVERSITY B...| $19721.16|039 - EXTRACRANIA...| $5179.38| AL - Tuscaloosa|[35401, TUSCALOOS...| 10092| 31|D C H REGIONAL ME...| | $4968.00|[750 MORPHY AVENU...| $10710.88|039 - EXTRACRANIA...| $3898.88| AL - Mobile|[36532, FAIRHOPE,...| 10100| 18| THOMAS HOSPITAL| | $5996.00|[701 PRINCETON AV...| $51343.75|039 - EXTRACRANIA...| $4962.45| AL - Birmingham|[35211, BIRMINGHA...| 10103| 33|BAPTIST MEDICAL C...| +----------------------+--------------------+-----------------------+--------------------+-------------------------+------------------------------------+--------------------+-----------+----------------+--------------------+ only showing top 20 rows ``` ## 聯集 **`union(frame1, frame2, transformation_ctx = "", info = "", stageThreshold = 0, totalThreshold = 0)`** 將兩個 DynamicFrames 聯集。傳回 DynamicFrame，其中包含來自兩個輸入 DynamicFrames 的所有記錄。此轉換可能會從兩個具有對等資料的 DataFrames 聯集傳回不同結果。若您需要 Spark DataFrame 聯集行為，請考慮使用 `toDF`。 + `frame1` – 要聯集的第一個 DynamicFrame。 + `frame2` – 要聯集的第二個 DynamicFrame。 + `transformation_ctx` – (選用) 用於識別統計資料/狀態資訊的唯一字串 + `info` – (選用) 與轉換中的錯誤相關的任何字串 + `stageThreshold` – (選用) 在處理輸出錯誤之前，轉換中的最大錯誤數 + `totalThreshold` – (選用) 在處理輸出錯誤之前的最大錯誤數。 ## 解巢狀 **`unnest(transformation_ctx="", info="", stageThreshold=0, totalThreshold=0)`** 對 `DynamicFrame` 中的巢狀化物件進行解除巢狀化，將其變為頂層元素，並傳回新的未巢狀化 `DynamicFrame`。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 + `totalThreshold` –直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用)。預設值為零，表示此流程不會發生錯誤。 ### 範例：使用 unnest 將巢狀化欄位轉換為頂層欄位 此程式碼範例使用 `unnest` 方法，將 `DynamicFrame` 中的所有巢狀化欄位壓平合併為頂層欄位。 **範例資料集** 此範例搭配使用稱為 `mapped_medicare` 的 `DynamicFrame` 與下列結構描述。請注意，`Address` 欄位是唯一包含巢狀化資料的欄位。 ``` root |-- Average Total Payments: string |-- Average Covered Charges: string |-- DRG Definition: string |-- Average Medicare Payments: string |-- Hospital Referral Region Description: string |-- Address: struct | |-- Zip.Code: string | |-- City: string | |-- Array: array | | |-- element: string | |-- State: string | |-- Street: string |-- Provider Id: string |-- Total Discharges: string |-- Provider Name: string ``` **範例程式碼** ``` # Example: Use unnest to unnest nested # objects in a DynamicFrame from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Unnest all nested fields unnested = mapped_medicare.unnest() unnested.printSchema() ``` #### Output ``` root |-- Average Total Payments: string |-- Average Covered Charges: string |-- DRG Definition: string |-- Average Medicare Payments: string |-- Hospital Referral Region Description: string |-- Address.Zip.Code: string |-- Address.City: string |-- Address.Array: array | |-- element: string |-- Address.State: string |-- Address.Street: string |-- Provider Id: string |-- Total Discharges: string |-- Provider Name: string ``` ## unnest\$1ddb\$1json 解除專屬於 DynamoDB JSON 結構中 `DynamicFrame` 內的巢狀欄的巢狀化，並傳回新的解巢狀 `DynamicFrame`。結構類型陣列的欄將不是解巢狀狀態。請注意，這是一種特定類型的解除巢狀化轉換，其行為與常規 `unnest` 轉換不同，且資料必須已經位於 DynamoDB JSON 結構中。如需詳細資訊，請參閱 [DynamoDB JSON](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataExport.Output.html#DataExport.Output.Data)。 **`unnest_ddb_json(transformation_ctx="", info="", stageThreshold=0, totalThreshold=0)`** + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與此轉換回報錯誤關聯的字串 (選用)。 + `stageThreshold` – 此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用：預設為 0，表示流程不會錯誤輸出)。 + `totalThreshold` – 直到及包含此轉換期間流程應錯誤輸出之前遇到的錯誤次數 (選用：預設為 0，表示流程不會錯誤輸出)。 例如，讀取 DynamoDB JSON 結構的匯出結構描述與以下類似： ``` root |-- Item: struct | |-- ColA: struct | | |-- S: string | |-- ColB: struct | | |-- S: string | |-- ColC: struct | | |-- N: string | |-- ColD: struct | | |-- L: array | | | |-- element: null ``` `unnest_ddb_json()` 轉換會將此轉換為： ``` root |-- ColA: string |-- ColB: string |-- ColC: string |-- ColD: array | |-- element: null ``` 下列程式碼範例示範如何使用 AWS Glue DynamoDB 匯出連接器、叫用 DynamoDB JSON unnest，以及列印分割區數量： ``` 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_options( connection_type="dynamodb", connection_options={ "dynamodb.export": "ddb", "dynamodb.tableArn": "", "dynamodb.s3.bucket": "", "dynamodb.s3.prefix": "", "dynamodb.s3.bucketOwner": "", } ) unnested = dynamicFrame.unnest_ddb_json() print(unnested.getNumPartitions()) job.commit() ``` ## write **`write(connection_type, connection_options, format, format_options, accumulator_size)`** 從此 `DynamicFrame` 的 [GlueContext 類別](aws-glue-api-crawler-pyspark-extensions-glue-context.md) 取得指定連線類型的 [DataSink(object)](aws-glue-api-crawler-pyspark-extensions-types.md#aws-glue-api-crawler-pyspark-extensions-types-awsglue-data-sink)，並用其來格式化及寫入此 `DynamicFrame` 的內容。傳回依指定格式化和寫入的新 `DynamicFrame`。 + `connection_type` – 使用的連線類型。有效值包括 `s3`、`mysql`、`postgresql`、`redshift`、`sqlserver` 及 `oracle`。 + `connection_options` – 使用的連線選項 (選用)。如果是 `connection_type` 的 `s3`，會定義 Amazon S3 路徑。 ``` connection_options = {"path": "s3://aws-glue-target/temp"} ``` 如果是 JDBC 連線，必須定義幾項屬性。請注意，資料庫名稱必須是 URL 的一部分。它可以選擇性包含在連線選項中。 **警告** 不建議在指令碼中存放密碼。考慮使用 從 AWS Secrets Manager 或 Glue Data Catalog AWS `boto3`擷取它們。 ``` connection_options = {"url": "jdbc-url/database", "user": "username", "password": passwordVariable,"dbtable": "table-name", "redshiftTmpDir": "s3-tempdir-path"} ``` + `format` – 格式化規格 (選用)。這用於 Amazon Simple Storage Service (Amazon S3) 或支援多種格式的 AWS Glue 連線。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `format_options` – 指定格式的格式選項。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `accumulator_size`：要使用的 accumulable 大小，以位元組為單位 (選用)。 ##  — errors — + [assertErrorThreshold](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-assertErrorThreshold) + [errorsAsDynamicFrame](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-errorsAsDynamicFrame) + [errorsCount](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-errorsCount) + [stageErrorsCount](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-stageErrorsCount) ## assertErrorThreshold `assertErrorThreshold( )` – 建立此 `DynamicFrame` 的轉換中的錯誤宣告。從基礎 `DataFrame` 傳回 `Exception`。 ## errorsAsDynamicFrame `errorsAsDynamicFrame( )` – 傳回 `DynamicFrame`，其內部有巢狀的錯誤記錄。 ### 範例：使用 errorsAsDynamicFrame 來檢視錯誤記錄 以下程式碼範例顯示如何使用 `errorsAsDynamicFrame` 方法來檢視 `DynamicFrame` 的錯誤記錄。 **範例資料集** 此範例使用下列資料集，您可以將其作為 JSON 上傳到 Amazon S3。請注意，第二條記錄的格式錯誤。當您使用 SparkSQL 時，格式錯誤的資料通常會中斷檔案剖析。但是，`DynamicFrame` 會辨識出格式錯誤問題，並將格式錯誤的行轉換為可以單獨處理的錯誤記錄。 ``` {"id": 1, "name": "george", "surname": "washington", "height": 178} {"id": 2, "name": "benjamin", "surname": "franklin", {"id": 3, "name": "alexander", "surname": "hamilton", "height": 171} {"id": 4, "name": "john", "surname": "jay", "height": 190} ``` **範例程式碼** ``` # Example: Use errorsAsDynamicFrame to view error records. # Replace s3://DOC-EXAMPLE-S3-BUCKET/error_data.json with your location. from pyspark.context import SparkContext from awsglue.context import GlueContext # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Create errors DynamicFrame, view schema errors = glueContext.create_dynamic_frame.from_options( "s3", {"paths": ["s3://DOC-EXAMPLE-S3-BUCKET/error_data.json"]}, "json" ) print("Schema of errors DynamicFrame:") errors.printSchema() # Show that errors only contains valid entries from the dataset print("errors contains only valid records from the input dataset (2 of 4 records)") errors.toDF().show() # View errors print("Errors count:", str(errors.errorsCount())) print("Errors:") errors.errorsAsDynamicFrame().toDF().show() # View error fields and error data error_record = errors.errorsAsDynamicFrame().toDF().head() error_fields = error_record["error"] print("Error fields: ") print(error_fields.asDict().keys()) print("\nError record data:") for key in error_fields.asDict().keys(): print("\n", key, ": ", str(error_fields[key])) ``` #### Output ``` Schema of errors DynamicFrame: root |-- id: int |-- name: string |-- surname: string |-- height: int errors contains only valid records from the input dataset (2 of 4 records) +---+------+----------+------+ | id| name| surname|height| +---+------+----------+------+ | 1|george|washington| 178| | 4| john| jay| 190| +---+------+----------+------+ Errors count: 1 Errors: +--------------------+ | error| +--------------------+ |[[ File "/tmp/20...| +--------------------+ Error fields: dict_keys(['callsite', 'msg', 'stackTrace', 'input', 'bytesread', 'source', 'dynamicRecord']) Error record data: callsite : Row(site=' File "/tmp/2060612586885849088", line 549, in \n sys.exit(main())\n File "/tmp/2060612586885849088", line 523, in main\n response = handler(content)\n File "/tmp/2060612586885849088", line 197, in execute_request\n result = node.execute()\n File "/tmp/2060612586885849088", line 103, in execute\n exec(code, global_dict)\n File "", line 10, in \n File "/opt/amazon/lib/python3.6/site-packages/awsglue/dynamicframe.py", line 625, in from_options\n format_options, transformation_ctx, push_down_predicate, **kwargs)\n File "/opt/amazon/lib/python3.6/site-packages/awsglue/context.py", line 233, in create_dynamic_frame_from_options\n source.setFormat(format, **format_options)\n', info='') msg : error in jackson reader stackTrace : com.fasterxml.jackson.core.JsonParseException: Unexpected character ('{' (code 123)): was expecting either valid name character (for unquoted name) or double-quote (for quoted) to start field name at [Source: com.amazonaws.services.glue.readers.BufferedStream@73492578; line: 3, column: 2] at com.fasterxml.jackson.core.JsonParser._constructError(JsonParser.java:1581) at com.fasterxml.jackson.core.base.ParserMinimalBase._reportError(ParserMinimalBase.java:533) at com.fasterxml.jackson.core.base.ParserMinimalBase._reportUnexpectedChar(ParserMinimalBase.java:462) at com.fasterxml.jackson.core.json.UTF8StreamJsonParser._handleOddName(UTF8StreamJsonParser.java:2012) at com.fasterxml.jackson.core.json.UTF8StreamJsonParser._parseName(UTF8StreamJsonParser.java:1650) at com.fasterxml.jackson.core.json.UTF8StreamJsonParser.nextToken(UTF8StreamJsonParser.java:740) at com.amazonaws.services.glue.readers.JacksonReader$$anonfun$hasNextGoodToken$1.apply(JacksonReader.scala:57) at com.amazonaws.services.glue.readers.JacksonReader$$anonfun$hasNextGoodToken$1.apply(JacksonReader.scala:57) at scala.collection.Iterator$$anon$9.next(Iterator.scala:162) at scala.collection.Iterator$$anon$16.hasNext(Iterator.scala:599) at scala.collection.Iterator$$anon$16.hasNext(Iterator.scala:598) at scala.collection.Iterator$class.foreach(Iterator.scala:891) at scala.collection.AbstractIterator.foreach(Iterator.scala:1334) at com.amazonaws.services.glue.readers.JacksonReader$$anonfun$1.apply(JacksonReader.scala:120) at com.amazonaws.services.glue.readers.JacksonReader$$anonfun$1.apply(JacksonReader.scala:116) at com.amazonaws.services.glue.DynamicRecordBuilder.handleErr(DynamicRecordBuilder.scala:209) at com.amazonaws.services.glue.DynamicRecordBuilder.handleErrorWithException(DynamicRecordBuilder.scala:202) at com.amazonaws.services.glue.readers.JacksonReader.nextFailSafe(JacksonReader.scala:116) at com.amazonaws.services.glue.readers.JacksonReader.next(JacksonReader.scala:109) at com.amazonaws.services.glue.readers.JSONReader.next(JSONReader.scala:247) at com.amazonaws.services.glue.hadoop.TapeHadoopRecordReaderSplittable.nextKeyValue(TapeHadoopRecordReaderSplittable.scala:103) at org.apache.spark.rdd.NewHadoopRDD$$anon$1.hasNext(NewHadoopRDD.scala:230) at org.apache.spark.InterruptibleIterator.hasNext(InterruptibleIterator.scala:37) at scala.collection.Iterator$$anon$11.hasNext(Iterator.scala:409) at scala.collection.Iterator$$anon$11.hasNext(Iterator.scala:409) at scala.collection.Iterator$$anon$13.hasNext(Iterator.scala:462) at scala.collection.Iterator$$anon$11.hasNext(Iterator.scala:409) at scala.collection.Iterator$$anon$11.hasNext(Iterator.scala:409) at scala.collection.Iterator$$anon$13.hasNext(Iterator.scala:462) at scala.collection.Iterator$$anon$11.hasNext(Iterator.scala:409) at scala.collection.Iterator$$anon$11.hasNext(Iterator.scala:409) at org.apache.spark.sql.execution.SparkPlan$$anonfun$2.apply(SparkPlan.scala:255) at org.apache.spark.sql.execution.SparkPlan$$anonfun$2.apply(SparkPlan.scala:247) at org.apache.spark.rdd.RDD$$anonfun$mapPartitionsInternal$1$$anonfun$apply$24.apply(RDD.scala:836) at org.apache.spark.rdd.RDD$$anonfun$mapPartitionsInternal$1$$anonfun$apply$24.apply(RDD.scala:836) at org.apache.spark.rdd.MapPartitionsRDD.compute(MapPartitionsRDD.scala:52) at org.apache.spark.rdd.RDD.computeOrReadCheckpoint(RDD.scala:324) at org.apache.spark.rdd.RDD.iterator(RDD.scala:288) at org.apache.spark.rdd.MapPartitionsRDD.compute(MapPartitionsRDD.scala:52) at org.apache.spark.rdd.RDD.computeOrReadCheckpoint(RDD.scala:324) at org.apache.spark.rdd.RDD.iterator(RDD.scala:288) at org.apache.spark.scheduler.ResultTask.runTask(ResultTask.scala:90) at org.apache.spark.scheduler.Task.run(Task.scala:121) at org.apache.spark.executor.Executor$TaskRunner$$anonfun$10.apply(Executor.scala:408) at org.apache.spark.util.Utils$.tryWithSafeFinally(Utils.scala:1360) at org.apache.spark.executor.Executor$TaskRunner.run(Executor.scala:414) at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149) at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624) at java.lang.Thread.run(Thread.java:750) input : bytesread : 252 source : dynamicRecord : Row(id=2, name='benjamin', surname='franklin') ``` ## 全方位 DynamicFrame 範例 下列範例示範在基本 Glue 目錄案例之外建立和使用 DynamicFrames 的各種方法。 ### 使用 SQL SELECT 查詢從 PostgreSQL 載入 此範例說明如何使用自訂 SQL SELECT 查詢從 PostgreSQL 資料庫載入資料： ``` from awsglue.context import GlueContext from pyspark.context import SparkContext sc = SparkContext() glueContext = GlueContext(sc) # Load specific data from PostgreSQL with custom query postgres_dyf = glueContext.create_dynamic_frame.from_options( connection_type="postgresql", connection_options={ "url": "jdbc:postgresql://your-postgres-host:5432/your-database", "user": "your-username", "password": "your-password", "dbtable": "(SELECT customer_id, customer_name, email FROM customers WHERE active = true) AS filtered_customers" } ) ``` ### 載入特定資料欄以避免完整資料表掃描 此範例示範如何僅從大型資料庫資料表載入特定資料欄： ``` from awsglue.context import GlueContext from pyspark.context import SparkContext sc = SparkContext() glueContext = GlueContext(sc) # Load only specific columns from a large table selected_columns_dyf = glueContext.create_dynamic_frame.from_options( connection_type="mysql", connection_options={ "url": "jdbc:mysql://your-mysql-host:3306/your-database", "user": "your-username", "password": "your-password", "dbtable": "(SELECT order_id, customer_id FROM large_orders_table) AS selected_data" } ) # Alternative approach using column selection in query efficient_load_dyf = glueContext.create_dynamic_frame.from_options( connection_type="postgresql", connection_options={ "url": "jdbc:postgresql://your-postgres-host:5432/your-database", "user": "your-username", "password": "your-password", "query": "SELECT product_id, product_name FROM products WHERE category = 'electronics'" } ) ``` ### 透過 JDBC 連線進行資料列層級篩選 此範例示範如何使用資料列層級篩選，僅從資料庫資料表載入特定資料列： ``` from awsglue.context import GlueContext from pyspark.context import SparkContext sc = SparkContext() glueContext = GlueContext(sc) # Load filtered rows using WHERE clause filtered_rows_dyf = glueContext.create_dynamic_frame.from_options( connection_type="postgresql", connection_options={ "url": "jdbc:postgresql://your-postgres-host:5432/your-database", "user": "your-username", "password": "your-password", "dbtable": "(SELECT * FROM transactions WHERE transaction_date >= '2024-01-01' AND amount > 100) AS recent_large_transactions" } ) # Using partitionColumn for parallel loading with filtering partitioned_load_dyf = glueContext.create_dynamic_frame.from_options( connection_type="mysql", connection_options={ "url": "jdbc:mysql://your-mysql-host:3306/your-database", "user": "your-username", "password": "your-password", "dbtable": "sales_data", "partitionColumn": "sale_date", "lowerBound": "2024-01-01", "upperBound": "2024-12-31", "numPartitions": "10" } ) ``` ### 從記憶體內 Python 資料建立 DynamicFrame 此範例示範如何從 Python 清單、元組或字典建立 DynamicFrame： ``` from awsglue.context import GlueContext from awsglue.dynamicframe import DynamicFrame from pyspark.context import SparkContext from pyspark.sql import Row sc = SparkContext() glueContext = GlueContext(sc) # Method 1: From list of tuples data_tuples = [ ("John", "Doe", 30, "Engineer"), ("Jane", "Smith", 25, "Designer"), ("Bob", "Johnson", 35, "Manager") ] # Convert to RDD of Rows rdd = sc.parallelize([Row(first_name=row[0], last_name=row[1], age=row[2], job=row[3]) for row in data_tuples]) df = glueContext.spark_session.createDataFrame(rdd) dyf_from_tuples = DynamicFrame.fromDF(df, glueContext, "employees_from_tuples") # Method 2: From list of dictionaries data_dicts = [ {"product_id": 1, "product_name": "Laptop", "price": 999.99, "category": "Electronics"}, {"product_id": 2, "product_name": "Book", "price": 19.99, "category": "Education"}, {"product_id": 3, "product_name": "Chair", "price": 149.99, "category": "Furniture"} ] df_from_dicts = glueContext.spark_session.createDataFrame(data_dicts) dyf_from_dicts = DynamicFrame.fromDF(df_from_dicts, glueContext, "products_from_dicts") # Method 3: From nested data structures nested_data = [ { "customer_id": 1, "customer_info": { "name": "Alice Brown", "email": "alice@example.com" }, "orders": [ {"order_id": 101, "amount": 250.00}, {"order_id": 102, "amount": 175.50} ] } ] df_nested = glueContext.spark_session.createDataFrame(nested_data) dyf_nested = DynamicFrame.fromDF(df_nested, glueContext, "customers_with_orders") ``` ### 大型資料集的效能最佳化 使用大型資料集時，請考慮下列效能最佳化技術： ``` # Use partitioning for parallel reads large_table_dyf = glueContext.create_dynamic_frame.from_options( connection_type="postgresql", connection_options={ "url": "jdbc:postgresql://your-postgres-host:5432/your-database", "user": "your-username", "password": "your-password", "dbtable": "large_table", "partitionColumn": "id", "lowerBound": "1", "upperBound": "1000000", "numPartitions": "20" } ) # Use pushdown predicates to filter at source filtered_dyf = glueContext.create_dynamic_frame.from_options( connection_type="mysql", connection_options={ "url": "jdbc:mysql://your-mysql-host:3306/your-database", "user": "your-username", "password": "your-password", "dbtable": "transactions" }, push_down_predicate="transaction_date >= '2024-01-01'" ) ``` ## errorsCount `errorsCount( )` – 傳回 `DynamicFrame` 中的錯誤總數。 ## stageErrorsCount `stageErrorsCount` – 傳回產生此 `DynamicFrame` 過程中發生的錯誤數量。 # DynamicFrameCollection 類別 `DynamicFrameCollection` 為 [DynamicFrame 類別](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md) 物件的字典，其中索引鍵為 `DynamicFrames` 的名稱，值則為 `DynamicFrame` 物件。 ## \$1\$1init\$1\$1 **`__init__(dynamic_frames, glue_ctx)`** + `dynamic_frames` – [DynamicFrame 類別](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md) 物件的字典。 + `glue_ctx` – [GlueContext 類別](aws-glue-api-crawler-pyspark-extensions-glue-context.md) 物件。 ## 金鑰 `keys( )` – 傳回此集合裡的金鑰清單，通常包含了對應的 `DynamicFrame` 值之名稱。 ## 值 `values(key)` – 傳回此集合裡的 `DynamicFrame` 值清單。 ## Select **`select(key)`** 傳回的 `DynamicFrame` 會對應至指定的索引鍵 (通常為 `DynamicFrame` 的名稱)。 + `key` – `DynamicFrameCollection` 中的金鑰，通常代表 `DynamicFrame` 的名稱。 ## Map **`map(callable, transformation_ctx="")`** 使用傳入的函數，根據此集合中的 `DynamicFrames` 建立並傳回新的 `DynamicFrameCollection`。 + `callable` – 此函數會以 `DynamicFrame` 和指定的轉換細節做為參數，並傳回 `DynamicFrame`。 + `transformation_ctx` – 由 callable 使用的轉換細節 (選用)。 ## Flatmap **`flatmap(f, transformation_ctx="")`** 使用傳入的函數，根據此集合中的 `DynamicFrames` 建立並傳回新的 `DynamicFrameCollection`。 + `f` – 此函數以 `DynamicFrame` 做為參數並傳回 `DynamicFrame` 或 `DynamicFrameCollection`。 + `transformation_ctx` – 由函數使用的轉換細節 (選用)。 # DynamicFrameWriter 類別 ##   方法 + [\$1\$1init\$1\$1](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-writer-__init__) + [from\$1options](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-writer-from_options) + [from\$1catalog](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-writer-from_catalog) + [from\$1jdbc\$1conf](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-writer-from_jdbc_conf) ## \$1\$1init\$1\$1 **`__init__(glue_context)`** + `glue_context` – 所要使用的 [GlueContext 類別](aws-glue-api-crawler-pyspark-extensions-glue-context.md)。 ## from\$1options **`from_options(frame, connection_type, connection_options={}, format=None, format_options={}, transformation_ctx="")`** 使用指定的連線和格式來撰寫 `DynamicFrame`。 + `frame` – 所要撰寫的 `DynamicFrame`。 + `connection_type` – 連線類型。有效值包括 `s3`、`mysql`、`postgresql`、`redshift`、`sqlserver` 及 `oracle`。 + `connection_options` – 連線選項，例如路徑和資料庫資料表 (選用)。如果是 `connection_type` 的 `s3`，會定義 Amazon S3 路徑。 ``` connection_options = {"path": "s3://aws-glue-target/temp"} ``` 如果是 JDBC 連線，必須定義幾項屬性。請注意，資料庫名稱必須是 URL 的一部分。它可以選擇性包含在連線選項中。 **警告** 不建議在指令碼中存放密碼。考慮使用 從 AWS Secrets Manager 或 Glue Data Catalog AWS `boto3`擷取它們。 ``` connection_options = {"url": "jdbc-url/database", "user": "username", "password": passwordVariable,"dbtable": "table-name", "redshiftTmpDir": "s3-tempdir-path"} ``` `dbtable` 屬性為 JDBC 資料表的名稱。若是支援資料庫內結構描述的 JDBC 資料存放區，請指定 `schema.table-name`。如果未提供結構描述，則會使用預設的 "public" 結構描述。 如需詳細資訊，請參閱[AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `format` – 格式化規格 (選用)。這用於 Amazon Simple Storage Service (Amazon S3) 或支援多種格式的 AWS Glue 連線。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `format_options` – 指定格式的格式選項。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `transformation_ctx` – 所要使用的轉換細節 (選用)。 ## from\$1catalog **`from_catalog(frame, name_space, table_name, redshift_tmp_dir="", transformation_ctx="")`** 使用指定的目錄資料庫和資料表名稱，來撰寫 `DynamicFrame`。 + `frame` – 所要撰寫的 `DynamicFrame`。 + `name_space` – 所要使用的資料庫。 + `table_name` – 所要使用的 `table_name`。 + `redshift_tmp_dir` – 所要使用的 Amazon Redshift 暫時目錄 (選用)。 + `transformation_ctx` – 所要使用的轉換細節 (選用)。 + `additional_options` – 提供給 AWS Glue 的額外選項。 若要寫入受 Lake Formation 管控的資料表，您可以使用下列其他選項： + `transactionId` – (字串) 要寫入受管控資料表的交易 ID。此交易不能已遞交或中止，否則寫入將失敗。 + `callDeleteObjectsOnCancel ` – (布林值，選用) 如果設定為 `true` (預設值)，則 AWS Glue 會在物件寫入至 Amazon S3 之後自動呼叫 `DeleteObjectsOnCancel` API。如需詳細資訊，請參閱《*AWS Lake Formation 開發人員指南*》中的 [DeleteObjectsOnCancel](https://docs.aws.amazon.com/lake-formation/latest/dg/aws-lake-formation-api-transactions-api.html#aws-lake-formation-api-transactions-api-DeleteObjectsOnCancel)。 **Example 範例：寫入 Lake Formation 中的受管控資料表** ``` txId = glueContext.start_transaction(read_only=False) glueContext.write_dynamic_frame.from_catalog( frame=dyf, database = db, table_name = tbl, transformation_ctx = "datasource0", additional_options={"transactionId":txId}) ... glueContext.commit_transaction(txId) ``` ## from\$1jdbc\$1conf **`from_jdbc_conf(frame, catalog_connection, connection_options={}, redshift_tmp_dir = "", transformation_ctx="")`** 使用指定的 JDBC 連線資訊來撰寫 `DynamicFrame`。 + `frame` – 所要撰寫的 `DynamicFrame`。 + `catalog_connection` – 所要使用的目錄連線。 + `connection_options` – 連線選項，例如路徑和資料庫資料表 (選用)。 + `redshift_tmp_dir` – 所要使用的 Amazon Redshift 暫時目錄 (選用)。 + `transformation_ctx` – 所要使用的轉換細節 (選用)。 ## write\$1dynamic\$1frame 的範例 這個範例使用 S3 的 `connection_type` 和 `connection_options` 中的 POSIX 路徑參數在本機寫入輸出，這允許寫入本機儲存。 ``` glueContext.write_dynamic_frame.from_options(\ frame = dyf_splitFields,\ connection_options = {'path': '/home/glue/GlueLocalOutput/'},\ connection_type = 's3',\ format = 'json') ``` # DynamicFrameReader 類別 ##  — methods — + [\$1\$1init\$1\$1](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-reader-__init__) + [from\$1rdd](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-reader-from_rdd) + [from\$1options](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-reader-from_options) + [from\$1catalog](#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-reader-from_catalog) ## \$1\$1init\$1\$1 **`__init__(glue_context)`** + `glue_context` – 所要使用的 [GlueContext 類別](aws-glue-api-crawler-pyspark-extensions-glue-context.md)。 ## from\$1rdd **`from_rdd(data, name, schema=None, sampleRatio=None)`** `DynamicFrame` 從彈性分散式資料集 (RDD) 的讀取。 + `data` – 欲讀取的資料集。 + `name` – 欲讀取的名稱。 + `schema` - 欲讀取的結構描述 (選用)。 + `sampleRatio` – 取樣率 (選用)。 ## from\$1options **`from_options(connection_type, connection_options={}, format=None, format_options={}, transformation_ctx="")`** 使用指定的連線和格式讀取 `DynamicFrame`。 + `connection_type` – 連線類型。有效值包括 `s3`、`mysql`、`postgresql`、`redshift`、`sqlserver`、`oracle`、`dynamodb` 和 `snowflake`。 + `connection_options` – 連線選項，例如路徑和資料庫資料表 (選用)。如需詳細資訊，請參閱 [ Glue for Spark 中的 ETL AWS 連線類型和選項](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-connect.html)。如果是 `connection_type` 的 `s3`，Amazon S3 路徑定義在陣列中。 ``` connection_options = {"paths": [ "s3://amzn-s3-demo-bucket/object_a", "s3://amzn-s3-demo-bucket/object_b"]} ``` 如果是 JDBC 連線，必須定義幾項屬性。請注意，資料庫名稱必須是 URL 的一部分。它可以選擇性包含在連線選項中。 **警告** 不建議在指令碼中存放密碼。考慮使用 從 AWS Secrets Manager 或 Glue Data Catalog AWS `boto3`擷取它們。 ``` connection_options = {"url": "jdbc-url/database", "user": "username", "password": passwordVariable,"dbtable": "table-name", "redshiftTmpDir": "s3-tempdir-path"} ``` 若是執行平行讀取的 JDBC 連線，您可以設定 hashfield 選項。例如： ``` connection_options = {"url": "jdbc-url/database", "user": "username", "password": passwordVariable,"dbtable": "table-name", "redshiftTmpDir": "s3-tempdir-path" , "hashfield": "month"} ``` 如需詳細資訊，請參閱[從 JDBC 資料表中平行讀取](run-jdbc-parallel-read-job.md)。 + `format` – 格式化規格 (選用)。這用於 Amazon Simple Storage Service (Amazon S3) 或支援多種格式的 AWS Glue 連線。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `format_options` – 指定格式的格式選項。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 + `push_down_predicate` – 篩選分割區，而無需列出和讀取資料集中的所有檔案。如需詳細資訊，請參閱[使用 Pushdown 述詞預先篩選](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-partitions.html#aws-glue-programming-etl-partitions-pushdowns)。 ## from\$1catalog **`from_catalog(database, table_name, redshift_tmp_dir="", transformation_ctx="", push_down_predicate="", additional_options={})`** 使用指定的目錄命名空間和資料表名稱讀取 `DynamicFrame`。 + `database` – 欲讀取的資料庫。 + `table_name` – 欲讀取的資料表的名稱。 + `redshift_tmp_dir` - 要使用的 Amazon Redshift 暫時目錄 (如果不是從 Redshift 讀取資料，則為選用)。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 + `push_down_predicate` – 篩選分割區，而無需列出和讀取資料集中的所有檔案。如需詳細資訊，請參閱[使用 pushdown 述詞預先篩選](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-pushdowns)。 + `additional_options` – 提供給 AWS Glue 的額外選項。 + 若要使用執行平行讀取的 JDBC 連線，您可以設定 `hashfield`、`hashexpression` 或 `hashpartitions` 選項。例如： ``` additional_options = {"hashfield": "month"} ``` 如需詳細資訊，請參閱[從 JDBC 資料表中平行讀取](run-jdbc-parallel-read-job.md)。 + 若要傳遞目錄表達式以根據索引欄進行篩選，您可以參閱 `catalogPartitionPredicate` 選項。 `catalogPartitionPredicate` — 您可以傳遞目錄表達式以根據索引欄進行篩選。這會將篩選下推至伺服器端。如需詳細資訊，請參閱 [AWS Glue 分割區索引](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html)。注意 `push_down_predicate` 和 `catalogPartitionPredicate` 使用不同的語法。前者使用 Spark SQL 標準語法，後者使用 JSQL 剖析器。 如需詳細資訊，請參閱[在 AWS Glue 中管理適用於 ETL 輸出的分割區](aws-glue-programming-etl-partitions.md)。 # GlueContext 類別 包裝 Apache Spark [SparkContext](https://spark.apache.org/docs/latest/api/java/org/apache/spark/SparkContext.html) 物件，並提供與 Apache Spark 平台互動的機制。 ## \$1\$1init\$1\$1 **`__init__(sparkContext)`** + `sparkContext` – 欲使用的 Apache Spark 細節。 ## 正在建立 + [\$1\$1init\$1\$1](#aws-glue-api-crawler-pyspark-extensions-glue-context-__init__) + [getSource](#aws-glue-api-crawler-pyspark-extensions-glue-context-get-source) + [create\$1dynamic\$1frame\$1from\$1rdd](#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_rdd) + [create\$1dynamic\$1frame\$1from\$1catalog](#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_catalog) + [create\$1dynamic\$1frame\$1from\$1options](#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_options) + [create\$1sample\$1dynamic\$1frame\$1from\$1catalog](#aws-glue-api-crawler-pyspark-extensions-glue-context-create-sample-dynamic-frame-from-catalog) + [create\$1sample\$1dynamic\$1frame\$1from\$1options](#aws-glue-api-crawler-pyspark-extensions-glue-context-create-sample-dynamic-frame-from-options) + [add\$1ingestion\$1time\$1columns](#aws-glue-api-crawler-pyspark-extensions-glue-context-add-ingestion-time-columns) + [create\$1data\$1frame\$1from\$1catalog](#aws-glue-api-crawler-pyspark-extensions-glue-context-create-dataframe-from-catalog) + [create\$1data\$1frame\$1from\$1options](#aws-glue-api-crawler-pyspark-extensions-glue-context-create-dataframe-from-options) + [forEachBatch](#aws-glue-api-crawler-pyspark-extensions-glue-context-forEachBatch) ## getSource **`getSource(connection_type, transformation_ctx = "", **options)`** 建立可用於從外部來源讀取 `DynamicFrames` 的 `DataSource` 物件。 + `connection_type` – 要使用的連線類型，例如 Amazon Simple Storage Service (Amazon S3)、Amazon Redshift 及 JDBC。有效值包括 `s3`、`mysql`、`postgresql`、`redshift`、`sqlserver`、`oracle` 和 `dynamodb`。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 + `options` – 選擇性的名稱/值對的集合。如需詳細資訊，請參閱[AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 以下是 `getSource` 的使用範例： ``` >>> data_source = context.getSource("file", paths=["/in/path"]) >>> data_source.setFormat("json") >>> myFrame = data_source.getFrame() ``` ## create\$1dynamic\$1frame\$1from\$1rdd **`create_dynamic_frame_from_rdd(data, name, schema=None, sample_ratio=None, transformation_ctx="")`** 傳回從 Apache Spark 彈性分散式資料集 (RDD) 建立的 `DynamicFrame`。 + `data` – 欲使用的資料來源。 + `name` – 欲使用的資料名稱。 + `schema` – 欲使用的結構描述 (選用)。 + `sample_ratio` – 欲使用的取樣率 (選用)。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 ## create\$1dynamic\$1frame\$1from\$1catalog **`create_dynamic_frame_from_catalog(database, table_name, redshift_tmp_dir, transformation_ctx = "", push_down_predicate= "", additional_options = {}, catalog_id = None)`** 傳回使用 Data Catalog 資料庫和資料表名稱建立的 `DynamicFrame`。使用此方法時，您可以在指定的 AWS Glue Data Catalog 資料表上`format_options`透過資料表屬性提供 ，並透過 `additional_options` 引數提供其他選項。 + `Database` – 欲讀取的資料庫。 + `table_name` – 欲讀取的資料表的名稱。 + `redshift_tmp_dir` – 所要使用的 Amazon Redshift 暫時目錄 (選用)。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 + `push_down_predicate` – 篩選分割區，而無需列出和讀取資料集中的所有檔案。如需支援的來源和限制，請參閱在 [Glue ETL AWS 中使用下推來最佳化讀取](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-pushdown.html)。如需詳細資訊，請參閱[使用 pushdown 述詞預先篩選](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-pushdowns)。 + `additional_options` – 選擇性的名稱/值對的集合。可能的選項包括 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md) 中列出的項目，除了 `endpointUrl`、`streamName`、`bootstrap.servers`、`security.protocol`、`topicName`、`classification` 以及`delimiter`。另一個支援的選項是 `catalogPartitionPredicate`： `catalogPartitionPredicate` — 您可以傳遞目錄表達式以根據索引欄進行篩選。這會將篩選下推至伺服器端。如需詳細資訊，請參閱 [AWS Glue 分割區索引](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html)。注意 `push_down_predicate` 和 `catalogPartitionPredicate` 使用不同的語法。前者使用 Spark SQL 標準語法，後者使用 JSQL 剖析器。 + `catalog_id` — 要存取之 Data Catalog 的目錄 ID (帳戶 ID)。若無，會使用發起人的預設帳戶 ID。 ## create\$1dynamic\$1frame\$1from\$1options **`create_dynamic_frame_from_options(connection_type, connection_options={}, format=None, format_options={}, transformation_ctx = "")`** 傳回使用指定的連線和格式建立的 `DynamicFrame`。 + `connection_type` – 連線類型，例如 Amazon S3、Amazon Redshift 及 JDBC。有效值包括 `s3`、`mysql`、`postgresql`、`redshift`、`sqlserver`、`oracle` 和 `dynamodb`。 + `connection_options` - 連線選項，例如路徑和資料庫資料表 (選用)。如果是 `connection_type` 的 `s3`，會定義 Amazon S3 路徑清單。 ``` connection_options = {"paths": ["s3://aws-glue-target/temp"]} ``` 如果是 JDBC 連線，必須定義幾項屬性。請注意，資料庫名稱必須是 URL 的一部分。它可以選擇性包含在連線選項中。 **警告** 不建議在指令碼中存放密碼。考慮使用 從 AWS Secrets Manager 或 Glue Data Catalog AWS `boto3`擷取它們。 ``` connection_options = {"url": "jdbc-url/database", "user": "username", "password": passwordVariable,"dbtable": "table-name", "redshiftTmpDir": "s3-tempdir-path"} ``` `dbtable` 屬性為 JDBC 資料表的名稱。若是支援資料庫內結構描述的 JDBC 資料存放區，請指定 `schema.table-name`。如果未提供結構描述，則會使用預設的 "public" 結構描述。 如需詳細資訊，請參閱[AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `format` – 格式規格。這是用於 Amazon S3 或支援多種格式的 AWS Glue 連線。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `format_options` – 指定格式的格式選項。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 + `push_down_predicate` – 篩選分割區，而無需列出和讀取資料集中的所有檔案。如需支援的來源和限制，請參閱在 [Glue ETL AWS 中使用下推來最佳化讀取](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-pushdown.html)。如需詳細資訊，請參閱[使用 Pushdown 述詞預先篩選](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-partitions.html#aws-glue-programming-etl-partitions-pushdowns)。 ## create\$1sample\$1dynamic\$1frame\$1from\$1catalog **`create_sample_dynamic_frame_from_catalog(database, table_name, num, redshift_tmp_dir, transformation_ctx = "", push_down_predicate= "", additional_options = {}, sample_options = {}, catalog_id = None)`** 傳回使用 Data Catalog 資料庫和資料表名稱建立的範例 `DynamicFrame`。`DynamicFrame` 僅包含來自資料來源的第一個 `num` 記錄。 + `database` – 欲讀取的資料庫。 + `table_name` – 欲讀取的資料表的名稱。 + `num` – 傳回的範例動態框架中記錄的最大數目。 + `redshift_tmp_dir`：所要使用的 Amazon Redshift 臨時目錄 (選用)。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 + `push_down_predicate` – 篩選分割區，而無需列出和讀取資料集中的所有檔案。如需詳細資訊，請參閱[使用 pushdown 述詞預先篩選](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-pushdowns)。 + `additional_options` – 選擇性的名稱/值對的集合。可能的選項包括 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md) 中列出的項目，除了 `endpointUrl`、`streamName`、`bootstrap.servers`、`security.protocol`、`topicName`、`classification` 以及`delimiter`。 + `sample_options` – 用於控制取樣行為的參數 (選用)。Amazon S3 來源的目前可用參數： + `maxSamplePartitions` – 取樣將讀取的分割區數目上限。預設值為 10 + `maxSampleFilesPerPartition` – 取樣將在一個分割區中讀取的檔案數目上限。預設值為 10。 這些參數有助於減少檔案清單所耗用的時間。例如，假設資料集有 1000 個分割區，並且每個分割區都有 10 個檔案。如果您設定 `maxSamplePartitions` = 10 和 `maxSampleFilesPerPartition` = 10，而不是列出所有 10,000 個檔案，而是僅列出和讀取前 10 個分割區及每個分割區的前 10 個檔案 (總計為 10\$110 = 100 個檔案)。 + `catalog_id` – 要存取之 Data Catalog 的目錄 ID ( Data Catalog 的帳戶 ID)。依預設設定為 `None`。`None` 預設為服務中呼叫帳戶的目錄 ID。 ## create\$1sample\$1dynamic\$1frame\$1from\$1options **`create_sample_dynamic_frame_from_options(connection_type, connection_options={}, num, sample_options={}, format=None, format_options={}, transformation_ctx = "")`** 傳回使用指定的連線和格式建立的範例 `DynamicFrame`。`DynamicFrame` 僅包含來自資料來源的第一個 `num` 記錄。 + `connection_type` – 連線類型，例如 Amazon S3、Amazon Redshift 及 JDBC。有效值包括 `s3`、`mysql`、`postgresql`、`redshift`、`sqlserver`、`oracle` 和 `dynamodb`。 + `connection_options` - 連線選項，例如路徑和資料庫資料表 (選用)。如需詳細資訊，請參閱[AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `num` – 傳回的範例動態框架中記錄的最大數目。 + `sample_options` – 用於控制取樣行為的參數 (選用)。Amazon S3 來源的目前可用參數： + `maxSamplePartitions` – 取樣將讀取的分割區數目上限。預設值為 10 + `maxSampleFilesPerPartition` – 取樣將在一個分割區中讀取的檔案數目上限。預設值為 10。 這些參數有助於減少檔案清單所耗用的時間。例如，假設資料集有 1000 個分割區，並且每個分割區都有 10 個檔案。如果您設定 `maxSamplePartitions` = 10 和 `maxSampleFilesPerPartition` = 10，而不是列出所有 10,000 個檔案，而是僅列出和讀取前 10 個分割區及每個分割區的前 10 個檔案 (總計為 10\$110 = 100 個檔案)。 + `format` – 格式規格。這是用於 Amazon S3 或支援多種格式的 AWS Glue 連線。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `format_options` – 指定格式的格式選項。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 + `push_down_predicate` – 篩選分割區，而無需列出和讀取資料集中的所有檔案。如需詳細資訊，請參閱[使用 pushdown 述詞預先篩選](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-pushdowns)。 ## add\$1ingestion\$1time\$1columns **`add_ingestion_time_columns(dataFrame, timeGranularity = "")`** 附加擷取時間欄 (如 `ingest_year`、`ingest_month`、`ingest_day`、`ingest_hour`、`ingest_minute`) 到輸入 `DataFrame`。當您指定以 Amazon S3 為目標的 Data Catalog 資料表時，此函數會在 AWS Glue 產生的指令碼中自動產生。此函數會自動使用輸出資料表上的擷取時間欄來更新分割區。這可讓輸出資料在擷取時間自動分割，而不需要輸入資料中的明確擷取時間欄。 + `dataFrame` – 要將擷取時間欄附加到的 `dataFrame`。 + `timeGranularity` – 時間欄的精密程度。有效值為 "`day`"、"`hour`" 和 "`minute`"。例如：如果 "`hour`" 被傳遞給函數，原始 `dataFrame` 會附加上 "`ingest_year`"、"`ingest_month`"、"`ingest_day`" 和 "`ingest_hour`" 時間欄。 傳回附加時間粒度欄後的資料框架。 範例： ``` dynamic_frame = DynamicFrame.fromDF(glueContext.add_ingestion_time_columns(dataFrame, "hour")) ``` ## create\$1data\$1frame\$1from\$1catalog **`create_data_frame_from_catalog(database, table_name, transformation_ctx = "", additional_options = {})`** 傳回使用 Data Catalog 資料表的資訊建立的 `DataFrame`。 + `database` – 要從中讀取的 Data Catalog 資料庫。 + `table_name` – 要從中讀取的 Data Catalog 資料表的名稱。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 + `additional_options` – 選擇性的名稱/值對的集合。可能的選項包括 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md) 中列出用於串流來源的項目，例如 `startingPosition`、`maxFetchTimeInMs` 以及 `startingOffsets`。 + `useSparkDataSource` – 設為 true 時， 會強制 AWS Glue 使用原生 Spark 資料來源 API 讀取資料表。Spark Data Source API 支援下列格式：AVRO、二進位、CSV、JSON、ORC、Parquet 和文字。在 Data Catalog 資料表中，您可以使用 `classification` 屬性指定格式。若要進一步了解 Spark Data Source API，請參閱官方 [Apache Spark 文件](https://spark.apache.org/docs/latest/sql-data-sources-load-save-functions.html)。 將 `create_data_frame_from_catalog` 與 `useSparkDataSource` 一起使用具有以下好處： + 直接傳回 `DataFrame` 並提供 `create_dynamic_frame.from_catalog().toDF()` 的替代方案。 + 支援原生格式的 AWS Lake Formation 資料表層級許可控制。 + 支援在沒有 AWS Lake Formation 資料表層級許可控制的情況下讀取資料湖格式。如需詳細資訊，請參閱[搭配 AWS Glue ETL 任務使用資料湖架構](aws-glue-programming-etl-datalake-native-frameworks.md)。 啟用 時`useSparkDataSource`，您也可以`additional_options`視需要在 中新增任何 [Spark 資料來源選項](https://spark.apache.org/docs/latest/sql-data-sources.html)。 AWS Glue 會將這些選項直接傳遞給 Spark 讀取器。 + `useCatalogSchema` – 設為 true 時， AWS Glue 會將 Data Catalog 結構描述套用至產生的 `DataFrame`。否則，讀取器會從資料推斷結構描述。啟用 `useCatalogSchema` 時，也必須將 `useSparkDataSource` 設定為 true。 **限制** 使用 `useSparkDataSource` 選項時請考慮以下限制： + 當您使用 時`useSparkDataSource`， AWS Glue 會在與原始 Spark 工作階段不同的個別 Spark 工作階段`DataFrame`中建立新的 。 + Spark DataFrame 分割區篩選不適用於下列 AWS Glue 功能。 + [任務書籤](monitor-continuations.md) + [排除 Amazon S3 儲存類別](aws-glue-programming-etl-storage-classes.md#aws-glue-programming-etl-storage-classes-dynamic-frame) + [目錄分割區述詞](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-cat-predicates) 若要搭配這些功能使用分割區篩選，您可以使用 AWS Glue 下推述詞。如需詳細資訊，請參閱[使用 pushdown 述詞預先篩選](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-pushdowns)。篩選未分割資料欄不會受到影響。 下列範例指令碼示範使用 `excludeStorageClasses` 選項執行分割區篩選的不正確方法。 ``` // Incorrect partition filtering using Spark filter with excludeStorageClasses read_df = glueContext.create_data_frame.from_catalog( database=database_name, table_name=table_name, additional_options = { "useSparkDataSource": True, "excludeStorageClasses" : ["GLACIER", "DEEP_ARCHIVE"] } ) // Suppose year and month are partition keys. // Filtering on year and month won't work, the filtered_df will still // contain data with other year/month values. filtered_df = read_df.filter("year == '2017 and month == '04' and 'state == 'CA'") ``` 下列範例指令碼示範使用 `excludeStorageClasses` 選項，利用下推述詞來執行分割區篩選的正確方法。 ``` // Correct partition filtering using the AWS Glue pushdown predicate // with excludeStorageClasses read_df = glueContext.create_data_frame.from_catalog( database=database_name, table_name=table_name, // Use AWS Glue pushdown predicate to perform partition filtering push_down_predicate = "(year=='2017' and month=='04')" additional_options = { "useSparkDataSource": True, "excludeStorageClasses" : ["GLACIER", "DEEP_ARCHIVE"] } ) // Use Spark filter only on non-partitioned columns filtered_df = read_df.filter("state == 'CA'") ``` **範例：使用 Spark Data Source 讀取器來建立 CSV 資料表** ``` // Read a CSV table with '\t' as separator read_df = glueContext.create_data_frame.from_catalog( database=, table_name=, additional_options = {"useSparkDataSource": True, "sep": '\t'} ) ``` ## create\$1data\$1frame\$1from\$1options **`create_data_frame_from_options(connection_type, connection_options={}, format=None, format_options={}, transformation_ctx = "")`** 此 API 現已棄用。請改用 `getSource()` API。傳回使用指定的連線和格式建立的 `DataFrame`。這個函數只能用於 AWS Glue 串流來源。 + `connection_type` - 串流連線類型。有效值包括 `kinesis` 與 `kafka`。 + `connection_options`— 連線選項，這些選項對於 Kinesis 和 Kafka 而言是不同的。您可以在 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md) 中找到每個串流資料來源的所有連線選項清單。請注意串流連線選項的下列不同處： + Kinesis 串流來源需要 `streamARN`、`startingPosition`、`inferSchema` 以及 `classification`。 + Kafka 串流來源需要 `connectionName`、`topicName`、`startingOffsets`、`inferSchema` 以及 `classification`。 + `format` – 格式規格。這是用於 Amazon S3 或支援多種格式的 AWS Glue 連線。如需有關支援格式的資訊，請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md)。 + `format_options` – 指定格式的格式選項。如需支援格式選項的詳細資訊，請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md)。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 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) ``` 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) ``` ## forEachBatch **`forEachBatch(frame, batch_function, options)`** 將傳入的 `batch_function` 套用至從串流來源讀取的每個微批次。 + `frame` – 包含目前微批次的 DataFrame。 + `batch_function` – 將套用至每個微批次的函數。 + `options` – 索引鍵/值配對的集合，其中包含如何處理微批次的相關資訊。下列選項是必要的： + `windowSize` – 處理每個批次的時間量。 + `checkpointLocation` - 串流 ETL 任務的檢查點儲存位置。 + `batchMaxRetries` – 如果失敗，可重試批次的次數上限。預設值為 3。此選項僅在 Glue 2.0 及以上版本上才可設定。 **範例**： ``` glueContext.forEachBatch( frame = data_frame_datasource0, batch_function = processBatch, options = { "windowSize": "100 seconds", "checkpointLocation": "s3://kafka-auth-dataplane/confluent-test/output/checkpoint/" } ) def processBatch(data_frame, batchId): if (data_frame.count() > 0): datasource0 = DynamicFrame.fromDF( glueContext.add_ingestion_time_columns(data_frame, "hour"), glueContext, "from_data_frame" ) additionalOptions_datasink1 = {"enableUpdateCatalog": True} additionalOptions_datasink1["partitionKeys"] = ["ingest_yr", "ingest_mo", "ingest_day"] datasink1 = glueContext.write_dynamic_frame.from_catalog( frame = datasource0, database = "tempdb", table_name = "kafka-auth-table-output", transformation_ctx = "datasink1", additional_options = additionalOptions_datasink1 ) ``` ## 在 Amazon S3 中使用資料集 + [purge\$1table](#aws-glue-api-crawler-pyspark-extensions-glue-context-purge_table) + [purge\$1s3\$1path](#aws-glue-api-crawler-pyspark-extensions-glue-context-purge_s3_path) + [transition\$1table](#aws-glue-api-crawler-pyspark-extensions-glue-context-transition_table) + [transition\$1s3\$1path](#aws-glue-api-crawler-pyspark-extensions-glue-context-transition_s3_path) ## purge\$1table **`purge_table(catalog_id=None, database="", table_name="", options={}, transformation_ctx="")`** 從 Amazon S3 中刪除指定目錄資料庫和資料表的檔案。如果刪除分割區中的所有檔案，該分割區也會從目錄中刪除。對於向 Lake Formation 註冊的資料表，我們不支援 purge\$1table 動作。 如果您希望能夠復原已刪除的物件，您可以在 Amazon S3 儲存貯體上開啟[物件版本控制](https://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectVersioning.html)。從未啟用物件版本控制的儲存貯體中刪除物件時，無法復原物件。如需如何復原已啟用版本控制之儲存貯體中已刪除物件的詳細資訊，請參閱 AWS 支援 知識中心的[如何擷取已刪除的 Amazon S3 物件？](https://aws.amazon.com/premiumsupport/knowledge-center/s3-undelete-configuration/)。 + `catalog_id` – 要存取之 Data Catalog 的目錄 ID ( Data Catalog 的帳戶 ID)。依預設設定為 `None`。`None` 預設為服務中呼叫帳戶的目錄 ID。 + `database` – 所要使用的資料庫。 + `table_name` - 要使用的資料表名稱。 + `options` - 篩選要刪除之檔案和用於產生資訊清單檔案的選項。 + `retentionPeriod` - 指定保留檔案的期間 (以小時為單位)。比保留期間新的檔案都會予以保留。依預設設定為 168 小時 (7 天)。 + `partitionPredicate` - 滿足此述詞的分割區會被刪除。這些分割區中仍在保留期間內的檔案不會被刪除。設定為 `""` – 預設為空值。 + `excludeStorageClasses` - 不會刪除 `excludeStorageClasses` 集合中具有儲存體方案的檔案。預設為 `Set()` – 空集合。 + `manifestFilePath` - 產生資訊清單檔案的選用路徑。所有已成功清除的檔案都會記錄在 `Success.csv` 中，失敗的則記錄在 `Failed.csv` 中 + `transformation_ctx` – 欲使用的轉換細節 (選用)。用於資訊清單檔案的路徑。 **Example** ``` glueContext.purge_table("database", "table", {"partitionPredicate": "(month=='march')", "retentionPeriod": 1, "excludeStorageClasses": ["STANDARD_IA"], "manifestFilePath": "s3://bucketmanifest/"}) ``` ## purge\$1s3\$1path **`purge_s3_path(s3_path, options={}, transformation_ctx="")`** 以遞迴方式刪除指定 Amazon S3 路徑中的檔案。 如果您希望能夠復原已刪除的物件，您可以在 Amazon S3 儲存貯體上開啟[物件版本控制](https://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectVersioning.html)。從未開啟物件版本控制的儲存貯體中刪除物件時，無法復原物件。如需如何使用版本控制復原儲存貯體中已刪除物件的詳細資訊，請參閱 支援 知識中心中的[如何擷取已刪除的 Amazon S3 物件？](https://aws.amazon.com/premiumsupport/knowledge-center/s3-undelete-configuration/)。 + `s3_path` - 要刪除之檔案的 Amazon S3 路徑，格式為 `s3:////` + `options` - 篩選要刪除之檔案和用於產生資訊清單檔案的選項。 + `retentionPeriod` - 指定保留檔案的期間 (以小時為單位)。比保留期間新的檔案都會予以保留。依預設設定為 168 小時 (7 天)。 + `excludeStorageClasses` - 不會刪除 `excludeStorageClasses` 集合中具有儲存體方案的檔案。預設為 `Set()` – 空集合。 + `manifestFilePath` - 產生資訊清單檔案的選用路徑。所有已成功清除的檔案都會記錄在 `Success.csv` 中，失敗的則記錄在 `Failed.csv` 中 + `transformation_ctx` – 欲使用的轉換細節 (選用)。用於資訊清單檔案的路徑。 **Example** ``` glueContext.purge_s3_path("s3://bucket/path/", {"retentionPeriod": 1, "excludeStorageClasses": ["STANDARD_IA"], "manifestFilePath": "s3://bucketmanifest/"}) ``` ## transition\$1table **`transition_table(database, table_name, transition_to, options={}, transformation_ctx="", catalog_id=None)`** 針對指定之目錄的資料庫和資料表，轉換儲存在 Amazon S3 上之檔案的儲存體方案。 您可以在任意兩個儲存體方案之間轉換。對於 `GLACIER` 和 `DEEP_ARCHIVE` 儲存體方案，您可以轉換到這些方案。但是，您可以使用 `S3 RESTORE` 從 `GLACIER` 和 `DEEP_ARCHIVE` 儲存體方案轉換。 如果您執行的 AWS Glue ETL 任務會從 Amazon S3 讀取檔案或分割區，則您可排除部分 Amazon S3 儲存類別類型。如需詳細資訊，請參閱[排除 Amazon S3 儲存體方案](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-storage-classes.html)。 + `database` – 所要使用的資料庫。 + `table_name` - 要使用的資料表名稱。 + `transition_to` – 要轉移的 [Amazon S3 儲存方案](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/model/StorageClass.html)。 + `options` - 篩選要刪除之檔案和用於產生資訊清單檔案的選項。 + `retentionPeriod` - 指定保留檔案的期間 (以小時為單位)。比保留期間新的檔案都會予以保留。依預設設定為 168 小時 (7 天)。 + `partitionPredicate` - 滿足此述詞的分割區會被轉換。這些分割區中仍在保留期間內的檔案不會被轉換。設定為 `""` – 預設為空值。 + `excludeStorageClasses` - 不會轉換 `excludeStorageClasses` 集合中具有儲存體方案的檔案。預設為 `Set()` – 空集合。 + `manifestFilePath` - 產生資訊清單檔案的選用路徑。所有已成功轉換的檔案都會記錄在 `Success.csv` 中，失敗的則記錄在 `Failed.csv` 中 + `accountId` – 要執行轉移轉換的 Amazon Web Services 帳戶 ID。對於這種轉換是強制性的。 + `roleArn` – AWS 執行轉換的角色。對於這種轉換是強制性的。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。用於資訊清單檔案的路徑。 + `catalog_id` – 要存取之 Data Catalog 的目錄 ID ( Data Catalog 的帳戶 ID)。依預設設定為 `None`。`None` 預設為服務中呼叫帳戶的目錄 ID。 **Example** ``` glueContext.transition_table("database", "table", "STANDARD_IA", {"retentionPeriod": 1, "excludeStorageClasses": ["STANDARD_IA"], "manifestFilePath": "s3://bucketmanifest/", "accountId": "12345678901", "roleArn": "arn:aws:iam::123456789012:user/example-username"}) ``` ## transition\$1s3\$1path **`transition_s3_path(s3_path, transition_to, options={}, transformation_ctx="")`** 以遞迴方式轉換指定 Amazon S3 路徑中檔案的儲存體方案。 您可以在任意兩個儲存體方案之間轉換。對於 `GLACIER` 和 `DEEP_ARCHIVE` 儲存體方案，您可以轉換到這些方案。但是，您可以使用 `S3 RESTORE` 從 `GLACIER` 和 `DEEP_ARCHIVE` 儲存體方案轉換。 如果您執行的 AWS Glue ETL 任務會從 Amazon S3 讀取檔案或分割區，則您可排除部分 Amazon S3 儲存類別類型。如需詳細資訊，請參閱[排除 Amazon S3 儲存體方案](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-storage-classes.html)。 + `s3_path` - 要以格式 `s3:////` 轉換之檔案的 Amazon S3 路徑。 + `transition_to` – 要轉移的 [Amazon S3 儲存方案](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/model/StorageClass.html)。 + `options` - 篩選要刪除之檔案和用於產生資訊清單檔案的選項。 + `retentionPeriod` - 指定保留檔案的期間 (以小時為單位)。比保留期間新的檔案都會予以保留。依預設設定為 168 小時 (7 天)。 + `partitionPredicate` - 滿足此述詞的分割區會被轉換。這些分割區中仍在保留期間內的檔案不會被轉換。設定為 `""` – 預設為空值。 + `excludeStorageClasses` - 不會轉換 `excludeStorageClasses` 集合中具有儲存體方案的檔案。預設為 `Set()` – 空集合。 + `manifestFilePath` - 產生資訊清單檔案的選用路徑。所有已成功轉換的檔案都會記錄在 `Success.csv` 中，失敗的則記錄在 `Failed.csv` 中 + `accountId` – 要執行轉移轉換的 Amazon Web Services 帳戶 ID。對於這種轉換是強制性的。 + `roleArn` – AWS 執行轉換的角色。對於這種轉換是強制性的。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。用於資訊清單檔案的路徑。 **Example** ``` glueContext.transition_s3_path("s3://bucket/prefix/", "STANDARD_IA", {"retentionPeriod": 1, "excludeStorageClasses": ["STANDARD_IA"], "manifestFilePath": "s3://bucketmanifest/", "accountId": "12345678901", "roleArn": "arn:aws:iam::123456789012:user/example-username"}) ``` ## 擷取 + [extract\$1jdbc\$1conf](#aws-glue-api-crawler-pyspark-extensions-glue-context-extract_jdbc_conf) ## extract\$1jdbc\$1conf **`extract_jdbc_conf(connection_name, catalog_id = None)`** 從 Data Catalog 中的 AWS Glue 連線物件傳回含索引鍵 (具有組態屬性) 的 `dict`。 + `user`：資料庫使用者名稱。 + `password`：資料庫密碼。 + `vendor`：指定廠商 (`mysql`、`postgresql`、`oracle`、`sqlserver` 等)。 + `enforceSSL`：布林字串，指示是否需要安全連線。 + `customJDBCCert`：使用指定 Amazon S3 路徑中的特定用戶端憑證。 + `skipCustomJDBCCertValidation`：布林字串，指示 `customJDBCCert` 必須由 CA 驗證。 + `customJDBCCertString`：有關自訂憑證的其他資訊，因驅動程式類型而異。 + `url`：(已棄用) 僅包含通訊協定、伺服器和連接埠的 JDBC URL。 + `fullUrl`：建立連線時輸入的 JDBC URL (適用於 AWS Glue 3.0 版或更新版本)。 擷取 JDBC 組態的範例： ``` jdbc_conf = glueContext.extract_jdbc_conf(connection_name="your_glue_connection_name") print(jdbc_conf) >>> {'enforceSSL': 'false', 'skipCustomJDBCCertValidation': 'false', 'url': 'jdbc:mysql://myserver:3306', 'fullUrl': 'jdbc:mysql://myserver:3306/mydb', 'customJDBCCertString': '', 'user': 'admin', 'customJDBCCert': '', 'password': '1234', 'vendor': 'mysql'} ``` ## 交易 + [start\$1transaction](#aws-glue-api-pyspark-extensions-glue-context-start-transaction) + [commit\$1transaction](#aws-glue-api-pyspark-extensions-glue-context-commit-transaction) + [cancel\$1transaction](#aws-glue-api-pyspark-extensions-glue-cancel-transaction) ## start\$1transaction **`start_transaction(read_only)`** 開始新交易。內部呼叫 Lake Formation [startTransaction](https://docs.aws.amazon.com/lake-formation/latest/dg/aws-lake-formation-api-aws-lake-formation-api-transactions.html#aws-lake-formation-api-aws-lake-formation-api-transactions-StartTransaction) API。 + `read_only` – (布林值) 指出此交易應該是唯讀，還是讀取和寫入。使用唯讀交易 ID 進行的寫入將被拒絕。唯讀交易不需要遞交。 傳回交易 ID。 ## commit\$1transaction **`commit_transaction(transaction_id, wait_for_commit = True)`** 嘗試遞交指定的交易。`commit_transaction` 可能會在交易完成遞交之前返回。內部呼叫 Lake Formation [commitTransaction](https://docs.aws.amazon.com/lake-formation/latest/dg/aws-lake-formation-api-aws-lake-formation-api-transactions.html#aws-lake-formation-api-aws-lake-formation-api-transactions-CommitTransaction) API。 + `transaction_id ` – (字串) 要遞交的交易。 + `wait_for_commit` – (布林值) 決定 `commit_transaction` 是否立即傳回。預設值為 true。如為 False，`commit_transaction` 輪詢並等待，直到交易完成遞交。使用指數退避時，等待時間長度限制為 1 分鐘，最多可嘗試 6 次重試。 傳回一個布林值，指示遞交是否完成。 ## cancel\$1transaction **`cancel_transaction(transaction_id)`** 嘗試取消指定的交易。如果交易先前已遞交，傳回 `TransactionCommittedException` 例外狀況。內部呼叫 Lake Formation [CancelTransaction](https://docs.aws.amazon.com/lake-formation/latest/dg/aws-lake-formation-api-aws-lake-formation-api-transactions.html#aws-lake-formation-api-aws-lake-formation-api-transactions-CancelTransaction) API。 + `transaction_id` – (字串) 要取消的交易。 ## 寫入 + [getSink](#aws-glue-api-crawler-pyspark-extensions-glue-context-get-sink) + [write\$1dynamic\$1frame\$1from\$1options](#aws-glue-api-crawler-pyspark-extensions-glue-context-write_dynamic_frame_from_options) + [write\$1from\$1options](#aws-glue-api-crawler-pyspark-extensions-glue-context-write_from_options) + [write\$1dynamic\$1frame\$1from\$1catalog](#aws-glue-api-crawler-pyspark-extensions-glue-context-write_dynamic_frame_from_catalog) + [write\$1data\$1frame\$1from\$1catalog](#aws-glue-api-crawler-pyspark-extensions-glue-context-write_data_frame_from_catalog) + [write\$1dynamic\$1frame\$1from\$1jdbc\$1conf](#aws-glue-api-crawler-pyspark-extensions-glue-context-write_dynamic_frame_from_jdbc_conf) + [write\$1from\$1jdbc\$1conf](#aws-glue-api-crawler-pyspark-extensions-glue-context-write_from_jdbc_conf) ## getSink **`getSink(connection_type, format = None, transformation_ctx = "", **options)`** 取得可用於將 `DynamicFrames` 寫入外部來源的 `DataSink` 物件。請先檢查 SparkSQL `format` 以確保取得預期的目的地。 + `connection_type` – 要使用的連線類型，例如 Amazon S3、Amazon Redshift 及 JDBC。有效值包括 `s3`、`mysql`、`postgresql`、`redshift`、`sqlserver`、`oracle`、`kinesis` 和 `kafka`。 + `format` – 要使用的 SparkSQL 格式 (選用)。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 + `options` – 名稱/值對的集合，用來指定連線選項。一些可能的值為： + `user` 和 `password`：適用於授權 + `url`：資料存放區的端點 + `dbtable`：目標資料表的名稱。 + `bulkSize`：插入操作的平行程度 您可以指定的選項取決於連線類型。如需其他值和範例，請參閱 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 範例： ``` >>> data_sink = context.getSink("s3") >>> data_sink.setFormat("json"), >>> data_sink.writeFrame(myFrame) ``` ## write\$1dynamic\$1frame\$1from\$1options **`write_dynamic_frame_from_options(frame, connection_type, connection_options={}, format=None, format_options={}, transformation_ctx = "")`** 使用指定的連線和格式來撰寫並傳回 `DynamicFrame`。 + `frame` – 所要撰寫的 `DynamicFrame`。 + `connection_type` – 連線類型，例如 Amazon S3、Amazon Redshift 及 JDBC。有效值包括 `s3`、`mysql`、`postgresql`、`redshift`、`sqlserver`、`oracle`、`kinesis` 和 `kafka`。 + `connection_options` – 連線選項，例如路徑和資料庫資料表 (選用)。如果是 `connection_type` 的 `s3`，會定義 Amazon S3 路徑。 ``` connection_options = {"path": "s3://aws-glue-target/temp"} ``` 如果是 JDBC 連線，必須定義幾項屬性。請注意，資料庫名稱必須是 URL 的一部分。它可以選擇性包含在連線選項中。 **警告** 不建議在指令碼中存放密碼。考慮使用 從 AWS Secrets Manager 或 Glue Data Catalog AWS `boto3`擷取它們。 ``` connection_options = {"url": "jdbc-url/database", "user": "username", "password": passwordVariable,"dbtable": "table-name", "redshiftTmpDir": "s3-tempdir-path"} ``` `dbtable` 屬性為 JDBC 資料表的名稱。若是支援資料庫內結構描述的 JDBC 資料存放區，請指定 `schema.table-name`。如果未提供結構描述，則會使用預設的 "public" 結構描述。 如需詳細資訊，請參閱[AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `format` – 格式規格。這是用於 Amazon S3 或支援多種格式的 AWS Glue 連線。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `format_options` – 指定格式的格式選項。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `transformation_ctx` – 所要使用的轉換細節 (選用)。 ## write\$1from\$1options **`write_from_options(frame_or_dfc, connection_type, connection_options={}, format={}, format_options={}, transformation_ctx = "")`** 寫入和傳回以指定的連線和格式資訊建立的 `DynamicFrame` 或 `DynamicFrameCollection`。 + `frame_or_dfc` – 所要撰寫的 `DynamicFrame` 或 `DynamicFrameCollection`。 + `connection_type` – 連線類型，例如 Amazon S3、Amazon Redshift 及 JDBC。有效值包括 `s3`、`mysql`、`postgresql`、`redshift`、`sqlserver` 及 `oracle`。 + `connection_options` – 連線選項，例如路徑和資料庫資料表 (選用)。如果是 `connection_type` 的 `s3`，會定義 Amazon S3 路徑。 ``` connection_options = {"path": "s3://aws-glue-target/temp"} ``` 如果是 JDBC 連線，必須定義幾項屬性。請注意，資料庫名稱必須是 URL 的一部分。它可以選擇性包含在連線選項中。 **警告** 不建議在指令碼中存放密碼。考慮使用 從 AWS Secrets Manager 或 Glue Data Catalog AWS `boto3`擷取它們。 ``` connection_options = {"url": "jdbc-url/database", "user": "username", "password": passwordVariable,"dbtable": "table-name", "redshiftTmpDir": "s3-tempdir-path"} ``` `dbtable` 屬性為 JDBC 資料表的名稱。若是支援資料庫內結構描述的 JDBC 資料存放區，請指定 `schema.table-name`。如果未提供結構描述，則會使用預設的 "public" 結構描述。 如需詳細資訊，請參閱[AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `format` – 格式規格。這是用於 Amazon S3 或支援多種格式的 AWS Glue 連線。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `format_options` – 指定格式的格式選項。請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) 以了解受支援的格式。 + `transformation_ctx` – 所要使用的轉換細節 (選用)。 ## write\$1dynamic\$1frame\$1from\$1catalog **`write_dynamic_frame_from_catalog(frame, database, table_name, redshift_tmp_dir, transformation_ctx = "", additional_options = {}, catalog_id = None)`** 使用來自 Data Catalog 資料庫和資料表的資訊寫入並傳回 `DynamicFrame`。 + `frame` – 所要撰寫的 `DynamicFrame`。 + `Database` – 包含資料表的 Data Catalog 資料庫。 + `table_name` – 與目標關聯的 Data Catalog 資料表名稱。 + `redshift_tmp_dir` – 所要使用的 Amazon Redshift 暫時目錄 (選用)。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 + `additional_options` – 選擇性的名稱/值對的集合。 + `catalog_id` — 要存取之 Data Catalog 的目錄 ID (帳戶 ID)。若無，會使用發起人的預設帳戶 ID。 ## write\$1data\$1frame\$1from\$1catalog **`write_data_frame_from_catalog(frame, database, table_name, redshift_tmp_dir, transformation_ctx = "", additional_options = {}, catalog_id = None)`** 使用來自 Data Catalog 資料庫和資料表的資訊寫入並傳回 `DataFrame`。此方法支援寫入資料湖格式 (Hudi、Iceberg 和 Delta Lake)。如需詳細資訊，請參閱[搭配 AWS Glue ETL 任務使用資料湖架構](aws-glue-programming-etl-datalake-native-frameworks.md)。 + `frame` – 所要撰寫的 `DataFrame`。 + `Database` – 包含資料表的 Data Catalog 資料庫。 + `table_name` – 與目標關聯的 Data Catalog 資料表名稱。 + `redshift_tmp_dir`：所要使用的 Amazon Redshift 臨時目錄 (選用)。 + `transformation_ctx` – 欲使用的轉換細節 (選用)。 + `additional_options` – 選擇性的名稱/值對的集合。 + `useSparkDataSink` – 設為 true 時， 會強制 AWS Glue 使用原生 Spark Data Sink API 寫入資料表。啟用此選項時，您可以`additional_options`視需要將任何 [Spark 資料來源選項](https://spark.apache.org/docs/latest/sql-data-sources.html)新增至 。 AWS Glue 會將這些選項直接傳遞給 Spark 寫入器。 + `catalog_id` – 要存取之 Data Catalog 的目錄 ID (帳戶 ID)。如果您未指定值，則會使用發起人的預設帳戶 ID。 **限制** 使用 `useSparkDataSink` 選項時請考慮以下限制： + 使用 `useSparkDataSink` 選項時，不支援 [`enableUpdateCatalog`](update-from-job.md) 選項。 **範例：使用 Spark Data Source 寫入器寫入 Hudi 資料表** ``` hudi_options = { 'useSparkDataSink': True, 'hoodie.table.name': , 'hoodie.datasource.write.storage.type': 'COPY_ON_WRITE', 'hoodie.datasource.write.recordkey.field': 'product_id', 'hoodie.datasource.write.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, 'hoodie.datasource.hive_sync.enable': 'true', 'hoodie.datasource.hive_sync.database': , 'hoodie.datasource.hive_sync.table': , 'hoodie.datasource.hive_sync.use_jdbc': 'false', 'hoodie.datasource.hive_sync.mode': 'hms'} glueContext.write_data_frame.from_catalog( frame = , database = , table_name = , additional_options = hudi_options ) ``` ## write\$1dynamic\$1frame\$1from\$1jdbc\$1conf **`write_dynamic_frame_from_jdbc_conf(frame, catalog_connection, connection_options={}, redshift_tmp_dir = "", transformation_ctx = "", catalog_id = None)`** 使用指定的 JDBC 連線資訊撰寫並傳回 `DynamicFrame`。 + `frame` – 所要撰寫的 `DynamicFrame`。 + `catalog_connection` – 所要使用的目錄連線。 + `connection_options` – 連線選項，例如路徑和資料庫資料表 (選用)。如需詳細資訊，請參閱[AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `redshift_tmp_dir` – 所要使用的 Amazon Redshift 暫時目錄 (選用)。 + `transformation_ctx` – 所要使用的轉換細節 (選用)。 + `catalog_id` — 要存取之 Data Catalog 的目錄 ID (帳戶 ID)。若無，會使用發起人的預設帳戶 ID。 ## write\$1from\$1jdbc\$1conf **`write_from_jdbc_conf(frame_or_dfc, catalog_connection, connection_options={}, redshift_tmp_dir = "", transformation_ctx = "", catalog_id = None)`** 使用指定的 JDBC 連線資訊撰寫並傳回 `DynamicFrame` 或 `DynamicFrameCollection`。 + `frame_or_dfc` – 所要撰寫的 `DynamicFrame` 或 `DynamicFrameCollection`。 + `catalog_connection` – 所要使用的目錄連線。 + `connection_options` – 連線選項，例如路徑和資料庫資料表 (選用)。如需詳細資訊，請參閱[AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `redshift_tmp_dir` – 所要使用的 Amazon Redshift 暫時目錄 (選用)。 + `transformation_ctx` – 所要使用的轉換細節 (選用)。 + `catalog_id` — 要存取之 Data Catalog 的目錄 ID (帳戶 ID)。若無，會使用發起人的預設帳戶 ID。 # AWS Glue PySpark 轉換參考 AWS Glue 提供下列內建轉換，您可以在 PySpark ETL 操作中使用。您的資料會在資料結構中從轉換傳遞至轉換，而此資料結構稱為 *DynamicFrame*，是 Apache Spark SQL `DataFrame` 的延伸。`DynamicFrame` 包含您的資料，而您可以參考其結構描述以處理資料。 這些轉換大多數也作為 `DynamicFrame` 類別的方法存在。如需詳細資訊，請參閱 [DynamicFrame 轉換](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-_transforms)。 + [GlueTransform base 類別](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md) + [ApplyMapping 類別](aws-glue-api-crawler-pyspark-transforms-ApplyMapping.md) + [DropFields 類別](aws-glue-api-crawler-pyspark-transforms-DropFields.md) + [DropNullFields 類別](aws-glue-api-crawler-pyspark-transforms-DropNullFields.md) + [ErrorsAsDynamicFrame 類別](aws-glue-api-crawler-pyspark-transforms-ErrorsAsDynamicFrame.md) + [EvaluateDataQuality 類別](aws-glue-api-crawler-pyspark-transforms-EvaluateDataQuality.md) + [FillMissingValues 類別](aws-glue-api-crawler-pyspark-transforms-fillmissingvalues.md) + [Filter 類別](aws-glue-api-crawler-pyspark-transforms-filter.md) + [FindIncrementalMatches 類別](aws-glue-api-crawler-pyspark-transforms-findincrementalmatches.md) + [FindMatches 類別](aws-glue-api-crawler-pyspark-transforms-findmatches.md) + [FlatMap 類別](aws-glue-api-crawler-pyspark-transforms-flat-map.md) + [Join 類別](aws-glue-api-crawler-pyspark-transforms-join.md) + [Map 類別](aws-glue-api-crawler-pyspark-transforms-map.md) + [MapToCollection 類別](aws-glue-api-crawler-pyspark-transforms-MapToCollection.md) + [mergeDynamicFrame](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-merge) + [Relationalize 類別](aws-glue-api-crawler-pyspark-transforms-Relationalize.md) + [RenameField 類別](aws-glue-api-crawler-pyspark-transforms-RenameField.md) + [ResolveChoice 類別](aws-glue-api-crawler-pyspark-transforms-ResolveChoice.md) + [SelectFields 類別](aws-glue-api-crawler-pyspark-transforms-SelectFields.md) + [SelectFromCollection 類別](aws-glue-api-crawler-pyspark-transforms-SelectFromCollection.md) + [Simplify\$1ddb\$1json 類別](aws-glue-api-crawler-pyspark-transforms-simplify-ddb-json.md) + [Spigot 類別](aws-glue-api-crawler-pyspark-transforms-spigot.md) + [SplitFields 類別](aws-glue-api-crawler-pyspark-transforms-SplitFields.md) + [SplitRows 類別](aws-glue-api-crawler-pyspark-transforms-SplitRows.md) + [Unbox 類別](aws-glue-api-crawler-pyspark-transforms-Unbox.md) + [UnnestFrame 類別](aws-glue-api-crawler-pyspark-transforms-UnnestFrame.md) # GlueTransform base 類別 所有 `awsglue.transforms` 類別繼承的基底類別。 所有類別皆定義一項 `__call__` 方法。依據預設，它們會覆寫下列的 `GlueTransform` 類別方法，或者透過使用類別名稱呼叫。 ## 方法 + [apply(cls, \$1args, \$1\$1kwargs)](#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply) + [name(cls)](#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name) + [describeArgs(cls)](#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs) + [describeReturn(cls)](#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn) + [describeTransform(cls)](#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform) + [describeErrors(cls)](#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors) + [describe(cls)](#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe) ## apply(cls, \$1args, \$1\$1kwargs) 藉由呼叫轉換類別並傳回結果以套用轉換。 + `cls` – `self` 類別物件。 ## name(cls) 傳回衍生的轉換類別名稱。 + `cls` – `self` 類別物件。 ## describeArgs(cls) + `cls` – `self` 類別物件。 傳回字典清單，每個皆對應至一個具名引數，格式如下： ``` [ { "name": "(name of argument)", "type": "(type of argument)", "description": "(description of argument)", "optional": "(Boolean, True if the argument is optional)", "defaultValue": "(Default value string, or None)(String; the default value, or None)" }, ... ] ``` 呼叫未實作的衍生轉換時，引發 `NotImplementedError` 例外。 ## describeReturn(cls) + `cls` – `self` 類別物件。 傳回字典及有關傳回類型的資訊，格式如下： ``` { "type": "(return type)", "description": "(description of output)" } ``` 呼叫未實作的衍生轉換時，引發 `NotImplementedError` 例外。 ## describeTransform(cls) 傳回描述轉換的字串。 + `cls` – `self` 類別物件。 呼叫未實作的衍生轉換時，引發 `NotImplementedError` 例外。 ## describeErrors(cls) + `cls` – `self` 類別物件。 傳回字典的清單，每個皆描述此轉換可能擲出的例外狀況，格式如下： ``` [ { "type": "(type of error)", "description": "(description of error)" }, ... ] ``` ## describe(cls) + `cls` – `self` 類別物件。 以下列格式傳回物件： ``` { "transform" : { "name" : cls.name( ), "args" : cls.describeArgs( ), "returns" : cls.describeReturn( ), "raises" : cls.describeErrors( ), "location" : "internal" } } ``` # ApplyMapping 類別 在 `DynamicFrame` 套用映射。 ## 範例 建議您使用 [`DynamicFrame.apply_mapping()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-apply_mapping) 在 `DynamicFrame` 中套用映射。若要檢視程式碼範例，請參閱 [範例：使用 apply\$1map 來重新命名欄位並變更欄位類型](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-apply_mapping-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-ApplyMapping-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-ApplyMapping-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-ApplyMapping-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-ApplyMapping-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-ApplyMapping-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-ApplyMapping-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-ApplyMapping-describeErrors) + [描述](#aws-glue-api-crawler-pyspark-transforms-ApplyMapping-describe) ## \$1\$1call\$1\$1(frame, mappings, transformation\$1ctx = "", info = "", stageThreshold = 0, totalThreshold = 0) 將宣告式映射套用於指定的 `DynamicFrame`。 + `frame` – 要套用映射的 `DynamicFrame` (必要)。 + `mappings` –映射元組的清單 (必要)。每個清單包括：(來源欄、來源類型、目標欄、目標類型)。 如果來源欄的名稱中有一個小點 "`.`"，則您必須在其前後加上反引號 "````"。例如，若要將 `this.old.name` (字串) 對應至 `thisNewName`，會使用以下元組： ``` ("`this.old.name`", "string", "thisNewName", "string") ``` + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 只傳回「映射」元組中指定的 `DynamicFrame` 欄位。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # DropFields 類別 在 `DynamicFrame` 內捨棄欄位。 ## 範例 建議您使用 [`DynamicFrame.drop_fields()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-drop_fields) 方法從 `DynamicFrame` 中刪除欄位。若要檢視程式碼範例，請參閱 [範例：使用 drop\$1fields 從 `DynamicFrame` 中移除欄位](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-drop_fields-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-DropFields-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-DropFields-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-DropFields-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-DropFields-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-DropFields-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-DropFields-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-DropFields-describeErrors) + [描述](#aws-glue-api-crawler-pyspark-transforms-DropFields-describe) ## \$1\$1call\$1\$1(frame, paths, transformation\$1ctx = "", info = "", stageThreshold = 0, totalThreshold = 0) 在 `DynamicFrame` 內捨棄節點。 + `frame` – 要捨棄節點的 `DynamicFrame` (必要)。 + `paths` – 要捨棄之節點的完整路徑清單 (必要)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 傳回無指定欄位的新 `DynamicFrame`。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # DropNullFields 類別 捨棄 `DynamicFrame` 中類型為 `NullType` 的所有 null 欄位。在 `DynamicFrame` 資料集的每筆記錄中，皆存在缺少值或為空值的欄位。 ## 範例 此範例使用 `DropNullFields` 建立新的 `DynamicFrame`，其中類型 `NullType` 的欄位已刪除。為了演示 `DropNullFields`，我們將類型為 null 的名為 `empty_column` 的新資料欄新增至已加載的 `persons` 資料集。 **注意** 若要存取此範例中使用的資料集，請參閱 [程式碼範例：加入和關聯化資料](aws-glue-programming-python-samples-legislators.md) 並依照 [步驟 1：在 Amazon S3 儲存貯體中網路爬取資料](aws-glue-programming-python-samples-legislators.md#aws-glue-programming-python-samples-legislators-crawling) 中的說明進行。 ``` # Example: Use DropNullFields to create a new DynamicFrame without NullType fields from pyspark.context import SparkContext from awsglue.context import GlueContext from pyspark.sql.functions import lit from pyspark.sql.types import NullType from awsglue.dynamicframe import DynamicFrame from awsglue.transforms import DropNullFields # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Create DynamicFrame persons = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="persons_json" ) print("Schema for the persons DynamicFrame:") persons.printSchema() # Add new column "empty_column" with NullType persons_with_nulls = persons.toDF().withColumn("empty_column", lit(None).cast(NullType())) persons_with_nulls_dyf = DynamicFrame.fromDF(persons_with_nulls, glueContext, "persons_with_nulls") print("Schema for the persons_with_nulls_dyf DynamicFrame:") persons_with_nulls_dyf.printSchema() # Remove the NullType field persons_no_nulls = DropNullFields.apply(persons_with_nulls_dyf) print("Schema for the persons_no_nulls DynamicFrame:") persons_no_nulls.printSchema() ``` ### Output ``` Schema for the persons DynamicFrame: root |-- family_name: string |-- name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- gender: string |-- image: string |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- other_names: array | |-- element: struct | | |-- lang: string | | |-- note: string | | |-- name: string |-- sort_name: string |-- images: array | |-- element: struct | | |-- url: string |-- given_name: string |-- birth_date: string |-- id: string |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string |-- death_date: string Schema for the persons_with_nulls_dyf DynamicFrame: root |-- family_name: string |-- name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- gender: string |-- image: string |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- other_names: array | |-- element: struct | | |-- lang: string | | |-- note: string | | |-- name: string |-- sort_name: string |-- images: array | |-- element: struct | | |-- url: string |-- given_name: string |-- birth_date: string |-- id: string |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string |-- death_date: string |-- empty_column: null null_fields ['empty_column'] Schema for the persons_no_nulls DynamicFrame: root |-- family_name: string |-- name: string |-- links: array | |-- element: struct | | |-- note: string | | |-- url: string |-- gender: string |-- image: string |-- identifiers: array | |-- element: struct | | |-- scheme: string | | |-- identifier: string |-- other_names: array | |-- element: struct | | |-- lang: string | | |-- note: string | | |-- name: string |-- sort_name: string |-- images: array | |-- element: struct | | |-- url: string |-- given_name: string |-- birth_date: string |-- id: string |-- contact_details: array | |-- element: struct | | |-- type: string | | |-- value: string |-- death_date: string ``` ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-DropNullFields-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-DropNullFields-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-DropNullFields-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-DropNullFields-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-DropNullFields-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-DropNullFields-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-DropNullFields-describeErrors) + [描述](#aws-glue-api-crawler-pyspark-transforms-DropNullFields-describe) ## \$1\$1call\$1\$1(frame, transformation\$1ctx = "", info = "", stageThreshold = 0, totalThreshold = 0) 刪除 `DynamicFrame` 中類型為 `NullType` 的所有 null 欄位。在 `DynamicFrame` 資料集的每筆記錄中，皆存在缺少值或為空值的欄位。 + `frame` – 要刪除其 null 欄位的 `DynamicFrame` (必要)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 傳回不含 null 欄位的新 `DynamicFrame`。 ## apply(cls, \$1args, \$1\$1kwargs) + `cls` – cls ## name(cls) + `cls` – cls ## describeArgs(cls) + `cls` – cls ## describeReturn(cls) + `cls` – cls ## describeTransform(cls) + `cls` – cls ## describeErrors(cls) + `cls` – cls ## describe(cls) + `cls` – cls # ErrorsAsDynamicFrame 類別 傳回一個 `DynamicFrame`，其中包含建立來源 `DynamicFrame` 時發生的錯誤的巢狀錯誤。 ## 範例 建議您使用 [`DynamicFrame.errorsAsDynamicFrame()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-errorsAsDynamicFrame) 方法擷取和檢視錯誤記錄。若要檢視程式碼範例，請參閱 [範例：使用 errorsAsDynamicFrame 來檢視錯誤記錄](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-errorsAsDynamicFrame-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-ErrorsAsDynamicFrame-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-ErrorsAsDynamicFrame-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-ErrorsAsDynamicFrame-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-ErrorsAsDynamicFrame-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-ErrorsAsDynamicFrame-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-ErrorsAsDynamicFrame-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-ErrorsAsDynamicFrame-describeErrors) + [描述](#aws-glue-api-crawler-pyspark-transforms-ErrorsAsDynamicFrame-describe) ## \$1\$1call\$1\$1(frame) 傳回 `DynamicFrame`，其中包含與來源 `DynamicFrame` 有關的巢狀錯誤記錄。 + `frame` – 來源 `DynamicFrame` (必要)。 ## apply(cls, \$1args, \$1\$1kwargs) + `cls` – cls ## name(cls) + `cls` – cls ## describeArgs(cls) + `cls` – cls ## describeReturn(cls) + `cls` – cls ## describeTransform(cls) + `cls` – cls ## describeErrors(cls) + `cls` – cls ## describe(cls) + `cls` – cls # EvaluateDataQuality 類別 根據 `DynamicFrame` 評估資料品質規則集，並傳回包含評估結果的新 `DynamicFrame`。 ## 範例 下列範例程式碼示範如何評估 `DynamicFrame` 的資料品質，然後檢視資料品質結果。 ``` from awsglue.transforms import * from pyspark.context import SparkContext from awsglue.context import GlueContext from awsgluedq.transforms import EvaluateDataQuality #Create Glue context sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Define DynamicFrame legislatorsAreas = glueContext.create_dynamic_frame.from_catalog( database="legislators", table_name="areas_json") # Create data quality ruleset ruleset = """Rules = [ColumnExists "id", IsComplete "id"]""" # Evaluate data quality dqResults = EvaluateDataQuality.apply( frame=legislatorsAreas, ruleset=ruleset, publishing_options={ "dataQualityEvaluationContext": "legislatorsAreas", "enableDataQualityCloudWatchMetrics": True, "enableDataQualityResultsPublishing": True, "resultsS3Prefix": "amzn-s3-demo-bucket1", }, ) # Inspect data quality results dqResults.printSchema() dqResults.toDF().show() ``` ### Output ``` root |-- Rule: string |-- Outcome: string |-- FailureReason: string |-- EvaluatedMetrics: map | |-- keyType: string | |-- valueType: double +-----------------------+-------+-------------+---------------------------------------+ |Rule |Outcome|FailureReason|EvaluatedMetrics | +-----------------------+-------+-------------+---------------------------------------+ |ColumnExists "id" |Passed |null |{} | |IsComplete "id" |Passed |null |{Column.first_name.Completeness -> 1.0}| +-----------------------+-------+-------------+---------------------------------------+ ``` ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-EvaluateDataQuality-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-EvaluateDataQuality-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-EvaluateDataQuality-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-EvaluateDataQuality-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-EvaluateDataQuality-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-EvaluateDataQuality-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-EvaluateDataQuality-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-EvaluateDataQuality-describe) ## \$1\$1call\$1\$1(frame, ruleset, publishing\$1options = \$1\$1) + `frame` – 您要評估資料品質的 `DynamicFrame`。 + `ruleset` – 字串格式的資料品質定義語言 (DQDL) 規則集。若要進一步了解 DQDL，請參閱 [資料品質定義語言 (DQDL) 參考](dqdl.md) 指南。 + `publishing_options` – 指定以下用於發佈評估結果和指標的選項的字典： + `dataQualityEvaluationContext` – 指定 Glue AWS 應發佈 Amazon CloudWatch 指標和資料品質結果的命名空間的字串。彙總指標會出現在 CloudWatch 中，而完整結果會出現在 AWS Glue Studio 界面中。 + 必要：否 + 預設值：`default_context` + `enableDataQualityCloudWatchMetrics` – 指定是否應將資料品質評估的結果發佈至 CloudWatch。您可以使用 `dataQualityEvaluationContext` 選項指定指標的命名空間。 + 必要：否 + 預設值：False + `enableDataQualityResultsPublishing` – 指定資料品質結果是否應顯示在 AWS Glue Studio 介面的 **Data Quality** (資料品質) 索引標籤上。 + 必要：否 + 預設值：True + `resultsS3Prefix` – 指定 Glue AWS 可以寫入資料品質評估結果的 Amazon S3 位置。 + 必要：否 + 預設值："" (空字串) ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # FillMissingValues 類別 `FillMissingValues` 類別會在指定的 `DynamicFrame` 中找到 null 值和空字串，並使用機器學習方法 (例如線性迴歸和隨機樹系) 來預測缺少的值。ETL 任務會使用輸入資料集中的值來訓練機器學習模型，然後預測缺少的值應該是什麼。 **提示** 如果您使用增量資料集，則每個增量集都會用作機器學習模型的訓練資料，因此結果可能不準確。 若要匯入： ``` from awsglueml.transforms import FillMissingValues ``` ## 方法 + [套用](#aws-glue-api-crawler-pyspark-transforms-fillmissingvalues-apply) ## apply(frame, missing\$1values\$1column, output\$1column ="", transformation\$1ctx ="", info ="", stageThreshold = 0, totalThreshold = 0) 在指定的欄中填入動態框架的缺少值，並在新的欄中傳回具有估計值的新框架。對於沒有缺少值的列，指定欄的值將被複製到新欄。 + `frame` – 在其中填入缺少值的 `DynamicFrame`。必要。 + `missing_values_column` – 包含缺少值的欄 (`null` 值和空字串)。必要. + `output_column` – 新欄的名稱，該欄將包含所有缺少值的列的估計值。選擇性；預設值為 `missing_values_column` 的名稱，字尾為 `"_filled"`。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用；預設值為零)。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用；預設值為零)。 傳回具有一個額外欄的新 `DynamicFrame`，其中包含缺少值的列估計和其他列的目前值。 # Filter 類別 建立新的 `DynamicFrame`，其中包含來自輸入 `DynamicFrame` 的符合指定述詞函數的記錄。 ## 範例 建議您使用 [`DynamicFrame.filter()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-filter) 方法篩選 `DynamicFrame` 中的記錄。若要檢視程式碼範例，請參閱 [範例：使用篩選條件取得已篩選的欄位選取](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-filter-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-filter-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-filter-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-filter-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-filter-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-filter-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-filter-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-filter-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-filter-describe) ## \$1\$1call\$1\$1(frame, f, transformation\$1ctx="", info="", stageThreshold=0, totalThreshold=0)) 傳回新 `DynamicFrame`，其藉由從符合指定述詞函數的輸入 `DynamicFrame` 選擇記錄所建置。 + `frame` – 要套用指定篩選條件函數的來源 `DynamicFrame` (必要)。 + `f` – 要套用到 `DynamicFrame` 中各個 `DynamicRecord` 的述詞函數。此函數必須以 `DynamicRecord` 做為引數並傳回 True，如果 `DynamicRecord` 符合篩選條件要求，否則將傳回 False (必要)。 `DynamicRecord` 代表 `DynamicFrame` 中的邏輯記錄。它類似 Spark `DataFrame` 中的一列，除了它是自我描述的，以及可用於不符合固定結構描述的資料。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # FindIncrementalMatches 類別 識別現有和增量 `DynamicFrame` 中的相符記錄，並使用指派給每個相符記錄群組的唯一識別碼來建立新的 `DynamicFrame`。 若要匯入： ``` from awsglueml.transforms import FindIncrementalMatches ``` ## 方法 + [套用](#aws-glue-api-crawler-pyspark-transforms-findincrementalmatches-apply) ## apply(existingFrame, incrementalFrame, transformId, transformation\$1ctx = "", info = "", stageThreshold = 0, totalThreshold = 0, enforcedMatches = none, computeMatchConfidenceScores = 0) 識別輸入 `DynamicFrame` 中的相符記錄，並使用指派給每個相符記錄群組的唯一識別碼來建立新的 `DynamicFrame`。 + `existingFrame` – 現有和預先符合的 `DynamicFrame` 以套用 FindIncrementalMatches 轉換。必要. + `incrementalFrame` – 要套用 FindIncrementalMatches 轉換以比對 `existingFrame` 的增量 `DynamicFrame`。必要. + `transformId` – 與 FindIncrementalMatches 轉換相關聯的唯一 ID，以套用於 `DynamicFrames` 中的記錄。必要. + `transformation_ctx` – 用於識別統計資料/狀態資訊的唯一字串。選用。 + `info` – 與轉換中的錯誤相關的字串。選用。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限。選用。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限。選用。預設為零。 + `enforcedMatches` – 用於強制符合的 `DynamicFrame`。選用。預設值為 None (無)。 + `computeMatchConfidenceScores` – 布林值，指出是否運算每個相符記錄群組的可信度分數。選用。預設值為 false。 傳回具有指派給每個相符記錄群組之唯一識別碼的新 `DynamicFrame`。 # FindMatches 類別 識別輸入 `DynamicFrame` 中的相符記錄，並使用指派給每個相符記錄群組的唯一識別碼來建立新的 `DynamicFrame`。 若要匯入： ``` from awsglueml.transforms import FindMatches ``` ## 方法 + [套用](#aws-glue-api-crawler-pyspark-transforms-findmatches-apply) ## apply(frame, transformId, transformation\$1ctx = "", info = "", stageThreshold = 0, totalThreshold = 0, enforcedMatches = none, computeMatchConfidenceScores = 0) 識別輸入 `DynamicFrame` 中的相符記錄，並使用指派給每個相符記錄群組的唯一識別碼來建立新的 `DynamicFrame`。 + `frame` – 要套用 FindMatches 轉換的 `DynamicFrame`。必要. + `transformId` – 與 FindMatches 轉換相關聯的唯一 ID，以套用於 `DynamicFrame` 中的記錄。必要. + `transformation_ctx` – 用於識別統計資料/狀態資訊的唯一字串。選用。 + `info` – 與轉換中的錯誤相關的字串。選用。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限。選用。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限。選用。預設為零。 + `enforcedMatches` – 用於強制符合的 `DynamicFrame`。選用。預設值為 None (無)。 + `computeMatchConfidenceScores` – 布林值，指出是否運算每個相符記錄群組的可信度分數。選用。預設值為 false。 傳回具有指派給每個相符記錄群組之唯一識別碼的新 `DynamicFrame`。 # FlatMap 類別 將轉換套用至集合中的各個 `DynamicFrame`。結果不會扁平化為單一的 `DynamicFrame`，而是保留為集合。 ## FlatMap 的範例 下列範例程式碼片段示範如何在套用至 `FlatMap` 時對動態影格集合使用 `ResolveChoice` 轉換。用於輸入的資料位於 Amazon S3 地址 `s3://bucket/path-for-data/sample.json` 預留位置的 JSON 中，並包含下列資料。 ### 範例 JSON 資料 ``` [{ "firstname": "Arnav", "lastname": "Desai", "address": { "street": "6 Anyroad Avenue", "city": "London", "state": "England", "country": "UK" }, "phone": 17235550101, "affiliations": [ "General Anonymous Example Products", "Example Independent Research", "Government Department of Examples" ] }, { "firstname": "Mary", "lastname": "Major", "address": { "street": "7821 Spot Place", "city": "Centerville", "state": "OK", "country": "US" }, "phone": 19185550023, "affiliations": [ "Example Dot Com", "Example Independent Research", "Example.io" ] }, { "firstname": "Paulo", "lastname": "Santos", "address": { "street": "123 Maple Street", "city": "London", "state": "Ontario", "country": "CA" }, "phone": 12175550181, "affiliations": [ "General Anonymous Example Products", "Example Dot Com" ] }] ``` **Example 將 ResolveChoice 套用至 DynamicFrameCollection 並顯示輸出。** ``` #Read DynamicFrame datasource = glueContext.create_dynamic_frame_from_options("s3", connection_options = {"paths":["s3://bucket/path/to/file/mysamplejson.json"]}, format="json") datasource.printSchema() datasource.show() ## Split to create a DynamicFrameCollection split_frame=datasource.split_fields(["firstname","lastname","address"],"personal_info","business_info") split_frame.keys() print("---") ## Use FlatMap to run ResolveChoice kwargs = {"choice": "cast:string"} flat = FlatMap.apply(split_frame, ResolveChoice, frame_name="frame", transformation_ctx='tcx', **kwargs) flat.keys() ##Select one of the DynamicFrames personal_info = flat.select("personal_info") personal_info.printSchema() personal_info.show() print("---") business_info = flat.select("business_info") business_info.printSchema() business_info.show() ``` 呼叫 `FlatMap.apply` 時，`frame_name` 參數**必須**是 `"frame"`。目前不接受其他值。 ### 範例輸出 ``` root |-- firstname: string |-- lastname: string |-- address: struct | |-- street: string | |-- city: string | |-- state: string | |-- country: string |-- phone: long |-- affiliations: array | |-- element: string --- { "firstname": "Mary", "lastname": "Major", "address": { "street": "7821 Spot Place", "city": "Centerville", "state": "OK", "country": "US" }, "phone": 19185550023, "affiliations": [ "Example Dot Com", "Example Independent Research", "Example.io" ] } { "firstname": "Paulo", "lastname": "Santos", "address": { "street": "123 Maple Street", "city": "London", "state": "Ontario", "country": "CA" }, "phone": 12175550181, "affiliations": [ "General Anonymous Example Products", "Example Dot Com" ] } --- root |-- firstname: string |-- lastname: string |-- address: struct | |-- street: string | |-- city: string | |-- state: string | |-- country: string { "firstname": "Mary", "lastname": "Major", "address": { "street": "7821 Spot Place", "city": "Centerville", "state": "OK", "country": "US" } } { "firstname": "Paulo", "lastname": "Santos", "address": { "street": "123 Maple Street", "city": "London", "state": "Ontario", "country": "CA" } } --- root |-- phone: long |-- affiliations: array | |-- element: string { "phone": 19185550023, "affiliations": [ "Example Dot Com", "Example Independent Research", "Example.io" ] } { "phone": 12175550181, "affiliations": [ "General Anonymous Example Products", "Example Dot Com" ] } ``` ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-flat-map-__call__) + [套用](#aws-glue-api-crawler-pyspark-transforms-flat-map-apply) + [名稱](#aws-glue-api-crawler-pyspark-transforms-flat-map-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-flat-map-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-flat-map-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-flat-map-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-flat-map-describeErrors) + [描述](#aws-glue-api-crawler-pyspark-transforms-flat-map-describe) ## \$1\$1call\$1\$1(dfc, BaseTransform, frame\$1name, transformation\$1ctx = "", \$1\$1base\$1kwargs) 對集合中的每個 `DynamicFrame` 套用轉換，並將結果扁平化。 + `dfc` – 要對其套用 flatmap 的 `DynamicFrameCollection` (必要)。 + `BaseTransform` – 從 `GlueTransform` 衍生的轉換功能，要套用到集合中的每個成員 (必要)， + `frame_name` – 做為集合元素傳遞目標的引數名稱 (必要)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `base_kwargs` – 要傳遞到基本轉換的引數 (必要)。 傳回新的 `DynamicFrameCollection`，也就是對來源 `DynamicFrameCollection` 中個別 `DynamicFrame` 所套用轉換後所產生的集合。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # Join 類別 對兩個 `DynamicFrames` 執行對等性加入。 ## 範例 建議您使用 [`DynamicFrame.join()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-join) 聯結 `DynamicFrames`。若要檢視程式碼範例，請參閱 [範例：使用聯結合併 `DynamicFrames`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-join-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-join-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-join-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-join-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-join-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-join-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-join-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-join-describeErrors) + [描述](#aws-glue-api-crawler-pyspark-transforms-join-describe) ## \$1\$1call\$1\$1(frame1, frame2, keys1, keys2, transformation\$1ctx = "") 對兩個 `DynamicFrames` 執行對等性加入。 + `frame1` – 第一個要加入的 `DynamicFrame` (必要)。 + `frame2` – 第二個要加入的 `DynamicFrame` (必要)。 + `keys1` – 第一個框架要加入的金鑰 (必要)。 + `keys2` – 第二個框架要加入的金鑰 (必要)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 傳回建立的新 `DynamicFrame`，其建立透過聯結兩個 `DynamicFrames`。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # Map 類別 透過將函數套用到輸入 `DynamicFrame` 中的所有記錄，以建置新的 `DynamicFrame`。 ## 範例 建議您使用 [`DynamicFrame.map()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-map) 方法將函數套用至 `DynamicFrame` 中的所有記錄。若要檢視程式碼範例，請參閱 [範例：使用 map 將函數套用至 `DynamicFrame` 中的每個記錄](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-map-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-map-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-map-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-map-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-map-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-map-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-map-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-map-describeErrors) + [描述](#aws-glue-api-crawler-pyspark-transforms-map-describe) ## \$1\$1call\$1\$1(frame, f, transformation\$1ctx="", info="", stageThreshold=0, totalThreshold=0) 傳回透過將指定函數套用到原始 `DynamicFrame` 中所有 `DynamicRecords` 所產生的新 `DynamicFrame`。 + `frame` – 要套用映射函數的 `DynamicFrame` (必要)。 + `f` – 要套用到 `DynamicFrame` 中所有 `DynamicRecords` 的函數。此函數必須以 `DynamicRecord` 做為參數，並傳回以映射產生的新 `DynamicRecord` (必要)。 `DynamicRecord` 代表 `DynamicFrame` 中的邏輯記錄。它類似 Apache Spark `DataFrame` 中的一列，除了它是自我描述的，以及可用於不符合固定結構描述的資料。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 傳回透過將指定函數套用到原始 `DynamicFrame` 中所有 `DynamicRecords` 所產生的新 `DynamicFrame`。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # MapToCollection 類別 將轉換套用到指定的 `DynamicFrameCollection` 中的各個 `DynamicFrame`。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-MapToCollection-__call__) + [套用](#aws-glue-api-crawler-pyspark-transforms-MapToCollection-apply) + [名稱](#aws-glue-api-crawler-pyspark-transforms-MapToCollection-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-MapToCollection-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-MapToCollection-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-MapToCollection-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-MapToCollection-describeErrors) + [描述](#aws-glue-api-crawler-pyspark-transforms-MapToCollection-describe) ## \$1\$1call\$1\$1(dfc, BaseTransform, frame\$1name, transformation\$1ctx = "", \$1\$1base\$1kwargs) 將轉換函式套用到指定的 `DynamicFrameCollection` 中的各個 `DynamicFrame`。 + `dfc` – 要套用轉換函數的 `DynamicFrameCollection` (必要)。 + `callable` – 要套用到各個成員集合的可呼叫轉換函數 (必要)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 傳回新的 `DynamicFrameCollection`，也就是對來源 `DynamicFrameCollection` 中個別 `DynamicFrame` 所套用轉換後所產生的集合。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply) ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # Relationalize 類別 對 `DynamicFrame` 中的巢狀化結構描述進行壓平合併，並針對已攤平的框架，將陣列欄直轉橫。 ## 範例 建議您使用 [`DynamicFrame.relationalize()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-relationalize) 方法來關聯化 `DynamicFrame`。若要檢視程式碼範例，請參閱 [範例：使用 relationalize 來壓平合併 `DynamicFrame` 中的巢狀化結構描述](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-relationalize-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-Relationalize-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-Relationalize-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-Relationalize-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-Relationalize-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-Relationalize-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-Relationalize-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-Relationalize-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-Relationalize-describe) ## \$1\$1call\$1\$1(frame, staging\$1path=None, name='roottable', options=None, transformation\$1ctx = "", info = "", stageThreshold = 0, totalThreshold = 0) 將 `DynamicFrame` 關聯化，並針對將巢狀欄解巢狀和將陣列欄直轉橫所產生的框架，來製作清單。使用在解除巢狀化階段中所產生的聯結鍵，將直轉橫的陣列欄聯結至根資料表。 + `frame` – 要進行關聯化的 `DynamicFrame` (必要)。 + `staging_path` – 該方法用來以 CSV 格式存放直轉橫資料表分區的路徑 (選用)。直轉橫資料表從這個路徑讀回。 + `name` – 根資料表的名稱 (選用)。 + `options` – 選用參數的字典。目前未使用。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # RenameField 類別 重新命名 `DynamicFrame` 內的節點。 ## 範例 建議您使用 [`DynamicFrame.rename_field()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-rename_field) 方法重新命名 `DynamicFrame` 中的欄位。若要檢視程式碼範例，請參閱 [範例：使用 rename\$1field 重新命名 `DynamicFrame` 中的欄位](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-rename_field-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-RenameField-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-RenameField-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-RenameField-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-RenameField-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-RenameField-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-RenameField-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-RenameField-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-RenameField-describe) ## \$1\$1call\$1\$1(frame, old\$1name, new\$1name, transformation\$1ctx = "", info = "", stageThreshold = 0, totalThreshold = 0) 重新命名 `DynamicFrame` 內的節點。 + `frame` - 要重新命名其中節點的 `DynamicFrame` (必要)。 + `old_name` – 要重新命名之節點的完整路徑 (必要)。 如果舊名稱內有小點，RenameField 無法正常運作，除非在前後加上反引號 (````)。例如，若要將 `this.old.name` 換成 `thisNewName`，您可以用下列方式呼叫 RenameField： ``` newDyF = RenameField(oldDyF, "`this.old.name`", "thisNewName") ``` + `new_name` – 新的名稱，包含完整路徑 (必要)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # ResolveChoice 類別 解析 `DynamicFrame` 內的選擇類型。 ## 範例 建議您使用 [`DynamicFrame.resolveChoice()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-resolveChoice) 方法來處理 `DynamicFrame` 中包含多個類型的欄位。若要檢視程式碼範例，請參閱 [範例：使用 resolveChoice 來處理包含多種類型的資料欄](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-resolveChoice-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-ResolveChoice-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-ResolveChoice-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-ResolveChoice-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-ResolveChoice-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-ResolveChoice-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-ResolveChoice-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-ResolveChoice-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-ResolveChoice-describe) ## \$1\$1call\$1\$1(frame, specs = none, choice = "", transformation\$1ctx = "", info = "", stageThreshold = 0, totalThreshold = 0) 提供資訊以解析 `DynamicFrame` 內模棱兩可的類型。它會傳回產生的 `DynamicFrame`。 + `frame` – 要解析其中選擇類型的 `DynamicFrame` (必要)。 + `specs` – 要解析的特定模棱兩可項目的清單，形式皆為 tuple:`(path, action)`。`path` 值代表模棱兩可的特定元素，`action` 值則代表對應的解析動作。 您只能使用 `spec` 和 `choice` 參數的其中一項。如果 `spec` 參數不是 `None`，則 `choice` 參數必須為空字串。相反地，如果 `choice` 不是空字串，則 `spec` 參數必須為 `None`。如果未提供任何參數， AWS Glue 會嘗試剖析結構描述，並使用它來解決模棱兩可的情況。 可在 `specs` 元組的 `action` 部分中指定下列解析策略的其中一種： + `cast` - 可讓您指定轉換的目標類型 (例如 `cast:int`)。 + `make_cols` – 透過將資料壓平合併來解析可能的模棱兩可項目。例如，如果 `columnA` 可能是 `int` 或 `string`，則在得出的 `DynamicFrame` 中，解析動作會產生名為 `columnA_int` 和 `columnA_string` 的兩個欄。 + `make_struct` - 藉由以結構表示資料，來解決可能的模棱兩可項目。舉例來說，如果欄中的資料可能是 `int` 或 `string`，則使用 `make_struct` 動作會在結果的 `DynamicFrame` 中產生結構的欄，每個欄同時包含 `int` 和 `string`。 + `project` - 在產生的 `DynamicFrame` 中只擷取指定種類的值，以此解析可能的模棱兩可項目。例如，如果 `ChoiceType` 欄中的資料可能是 `int` 或 `string`，指定 `project:string` 動作會從並非 `string` 類型產生的 `DynamicFrame` 捨棄欄。 若 `path` 識別到陣列，在陣列的名稱後放置空白的方括號以避免模棱兩可的狀況。例如，假設您使用如下結構化的資料： ``` "myList": [ { "price": 100.00 }, { "price": "$100.00" } ] ``` 您可以選取數值而不是價格字串版本，方法是將 `path` 設定為 `"myList[].price"`，且將 `action` 設定為 `"cast:double"`。 + `choice` – 當 `specs` 參數為 `None` 時的預設解析動作。如果 `specs` 參數不是 `None`，則此值只能為空字串，不能設定成其他的值。 除了上述 `specs` 動作，此引數也支援下列動作： + `MATCH_CATALOG` – 嘗試將每個 `ChoiceType` 投射至指定 Data Catalog 資料表中的對應類型。 + `database` – 要與 `MATCH_CATALOG` 選項搭配使用的 AWS Glue Data Catalog 資料庫 `MATCH_CATALOG` ( 需要）。 + `table_name` – 要與 `MATCH_CATALOG`動作搭配使用的 AWS Glue Data Catalog 資料表名稱 `MATCH_CATALOG` ( 需要）。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # SelectFields 類別 `SelectFields` 類別建立新的 `DynamicFrame` 從現有 `DynamicFrame`，並僅保留您指定的欄位。`SelectFields` 提供類似 SQL `SELECT` 陳述式的功能。 ## 範例 建議您使用 [`DynamicFrame.select_fields()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-select_fields) 方法從 `DynamicFrame` 中選擇欄位。若要檢視程式碼範例，請參閱 [範例：使用 select\$1fields 來用所選欄位建立新的 `DynamicFrame`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-select_fields-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-SelectFields-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-SelectFields-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-SelectFields-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-SelectFields-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-SelectFields-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-SelectFields-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-SelectFields-describeErrors) + [描述](#aws-glue-api-crawler-pyspark-transforms-SelectFields-describe) ## \$1\$1call\$1\$1(frame, paths, transformation\$1ctx = "", info = "", stageThreshold = 0, totalThreshold = 0) 在 `DynamicFrame` 中取得欄位 (節點)。 + `frame` – 要在其中選擇欄位的 `DynamicFrame` (必要)。 + `paths` – 所要選擇的欄位的完整路徑清單 (必要)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 傳回僅包含指定欄位的新 `DynamicFrame`。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # SelectFromCollection 類別 在 `DynamicFrameCollection` 中選擇一個 `DynamicFrame`。 ## 範例 此範例使用 `SelectFromCollection` 從 `DynamicFrameCollection` 中選取 `DynamicFrame`。 **範例資料集** 該範例從稱為 `split_rows_collection` 的 `DynamicFrameCollection` 中選取兩個 `DynamicFrames`。以下是 `split_rows_collection` 中的索引鍵清單。 ``` dict_keys(['high', 'low']) ``` **範例程式碼** ``` # Example: Use SelectFromCollection to select # DynamicFrames from a DynamicFrameCollection from pyspark.context import SparkContext from awsglue.context import GlueContext from awsglue.transforms import SelectFromCollection # Create GlueContext sc = SparkContext.getOrCreate() glueContext = GlueContext(sc) # Select frames and inspect entries frame_low = SelectFromCollection.apply(dfc=split_rows_collection, key="low") frame_low.toDF().show() frame_high = SelectFromCollection.apply(dfc=split_rows_collection, key="high") frame_high.toDF().show() ``` ### Output ``` +---+-----+------------------------+-------------------------+ | id|index|contact_details.val.type|contact_details.val.value| +---+-----+------------------------+-------------------------+ | 1| 0| fax| 202-225-3307| | 1| 1| phone| 202-225-5731| | 2| 0| fax| 202-225-3307| | 2| 1| phone| 202-225-5731| | 3| 0| fax| 202-225-3307| | 3| 1| phone| 202-225-5731| | 4| 0| fax| 202-225-3307| | 4| 1| phone| 202-225-5731| | 5| 0| fax| 202-225-3307| | 5| 1| phone| 202-225-5731| | 6| 0| fax| 202-225-3307| | 6| 1| phone| 202-225-5731| | 7| 0| fax| 202-225-3307| | 7| 1| phone| 202-225-5731| | 8| 0| fax| 202-225-3307| | 8| 1| phone| 202-225-5731| | 9| 0| fax| 202-225-3307| | 9| 1| phone| 202-225-5731| | 10| 0| fax| 202-225-6328| | 10| 1| phone| 202-225-4576| +---+-----+------------------------+-------------------------+ only showing top 20 rows +---+-----+------------------------+-------------------------+ | id|index|contact_details.val.type|contact_details.val.value| +---+-----+------------------------+-------------------------+ | 11| 0| fax| 202-225-6328| | 11| 1| phone| 202-225-4576| | 11| 2| twitter| RepTrentFranks| | 12| 0| fax| 202-225-6328| | 12| 1| phone| 202-225-4576| | 12| 2| twitter| RepTrentFranks| | 13| 0| fax| 202-225-6328| | 13| 1| phone| 202-225-4576| | 13| 2| twitter| RepTrentFranks| | 14| 0| fax| 202-225-6328| | 14| 1| phone| 202-225-4576| | 14| 2| twitter| RepTrentFranks| | 15| 0| fax| 202-225-6328| | 15| 1| phone| 202-225-4576| | 15| 2| twitter| RepTrentFranks| | 16| 0| fax| 202-225-6328| | 16| 1| phone| 202-225-4576| | 16| 2| twitter| RepTrentFranks| | 17| 0| fax| 202-225-6328| | 17| 1| phone| 202-225-4576| +---+-----+------------------------+-------------------------+ only showing top 20 rows ``` ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-SelectFromCollection-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-SelectFromCollection-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-SelectFromCollection-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-SelectFromCollection-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-SelectFromCollection-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-SelectFromCollection-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-SelectFromCollection-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-SelectFromCollection-describe) ## \$1\$1call\$1\$1(dfc, key, transformation\$1ctx = "") 從 `DynamicFrameCollection` 取得一個 `DynamicFrame`。 + `dfc` – 應該從其中選取 `DynamicFrame` 的 `DynamicFrameCollection` (必要)。 + `key` – 所要選擇的 `DynamicFrame` 金鑰 (必要)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # Simplify\$1ddb\$1json 類別 簡化專屬於 DynamoDB JSON 結構中 `DynamicFrame` 內的巢狀資料欄，並傳回新的簡化 `DynamicFrame`。 ## 範例 我們建議您使用 `DynamicFrame.simplify_ddb_json()` 方法來簡化專屬於 DynamoDB JSON 結構的 `DynamicFrame` 中和巢狀資料欄。若要檢視程式碼範例，請參閱 [範例：使用 simplify\$1ddb\$1json 來調用 DynamoDB JSON 簡化](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-simplify-ddb-json-example)。 # Spigot 類別 將範例記錄寫入指定的目的地，以協助您驗證 AWS Glue 任務執行的轉換。 ## 範例 建議您使用 [`DynamicFrame.spigot()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-spigot) 方法，將記錄子集從 `DynamicFrame` 寫入指定目的地。若要檢視程式碼範例，請參閱 [範例：使用 spigot 將範例欄位從 `DynamicFrame` 寫入到 Amazon S3](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-spigot-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-spigot-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-spigot-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-spigot-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-spigot-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-spigot-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-spigot-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-spigot-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-spigot-describe) ## \$1\$1call\$1\$1(frame, path, options, transformation\$1ctx = "") 在轉換期間將範例記錄寫入到指定的目的地。 + `frame` – 欲 Spigot 的 `DynamicFrame` (必要)。 + `path` - 要寫入的目的地路徑 (必要)。 + `options` - 指定選項的 JSON 索引鍵/值對 (選用)。`"topk"` 選項指定應寫入前 *k* 個記錄。`"prob"` 選項指定挑選任何給定記錄的概率 (小數)。您可以使用它來選擇要寫入的記錄。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply) ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name) ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs) ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn) ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform) ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors) ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe) # SplitFields 類別 以指定欄位將 `DynamicFrame` 分割為二。 ## 範例 建議您使用 [`DynamicFrame.split_fields()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-split_fields) 方法分割 `DynamicFrame` 中的欄位。若要檢視程式碼範例，請參閱 [範例：使用 split\$1fields 將選取的欄位分割為單獨的 `DynamicFrame`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-split_fields-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-SplitFields-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-SplitFields-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-SplitFields-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-SplitFields-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-SplitFields-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-SplitFields-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-SplitFields-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-SplitFields-describe) ## \$1\$1call\$1\$1(frame, paths, name1 = none, name2 = none, transformation\$1ctx = "", info = "", stageThreshold = 0, totalThreshold = 0) 將 `DynamicFrame` 中一個或多個欄位分割成新的 `DynamicFrame`，並且建立另一個包含剩餘欄位的新 `DynamicFrame`。 + `frame` – 要分割為二的來源 `DynamicFrame` (必要)。 + `paths` – 欲分割欄位的完整路徑清單 (必要)。 + `name1` 指派給 `DynamicFrame` 的名稱，其中包含要分割的欄位 (選用)。如果未提供名稱，則會使用來源架構的名稱並加上「1」。 + `name2` – 指派給 `DynamicFrame` 的名稱，其中包含指定欄位分割後剩餘的欄位 (選用)。如果未提供名稱，則會使用來源架構的名稱並加上「2」。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # SplitRows 類別 建立 `DynamicFrameCollection`，其包含兩個 `DynamicFrames`。一個 `DynamicFrame` 僅包含要分割的指定資料列，另一個則包含所有剩餘的資料列。 ## 範例 建議您使用 [`DynamicFrame.split_rows()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-split_rows) 方法分割 `DynamicFrame` 中的資料列。若要檢視程式碼範例，請參閱 [範例：使用 split\$1rows 來分割 `DynamicFrame` 中的列](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-split_rows-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-SplitRows-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-SplitRows-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-SplitRows-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-SplitRows-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-SplitRows-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-SplitRows-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-SplitRows-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-SplitRows-describe) ## \$1\$1call\$1\$1(frame, comparison\$1dict, name1="frame1", name2="frame2", transformation\$1ctx = "", info = none, stageThreshold = 0, totalThreshold = 0) 將 `DynamicFrame` 中一個或多個欄分割成新的 `DynamicFrame`。 + `frame` – 要分割為二的來源 `DynamicFrame` (必要)。 + `comparison_dict` – 一個字典，其中索引鍵為欄位的完整路徑，而對於與欄位數值相比較的數值而言，此數值為另一種字典映射比較運算子。例如，`{"age": {">": 10, "<": 20}}` 會特別將介於 10 到 20 之間的 "age" (年齡) 數值與該範圍外的 "age" 列分割開來 (必要)。 + `name1` – 指派給 `DynamicFrame` 的名稱，其中包含要分割的資料列 (選用)。 + `name2` – 指派給 `DynamicFrame` 的名稱，其中包含指定資料列分割後剩餘的資料列 (選用)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # Unbox 類別 將 `DynamicFrame` 中的字串欄位拆箱 (重新格式化)。 ## 範例 建議您使用 [`DynamicFrame.unbox()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-unbox) 方法，對 `DynamicFrame` 中的欄位進行拆箱。若要檢視程式碼範例，請參閱 [範例：使用 unbox 將字串欄位拆箱到結構中](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-unbox-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-Unbox-__call__) + [applyapply](#aws-glue-api-crawler-pyspark-transforms-Unbox-apply) + [namename](#aws-glue-api-crawler-pyspark-transforms-Unbox-name) + [describeArgsdescribeArgs](#aws-glue-api-crawler-pyspark-transforms-Unbox-describeArgs) + [describeReturndescribeReturn](#aws-glue-api-crawler-pyspark-transforms-Unbox-describeReturn) + [describeTransformdescribeTransform](#aws-glue-api-crawler-pyspark-transforms-Unbox-describeTransform) + [describeErrorsdescribeErrors](#aws-glue-api-crawler-pyspark-transforms-Unbox-describeErrors) + [describedescribe](#aws-glue-api-crawler-pyspark-transforms-Unbox-describe) ## \$1\$1call\$1\$1(frame, path, format, transformation\$1ctx = "", info="", stageThreshold=0, totalThreshold=0, \$1\$1options) 將 `DynamicFrame` 中的字串欄位拆箱。 + `frame` - 具有要拆箱之欄位的 `DynamicFrame` (必要)。 + `path` – 欲拆箱的 `StringNode` 之完整路徑 (必要)。 + `format` – 格式化規格 (選用)。這是用於 Amazon S3 或支援多種格式的 AWS Glue 連線。如需了解受支援的格式，請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 + `separator` – 分隔符號符記 (選用)。 + `escaper` – 逸出符記 (選用)。 + `skipFirst` – 如果資料的第一行應略過則為 `True`，如果不應略過則為 `False` (選用)。 + withSchema`` – 這是一個字串，包含了要拆箱之資料的結構描述 (選用)。此字串應一律使用 `StructType.json` 來建立。 + `withHeader` – 如果被解壓縮的資料包含標頭則為 `True`，若無則為 `False` (選用)。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # UnnestFrame 類別 對 `DynamicFrame` 解除巢狀化，將巢狀化物件壓平合併為頂層元素，並且為陣列物件產生聯結鍵。 ## 範例 我們建議您使用 [`DynamicFrame.unnest()`](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#aws-glue-api-crawler-pyspark-extensions-dynamic-frame-unnest) 方法在 `DynamicFrame` 中壓平合併巢狀化結構。若要檢視程式碼範例，請參閱 [範例：使用 unnest 將巢狀化欄位轉換為頂層欄位](aws-glue-api-crawler-pyspark-extensions-dynamic-frame.md#pyspark-unnest-example)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-crawler-pyspark-transforms-UnnestFrame-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-UnnestFrame-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-UnnestFrame-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-UnnestFrame-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-UnnestFrame-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-UnnestFrame-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-UnnestFrame-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-UnnestFrame-describe) ## \$1\$1call\$1\$1(frame, transformation\$1ctx = "", info="", stageThreshold=0, totalThreshold=0) 對 `DynamicFrame` 解除巢狀化，將巢狀化物件壓平合併為頂層元素，並且為陣列物件產生聯結鍵。 + `frame` – 欲解巢狀的 `DynamicFrame` (必要)。 + `transformation_ctx` – 用於識別狀態資訊的唯一字串 (選用)。 + `info` – 與轉換中的錯誤相關的字串 (選用)。 + `stageThreshold` – 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用)。預設為零。 + `totalThreshold` – 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用)。預設為零。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # FlagDuplicatesInColumn 類別 `FlagDuplicatesInColumn` 會傳回一個新資料欄，每個資料列都有一個指定值，指示該資料列的來源資料欄中的值是否與來源資料欄的較早的資料列中的值相符。找到相符項目時，其會標記為重複項目。初始出現不會標記，因為其不符合較早的資料列。 ## 範例 ``` from pyspark.context import SparkContext from pyspark.sql import SparkSession from awsgluedi.transforms import * sc = SparkContext() spark = SparkSession(sc) datasource1 = spark.read.json("s3://${BUCKET}/json/zips/raw/data") try: df_output = column.FlagDuplicatesInColumn.apply( data_frame=datasource1, spark_context=sc, source_column="city", target_column="flag_col", true_string="True", false_string="False" ) except: print("Unexpected Error happened ") raise ``` ## Output `FlagDuplicatesInColumn` 轉換會將新的資料欄 `flag\$1col` 新增至 `df\$1output` DataFrame。此資料欄將包含字串值，指示對應的資料列在 `city` 資料欄中是否有重複的值。如果資料列具有重複的 `city` 值，`flag\$1col` 將包含 `true\$1string` 值 "True"。如果資料列具有唯一的 `city` 值，`flag\$1col` 將包含 `false\$1string` 值 "False"。 產生的 `df\$1output` DataFrame 將包含來自原始 `datasource1` DataFrame 的所有資料欄，加上指出重複 `city` 值的額外 `flag\$1col` 資料欄。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-FlagDuplicatesInColumn-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicatesInColumn-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicatesInColumn-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicatesInColumn-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicatesInColumn-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicatesInColumn-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicatesInColumn-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicatesInColumn-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, source\$1column, target\$1column, true\$1string=DEFAULT\$1TRUE\$1STRING, false\$1string=DEFAULT\$1FALSE\$1STRING) `FlagDuplicatesInColumn` 會傳回一個新資料欄，每個資料列都有一個指定值，指示該資料列的來源資料欄中的值是否與來源資料欄的較早的資料列中的值相符。找到相符項目時，其會標記為重複項目。初始出現不會標記，因為其不符合較早的資料列。 + `source_column` – 來源資料欄的名稱。 + `target_column` – 目標資料欄的名稱。 + `true_string` – 在來源資料欄值與該資料欄中的較早值重複時，要插入目標資料欄中的字串。 + `false_string` – 在來源資料欄值與該資料欄中的較早值不同時，要插入目標資料欄中的字串。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # FormatPhoneNumber 類別 `FormatPhoneNumber` 轉換會傳回一個資料欄，其中電話號碼字串會轉換為格式化值。 ## 範例 ``` from pyspark.context import SparkContext from pyspark.sql import SparkSession from awsgluedi.transforms import * sc = SparkContext() spark = SparkSession(sc) input_df = spark.createDataFrame( [ ("408-341-5669",), ("4083415669",) ], ["phone"], ) try: df_output = column_formatting.FormatPhoneNumber.apply( data_frame=input_df, spark_context=sc, source_column="phone", default_region="US" ) df_output.show() except: print("Unexpected Error happened ") raise ``` ## Output 輸出將是： ``` ``` +---------------+ | phone| +---------------+ |(408) 341-5669| |(408) 341-5669| +---------------+ ``` ``` `FormatPhoneNumber` 轉換會將 `source\$1column` 作為 `"phone"`，並將 `default\$1region` 作為 `"US"`。 無論電話號碼的初始格式為何，轉換都會成功將這兩個電話號碼格式化為標準美國格式 `(408) 341-5669`。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-FormatPhoneNumber-__call__) + [applyapply](#aws-glue-api-crawler-pyspark-transforms-FormatPhoneNumber-apply) + [namename](#aws-glue-api-crawler-pyspark-transforms-FormatPhoneNumber-name) + [describeArgsdescribeArgs](#aws-glue-api-crawler-pyspark-transforms-FormatPhoneNumber-describeArgs) + [describeReturndescribeReturn](#aws-glue-api-crawler-pyspark-transforms-FormatPhoneNumber-describeReturn) + [describeTransformdescribeTransform](#aws-glue-api-crawler-pyspark-transforms-FormatPhoneNumber-describeTransform) + [describeErrorsdescribeErrors](#aws-glue-api-crawler-pyspark-transforms-FormatPhoneNumber-describeErrors) + [describedescribe](#aws-glue-api-crawler-pyspark-transforms-FormatPhoneNumber-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, source\$1column, phone\$1number\$1format=None, default\$1region=None, default\$1region\$1column=None) `FormatPhoneNumber` 轉換會傳回一個資料欄，其中電話號碼字串會轉換為格式化值。 + `source_column` – 現有資料欄的名稱。 + `phone_number_format` – 將電話號碼轉換為的格式。如果未指定格式，預設值為 `E.164`，這是國際認可的標準電話號碼格式。有效值包括下列項目： + E164 (省略 E 後的句點) + `default_region` – 由兩個或三個大寫字母組成的有效區域代碼，當號碼本身沒有國家/地區代碼時，用於指定電話號碼所在的區域。最多可以提供 `defaultRegion` 或 `defaultRegionColumn` 之一。 + `default_region_column` – 進階資料類型 `Country` 的資料欄名稱。當號碼本身沒有國家/地區代碼時，所指定資料欄中的區域代碼用於確定電話號碼的國家/地區代碼。最多可以提供 `defaultRegion` 或 `defaultRegionColumn` 之一。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # FormatCase 類別 `FormatCase` 轉換會將資料欄中的每個字串變更為指定的案例類型。 ## 範例 ``` from pyspark.context import SparkContext from pyspark.sql import SparkSession from awsgluedi.transforms import * sc = SparkContext() spark = SparkSession(sc) datasource1 = spark.read.json("s3://${BUCKET}/json/zips/raw/data") try: df_output = data_cleaning.FormatCase.apply( data_frame=datasource1, spark_context=sc, source_column="city", case_type="LOWER" ) except: print("Unexpected Error happened ") raise ``` ## Output `FormatCase` 轉換會根據 `case\$1type="LOWER"` 參數，將 `city` 資料欄中的值轉換為小寫。產生的 `df\$1output` DataFrame 將包含原始 `datasource1` DataFrame 中的所有資料欄，但 `city` 資料欄值為小寫。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-FormatCase-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-FormatCase-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-FormatCase-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-FormatCase-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-FormatCase-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-FormatCase-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-FormatCase-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-FormatCase-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, source\$1column, case\$1type) `FormatCase` 轉換會將資料欄中的每個字串變更為指定的案例類型。 + `source_column` – 現有資料欄的名稱。 + `case_type` – 支援的案例類型為 `CAPITAL`、`LOWER`、`UPPER`、`SENTENCE`。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # FillWithMode 類別 `FillWithMode` 轉換會根據您指定的電話號碼格式，來格式化資料欄。您也可以指定和局中斷器邏輯，其中一些值是相同的。例如，請考慮下列值：`1 2 2 3 3 4` modeType `MINIMUM` 導致 `FillWithMode` 傳回 2 作為模式值。如果 modeType 為 `MAXIMUM`，則模式為 3。對於 `AVERAGE`，模式為 2.5。 ## 範例 ``` from awsglue.context import * from pyspark.sql import SparkSession from awsgluedi.transforms import * sc = SparkContext() spark = SparkSession(sc) input_df = spark.createDataFrame( [ (105.111, 13.12), (1055.123, 13.12), (None, 13.12), (13.12, 13.12), (None, 13.12), ], ["source_column_1", "source_column_2"], ) try: df_output = data_quality.FillWithMode.apply( data_frame=input_df, spark_context=sc, source_column="source_column_1", mode_type="MAXIMUM" ) df_output.show() except: print("Unexpected Error happened ") raise ``` ## Output 指定的程式碼的輸出將是： ``` ``` +---------------+---------------+ |source_column_1|source_column_2| +---------------+---------------+ | 105.111| 13.12| | 1055.123| 13.12| | 1055.123| 13.12| | 13.12| 13.12| | 1055.123| 13.12| +---------------+---------------+ ``` ``` 從 `awsglue.data\$1quality` 模組的 `FillWithMode` 轉換會套用至 `input\$1df` DataFrame。其會將 `source_column_1` 資料欄中的 `null` 值取代為該資料欄中非 Null 值的最大值 (`mode\$1type="MAXIMUM"`)。 在此情況下，`source_column_1` 資料欄中的最大值為 `1055.123`。因此，`source_column_1` 中的 `null` 值會由輸出 DataFrame `df\$1output` 中的 `1055.123` 取代。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-FillWithMode-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-FillWithMode-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-FillWithMode-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-FillWithMode-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-FillWithMode-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-FillWithMode-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-FillWithMode-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-FillWithMode-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, source\$1column, mode\$1type) `FillWithMode` 轉換會格式化資料欄中的字串大小寫。 + `source_column` – 現有資料欄的名稱。 + `mode_type` – 如何解析資料中的和局值。此值必須是 `MINIMUM`、`NONE`、`AVERAGE` 或 `MAXIMUM` 之一。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # FlagDuplicateRows 類別 `FlagDuplicateRows` 會傳回一個新資料欄，其中每個資料列都有一個指定的值，指示該資料列是否與資料集中較早的資料列完全相符。找到相符項目時，其會標記為重複項目。初始出現不會標記，因為其不符合較早的資料列。 ## 範例 ``` from pyspark.context import SparkContext from pyspark.sql import SparkSession from awsgluedi.transforms import * sc = SparkContext() spark = SparkSession(sc) input_df = spark.createDataFrame( [ (105.111, 13.12), (13.12, 13.12), (None, 13.12), (13.12, 13.12), (None, 13.12), ], ["source_column_1", "source_column_2"], ) try: df_output = data_quality.FlagDuplicateRows.apply( data_frame=input_df, spark_context=sc, target_column="flag_row", true_string="True", false_string="False", target_index=1 ) except: print("Unexpected Error happened ") raise ``` ## Output 輸出將是具有額外資料欄 `flag_row` 的 PySpark DataFrame，根據 `source_column_1` 資料欄指出資料列是否重複。產生的 `df\$1output` DataFrame 將包含下列資料列： ``` ``` +---------------+---------------+--------+ |source_column_1|source_column_2|flag_row| +---------------+---------------+--------+ | 105.111| 13.12| False| | 13.12| 13.12| True| | null| 13.12| True| | 13.12| 13.12| True| | null| 13.12| True| +---------------+---------------+--------+ ``` ``` `flag_row` 資料欄指出資料列是否重複。`true\$1string` 設定為 "True"，而 `false\$1string` 設定為 "False"。`target\$1index` 設定為 1，這表示 `flag_row` 資料欄將插入輸出 DataFrame 中的第二個位置 (索引 1)。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-FlagDuplicateRows-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicateRows-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicateRows-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicateRows-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicateRows-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicateRows-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicateRows-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-FlagDuplicateRows-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, target\$1column, true\$1string=DEFAULT\$1TRUE\$1STRING, false\$1string=DEFAULT\$1FALSE\$1STRING, target\$1index=None) `FlagDuplicateRows` 會傳回一個新資料欄，其中每個資料列都有一個指定的值，指示該資料列是否與資料集中較早的資料列完全相符。找到相符項目時，其會標記為重複項目。初始出現不會標記，因為其不符合較早的資料列。 + `true_string` – 在資料列符合較早的資料列時要插入的值。 + `false_string` – 在資料列是唯一時要插入的值。 + `target_column` – 插入資料集的新資料欄名稱。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # RemoveDuplicates 類別 如果在選取的來源資料欄中遇到重複值，`RemoveDuplicates` 轉換會刪除整個資料列。 ## 範例 ``` from pyspark.context import SparkContext from pyspark.sql import SparkSession from awsgluedi.transforms import * sc = SparkContext() spark = SparkSession(sc) input_df = spark.createDataFrame( [ (105.111, 13.12), (13.12, 13.12), (None, 13.12), (13.12, 13.12), (None, 13.12), ], ["source_column_1", "source_column_2"], ) try: df_output = data_quality.RemoveDuplicates.apply( data_frame=input_df, spark_context=sc, source_column="source_column_1" ) except: print("Unexpected Error happened ") raise ``` ## Output 輸出將是 PySpark DataFrame，並根據 `source_column_1` 資料欄移除重複項目。產生的 `df\$1output` DataFrame 將包含下列資料列： ``` ``` +---------------+---------------+ |source_column_1|source_column_2| +---------------+---------------+ | 105.111| 13.12| | 13.12| 13.12| | null| 13.12| +---------------+---------------+ ``` ``` 請注意，`source_column_1` 值為 `13.12` 和 `null` 的資料列只會在輸出 DataFrame 中出現一次，因為已根據 `source_column_1` 資料欄移除重複項目。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-RemoveDuplicates-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-RemoveDuplicates-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-RemoveDuplicates-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-RemoveDuplicates-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-RemoveDuplicates-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-RemoveDuplicates-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-RemoveDuplicates-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-RemoveDuplicates-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, source\$1column) 如果在選取的來源資料欄中遇到重複值，`RemoveDuplicates` 轉換會刪除整個資料列。 + `source_column` – 現有資料欄的名稱。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # MonthName 類別 `MonthName` 轉換會從代表日期的字串建立新的資料欄，其中包含月份名稱。 ## 範例 ``` from pyspark.context import SparkContext from pyspark.sql import SparkSession from awsgluedi.transforms import * sc = SparkContext() spark = SparkSession(sc) spark.conf.set("spark.sql.legacy.timeParserPolicy", "LEGACY") input_df = spark.createDataFrame( [ ("20-2018-12",), ("2018-20-12",), ("20182012",), ("12202018",), ("20122018",), ("20-12-2018",), ("12/20/2018",), ("02/02/02",), ("02 02 2009",), ("02/02/2009",), ("August/02/2009",), ("02/june/2009",), ("02/2020/june",), ("2013-02-21 06:35:45.658505",), ("August 02 2009",), ("2013/02/21",), (None,), ], ["column_1"], ) try: df_output = datetime_functions.MonthName.apply( data_frame=input_df, spark_context=sc, source_column="column_1", target_column="target_column" ) df_output.show() except: print("Unexpected Error happened ") raise ``` ## Output 輸出將是： ``` ``` +------------+------------+ | column_1|target_column| +------------+------------+ |20-2018-12 | December | |2018-20-12 | null | | 20182012| null | | 12202018| null | | 20122018| null | |20-12-2018 | December | |12/20/2018 | December | | 02/02/02 | February | |02 02 2009 | February | |02/02/2009 | February | |August/02/2009| August | |02/june/2009| null | |02/2020/june| null | |2013-02-21 06:35:45.658505| February | |August 02 2009| August | | 2013/02/21| February | | null | null | +------------+------------+ ``` ``` `MonthName` 轉換會將 `source\$1column` 作為 `"column\$11"`，並將 `target\$1column` 作為 `"target\$1column"`。其會嘗試從 `"column\$11"` 資料欄中的日期/時間字串中擷取月份名稱，並將其放在 `"target\$1column"` 資料欄中。如果日期/時間字串的格式無法辨識或無法剖析，則 `"target\$1column"` 值會設定為 `null`。 轉換會從各種日期/時間格式成功擷取月份名稱，例如 "20-12-2018"、"12/20/2018"、"02/02/2009"、"2013-02-21 06:35:45.658505" 和 "August 02 2009"。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-MonthName-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-MonthName-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-MonthName-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-MonthName-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-MonthName-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-MonthName-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-MonthName-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-MonthName-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, target\$1column, source\$1column=None, value=None) `MonthName` 轉換會從代表日期的字串建立新的資料欄，其中包含月份名稱。 + `source_column` – 現有資料欄的名稱。 + `value` – 要評估的字元字串。 + `target_column` – 新建立資料欄的名稱。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # IsEven 類別 `IsEven` 轉換會在新資料欄中傳回布林值，指示來源資料欄或值是否為偶數。如果來源資料欄或值為小數，則結果為 false。 ## 範例 ``` from pyspark.context import SparkContext from pyspark.sql import SparkSession from awsgluedi.transforms import * sc = SparkContext() spark = SparkSession(sc) input_df = spark.createDataFrame( [(5,), (0,), (-1,), (2,), (None,)], ["source_column"], ) try: df_output = math_functions.IsEven.apply( data_frame=input_df, spark_context=sc, source_column="source_column", target_column="target_column", value=None, true_string="Even", false_string="Not even", ) df_output.show() except: print("Unexpected Error happened ") raise ``` ## Output 輸出將是： ``` ``` +------------+------------+ |source_column|target_column| +------------+------------+ | 5| Not even| | 0| Even| | -1| Not even| | 2| Even| | null| null| +------------+------------+ ``` ``` `IsEven` 轉換會將 `source\$1column` 作為 "source\$1column"，並將 `target\$1column` 作為 "target\$1column"。其會檢查 `"source\$1column"` 中的值是否為偶數。如果值為偶數，則會將 `"target\$1column"` 值設定為 `true\$1string` "Even"。如果值為奇數，則會將 `"target\$1column"` 值設定為 `false\$1string` "Not even"。如果 `"source\$1column"` 值為 `null`，`"target\$1column"` 值會設定為 `null`。 轉換會正確識別偶數 (0 和 2)，並將 `"target\$1column"` 值設定為 "Even"。對於奇數 (5 和 -1)，其會將 `"target\$1column"` 值設定為 "Not even"。對於 `"source\$1column"` 中的 `null` 值，`"target\$1column"` 值設定為 `null`。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-IsEven-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-IsEven-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-IsEven-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-IsEven-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-IsEven-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-IsEven-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-IsEven-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-IsEven-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, target\$1column, source\$1column=None, true\$1string=DEFAULT\$1TRUE\$1STRING, false\$1string=DEFAULT\$1FALSE\$1STRING, value=None) `IsEven` 轉換會在新資料欄中傳回布林值，指示來源資料欄或值是否為偶數。如果來源資料欄或值為小數，則結果為 false。 + `source_column` – 現有資料欄的名稱。 + `target_column` – 要建立的新資料欄的名稱。 + `true_string` – 指示值是否為偶數的字串。 + `false_string` – 指示值是否為非偶數的字串。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # CryptographicHash 類別 `CryptographicHash` 轉換會將演算法套用至資料欄中的雜湊值。 ## 範例 ``` from pyspark.context import SparkContext from pyspark.sql import SparkSession from awsgluedi.transforms import * secret = "${SECRET}" sc = SparkContext() spark = SparkSession(sc) input_df = spark.createDataFrame( [ (1, "1234560000"), (2, "1234560001"), (3, "1234560002"), (4, "1234560003"), (5, "1234560004"), (6, "1234560005"), (7, "1234560006"), (8, "1234560007"), (9, "1234560008"), (10, "1234560009"), ], ["id", "phone"], ) try: df_output = pii.CryptographicHash.apply( data_frame=input_df, spark_context=sc, source_columns=["id", "phone"], secret_id=secret, algorithm="HMAC_SHA256", output_format="BASE64", ) df_output.show() except: print("Unexpected Error happened ") raise ``` ## Output 輸出將是： ``` ``` +---+------------+-------------------+-------------------+ | id| phone | id_hashed | phone_hashed | +---+------------+-------------------+-------------------+ | 1| 1234560000 | QUI1zXTJiXmfIb... | juDBAmiRnnO3g... | | 2| 1234560001 | ZAUWiZ3dVTzCo... | vC8lgUqBVDMNQ... | | 3| 1234560002 | ZP4VvZWkqYifu... | Kl3QAkgswYpzB... | | 4| 1234560003 | 3u8vO3wQ8EQfj... | CPBzK1P8PZZkV... | | 5| 1234560004 | eWkQJk4zAOIzx... | aLf7+mHcXqbLs... | | 6| 1234560005 | xtI9fZCJZCvsa... | dy2DFgdYWmr0p... | | 7| 1234560006 | iW9hew7jnHuOf... | wwfGMCOEv6oOv... | | 8| 1234560007 | H9V1pqvgkFhfS... | g9WKhagIXy9ht... | | 9| 1234560008 | xDhEuHaxAUbU5... | b3uQLKPY+Q5vU... | | 10| 1234560009 | GRN6nFXkxk349... | VJdsKt8VbxBbt... | +---+------------+-------------------+-------------------+ ``` ``` 轉換會使用指定的演算法和機密金鑰運算 `id` 和 `phone` 資料欄中值的密碼編譯雜湊，並以 Base64 格式編碼雜湊。產生的 `df\$1output` DataFrame 包含來自原始 `input\$1df` DataFrame 的所有資料欄，以及具有計算雜湊的額外 `id\$1hashed` 和 `phone\$1hashed` 資料欄。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-CryptographicHash-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-CryptographicHash-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-CryptographicHash-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-CryptographicHash-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-CryptographicHash-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-CryptographicHash-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-CryptographicHash-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-CryptographicHash-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, source\$1columns, secret\$1id, algorithm=None, secret\$1version=None, create\$1secret\$1if\$1missing=False, output\$1format=None, entity\$1type\$1filter=None) `CryptographicHash` 轉換會將演算法套用至資料欄中的雜湊值。 + `source_columns` – 現有資料欄的陣列。 + `secret_id` – Secrets Manager 機密金鑰的 ARN。雜湊訊息驗證碼 (HMAC) 字首演算法中使用的金鑰，用於雜湊來源資料欄。 + `secret_version` - 選用。預設為最新機密版本。 + `entity_type_filter` – 實體類型的選用陣列。可用於僅加密任意文字資料欄中偵測到的 PII。 + `create_secret_if_missing` – 選用布林值。如果為 true，將嘗試代表發起人建立機密。 + `algorithm` – 用於雜湊資料的演算法。有效列舉值：MD5、SHA1、SHA256、SHA512、HMAC\$1MD5、HMAC\$1SHA1、HMAC\$1SHA256、HMAC\$1SHA512。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # 解密類別 `Decrypt` 轉換會在 Glue AWS 內部解密。您的資料也可以使用 AWS Encryption SDK 在 AWS Glue 外部解密。如果提供的 KMS 金鑰 ARN 不符合用於加密資料欄的內容，解密操作會失敗。 ## 範例 ``` from pyspark.context import SparkContext from pyspark.sql import SparkSession from awsgluedi.transforms import * kms = "${KMS}" sc = SparkContext() spark = SparkSession(sc) input_df = spark.createDataFrame( [ (1, "1234560000"), (2, "1234560001"), (3, "1234560002"), (4, "1234560003"), (5, "1234560004"), (6, "1234560005"), (7, "1234560006"), (8, "1234560007"), (9, "1234560008"), (10, "1234560009"), ], ["id", "phone"], ) try: df_encrypt = pii.Encrypt.apply( data_frame=input_df, spark_context=sc, source_columns=["phone"], kms_key_arn=kms ) df_decrypt = pii.Decrypt.apply( data_frame=df_encrypt, spark_context=sc, source_columns=["phone"], kms_key_arn=kms ) df_decrypt.show() except: print("Unexpected Error happened ") raise ``` ## Output 輸出將是具有原始 `id` 資料欄和解密 `phone` 資料欄的 PySpark DataFrame： ``` ``` +---+------------+ | id| phone| +---+------------+ | 1| 1234560000| | 2| 1234560001| | 3| 1234560002| | 4| 1234560003| | 5| 1234560004| | 6| 1234560005| | 7| 1234560006| | 8| 1234560007| | 9| 1234560008| | 10| 1234560009| +---+------------+ ``` ``` `Encrypt` 轉換會將 `source\$1columns` 作為 `["phone"]` 及將 `kms\$1key\$1arn` 作為 `\$1\$1KMS\$1` 環境變數的值。轉換會使用指定的 KMS 金鑰加密 `phone` 資料欄中的值。然後，加密的 DataFrame `df\$1encrypt` 會從 `awsglue.pii` 模組傳遞至 `Decrypt` 轉換。其會將 `source\$1columns` 作為 `["phone"]` 及將 `kms\$1key\$1arn` 作為 `\$1\$1KMS\$1` 環境變數的值。轉換會使用相同的 KMS 金鑰加密 `phone` 資料欄中的加密值。產生的 `df\$1decrypt` DataFrame 包含原始 `id` 資料欄和解密的 `phone` 資料欄。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-Decrypt-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-Decrypt-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-Decrypt-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-Decrypt-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-Decrypt-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-Decrypt-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-Decrypt-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-Decrypt-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, source\$1columns, kms\$1key\$1arn) `Decrypt` 轉換會在 Glue AWS 內部解密。您的資料也可以使用 AWS Encryption SDK 在 AWS Glue 外部解密。如果提供的 KMS 金鑰 ARN 不符合用於加密資料欄的內容，解密操作會失敗。 + `source_columns` – 現有資料欄的陣列。 + `kms_key_arn` – Key AWS Management Service 金鑰的金鑰 ARN，用於解密來源資料欄。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # 加密類別 `Encrypt` 轉換會使用 AWS Key Management Service 金鑰加密來源資料欄。`Encrypt` 轉換每個儲存格最多可加密 128 MiB。其會嘗試在解密時保留格式。若要保留資料類型，資料類型中繼資料必須序列化為小於 1KB。否則，您必須將 `preserve_data_type` 參數設定為 false。資料類型中繼資料將在加密內容中以純文字儲存。 ## 範例 ``` from pyspark.context import SparkContext from pyspark.sql import SparkSession from awsgluedi.transforms import * kms = "${KMS}" sc = SparkContext() spark = SparkSession(sc) input_df = spark.createDataFrame( [ (1, "1234560000"), (2, "1234560001"), (3, "1234560002"), (4, "1234560003"), (5, "1234560004"), (6, "1234560005"), (7, "1234560006"), (8, "1234560007"), (9, "1234560008"), (10, "1234560009"), ], ["id", "phone"], ) try: df_encrypt = pii.Encrypt.apply( data_frame=input_df, spark_context=sc, source_columns=["phone"], kms_key_arn=kms ) except: print("Unexpected Error happened ") raise ``` ## Output 輸出將是具有原始 `id` 資料欄的 PySpark DataFrame，及包含 `phone` 資料欄加密值的額外資料欄。 ``` ``` +---+------------+-------------------------+ | id| phone | phone_encrypted | +---+------------+-------------------------+ | 1| 1234560000| EncryptedData1234...abc | | 2| 1234560001| EncryptedData5678...def | | 3| 1234560002| EncryptedData9012...ghi | | 4| 1234560003| EncryptedData3456...jkl | | 5| 1234560004| EncryptedData7890...mno | | 6| 1234560005| EncryptedData1234...pqr | | 7| 1234560006| EncryptedData5678...stu | | 8| 1234560007| EncryptedData9012...vwx | | 9| 1234560008| EncryptedData3456...yz0 | | 10| 1234560009| EncryptedData7890...123 | +---+------------+-------------------------+ ``` ``` `Encrypt` 轉換會將 `source\$1columns` 作為 `["phone"]` 及將 `kms\$1key\$1arn` 作為 `\$1\$1KMS\$1` 環境變數的值。轉換會使用指定的 KMS 金鑰加密 `phone` 資料欄中的值。產生的 `df\$1encrypt` DataFrame 包含原始 `id` 資料欄、原始 `phone` 資料欄，及名為 `phone\$1encrypted` 的額外資料欄，其中包含 `phone` 資料欄的加密值。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-Encrypt-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-Encrypt-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-Encrypt-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-Encrypt-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-Encrypt-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-Encrypt-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-Encrypt-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-Encrypt-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, source\$1columns, kms\$1key\$1arn, entity\$1type\$1filter=None, preserve\$1data\$1type=None) `Encrypt` 轉換會使用 AWS Key Management Service 金鑰加密來源資料欄。 + `source_columns` – 現有資料欄的陣列。 + `kms_key_arn` – Key AWS Management Service 金鑰的金鑰 ARN，用於加密來源資料欄。 + `entity_type_filter` – 實體類型的選用陣列。可用於僅加密任意文字資料欄中偵測到的 PII。 + `preserve_data_type` – 選用布林值。預設為 true。如果為 false，則不會儲存資料類型。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # IntToIp 類別 `IntToIp` 轉換會將來源資料欄的整數值或其他值轉換為目標資料欄中對應的 IPv4 值，並在新的資料欄中傳回結果。 ## 範例 ``` from pyspark.context import SparkContext from pyspark.sql import SparkSession from awsgluedi.transforms import * sc = SparkContext() spark = SparkSession(sc) input_df = spark.createDataFrame( [ (3221225473,), (0,), (1,), (100,), (168430090,), (4294967295,), (4294967294,), (4294967296,), (-1,), (None,), ], ["source_column_int"], ) try: df_output = web_functions.IntToIp.apply( data_frame=input_df, spark_context=sc, source_column="source_column_int", target_column="target_column", value=None ) df_output.show() except: print("Unexpected Error happened ") raise ``` ## Output 輸出將是： ``` ``` +---------------+---------------+ |source_column_int|target_column| +---------------+---------------+ | 3221225473| 192.0.0.1 | | 0| 0.0.0.0 | | 1| 0.0.0.1 | | 100| 0.0.0.100| | 168430090 | 10.0.0.10 | | 4294967295| 255.255.255.255| | 4294967294| 255.255.255.254| | 4294967296| null | | -1| null | | null| null | +---------------+---------------+ ``` ``` `IntToIp.apply` 轉換會將 `source\$1column` 作為 `"source\$1column\$1int"`，將 `target\$1column` 作為 `"target\$1column"`，將 `source\$1column\$1int` 資料欄中的整數值轉換為對應的 IPv4 地址表示法，並將結果儲存在 `target\$1column` 資料欄中。 對於 IPv4 地址範圍內的有效整數值 (0 至 4294967295)，轉換會成功將其轉換為 IPv4 地址表示法 (例如 192.0.0.1、0.0.0.0、10.0.0.10、255.255.255.255)。 對於有效範圍外的整數值 (例如 4294967296、-1)，`target\$1column` 值會設為 `null`。對於 `source\$1column\$1int` 資料欄中的 `null` 值，`target\$1column` 值也會設定為 `null`。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-IntToIp-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-IntToIp-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-IntToIp-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-IntToIp-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-IntToIp-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-IntToIp-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-IntToIp-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-IntToIp-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, target\$1column, source\$1column=None, value=None) `IntToIp` 轉換會將來源資料欄的整數值或其他值轉換為目標資料欄中對應的 IPv4 值，並在新的資料欄中傳回結果。 + `sourceColumn` – 現有資料欄的名稱。 + `value` – 要評估的字元字串。 + `targetColumn` – 要建立的新資料欄的名稱。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 # IpToInt 類別 `IpToInt` 轉換會將來源資料欄的網際網路協定第 4 版 (IPv4) 值或其他值轉換為目標資料欄中對應的整數值，並在新的資料欄中傳回結果。 ## 範例 對於 AWS Glue 4.0 及更高版本，使用 建立或更新任務引數 `key: --enable-glue-di-transforms, value: true` ``` from pyspark.context import SparkContext from awsgluedi.transforms import * sc = SparkContext() input_df = spark.createDataFrame( [ ("192.0.0.1",), ("10.10.10.10",), ("1.2.3.4",), ("1.2.3.6",), ("http://12.13.14.15",), ("https://16.17.18.19",), ("1.2.3.4",), (None,), ("abc",), ("abc.abc.abc.abc",), ("321.123.123.123",), ("244.4.4.4",), ("255.255.255.255",), ], ["source_column_ip"], ) df_output = web_functions.IpToInt.apply( data_frame=input_df, spark_context=sc, source_column="source_column_ip", target_column="target_column", value=None ) df_output.show() ``` ## Output 輸出將是： ``` ``` +----------------+---------------+ |source_column_ip| target_column| +----------------+---------------+ | 192.0.0.1| 3221225473| | 10.10.10.10| 168427722| | 1.2.3.4| 16909060| | 1.2.3.6| 16909062| |http://12.13.14.15| null| |https://16.17.18.19| null| | 1.2.3.4| 16909060| | null| null| | abc| null| |abc.abc.abc.abc| null| | 321.123.123.123| null| | 244.4.4.4| 4102444804| | 255.255.255.255| 4294967295| +----------------+---------------+ ``` ``` `IpToInt` 轉換會將 `source\$1column` 作為 `"source\$1column\$1ip"`，將 `target\$1column` 作為 `"target\$1column"`，將 `source\$1column\$1ip` 資料欄中的有效 IPv4 地址字串轉換為對應的 32 位元整數表示法，並將結果儲存在 `target\$1column` 資料欄中。 對於有效的 IPv4 地址字串 (例如 "192.0.0.1"、"10.10.10.10"、"1.2.3.4")，轉換會成功將其轉換為整數表示法 (例如 3221225473、168427722、16909060)。對於不是有效 IPv4 地址的字串 (例如 URL、"abc" 等非 IP 字串、"abc.abc.abc.abc" 等無效的 IP 格式)，`target\$1column` 值設定為 `null`。對於 `source\$1column\$1ip` 資料欄中的 `null` 值，`target\$1column` 值也會設定為 `null`。 ## 方法 + [\$1\$1call\$1\$1](#aws-glue-api-pyspark-transforms-IpToInt-__call__) + [apply](#aws-glue-api-crawler-pyspark-transforms-IpToInt-apply) + [name](#aws-glue-api-crawler-pyspark-transforms-IpToInt-name) + [describeArgs](#aws-glue-api-crawler-pyspark-transforms-IpToInt-describeArgs) + [describeReturn](#aws-glue-api-crawler-pyspark-transforms-IpToInt-describeReturn) + [describeTransform](#aws-glue-api-crawler-pyspark-transforms-IpToInt-describeTransform) + [describeErrors](#aws-glue-api-crawler-pyspark-transforms-IpToInt-describeErrors) + [describe](#aws-glue-api-crawler-pyspark-transforms-IpToInt-describe) ## \$1\$1call\$1\$1(spark\$1context, data\$1frame, target\$1column, source\$1column=None, value=None) `IpToInt` 轉換會將來源資料欄的網際網路協定第 4 版 (IPv4) 值或其他值轉換為目標資料欄中對應的整數值，並在新的資料欄中傳回結果。 + `sourceColumn` – 現有資料欄的名稱。 + `value` – 要評估的字元字串。 + `targetColumn` – 要建立的新資料欄的名稱。 ## apply(cls, \$1args, \$1\$1kwargs) 繼承自 `GlueTransform` [apply](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-apply)。 ## name(cls) 繼承自 `GlueTransform` [name](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-name)。 ## describeArgs(cls) 繼承自 `GlueTransform` [describeArgs](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeArgs)。 ## describeReturn(cls) 繼承自 `GlueTransform` [describeReturn](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeReturn)。 ## describeTransform(cls) 繼承自 `GlueTransform` [describeTransform](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeTransform)。 ## describeErrors(cls) 繼承自 `GlueTransform` [describeErrors](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describeErrors)。 ## describe(cls) 繼承自 `GlueTransform` [describe](aws-glue-api-crawler-pyspark-transforms-GlueTransform.md#aws-glue-api-crawler-pyspark-transforms-GlueTransform-describe)。 ## 資料整合轉換 對於 AWS Glue 4.0 及更高版本，請使用 建立或更新任務引數`key: --enable-glue-di-transforms, value: true`。 範例任務指令碼： ``` from pyspark.context import SparkContext from awsgluedi.transforms import * sc = SparkContext() input_df = spark.createDataFrame( [(5,), (0,), (-1,), (2,), (None,)], ["source_column"], ) try: df_output = math_functions.IsEven.apply( data_frame=input_df, spark_context=sc, source_column="source_column", target_column="target_column", value=None, true_string="Even", false_string="Not even", ) df_output.show() except: print("Unexpected Error happened ") raise ``` 使用筆記本的範例工作階段 ``` %idle_timeout 2880 %glue_version 4.0 %worker_type G.1X %number_of_workers 5 %region eu-west-1 ``` ``` %%configure { "--enable-glue-di-transforms": "true" } ``` ``` from pyspark.context import SparkContext from awsgluedi.transforms import * sc = SparkContext() input_df = spark.createDataFrame( [(5,), (0,), (-1,), (2,), (None,)], ["source_column"], ) try: df_output = math_functions.IsEven.apply( data_frame=input_df, spark_context=sc, source_column="source_column", target_column="target_column", value=None, true_string="Even", false_string="Not even", ) df_output.show() except: print("Unexpected Error happened ") raise ``` 使用 的範例工作階段 AWS CLI ``` aws glue create-session --default-arguments "--enable-glue-di-transforms=true" ``` DI 轉換： + [FlagDuplicatesInColumn 類別](aws-glue-api-pyspark-transforms-FlagDuplicatesInColumn.md) + [FormatPhoneNumber 類別](aws-glue-api-pyspark-transforms-FormatPhoneNumber.md) + [FormatCase 類別](aws-glue-api-pyspark-transforms-FormatCase.md) + [FillWithMode 類別](aws-glue-api-pyspark-transforms-FillWithMode.md) + [FlagDuplicateRows 類別](aws-glue-api-pyspark-transforms-FlagDuplicateRows.md) + [RemoveDuplicates 類別](aws-glue-api-pyspark-transforms-RemoveDuplicates.md) + [MonthName 類別](aws-glue-api-pyspark-transforms-MonthName.md) + [IsEven 類別](aws-glue-api-pyspark-transforms-IsEven.md) + [CryptographicHash 類別](aws-glue-api-pyspark-transforms-CryptographicHash.md) + [解密類別](aws-glue-api-pyspark-transforms-Decrypt.md) + [加密類別](aws-glue-api-pyspark-transforms-Encrypt.md) + [IntToIp 類別](aws-glue-api-pyspark-transforms-IntToIp.md) + [IpToInt 類別](aws-glue-api-pyspark-transforms-IpToInt.md) ### Maven：將外掛程式與 Spark 應用程式綁定在一起 您可以在本機開發 Spark 應用程式時，透過在 Maven `pom.xml` 中新增外掛程式相依項，將轉換相依項與您的 Spark 應用程式和 Spark 發行版本 (3.3 版) 捆綁在一起。 ``` ... aws-glue-etl-artifacts https://aws-glue-etl-artifacts.s3.amazonaws.com/release/ ... com.amazonaws AWSGlueTransforms 4.0.0 ``` 或者，您也可以直接從 AWS Glue Maven 成品下載二進位檔，並將其包含在 Spark 應用程式中，如下所示。 ``` #!/bin/bash sudo wget -v https://aws-glue-etl-artifacts.s3.amazonaws.com/release/com/amazonaws/AWSGlueTransforms/4.0.0/AWSGlueTransforms-4.0.0.jar -P /usr/lib/spark/jars/ ``` # 在 Scala 中進行 AWS Glue ETL 指令碼程式設計 您可以在 GitHub 網站上的 [AWS Glue 範例儲存庫](https://github.com/awslabs/aws-glue-samples)中，找到適用於 AWS Glue 的 Scala 程式碼範例與公用程式。 AWS Glue 支援 PySpark Scala 方言的延伸，用於指令碼擷取、轉換和載入 (ETL) 任務。以下部分說明如何使用 ETL 指令碼的 AWS Glue Scala 程式庫和 AWS Glue API，並提供該程式庫的參考文件。 **Contents** + [使用 Scala](glue-etl-scala-using.md) + [在 DevEndpoint 筆記本上測試](glue-etl-scala-using.md#aws-glue-programming-scala-using-notebook) + [在 DevEndpoint REPL 上測試](glue-etl-scala-using.md#aws-glue-programming-scala-using-repl) + [Scala 指令碼範例](glue-etl-scala-example.md) + [Scala API 清單](glue-etl-scala-apis.md) + [com.amazonaws.services.glue](glue-etl-scala-apis.md#glue-etl-scala-apis-glue) + [com.amazonaws.services.glue.ml](glue-etl-scala-apis.md#glue-etl-scala-apis-glue-ml) + [com.amazonaws.services.glue.dq](glue-etl-scala-apis.md#glue-etl-scala-apis-glue-dq) + [com.amazonaws.services.glue.types](glue-etl-scala-apis.md#glue-etl-scala-apis-glue-types) + [com.amazonaws.services.glue.util](glue-etl-scala-apis.md#glue-etl-scala-apis-glue-util) + [ChoiceOption](glue-etl-scala-apis-glue-choiceoption.md) + [ChoiceOption 特徵](glue-etl-scala-apis-glue-choiceoption.md#glue-etl-scala-apis-glue-choiceoption-trait) + [ChoiceOption 物件](glue-etl-scala-apis-glue-choiceoption.md#glue-etl-scala-apis-glue-choiceoption-object) + [套用](glue-etl-scala-apis-glue-choiceoption.md#glue-etl-scala-apis-glue-choiceoption-object-def-apply) + [ChoiceOptionWithResolver](glue-etl-scala-apis-glue-choiceoption.md#glue-etl-scala-apis-glue-choiceoptionwithresolver-case-class) + [MatchCatalogSchemaChoiceOption](glue-etl-scala-apis-glue-choiceoption.md#glue-etl-scala-apis-glue-matchcatalogschemachoiceoption-case-class) + [DataSink](glue-etl-scala-apis-glue-datasink-class.md) + [writeDynamicFrame](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-class-defs-writeDynamicFrame) + [pyWriteDynamicFrame](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-class-defs-pyWriteDynamicFrame) + [writeDataFrame](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-class-defs-writeDataFrame) + [pyWriteDataFrame](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-class-defs-pyWriteDataFrame) + [setCatalogInfo](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-class-defs-setCatalogInfo) + [supportsFormat](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-class-defs-supportsFormat) + [setFormat](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-class-defs-setFormat) + [withFormat](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-class-defs-withFormat) + [setAccumulableSize](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-class-defs-setAccumulableSize) + [getOutputErrorRecordsAccumulable](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-class-defs-getOutputErrorRecordsAccumulable) + [errorsAsDynamicFrame](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-class-defs-errorsAsDynamicFrame) + [DataSink 物件](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-object) + [recordMetrics](glue-etl-scala-apis-glue-datasink-class.md#glue-etl-scala-apis-glue-datasink-object-defs-recordMetrics) + [DataSource 特徵](glue-etl-scala-apis-glue-datasource-trait.md) + [DynamicFrame](glue-etl-scala-apis-glue-dynamicframe.md) + [DynamicFrame 類別](glue-etl-scala-apis-glue-dynamicframe-class.md) + [errorsCount](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-vals-errorsCount) + [applyMapping](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-applyMapping) + [assertErrorThreshold](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-assertErrorThreshold) + [計數](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-count) + [dropField](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-dropField) + [dropFields](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-dropFields) + [dropNulls](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-dropNulls) + [errorsAsDynamicFrame](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-errorsAsDynamicFrame) + [篩選條件](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-filter) + [getName](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-getName) + [getNumPartitions](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-getNumPartitions) + [getSchemaIfComputed](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-getSchemaIfComputed) + [isSchemaComputed](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-isSchemaComputed) + [javaToPython](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-javaToPython) + [Join](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-join) + [Map](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-map) + [mergeDynamicFrames](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-merge) + [printSchema](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-printSchema) + [recomputeSchema](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-recomputeSchema) + [Relationalize](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-relationalize) + [renameField](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-renameField) + [Repartition](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-repartition) + [resolveChoice](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-resolveChoice) + [結構描述](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-schema) + [selectField](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-selectField) + [selectFields](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-selectFields) + [Show](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-show) + [SimplifyDDBJson](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-simplifyDDBJson) + [Spigot](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-spigot) + [splitFields](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-splitFields) + [Def splitRows](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-splitRows) + [stageErrorsCount](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-stageErrorsCount) + [toDF](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-toDF) + [Unbox](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-unbox) + [Unnest](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-unnest) + [unnestDDBJson](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-unnestddbjson) + [withFrameSchema](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-withFrameSchema) + [Def withName](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-withName) + [withTransformationContext](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-withTransformationContext) + [DynamicFrame 物件](glue-etl-scala-apis-glue-dynamicframe-object.md) + [Def apply](glue-etl-scala-apis-glue-dynamicframe-object.md#glue-etl-scala-apis-glue-dynamicframe-object-defs-apply) + [Def emptyDynamicFrame](glue-etl-scala-apis-glue-dynamicframe-object.md#glue-etl-scala-apis-glue-dynamicframe-object-defs-emptyDynamicFrame) + [Def fromPythonRDD](glue-etl-scala-apis-glue-dynamicframe-object.md#glue-etl-scala-apis-glue-dynamicframe-object-defs-fromPythonRDD) + [Def ignoreErrors](glue-etl-scala-apis-glue-dynamicframe-object.md#glue-etl-scala-apis-glue-dynamicframe-object-defs-ignoreErrors) + [Def inlineErrors](glue-etl-scala-apis-glue-dynamicframe-object.md#glue-etl-scala-apis-glue-dynamicframe-object-defs-inlineErrors) + [Def newFrameWithErrors](glue-etl-scala-apis-glue-dynamicframe-object.md#glue-etl-scala-apis-glue-dynamicframe-object-defs-newFrameWithErrors) + [DynamicRecord](glue-etl-scala-apis-glue-dynamicrecord-class.md) + [addField](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-addField) + [dropField](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-dropField) + [setError](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-setError) + [isError](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-isError) + [getError](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-getError) + [clearError](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-clearError) + [寫入](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-write) + [readFields](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-readFields) + [複製](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-clone) + [結構描述](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-schema) + [getRoot](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-getRoot) + [toJson](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-toJson) + [getFieldNode](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-getFieldNode) + [getField](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-getField) + [hashCode](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-hashCode) + [Equals](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-class-defs-equals) + [DynamicRecord 物件](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-object) + [套用](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-dynamicrecord-object-defs-apply) + [RecordTraverser 特徵](glue-etl-scala-apis-glue-dynamicrecord-class.md#glue-etl-scala-apis-glue-recordtraverser-trait) + [GlueContext](glue-etl-scala-apis-glue-gluecontext.md) + [addIngestionTimeColumns](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-addIngestionTimeColumns) + [createDataFrameFromOptions](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-createDataFrameFromOptions) + [forEachBatch](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-forEachBatch) + [getCatalogSink](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getCatalogSink) + [getCatalogSource](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getCatalogSource) + [getJDBCSink](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getJDBCSink) + [getSink](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSink) + [getSinkWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSinkWithFormat) + [getSource](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSource) + [getSourceWithFormat](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSourceWithFormat) + [getSparkSession](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getSparkSession) + [startTransaction](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-start-transaction) + [commitTransaction](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-commit-transaction) + [cancelTransaction](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-cancel-transaction) + [this](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-this-1) + [this](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-this-2) + [this](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-this-3) + [MappingSpec](glue-etl-scala-apis-glue-mappingspec.md) + [MappingSpec 案例類別](glue-etl-scala-apis-glue-mappingspec.md#glue-etl-scala-apis-glue-mappingspec-case-class) + [MappingSpec 物件](glue-etl-scala-apis-glue-mappingspec.md#glue-etl-scala-apis-glue-mappingspec-object) + [orderingByTarget](glue-etl-scala-apis-glue-mappingspec.md#glue-etl-scala-apis-glue-mappingspec-object-val-orderingbytarget) + [套用](glue-etl-scala-apis-glue-mappingspec.md#glue-etl-scala-apis-glue-mappingspec-object-defs-apply-1) + [套用](glue-etl-scala-apis-glue-mappingspec.md#glue-etl-scala-apis-glue-mappingspec-object-defs-apply-2) + [套用](glue-etl-scala-apis-glue-mappingspec.md#glue-etl-scala-apis-glue-mappingspec-object-defs-apply-3) + [ResolveSpec](glue-etl-scala-apis-glue-resolvespec.md) + [ResolveSpec 物件](glue-etl-scala-apis-glue-resolvespec.md#glue-etl-scala-apis-glue-resolvespec-object) + [Def](glue-etl-scala-apis-glue-resolvespec.md#glue-etl-scala-apis-glue-resolvespec-object-def-apply_1) + [Def](glue-etl-scala-apis-glue-resolvespec.md#glue-etl-scala-apis-glue-resolvespec-object-def-apply_2) + [ResolveSpec 案例類別](glue-etl-scala-apis-glue-resolvespec.md#glue-etl-scala-apis-glue-resolvespec-case-class) + [Def 方法](glue-etl-scala-apis-glue-resolvespec.md#glue-etl-scala-apis-glue-resolvespec-case-class-defs) + [ArrayNode](glue-etl-scala-apis-glue-types-arraynode.md) + [ArrayNode 案例類別](glue-etl-scala-apis-glue-types-arraynode.md#glue-etl-scala-apis-glue-types-arraynode-case-class) + [Def 方法](glue-etl-scala-apis-glue-types-arraynode.md#glue-etl-scala-apis-glue-types-arraynode-case-class-defs) + [BinaryNode](glue-etl-scala-apis-glue-types-binarynode.md) + [BinaryNode 案例類別](glue-etl-scala-apis-glue-types-binarynode.md#glue-etl-scala-apis-glue-types-binarynode-case-class) + [Val 欄位](glue-etl-scala-apis-glue-types-binarynode.md#glue-etl-scala-apis-glue-types-binarynode-case-class-vals) + [Def 方法](glue-etl-scala-apis-glue-types-binarynode.md#glue-etl-scala-apis-glue-types-binarynode-case-class-defs) + [BooleanNode](glue-etl-scala-apis-glue-types-booleannode.md) + [BooleanNode 案例類別](glue-etl-scala-apis-glue-types-booleannode.md#glue-etl-scala-apis-glue-types-booleannode-case-class) + [Val 欄位](glue-etl-scala-apis-glue-types-booleannode.md#glue-etl-scala-apis-glue-types-booleannode-case-class-vals) + [Def 方法](glue-etl-scala-apis-glue-types-booleannode.md#glue-etl-scala-apis-glue-types-booleannode-case-class-defs) + [ByteNode](glue-etl-scala-apis-glue-types-bytenode.md) + [ByteNode 案例類別](glue-etl-scala-apis-glue-types-bytenode.md#glue-etl-scala-apis-glue-types-bytenode-case-class) + [Val 欄位](glue-etl-scala-apis-glue-types-bytenode.md#glue-etl-scala-apis-glue-types-bytenode-case-class-vals) + [Def 方法](glue-etl-scala-apis-glue-types-bytenode.md#glue-etl-scala-apis-glue-types-bytenode-case-class-defs) + [DateNode](glue-etl-scala-apis-glue-types-datenode.md) + [DateNode 案例類別](glue-etl-scala-apis-glue-types-datenode.md#glue-etl-scala-apis-glue-types-datenode-case-class) + [Val 欄位](glue-etl-scala-apis-glue-types-datenode.md#glue-etl-scala-apis-glue-types-datenode-case-class-vals) + [Def 方法](glue-etl-scala-apis-glue-types-datenode.md#glue-etl-scala-apis-glue-types-datenode-case-class-defs) + [DecimalNode](glue-etl-scala-apis-glue-types-decimalnode.md) + [DecimalNode 案例類別](glue-etl-scala-apis-glue-types-decimalnode.md#glue-etl-scala-apis-glue-types-decimalnode-case-class) + [Val 欄位](glue-etl-scala-apis-glue-types-decimalnode.md#glue-etl-scala-apis-glue-types-decimalnode-case-class-vals) + [Def 方法](glue-etl-scala-apis-glue-types-decimalnode.md#glue-etl-scala-apis-glue-types-decimalnode-case-class-defs) + [DoubleNode](glue-etl-scala-apis-glue-types-doublenode.md) + [DoubleNode 案例類別](glue-etl-scala-apis-glue-types-doublenode.md#glue-etl-scala-apis-glue-types-doublenode-case-class) + [Val 欄位](glue-etl-scala-apis-glue-types-doublenode.md#glue-etl-scala-apis-glue-types-doublenode-case-class-vals) + [Def 方法](glue-etl-scala-apis-glue-types-doublenode.md#glue-etl-scala-apis-glue-types-doublenode-case-class-defs) + [DynamicNode](glue-etl-scala-apis-glue-types-dynamicnode.md) + [DynamicNode 類別](glue-etl-scala-apis-glue-types-dynamicnode.md#glue-etl-scala-apis-glue-types-dynamicnode-class) + [Def 方法](glue-etl-scala-apis-glue-types-dynamicnode.md#glue-etl-scala-apis-glue-types-dynamicnode-class-defs) + [DynamicNode 物件](glue-etl-scala-apis-glue-types-dynamicnode.md#glue-etl-scala-apis-glue-types-dynamicnode-object) + [Def 方法](glue-etl-scala-apis-glue-types-dynamicnode.md#glue-etl-scala-apis-glue-types-dynamicnode-object-defs) + [EvaluateDataQuality](glue-etl-scala-apis-glue-dq-EvaluateDataQuality.md) + [apply](glue-etl-scala-apis-glue-dq-EvaluateDataQuality.md#glue-etl-scala-apis-glue-dq-EvaluateDataQuality-defs-apply) + [範例](glue-etl-scala-apis-glue-dq-EvaluateDataQuality.md#glue-etl-scala-apis-glue-dq-EvaluateDataQuality-example) + [FloatNode](glue-etl-scala-apis-glue-types-floatnode.md) + [FloatNode 案例類別](glue-etl-scala-apis-glue-types-floatnode.md#glue-etl-scala-apis-glue-types-floatnode-case-class) + [Val 欄位](glue-etl-scala-apis-glue-types-floatnode.md#glue-etl-scala-apis-glue-types-floatnode-case-class-vals) + [Def 方法](glue-etl-scala-apis-glue-types-floatnode.md#glue-etl-scala-apis-glue-types-floatnode-case-class-defs) + [FillMissingValues](glue-etl-scala-apis-glue-ml-fillmissingvalues.md) + [套用](glue-etl-scala-apis-glue-ml-fillmissingvalues.md#glue-etl-scala-apis-glue-ml-fillmissingvalues-defs-apply) + [FindMatches](glue-etl-scala-apis-glue-ml-findmatches.md) + [套用](glue-etl-scala-apis-glue-ml-findmatches.md#glue-etl-scala-apis-glue-ml-findmatches-defs-apply) + [FindIncrementalMatches](glue-etl-scala-apis-glue-ml-findincrementalmatches.md) + [套用](glue-etl-scala-apis-glue-ml-findincrementalmatches.md#glue-etl-scala-apis-glue-ml-findincrementalmatches-defs-apply) + [IntegerNode](glue-etl-scala-apis-glue-types-integernode.md) + [IntegerNode 案例類別](glue-etl-scala-apis-glue-types-integernode.md#glue-etl-scala-apis-glue-types-integernode-case-class) + [Val 欄位](glue-etl-scala-apis-glue-types-integernode.md#glue-etl-scala-apis-glue-types-integernode-case-class-vals) + [Def 方法](glue-etl-scala-apis-glue-types-integernode.md#glue-etl-scala-apis-glue-types-integernode-case-class-defs) + [LongNode](glue-etl-scala-apis-glue-types-longnode.md) + [LongNode 案例類別](glue-etl-scala-apis-glue-types-longnode.md#glue-etl-scala-apis-glue-types-longnode-case-class) + [Val 欄位](glue-etl-scala-apis-glue-types-longnode.md#glue-etl-scala-apis-glue-types-longnode-case-class-vals) + [Def 方法](glue-etl-scala-apis-glue-types-longnode.md#glue-etl-scala-apis-glue-types-longnode-case-class-defs) + [MapLikeNode](glue-etl-scala-apis-glue-types-maplikenode.md) + [MapLikeNode 類別](glue-etl-scala-apis-glue-types-maplikenode.md#glue-etl-scala-apis-glue-types-maplikenode-class) + [Def 方法](glue-etl-scala-apis-glue-types-maplikenode.md#glue-etl-scala-apis-glue-types-maplikenode-class-defs) + [MapNode](glue-etl-scala-apis-glue-types-mapnode.md) + [MapNode 案例類別](glue-etl-scala-apis-glue-types-mapnode.md#glue-etl-scala-apis-glue-types-mapnode-case-class) + [Def 方法](glue-etl-scala-apis-glue-types-mapnode.md#glue-etl-scala-apis-glue-types-mapnode-case-class-defs) + [NullNode](glue-etl-scala-apis-glue-types-nullnode.md) + [NullNode 類別](glue-etl-scala-apis-glue-types-nullnode.md#glue-etl-scala-apis-glue-types-nullnode-class) + [NullNode 案例物件](glue-etl-scala-apis-glue-types-nullnode.md#glue-etl-scala-apis-glue-types-nullnode-case-object) + [ObjectNode](glue-etl-scala-apis-glue-types-objectnode.md) + [ObjectNode 物件](glue-etl-scala-apis-glue-types-objectnode.md#glue-etl-scala-apis-glue-types-objectnode-object) + [Def 方法](glue-etl-scala-apis-glue-types-objectnode.md#glue-etl-scala-apis-glue-types-objectnode-object-defs) + [ObjectNode 案例類別](glue-etl-scala-apis-glue-types-objectnode.md#glue-etl-scala-apis-glue-types-objectnode-case-class) + [Def 方法](glue-etl-scala-apis-glue-types-objectnode.md#glue-etl-scala-apis-glue-types-objectnode-case-class-defs) + [ScalarNode](glue-etl-scala-apis-glue-types-scalarnode.md) + [ScalarNode 類別](glue-etl-scala-apis-glue-types-scalarnode.md#glue-etl-scala-apis-glue-types-scalarnode-class) + [Def 方法](glue-etl-scala-apis-glue-types-scalarnode.md#glue-etl-scala-apis-glue-types-scalarnode-class-defs) + [ScalarNode 物件](glue-etl-scala-apis-glue-types-scalarnode.md#glue-etl-scala-apis-glue-types-scalarnode-object) + [Def 方法](glue-etl-scala-apis-glue-types-scalarnode.md#glue-etl-scala-apis-glue-types-scalarnode-object-defs) + [ShortNode](glue-etl-scala-apis-glue-types-shortnode.md) + [ShortNode 案例類別](glue-etl-scala-apis-glue-types-shortnode.md#glue-etl-scala-apis-glue-types-shortnode-case-class) + [Val 欄位](glue-etl-scala-apis-glue-types-shortnode.md#glue-etl-scala-apis-glue-types-shortnode-case-class-vals) + [Def 方法](glue-etl-scala-apis-glue-types-shortnode.md#glue-etl-scala-apis-glue-types-shortnode-case-class-defs) + [StringNode](glue-etl-scala-apis-glue-types-stringnode.md) + [StringNode 案例類別](glue-etl-scala-apis-glue-types-stringnode.md#glue-etl-scala-apis-glue-types-stringnode-case-class) + [Val 欄位](glue-etl-scala-apis-glue-types-stringnode.md#glue-etl-scala-apis-glue-types-stringnode-case-class-vals) + [Def 方法](glue-etl-scala-apis-glue-types-stringnode.md#glue-etl-scala-apis-glue-types-stringnode-case-class-defs) + [TimestampNode](glue-etl-scala-apis-glue-types-timestampnode.md) + [TimestampNode 案例類別](glue-etl-scala-apis-glue-types-timestampnode.md#glue-etl-scala-apis-glue-types-timestampnode-case-class) + [Val 欄位](glue-etl-scala-apis-glue-types-timestampnode.md#glue-etl-scala-apis-glue-types-timestampnode-case-class-vals) + [Def 方法](glue-etl-scala-apis-glue-types-timestampnode.md#glue-etl-scala-apis-glue-types-timestampnode-case-class-defs) + [GlueArgParser](glue-etl-scala-apis-glue-util-glueargparser.md) + [GlueArgParser 物件](glue-etl-scala-apis-glue-util-glueargparser.md#glue-etl-scala-apis-glue-util-glueargparser-object) + [Def 方法](glue-etl-scala-apis-glue-util-glueargparser.md#glue-etl-scala-apis-glue-util-glueargparser-object-defs) + [任務](glue-etl-scala-apis-glue-util-job.md) + [任務物件](glue-etl-scala-apis-glue-util-job.md#glue-etl-scala-apis-glue-util-job-object) + [Def 方法](glue-etl-scala-apis-glue-util-job.md#glue-etl-scala-apis-glue-util-job-object-defs) # 使用 Scala 以程式設計 AWS Glue ETL 指令碼 您可以使用 AWS Glue 主控台來自動產生 Scala 擷取、轉換和載入 (ETL) 程式並視需要修改，再將其指派到任務。或者，您也可以從頭開始撰寫自己的程式。如需更多資訊，請參閱 [在 中設定 Spark 任務的任務屬性 AWS Glue](add-job.md)。AWS Glue 會在執行相關的任務前在伺服器編譯 Scala 程式。 為了確保您的程式編譯無誤且如預期般執行，您必須在任務中執行該程式前，在 REPL (Read-Eval-Print Loop) 或 Jupyter 筆記本的開發端點上將其載入並測試。由於編譯處理會在伺服器上進行，您將無法詳細查看在其中發生的任何問題。 ## 在開發端點上使用 Jupyter 筆記本測試 Scala ETL 程式 若要在 AWS Glue 開發端點上測試 Scala 程式，請如 [新增開發端點](add-dev-endpoint.md) 所述來設定開發端點。 接著，將其連線至在本機電腦或 Amazon EC2 筆記本伺服器遠端執行中的 Jupyter 筆記本。若要安裝本機版本的 Jupyter 筆記本，請遵循 [教學課程：JupyterLab 中的 Jupyter 筆記本](dev-endpoint-tutorial-local-jupyter.md) 中的說明進行。 在筆記本上執行 Scala 程式碼與執行 PySpark 程式碼之間的唯一差別，是您應使用以下項目以在筆記本上開始每一段落： ``` %spark ``` 這可防止筆記本伺服器將 Spark 解譯器的 PySpark 類別設為預設。 ## 在 Scala REPL 測試 Scala ETL 程式 您可以使用 AWS Glue Scala REPL 在開發端點上測試 Scala 程式。請遵循[教學課程：使用 SageMaker AI 筆記本教學課程：使用 REPL shell](dev-endpoint-tutorial-repl.md)中的指示，但在 SSH-to-REPL 命令的結尾，將 `-t gluepyspark` 取代為 `-t glue-spark-shell`。這會呼叫 AWS Glue Scala REPL。 若要在完成時關閉 REPL，輸入 `sys.exit`。 # Scala 指令碼範例 - 串流 ETL **Example** 下列指令碼範例會連線到 Amazon Kinesis Data Streams，使用來自 Data Catalog 的結構描述剖析資料串流，將串流聯結至 Amazon S3 上的靜態資料集，然後將聯結的結果以 Parquet 格式輸出至 Amazon S3。 ``` // This script connects to an Amazon Kinesis stream, uses a schema from the data catalog to parse the stream, // joins the stream to a static dataset on Amazon S3, and outputs the joined results to Amazon S3 in parquet format. import com.amazonaws.services.glue.GlueContext import com.amazonaws.services.glue.util.GlueArgParser import com.amazonaws.services.glue.util.Job import java.util.Calendar import org.apache.spark.SparkContext import org.apache.spark.sql.Dataset import org.apache.spark.sql.Row import org.apache.spark.sql.SaveMode import org.apache.spark.sql.SparkSession import org.apache.spark.sql.functions.from_json import org.apache.spark.sql.streaming.Trigger import scala.collection.JavaConverters._ object streamJoiner { def main(sysArgs: Array[String]) { val spark: SparkContext = new SparkContext() val glueContext: GlueContext = new GlueContext(spark) val sparkSession: SparkSession = glueContext.getSparkSession import sparkSession.implicits._ // @params: [JOB_NAME] val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) val staticData = sparkSession.read // read() returns type DataFrameReader .format("csv") .option("header", "true") .load("s3://amzn-s3-demo-bucket/inputs/productsStatic.csv") // load() returns a DataFrame val datasource0 = sparkSession.readStream // readstream() returns type DataStreamReader .format("kinesis") .option("streamName", "stream-join-demo") .option("endpointUrl", "https://kinesis.us-east-1.amazonaws.com") .option("startingPosition", "TRIM_HORIZON") .load // load() returns a DataFrame val selectfields1 = datasource0.select(from_json($"data".cast("string"), glueContext.getCatalogSchemaAsSparkSchema("stream-demos", "stream-join-demo2")) as "data").select("data.*") val datasink2 = selectfields1.writeStream.foreachBatch { (dataFrame: Dataset[Row], batchId: Long) => { //foreachBatch() returns type DataStreamWriter val joined = dataFrame.join(staticData, "product_id") val year: Int = Calendar.getInstance().get(Calendar.YEAR) val month :Int = Calendar.getInstance().get(Calendar.MONTH) + 1 val day: Int = Calendar.getInstance().get(Calendar.DATE) val hour: Int = Calendar.getInstance().get(Calendar.HOUR_OF_DAY) if (dataFrame.count() > 0) { joined.write // joined.write returns type DataFrameWriter .mode(SaveMode.Append) .format("parquet") .option("quote", " ") .save("s3://amzn-s3-demo-bucket/output/" + "/year=" + "%04d".format(year) + "/month=" + "%02d".format(month) + "/day=" + "%02d".format(day) + "/hour=" + "%02d".format(hour) + "/") } } } // end foreachBatch() .trigger(Trigger.ProcessingTime("100 seconds")) .option("checkpointLocation", "s3://amzn-s3-demo-bucket/checkpoint/") .start().awaitTermination() // start() returns type StreamingQuery Job.commit() } } ``` # AWS Glue Scala 程式庫中的 API AWS Glue 支援 PySpark Scala 方言的延伸模組，適用於編寫擷取、轉換和載入 (ETL) 任務的指令碼。以下幾節會說明 AWS Glue Scala 程式庫中的 API。 ## com.amazonaws.services.glue 在 ** Scala 程式庫中 **com.amazonaws.services.glueAWS Glue 套件包含下列 API： + [ChoiceOption](glue-etl-scala-apis-glue-choiceoption.md) + [DataSink](glue-etl-scala-apis-glue-datasink-class.md) + [DataSource 特徵](glue-etl-scala-apis-glue-datasource-trait.md) + [DynamicFrame](glue-etl-scala-apis-glue-dynamicframe.md) + [DynamicRecord](glue-etl-scala-apis-glue-dynamicrecord-class.md) + [GlueContext](glue-etl-scala-apis-glue-gluecontext.md) + [MappingSpec](glue-etl-scala-apis-glue-mappingspec.md) + [ResolveSpec](glue-etl-scala-apis-glue-resolvespec.md) ## com.amazonaws.services.glue.ml 在 AWS Glue Scala 程式庫中 **com.amazonaws.services.glue.ml** 套件包含下列 API： + [FillMissingValues](glue-etl-scala-apis-glue-ml-fillmissingvalues.md) + [FindIncrementalMatches](glue-etl-scala-apis-glue-ml-findincrementalmatches.md) + [FindMatches](glue-etl-scala-apis-glue-ml-findmatches.md) ## com.amazonaws.services.glue.dq AWS Glue Scala 程式庫中的 **com.amazonaws.services.glue.dq** 套件包含下列 API： + [EvaluateDataQuality](glue-etl-scala-apis-glue-dq-EvaluateDataQuality.md) ## com.amazonaws.services.glue.types 在 ** Scala 程式庫中 **com.amazonaws.services.glue.typesAWS Glue 套件包含下列 API： + [ArrayNode](glue-etl-scala-apis-glue-types-arraynode.md) + [BinaryNode](glue-etl-scala-apis-glue-types-binarynode.md) + [BooleanNode](glue-etl-scala-apis-glue-types-booleannode.md) + [ByteNode](glue-etl-scala-apis-glue-types-bytenode.md) + [DateNode](glue-etl-scala-apis-glue-types-datenode.md) + [DecimalNode](glue-etl-scala-apis-glue-types-decimalnode.md) + [DoubleNode](glue-etl-scala-apis-glue-types-doublenode.md) + [DynamicNode](glue-etl-scala-apis-glue-types-dynamicnode.md) + [FloatNode](glue-etl-scala-apis-glue-types-floatnode.md) + [IntegerNode](glue-etl-scala-apis-glue-types-integernode.md) + [LongNode](glue-etl-scala-apis-glue-types-longnode.md) + [MapLikeNode](glue-etl-scala-apis-glue-types-maplikenode.md) + [MapNode](glue-etl-scala-apis-glue-types-mapnode.md) + [NullNode](glue-etl-scala-apis-glue-types-nullnode.md) + [ObjectNode](glue-etl-scala-apis-glue-types-objectnode.md) + [ScalarNode](glue-etl-scala-apis-glue-types-scalarnode.md) + [ShortNode](glue-etl-scala-apis-glue-types-shortnode.md) + [StringNode](glue-etl-scala-apis-glue-types-stringnode.md) + [TimestampNode](glue-etl-scala-apis-glue-types-timestampnode.md) ## com.amazonaws.services.glue.util 在 ** Scala 程式庫中 **com.amazonaws.services.glue.utilAWS Glue 套件包含下列 API： + [GlueArgParser](glue-etl-scala-apis-glue-util-glueargparser.md) + [任務](glue-etl-scala-apis-glue-util-job.md) # AWS Glue Scala ChoiceOption API **Topics** + [ChoiceOption 特徵](#glue-etl-scala-apis-glue-choiceoption-trait) + [ChoiceOption 物件](#glue-etl-scala-apis-glue-choiceoption-object) + [案例類別 ChoiceOptionWithResolver](#glue-etl-scala-apis-glue-choiceoptionwithresolver-case-class) + [案例類別 MatchCatalogSchemaChoiceOption](#glue-etl-scala-apis-glue-matchcatalogschemachoiceoption-case-class) **Package: com.amazonaws.services.glue** ## ChoiceOption 特徵 ``` trait ChoiceOption extends Serializable ``` ## ChoiceOption 物件 **ChoiceOption** ``` object ChoiceOption ``` 用來解析所有 `ChoiceType` 節點 (`DynamicFrame` 中) 適用選擇的一般策略。 + `val CAST` + `val MAKE_COLS` + `val MAKE_STRUCT` + `val MATCH_CATALOG` + `val PROJECT` ### Def apply ``` def apply(choice: String): ChoiceOption ``` ## 案例類別 ChoiceOptionWithResolver ``` case class ChoiceOptionWithResolver(name: String, choiceResolver: ChoiceResolver) extends ChoiceOption {} ``` ## 案例類別 MatchCatalogSchemaChoiceOption ``` case class MatchCatalogSchemaChoiceOption() extends ChoiceOption {} ``` # Abstract DataSink 類別 **Topics** + [Def writeDynamicFrame](#glue-etl-scala-apis-glue-datasink-class-defs-writeDynamicFrame) + [Def pyWriteDynamicFrame](#glue-etl-scala-apis-glue-datasink-class-defs-pyWriteDynamicFrame) + [Def writeDataFrame](#glue-etl-scala-apis-glue-datasink-class-defs-writeDataFrame) + [Def pyWriteDataFrame](#glue-etl-scala-apis-glue-datasink-class-defs-pyWriteDataFrame) + [Def setCatalogInfo](#glue-etl-scala-apis-glue-datasink-class-defs-setCatalogInfo) + [Def supportsFormat](#glue-etl-scala-apis-glue-datasink-class-defs-supportsFormat) + [Def setFormat](#glue-etl-scala-apis-glue-datasink-class-defs-setFormat) + [Def withFormat](#glue-etl-scala-apis-glue-datasink-class-defs-withFormat) + [Def setAccumulableSize](#glue-etl-scala-apis-glue-datasink-class-defs-setAccumulableSize) + [Def getOutputErrorRecordsAccumulable](#glue-etl-scala-apis-glue-datasink-class-defs-getOutputErrorRecordsAccumulable) + [Def errorsAsDynamicFrame](#glue-etl-scala-apis-glue-datasink-class-defs-errorsAsDynamicFrame) + [DataSink 物件](#glue-etl-scala-apis-glue-datasink-object) **Package: com.amazonaws.services.glue** ``` abstract class DataSink ``` 對 `DataSource` 的寫入類比。`DataSink` 會封裝 `DynamicFrame` 可寫入的目的地和格式。 ## Def writeDynamicFrame ``` def writeDynamicFrame( frame : DynamicFrame, callSite : CallSite = CallSite("Not provided", "") ) : DynamicFrame ``` ## Def pyWriteDynamicFrame ``` def pyWriteDynamicFrame( frame : DynamicFrame, site : String = "Not provided", info : String = "" ) ``` ## Def writeDataFrame ``` def writeDataFrame(frame: DataFrame, glueContext: GlueContext, callSite: CallSite = CallSite("Not provided", "") ): DataFrame ``` ## Def pyWriteDataFrame ``` def pyWriteDataFrame(frame: DataFrame, glueContext: GlueContext, site: String = "Not provided", info: String = "" ): DataFrame ``` ## Def setCatalogInfo ``` def setCatalogInfo(catalogDatabase: String, catalogTableName : String, catalogId : String = "") ``` ## Def supportsFormat ``` def supportsFormat( format : String ) : Boolean ``` ## Def setFormat ``` def setFormat( format : String, options : JsonOptions ) : Unit ``` ## Def withFormat ``` def withFormat( format : String, options : JsonOptions = JsonOptions.empty ) : DataSink ``` ## Def setAccumulableSize ``` def setAccumulableSize( size : Int ) : Unit ``` ## Def getOutputErrorRecordsAccumulable ``` def getOutputErrorRecordsAccumulable : Accumulable[List[OutputError], OutputError] ``` ## Def errorsAsDynamicFrame ``` def errorsAsDynamicFrame : DynamicFrame ``` ## DataSink 物件 ``` object DataSink ``` ### Def recordMetrics ``` def recordMetrics( frame : DynamicFrame, ctxt : String ) : DynamicFrame ``` # AWS Glue Scala DataSource 特徵 **Package: com.amazonaws.services.glue** 用於產生 `DynamicFrame` 的高階界面。 ``` trait DataSource { def getDynamicFrame : DynamicFrame def getDynamicFrame( minPartitions : Int, targetPartitions : Int ) : DynamicFrame def getDataFrame : DataFrame /** @param num: the number of records for sampling. * @param options: optional parameters to control sampling behavior. Current available parameter for Amazon S3 sources in options: * 1. maxSamplePartitions: the maximum number of partitions the sampling will read. * 2. maxSampleFilesPerPartition: the maximum number of files the sampling will read in one partition. */ def getSampleDynamicFrame(num:Int, options: JsonOptions = JsonOptions.empty): DynamicFrame def glueContext : GlueContext def setFormat( format : String, options : String ) : Unit def setFormat( format : String, options : JsonOptions ) : Unit def supportsFormat( format : String ) : Boolean def withFormat( format : String, options : JsonOptions = JsonOptions.empty ) : DataSource } ``` # AWS Glue Scala DynamicFrame API **Package: com.amazonaws.services.glue** **Contents** + [AWS Glue Scala DynamicFrame 類別](glue-etl-scala-apis-glue-dynamicframe-class.md) + [Val errorsCount](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-vals-errorsCount) + [Def applyMapping](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-applyMapping) + [Def assertErrorThreshold](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-assertErrorThreshold) + [Def count](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-count) + [Def dropField](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-dropField) + [Def dropFields](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-dropFields) + [Def dropNulls](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-dropNulls) + [Def errorsAsDynamicFrame](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-errorsAsDynamicFrame) + [Def filter](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-filter) + [Def getName](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-getName) + [Def getNumPartitions](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-getNumPartitions) + [Def getSchemaIfComputed](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-getSchemaIfComputed) + [Def isSchemaComputed](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-isSchemaComputed) + [Def javaToPython](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-javaToPython) + [Def join](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-join) + [Def map](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-map) + [Def mergeDynamicFrames](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-merge) + [Def printSchema](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-printSchema) + [Def recomputeSchema](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-recomputeSchema) + [Def relationalize](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-relationalize) + [Def renameField](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-renameField) + [Def repartition](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-repartition) + [Def resolveChoice](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-resolveChoice) + [Def schema](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-schema) + [Def selectField](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-selectField) + [Def selectFields](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-selectFields) + [Def show](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-show) + [Def simplifyDDBJson](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-simplifyDDBJson) + [Def spigot](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-spigot) + [Def splitFields](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-splitFields) + [Def splitRows](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-splitRows) + [Def stageErrorsCount](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-stageErrorsCount) + [Def toDF](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-toDF) + [Def unbox](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-unbox) + [Def unnest](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-unnest) + [Def unnestDDBJson](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-unnestddbjson) + [Def withFrameSchema](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-withFrameSchema) + [Def withName](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-withName) + [Def withTransformationContext](glue-etl-scala-apis-glue-dynamicframe-class.md#glue-etl-scala-apis-glue-dynamicframe-class-defs-withTransformationContext) + [DynamicFrame 物件](glue-etl-scala-apis-glue-dynamicframe-object.md) + [Def apply](glue-etl-scala-apis-glue-dynamicframe-object.md#glue-etl-scala-apis-glue-dynamicframe-object-defs-apply) + [Def emptyDynamicFrame](glue-etl-scala-apis-glue-dynamicframe-object.md#glue-etl-scala-apis-glue-dynamicframe-object-defs-emptyDynamicFrame) + [Def fromPythonRDD](glue-etl-scala-apis-glue-dynamicframe-object.md#glue-etl-scala-apis-glue-dynamicframe-object-defs-fromPythonRDD) + [Def ignoreErrors](glue-etl-scala-apis-glue-dynamicframe-object.md#glue-etl-scala-apis-glue-dynamicframe-object-defs-ignoreErrors) + [Def inlineErrors](glue-etl-scala-apis-glue-dynamicframe-object.md#glue-etl-scala-apis-glue-dynamicframe-object-defs-inlineErrors) + [Def newFrameWithErrors](glue-etl-scala-apis-glue-dynamicframe-object.md#glue-etl-scala-apis-glue-dynamicframe-object-defs-newFrameWithErrors) # AWS Glue Scala DynamicFrame 類別 **Package: com.amazonaws.services.glue** ``` class DynamicFrame extends Serializable with Logging ( val glueContext : GlueContext, _records : RDD[DynamicRecord], val name : String = s"", val transformationContext : String = DynamicFrame.UNDEFINED, callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0, prevErrors : => Long = 0, errorExpr : => Unit = {} ) ``` `DynamicFrame` 是自我描述 [DynamicRecord](glue-etl-scala-apis-glue-dynamicrecord-class.md) 物件的分散式集合。 `DynamicFrame` 旨在為 ETL (擷取、轉換和載入) 操作提供靈活的資料模型。它們不需要結構描述即可建立，並可用於讀取和轉換內含雜亂或不一致值和類型的資料。您可以為需要結構描述的操作隨需運算結構描述。 `DynamicFrame` 提供各種轉換以進行資料洗滌和 ETL。它們還支援與 SparkSQL DataFrames 的相互轉換，以整合現有程式碼以及 DataFrames 提供許多分析操作。 以下參數在許多 AWS Glue 轉換之間共用以建構 `DynamicFrame`： + `transformationContext` – 此 `DynamicFrame` 的識別碼。`transformationContext` 做為在執行之間持續存在之任務書籤狀態的金鑰使用。 + `callSite` – 提供錯誤報告的內容資訊。從 Python 呼叫時，會自動設定這些值。 + `stageThreshold` – 此 `DynamicFrame` 運算在擲回例外狀況之前允許的最大錯誤記錄數，不包含於先前 `DynamicFrame` 中存在的記錄。 + `totalThreshold` – 在擲回例外狀況之前，最大的錯誤記錄總計 (包括之前框架的數量)。 ## Val errorsCount ``` val errorsCount ``` 此 `DynamicFrame` 中的錯誤記錄數量。這包括之前操作的錯誤。 ## Def applyMapping ``` def applyMapping( mappings : Seq[Product4[String, String, String, String]], caseSensitive : Boolean = true, transformationContext : String = "", callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` + `mappings` – 用來建構新 `DynamicFrame` 的映射序列。 + `caseSensitive` – 是否將來源欄位視為區分大小寫。將此設定為 false 可能有助於與不區分大小寫的存放區整合，例如 AWS Glue Data Catalog。 依據映射序列選取、投影及投射欄位。 每個映射皆由來源欄位和類型以及目標欄位和類型所組成。映射可能會指定為四元組 (`source_path`、`source_type`、` target_path`、`target_type`) 或包含相同資訊的 [MappingSpec](glue-etl-scala-apis-glue-mappingspec.md) 物件。 映射除了可用來進行簡單的投影與投射，還可以用來將欄位巢狀化或解除巢狀化 (藉由使用「`.`」(句點) 分隔路徑元件來達成)。 例如，假設您有內含結構描述如下的 `DynamicFrame`。 ``` {{{ root |-- name: string |-- age: int |-- address: struct | |-- state: string | |-- zip: int }}} ``` 您可以進行以下呼叫來將 `state` 和 `zip` 欄位解除巢狀化。 ``` {{{ df.applyMapping( Seq(("name", "string", "name", "string"), ("age", "int", "age", "int"), ("address.state", "string", "state", "string"), ("address.zip", "int", "zip", "int"))) }}} ``` 產生的結構描述如下。 ``` {{{ root |-- name: string |-- age: int |-- state: string |-- zip: int }}} ``` 您也可以使用 `applyMapping` 來將欄位重新巢狀化。例如，以下會反轉之前的轉換並在目標中建立名為 `address` 的結構。 ``` {{{ df.applyMapping( Seq(("name", "string", "name", "string"), ("age", "int", "age", "int"), ("state", "string", "address.state", "string"), ("zip", "int", "address.zip", "int"))) }}} ``` 可使用反引號 (````) 來括住包含「`.`」(句點) 字元的欄位名稱。 **注意** 您目前無法使用 `applyMapping` 方法來映射於陣列下的巢狀欄位。 ## Def assertErrorThreshold ``` def assertErrorThreshold : Unit ``` 強制運算與驗證錯誤記錄數低於 `stageThreshold` 與 `totalThreshold` 的動作。如果任一條件失敗，將會擲出例外狀況。 ## Def count ``` lazy def count ``` 傳回此 `DynamicFrame` 中的元素數量。 ## Def dropField ``` def dropField( path : String, transformationContext : String = "", callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` 傳回已移除指定欄位的新 `DynamicFrame`。 ## Def dropFields ``` def dropFields( fieldNames : Seq[String], // The column names to drop. transformationContext : String = "", callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` 傳回已移除指定欄位的新 `DynamicFrame`。 您可以使用這個方法來刪除巢狀欄位 (包括陣列中的巢狀欄位)，但不能丟棄特定陣列元素。 ## Def dropNulls ``` def dropNulls( transformationContext : String = "", callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0 ) ``` 傳回新的 `DynamicFrame` 並移除所有 null 欄位。 **注意** 這只會移除 `NullType` 類型的欄位。其他欄位中的個別 null 值不會被移除或修改。 ## Def errorsAsDynamicFrame ``` def errorsAsDynamicFrame ``` 傳回包含此 `DynamicFrame` 錯誤記錄的新 `DynamicFrame`。 ## Def filter ``` def filter( f : DynamicRecord => Boolean, errorMsg : String = "", transformationContext : String = "", callSite : CallSite = CallSite("Not provided"), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` 建構新的 `DynamicFrame`，其中僅包含函數「`f`」傳回 `true` 的那些記錄。篩選條件函數「`f`」不應使輸入記錄產生變化。 ## Def getName ``` def getName : String ``` 傳回此 `DynamicFrame` 的名稱。 ## Def getNumPartitions ``` def getNumPartitions ``` 傳回此 `DynamicFrame` 中的分割區數量。 ## Def getSchemaIfComputed ``` def getSchemaIfComputed : Option[Schema] ``` 如果結構描述已經計算，即傳回結構描述。如果結構描述尚未計算，則不掃描資料。 ## Def isSchemaComputed ``` def isSchemaComputed : Boolean ``` 如果此 `DynamicFrame` 的結構描述已經計算，即傳回 `true`，否則傳回 `false`。如果此方法傳回 false，則呼叫 `schema` 方法需要另一個結構描述來在此 `DynamicFrame` 中傳遞記錄。 ## Def javaToPython ``` def javaToPython : JavaRDD[Array[Byte]] ``` ## Def join ``` def join( keys1 : Seq[String], keys2 : Seq[String], frame2 : DynamicFrame, transformationContext : String = "", callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` + `keys1` – 此 `DynamicFrame` 中要用於聯結的欄位。 + `keys2` – `frame2` 中要用於聯結的欄位。長度必須與 `keys1` 相同。 + `frame2` – 要據以加入的 `DynamicFrame`。 傳回使用指定金鑰以 `frame2` 執行對等聯結的結果。 ## Def map ``` def map( f : DynamicRecord => DynamicRecord, errorMsg : String = "", transformationContext : String = "", callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` 傳回藉由將指定函數「`f`」套用至此 `DynamicFrame` 中各個記錄而建構的新 `DynamicFrame`。 此方法會在套用指定的函數之前複製每個記錄，因此可以安全地改變記錄。如果映射函數在指定的記錄擲出例外狀況，會將該記錄標示為錯誤，而會將堆疊追蹤儲存為錯誤記錄中的欄位。 ## Def mergeDynamicFrames ``` def mergeDynamicFrames( stageDynamicFrame: DynamicFrame, primaryKeys: Seq[String], transformationContext: String = "", options: JsonOptions = JsonOptions.empty, callSite: CallSite = CallSite("Not provided"), stageThreshold: Long = 0, totalThreshold: Long = 0): DynamicFrame ``` + `stageDynamicFrame` – 要合併的暫存 `DynamicFrame`。 + `primaryKeys` – 要從來源和暫存 `DynamicFrame` 比對記錄的主索引鍵欄位清單。 + `transformationContext` – 用來擷取目前轉換之中繼資料的唯一字串 (選用)。 + `options` – JSON 名稱值組的字串，可提供此轉換的額外資料。 + `callSite` – 用於提供錯誤報告的內容資訊。 + `stageThreshold` – A `Long`。在給定轉換中的錯誤數量，其處理需要輸出錯誤。 + `totalThreshold` – A `Long`。在此轉換之前 (包括在此轉換中) 的錯誤總數，其處理需要輸出錯誤。 根據指定的主索引鍵來合併此 `DynamicFrame` 與暫存 `DynamicFrame` 以識別記錄。重複的記錄 (具有相同主索引鍵的記錄) 不會被刪除重複資料。如果暫存影格中沒有相符的記錄，則會保留來源中的所有記錄 (包括重複項)。如果暫存影格具有相符的記錄，則暫存影格中的記錄會覆寫 AWS Glue 中來源的記錄。 在下列情況下，傳回的 `DynamicFrame` 包含記錄 A： 1. 如果 `A` 同時存在於來源影格和暫存影格，則會傳回暫存影格中的 `A`。 1. 如果 `A` 位於來源資料表中而 `A.primaryKeys` 不在 `stagingDynamicFrame` 中 (這表示 `A` 未在暫存資料表中更新)。 來源影格和暫存影格不需要具有相同的結構描述。 **Example** ``` val mergedFrame: DynamicFrame = srcFrame.mergeDynamicFrames(stageFrame, Seq("id1", "id2")) ``` ## Def printSchema ``` def printSchema : Unit ``` 以人類可讀取的格式，將此 `DynamicFrame` 的結構描述列印至 `stdout`。 ## Def recomputeSchema ``` def recomputeSchema : Schema ``` 強制結構描述重新計算。這需要掃描資料，但如果目前的結構描述中有一些欄位不存在於資料中，則可能會「限鎖」結構描述。 傳回重新計算的結構描述。 ## Def relationalize ``` def relationalize( rootTableName : String, stagingPath : String, options : JsonOptions = JsonOptions.empty, transformationContext : String = "", callSite : CallSite = CallSite("Not provided"), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : Seq[DynamicFrame] ``` + `rootTableName` – 在輸出中用於基本 `DynamicFrame` 的名稱。藉由旋轉陣列所建立的 `DynamicFrame` 會以此做為字首。 + `stagingPath` – Amazon Simple Storage Service (Amazon S3) 路徑，用來寫入中繼資料。 + `options` – 關聯化選項和組態。目前未使用。 將所有巢狀結構平面化並將陣列旋轉為單獨的資料表。 您可以使用此操作來準備深度巢狀資料，以將該資料擷取至關聯式資料庫。巢狀結構以相同於 [Unnest](#glue-etl-scala-apis-glue-dynamicframe-class-defs-unnest) 轉換的方式平面化。此外，系統會將陣列旋轉為單獨的資料表，每個陣列元素都將成為資料列。例如，假設您有含以下資料的 `DynamicFrame`。 ``` {"name": "Nancy", "age": 47, "friends": ["Fred", "Lakshmi"]} {"name": "Stephanie", "age": 28, "friends": ["Yao", "Phil", "Alvin"]} {"name": "Nathan", "age": 54, "friends": ["Nicolai", "Karen"]} ``` 執行下列程式碼。 ``` {{{ df.relationalize("people", "s3:/my_bucket/my_path", JsonOptions.empty) }}} ``` 這會產生兩個資料表。第一個資料表名為「people」，並包含下列項目。 ``` {{{ {"name": "Nancy", "age": 47, "friends": 1} {"name": "Stephanie", "age": 28, "friends": 2} {"name": "Nathan", "age": 54, "friends": 3) }}} ``` 在此，friends 陣列已替換為自動產生的聯結索引鍵。建立名為 `people.friends` 的個別資料表，內含以下內容。 ``` {{{ {"id": 1, "index": 0, "val": "Fred"} {"id": 1, "index": 1, "val": "Lakshmi"} {"id": 2, "index": 0, "val": "Yao"} {"id": 2, "index": 1, "val": "Phil"} {"id": 2, "index": 2, "val": "Alvin"} {"id": 3, "index": 0, "val": "Nicolai"} {"id": 3, "index": 1, "val": "Karen"} }}} ``` 在此資料表中，「`id`」是一種聯結索引鍵，可識別陣列元素來自哪些記錄，「`index`」會參照原始陣列中的位置，而「`val`」則是實際的陣列項目。 `relationalize` 方法會傳回藉由將此程序遞迴套用至所有陣列而建立的一系列 `DynamicFrame`。 **注意** AWS Glue 程式庫會為新表格自動產生聯結索引鍵。為了確保聯結索引鍵在任務執行中是唯一的，您必須啟用任務書籤。 ## Def renameField ``` def renameField( oldName : String, newName : String, transformationContext : String = "", callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` + `oldName` – 欄位的原始名稱。 + `newName` – 欄位的新名稱。 傳回已重新命名指定欄位的新 `DynamicFrame`。 您可以使用這個方法來重新命名巢狀欄位。例如，以下程式碼會將地址結構中的 `state` 重新命名為 `state_code`。 ``` {{{ df.renameField("address.state", "address.state_code") }}} ``` ## Def repartition ``` def repartition( numPartitions : Int, transformationContext : String = "", callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` 傳回包含 `numPartitions` 分割區的新 `DynamicFrame`。 ## Def resolveChoice ``` def resolveChoice( specs : Seq[Product2[String, String]] = Seq.empty[ResolveSpec], choiceOption : Option[ChoiceOption] = None, database : Option[String] = None, tableName : Option[String] = None, transformationContext : String = "", callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` + `choiceOption` – 套用到所有未在規格序列中列出之 `ChoiceType` 欄位的動作。 + `database` – 搭配 `match_catalog` 動作使用的 Data Catalog 資料庫。 + `tableName` – 搭配 `match_catalog` 動作使用的 Data Catalog 資料表。 使用更為特定的類型取代一或多個 `ChoiceType` 以傳回新 `DynamicFrame`。 有兩種方式可以使用 `resolveChoice`。第一種是指定一系列的特定的欄以及解析它們的方式。這些是指定為由 (欄位、動作) 配對所組成的元組。 可行的動作如下： + `cast:type` – 嘗試將所有值投射至指定類型。 + `make_cols` – 將每個不同的類型轉換為具有 `columnName_type` 名稱的欄位。 + `make_struct` – 將欄位轉換為每個不同類型皆有金鑰的結構。 + `project:type` – 僅保留指定類型的值。 `resolveChoice` 的其他模式可為所有 `ChoiceType` 指定單一解析度。您可以在 `ChoiceType` 的完整清單在執行之前是未知的情況下使用此模式。除了以上列出的動作，此模式也支援下列動作： + `match_catalog``ChoiceType` – 嘗試將每個 投射至指定目錄資料表中的對應類型。 **範例**： 藉由投射至 int 以解析 `user.id` 欄位，並且讓 `address` 欄位僅保留結構。 ``` {{{ df.resolveChoice(specs = Seq(("user.id", "cast:int"), ("address", "project:struct"))) }}} ``` 藉由將每個選擇轉換單獨的欄位以解析所有 `ChoiceType`。 ``` {{{ df.resolveChoice(choiceOption = Some(ChoiceOption("make_cols"))) }}} ``` 藉由投射至指定目錄資料表中的類型以解析所有 `ChoiceType`。 ``` {{{ df.resolveChoice(choiceOption = Some(ChoiceOption("match_catalog")), database = Some("my_database"), tableName = Some("my_table")) }}} ``` ## Def schema ``` def schema : Schema ``` 傳回此 `DynamicFrame` 的結構描述。 傳回的結構描述會保證包含於此 `DynamicFrame` 中之記錄存在的每個欄位。但在少數情況下，它也可能包含額外的欄位。您可以使用 [Unnest](#glue-etl-scala-apis-glue-dynamicframe-class-defs-unnest) 方法，依據此 `DynamicFrame` 中的記錄來「限縮」結構描述。 ## Def selectField ``` def selectField( fieldName : String, transformationContext : String = "", callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` 以 `DynamicFrame` 傳回單一欄位。 ## Def selectFields ``` def selectFields( paths : Seq[String], transformationContext : String = "", callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` + `paths` – 要選取的欄位名稱序列。 傳回包含指定欄位的新 `DynamicFrame`。 **注意** 您只能使用 `selectFields` 方法來選取最上層欄位。您可以使用 [applyMapping](#glue-etl-scala-apis-glue-dynamicframe-class-defs-applyMapping) 方法來選取巢狀欄位。 ## Def show ``` def show( numRows : Int = 20 ) : Unit ``` + `numRows` – 要列印的資料列數。 以 JSON 格式列印此 `DynamicFrame` 的資料列。 ## Def simplifyDDBJson DynamoDB 會使用 AWS Glue DynamoDB 匯出連接器進行匯出，這會產生具有特定巢套結構的 JSON 檔案。如需詳細資訊，請參閱[資料物件](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/S3DataExport.Output.html)。`simplifyDDBJson`簡化此類資料的 DynamicFrame 中的巢狀資料欄，並傳回新的簡化 DynamicFrame。如果 List 類型中包含多種類型或 Map 類型，則 List 中的元素不會進行簡化。此方法僅支援 DynamoDB 匯出 JSON 格式的資料。考慮 `unnest` 對其他類型的資料執行類似的變更。 ``` def simplifyDDBJson() : DynamicFrame ``` 此方法不接受任何參數。 **範例輸入** 請考慮由 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 ``` **範例程式碼** ``` 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.SparkContextimport 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" -> "ddbTableARN", "dynamodb.s3.bucket" -> "exportBucketLocation", "dynamodb.s3.prefix" -> "exportBucketPrefix", "dynamodb.s3.bucketOwner" -> "exportBucketAccountID", )) ).getDynamicFrame() val simplified = dynamicFrame.simplifyDDBJson() simplified.printSchema() Job.commit() } } ``` ### 範例輸出 `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 ``` ## Def spigot ``` def spigot( path : String, options : JsonOptions = new JsonOptions("{}"), transformationContext : String = "", callSite : CallSite = CallSite("Not provided"), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` 傳遞轉換以傳回相同的記錄，但副作用是寫出部分記錄。 + `path` – 以 `s3://bucket//path` 格式將輸出寫入至 Amazon S3 中的路徑。 + `options` – 描述取樣行為的選用 `JsonOptions` 映射。 傳回包含與此相同記錄的 `DynamicFrame`。 在預設情況下，寫入 100 任意記錄到 `path` 指定的位置。您可以使用 `options` 對應來自訂此行為。有效索引鍵包括下列： + `topk` – 指定寫出的記錄總數。預設為 100。 + `prob` – 指定包含個別記錄的機率 (以小數表示)。預設值為 1。 例如，以下呼叫取樣資料集的方式是以 20% 的可能性選取每個記錄，並在已寫入 200 個記錄之後停止。 ``` {{{ df.spigot("s3://my_bucket/my_path", JsonOptions(Map("topk" -> 200, "prob" -> 0.2))) }}} ``` ## Def splitFields ``` def splitFields( paths : Seq[String], transformationContext : String = "", callSite : CallSite = CallSite("Not provided", ""), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : Seq[DynamicFrame] ``` + `paths` – 要包含在第一個 `DynamicFrame` 中的路徑。 傳回兩個 `DynamicFrame` 的序列。第一個 `DynamicFrame` 包含指定的路徑，第二個包含所有其他欄。 **範例** 此範例採用從 AWS Glue Data Catalog 中`legislators`資料庫中`persons`資料表建立的 DynamicFrame，並將 DynamicFrame 分割為兩個，其中指定的欄位進入第一個 DynamicFrame，其餘欄位進入第二個 DynamicFrame。然後，該範例從結果中選擇第一個 DynamicFrame。 ``` val InputFrame = glueContext.getCatalogSource(database="legislators", tableName="persons", transformationContext="InputFrame").getDynamicFrame() val SplitField_collection = InputFrame.splitFields(paths=Seq("family_name", "name", "links.note", "links.url", "gender", "image", "identifiers.scheme", "identifiers.identifier", "other_names.lang", "other_names.note", "other_names.name"), transformationContext="SplitField_collection") val ResultFrame = SplitField_collection(0) ``` ## Def splitRows ``` def splitRows( paths : Seq[String], values : Seq[Any], operators : Seq[String], transformationContext : String, callSite : CallSite, stageThreshold : Long, totalThreshold : Long ) : Seq[DynamicFrame] ``` 根據比較欄位與常數的述詞來分割列。 + `paths` – 用於比較的欄位。 + `values` – 用於比較的常數值。 + `operators` – 用於比較的運算子。 傳回兩個 `DynamicFrame` 的序列。第一個包含述詞為 true 的列，第二個包含述詞為 false 的列。 使用三個序列指定述詞：「`paths`」包含 (可能為巢狀) 欄位名稱、「`values`」包含要比較的常數值，以及「`operators`」包含用於比較的運算子。這三個序列的長度必須相同：第 `n` 個運算子會用於比較第 `n` 個欄位與第 `n` 個值。 每個運算子都必須是「`!=`」、「`=`」、「`<=`」、「`<`」、「`>=`」或「`>`」其中之一。 舉例來說，以下呼叫會分割 `DynamicFrame`，因此第一個輸出框架會包含來自美國超過 65 人的記錄，第二個會包含所有其他記錄。 ``` {{{ df.splitRows(Seq("age", "address.country"), Seq(65, "USA"), Seq(">=", "=")) }}} ``` ## Def stageErrorsCount ``` def stageErrorsCount ``` 傳回運算此 `DynamicFrame` 時建立的錯誤記錄的數量。這會排除之前傳遞至此 `DynamicFrame` 做為輸入之操作的錯誤。 ## Def toDF ``` def toDF( specs : Seq[ResolveSpec] = Seq.empty[ResolveSpec] ) : DataFrame ``` 以相同的結構描述和記錄，將此 `DynamicFrame` 轉換為 Apache Spark SQL `DataFrame`。 **注意** 由於 `DataFrame` 不支援 `ChoiceType`，因此這個方法會自動將 `ChoiceType` 欄轉換成 `StructType`。如需有關解析選擇的詳細資訊和選項，請參閱[resolveChoice](#glue-etl-scala-apis-glue-dynamicframe-class-defs-resolveChoice)。 ## Def unbox ``` def unbox( path : String, format : String, optionString : String = "{}", transformationContext : String = "", callSite : CallSite = CallSite("Not provided"), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` + `path` – 要剖析的欄。必須為字串或二進位。 + `format` – 用於剖析的格式。 + `optionString` – 傳送格式的選項，例如 CSV 分隔符號。 根據指定的格式，剖析嵌入字串或二進位欄位。剖析的欄位是具有原始資料欄名稱結構的巢狀欄位。 例如，假設您有 CSV 檔案與內嵌 JSON 欄位。 ``` name, age, address Sally, 36, {"state": "NE", "city": "Omaha"} ... ``` 完成初始剖析後，您會取得具有下列結構描述的 `DynamicFrame`。 ``` {{{ root |-- name: string |-- age: int |-- address: string }}} ``` 您可以呼叫地址欄位上的 `unbox` 以剖析特定元件。 ``` {{{ df.unbox("address", "json") }}} ``` 如此將提供我們具有下列結構描述的 `DynamicFrame`。 ``` {{{ root |-- name: string |-- age: int |-- address: struct | |-- state: string | |-- city: string }}} ``` ## Def unnest ``` def unnest( transformationContext : String = "", callSite : CallSite = CallSite("Not Provided"), stageThreshold : Long = 0, totalThreshold : Long = 0 ) : DynamicFrame ``` 傳回其所有巢狀結構皆已平面化的新 `DynamicFrame`。使用「`.`」(句點) 字元建構名稱。 例如，假設您有內含結構描述如下的 `DynamicFrame`。 ``` {{{ root |-- name: string |-- age: int |-- address: struct | |-- state: string | |-- city: string }}} ``` 以下呼叫將會解巢狀地址結構。 ``` {{{ df.unnest() }}} ``` 產生的結構描述如下。 ``` {{{ root |-- name: string |-- age: int |-- address.state: string |-- address.city: string }}} ``` 此方法也會解巢狀陣列中的巢狀結構。但因為歷史因素，這類欄位的名稱會附加封閉陣列和「`.val`」的名稱。 ## Def unnestDDBJson ``` unnestDDBJson(transformationContext : String = "", callSite : CallSite = CallSite("Not Provided"), stageThreshold : Long = 0, totalThreshold : Long = 0): DynamicFrame ``` 解除專屬於 DynamoDB JSON 結構中 `DynamicFrame` 內的巢狀欄的巢狀化，並傳回新的解巢狀 `DynamicFrame`。結構類型陣列的欄將不是解巢狀狀態。請注意，這是一種特定類型的解除巢狀化轉換，其行為與常規 `unnest` 轉換不同，且資料必須已經位於 DynamoDB JSON 結構中。如需詳細資訊，請參閱 [DynamoDB JSON](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataExport.Output.html#DataExport.Output.Data)。 例如，讀取 DynamoDB JSON 結構的匯出結構描述與以下類似： ``` root |-- Item: struct | |-- ColA: struct | | |-- S: string | |-- ColB: struct | | |-- S: string | |-- ColC: struct | | |-- N: string | |-- ColD: struct | | |-- L: array | | | |-- element: null ``` `unnestDDBJson()` 轉換會將此轉換為： ``` root |-- ColA: string |-- ColB: string |-- ColC: string |-- ColD: array | |-- element: null ``` 下列程式碼範例示範如何使用 AWS Glue DynamoDB 匯出連接器、叫用 DynamoDB JSON un巢狀，以及列印分割區數量： ``` 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" -> "", "dynamodb.s3.bucket" -> "", "dynamodb.s3.prefix" -> "", "dynamodb.s3.bucketOwner" -> "", )) ).getDynamicFrame() val unnested = dynamicFrame.unnestDDBJson() print(unnested.getNumPartitions()) Job.commit() } } ``` ## Def withFrameSchema ``` def withFrameSchema( getSchema : () => Schema ) : DynamicFrame ``` + `getSchema` – 傳回結構描述以供使用的函數。指定為零參數函數以延遲可能昂貴的運算。 將此 `DynamicFrame` 的結構描述設定為指定的值。這主要用於內部以避免昂貴的結構描述重新計算。傳入的結構描述必須包含存在於資料中的所有資料欄位。 ## Def withName ``` def withName( name : String ) : DynamicFrame ``` + `name` – 要使用的新名稱。 傳回此具有新名稱的 `DynamicFrame` 的副本。 ## Def withTransformationContext ``` def withTransformationContext( ctx : String ) : DynamicFrame ``` 傳回此具有指定轉換內容的 `DynamicFrame` 的副本。 # DynamicFrame 物件 **Package: com.amazonaws.services.glue** ``` object DynamicFrame ``` ## Def apply ``` def apply( df : DataFrame, glueContext : GlueContext ) : DynamicFrame ``` ## Def emptyDynamicFrame ``` def emptyDynamicFrame( glueContext : GlueContext ) : DynamicFrame ``` ## Def fromPythonRDD ``` def fromPythonRDD( rdd : JavaRDD[Array[Byte]], glueContext : GlueContext ) : DynamicFrame ``` ## Def ignoreErrors ``` def ignoreErrors( fn : DynamicRecord => DynamicRecord ) : DynamicRecord ``` ## Def inlineErrors ``` def inlineErrors( msg : String, callSite : CallSite ) : (DynamicRecord => DynamicRecord) ``` ## Def newFrameWithErrors ``` def newFrameWithErrors( prevFrame : DynamicFrame, rdd : RDD[DynamicRecord], name : String = "", transformationContext : String = "", callSite : CallSite, stageThreshold : Long, totalThreshold : Long ) : DynamicFrame ``` # AWS Glue Scala DynamicRecord 類別 **Topics** + [Def addField](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-addField) + [Def dropField](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-dropField) + [Def setError](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-setError) + [Def isError](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-isError) + [Def getError](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-getError) + [Def clearError](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-clearError) + [Def write](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-write) + [Def readFields](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-readFields) + [Def clone](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-clone) + [Def schema](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-schema) + [Def getRoot](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-getRoot) + [Def toJson](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-toJson) + [Def getFieldNode](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-getFieldNode) + [Def getField](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-getField) + [Def hashCode](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-hashCode) + [Def equals](#glue-etl-scala-apis-glue-dynamicrecord-class-defs-equals) + [DynamicRecord 物件](#glue-etl-scala-apis-glue-dynamicrecord-object) + [RecordTraverser 特徵](#glue-etl-scala-apis-glue-recordtraverser-trait) **Package: com.amazonaws.services.glue** ``` class DynamicRecord extends Serializable with Writable with Cloneable ``` `DynamicRecord` 本身是描述資料結構，其代表要處理的資料集內的資料列。其為自我描述，這表示您可以透過檢查記錄本身來取得由 `DynamicRecord` 所呈現的資料列資料結構。`DynamicRecord` 與 Apache Spark 中的 `Row` 類似。 ## Def addField ``` def addField( path : String, dynamicNode : DynamicNode ) : Unit ``` 將 [DynamicNode](glue-etl-scala-apis-glue-types-dynamicnode.md) 新增到指定的路徑。 + `path` — 要新增的欄位路徑。 + `dynamicNode` — 要在指定路徑中新增的 [DynamicNode](glue-etl-scala-apis-glue-types-dynamicnode.md)。 ## Def dropField ``` def dropField(path: String, underRename: Boolean = false): Option[DynamicNode] ``` 如果指定的路徑中沒有任何陣列，則從指定的路徑放入 [DynamicNode](glue-etl-scala-apis-glue-types-dynamicnode.md) 並傳回放入的節點。 + `path` — 要放入的欄位路徑。 + `underRename``dropField` — 若在更名轉換期間呼叫 則為 true，否則為 false (預設為 false)。 傳回 `scala.Option Option` ([DynamicNode](glue-etl-scala-apis-glue-types-dynamicnode.md))。 ## Def setError ``` def setError( error : Error ) ``` 將此記錄設定為錯誤記錄，如 `error` 參數所指定。 傳回 `DynamicRecord`。 ## Def isError ``` def isError ``` 檢查此記錄是否是錯誤記錄。 ## Def getError ``` def getError ``` 如果記錄是錯誤記錄，則取得 `Error`。如果此記錄是錯誤記錄，傳回 `scala.Some Some` (錯誤)，否則傳回 `scala.None`。 ## Def clearError ``` def clearError ``` 將 `Error` 設定為 `scala.None.None`。 ## Def write ``` override def write( out : DataOutput ) : Unit ``` ## Def readFields ``` override def readFields( in : DataInput ) : Unit ``` ## Def clone ``` override def clone : DynamicRecord ``` 將此記錄複製到新 `DynamicRecord` 並將其傳回。 ## Def schema ``` def schema ``` 檢查記錄以取得 `Schema`。 ## Def getRoot ``` def getRoot : ObjectNode ``` 取得記錄的根 `ObjectNode`。 ## Def toJson ``` def toJson : String ``` 取得記錄的 JSON 字串。 ## Def getFieldNode ``` def getFieldNode( path : String ) : Option[DynamicNode] ``` 在指定的 `path` 取得欄位值做為 `DynamicNode` 的選項。 如果欄位存在，傳回 `scala.Some Some` ([DynamicNode](glue-etl-scala-apis-glue-types-dynamicnode.md))，否則傳回 `scala.None.None`。 ## Def getField ``` def getField( path : String ) : Option[Any] ``` 在指定的 `path` 取得欄位值做為 `DynamicNode` 的選項。 傳回 `scala.Some Some` (值)。 ## Def hashCode ``` override def hashCode : Int ``` ## Def equals ``` override def equals( other : Any ) ``` ## DynamicRecord 物件 ``` object DynamicRecord ``` ### Def apply ``` def apply( row : Row, schema : SparkStructType ) ``` 套用將 Apache Spark SQL `Row` 轉換為 [DynamicRecord](#glue-etl-scala-apis-glue-dynamicrecord-class) 的方法。 + `row` — Spark SQL `Row`。 + `schema` — 該資料列的 `Schema`。 傳回 `DynamicRecord`。 ## RecordTraverser 特徵 ``` trait RecordTraverser { def nullValue(): Unit def byteValue(value: Byte): Unit def binaryValue(value: Array[Byte]): Unit def booleanValue(value: Boolean): Unit def shortValue(value: Short) : Unit def intValue(value: Int) : Unit def longValue(value: Long) : Unit def floatValue(value: Float): Unit def doubleValue(value: Double): Unit def decimalValue(value: BigDecimal): Unit def stringValue(value: String): Unit def dateValue(value: Date): Unit def timestampValue(value: Timestamp): Unit def objectStart(length: Int): Unit def objectKey(key: String): Unit def objectEnd(): Unit def mapStart(length: Int): Unit def mapKey(key: String): Unit def mapEnd(): Unit def arrayStart(length: Int): Unit def arrayEnd(): Unit } ``` # AWS Glue Scala GlueContext API **Package: com.amazonaws.services.glue** ``` class GlueContext extends SQLContext(sc) ( @transient val sc : SparkContext, val defaultSourcePartitioner : PartitioningStrategy ) ``` `GlueContext` 是讀取和寫入 [DynamicFrame](glue-etl-scala-apis-glue-dynamicframe.md) 至 Amazon Simple Storage Service (Amazon S3)、 AWS Glue Data Catalog 、JDBC 等的進入點。此類別提供公用程式函數來建立 [DataSource 特徵](glue-etl-scala-apis-glue-datasource-trait.md) 和 [DataSink](glue-etl-scala-apis-glue-datasink-class.md) 物件，從而用於讀取和寫入 `DynamicFrame`。 如果從來源建立的分割區數低於分割區的閾值下限 (預設 10)，您也可以使用 `GlueContext` 來設定在 `DynamicFrame` 中的分割區目標數 (預設 20)。 ## def addIngestionTimeColumns ``` def addIngestionTimeColumns( df : DataFrame, timeGranularity : String = "") : dataFrame ``` 附加擷取時間欄 (如 `ingest_year`、`ingest_month`、`ingest_day`、`ingest_hour`、`ingest_minute`) 到輸入 `DataFrame`。當您指定以 Amazon S3 為目標的 Data Catalog 資料表時，此函數會在 AWS Glue 產生的指令碼中自動產生。此函數會自動使用輸出資料表上的擷取時間欄來更新分割區。這可讓輸出資料在擷取時間自動分割，而不需要輸入資料中的明確擷取時間欄。 + `dataFrame` – 要將擷取時間欄附加到的 `dataFrame`。 + `timeGranularity` – 時間欄的精密程度。有效值為 "`day`"、"`hour`" 和 "`minute`"。例如：如果 "`hour`" 被傳遞給函數，原始 `dataFrame` 會附加上 "`ingest_year`"、"`ingest_month`"、"`ingest_day`" 和 "`ingest_hour`" 時間欄。 傳回附加時間粒度欄後的資料框架。 範例： ``` glueContext.addIngestionTimeColumns(dataFrame, "hour") ``` ## def createDataFrameFromOptions ``` def createDataFrameFromOptions( connectionType : String, connectionOptions : JsonOptions, transformationContext : String = "", format : String = null, formatOptions : JsonOptions = JsonOptions.empty ) : DataSource ``` 傳回使用指定的連線和格式建立的 `DataFrame`。此函數僅適用於 Glue AWS 串流來源。 + `connectionType` – 串流連線類型。有效值包括 `kinesis` 與 `kafka`。 + `connectionOptions` – 連線選項，這些選項對於 Kinesis 和 Kafka 而言是不同的。您可以在 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md) 中找到每個串流資料來源的所有連線選項清單。請注意串流連線選項的下列不同處： + Kinesis 串流來源需要 `streamARN`、`startingPosition`、`inferSchema` 以及 `classification`。 + Kafka 串流來源需要 `connectionName`、`topicName`、`startingOffsets`、`inferSchema` 以及 `classification`。 + `transformationContext` – 要使用的轉換細節 (選用)。 + `format` – 格式化規格 (選用)。這是用於 Amazon S3 或支援多種格式的 AWS Glue 連線。如需有關支援格式的資訊，請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md) + `formatOptions` – 指定格式的格式選項。如需支援格式選項的詳細資訊，請參閱 [資料格式選項](aws-glue-programming-etl-format.md)。 Amazon Kinesis 串流來源範例： ``` val data_frame_datasource0 = glueContext.createDataFrameFromOptions(transformationContext = "datasource0", connectionType = "kinesis", connectionOptions = JsonOptions("""{"streamName": "example_stream", "startingPosition": "TRIM_HORIZON", "inferSchema": "true", "classification": "json"}}""")) ``` Kafka 串流來源範例： ``` val data_frame_datasource0 = glueContext.createDataFrameFromOptions(transformationContext = "datasource0", connectionType = "kafka", connectionOptions = JsonOptions("""{"connectionName": "example_connection", "topicName": "example_topic", "startingPosition": "earliest", "inferSchema": "false", "classification": "json", "schema":"`column1` STRING, `column2` STRING"}""")) ``` ## forEachBatch **`forEachBatch(frame, batch_function, options)`** 將傳入的 `batch_function` 套用至從串流來源讀取的每個微批次。 + `frame` – 包含目前微批次的 DataFrame。 + `batch_function` – 將套用至每個微批次的函數。 + `options` – 索引鍵/值配對的集合，其中包含如何處理微批次的相關資訊。下列選項是必要的： + `windowSize` – 處理每個批次的時間量。 + `checkpointLocation` - 串流 ETL 任務的檢查點儲存位置。 + `batchMaxRetries` – 如果失敗，可重試批次的次數上限。預設值為 3。此選項僅在 Glue 2.0 及以上版本上才可設定。 **範例**： ``` glueContext.forEachBatch(data_frame_datasource0, (dataFrame: Dataset[Row], batchId: Long) => { if (dataFrame.count() > 0) { val datasource0 = DynamicFrame(glueContext.addIngestionTimeColumns(dataFrame, "hour"), glueContext) // @type: DataSink // @args: [database = "tempdb", table_name = "fromoptionsoutput", stream_batch_time = "100 seconds", // stream_checkpoint_location = "s3://from-options-testing-eu-central-1/fromOptionsOutput/checkpoint/", // transformation_ctx = "datasink1"] // @return: datasink1 // @inputs: [frame = datasource0] val options_datasink1 = JsonOptions( Map("partitionKeys" -> Seq("ingest_year", "ingest_month","ingest_day", "ingest_hour"), "enableUpdateCatalog" -> true)) val datasink1 = glueContext.getCatalogSink( database = "tempdb", tableName = "fromoptionsoutput", redshiftTmpDir = "", transformationContext = "datasink1", additionalOptions = options_datasink1).writeDynamicFrame(datasource0) } }, JsonOptions("""{"windowSize" : "100 seconds", "checkpointLocation" : "s3://from-options-testing-eu-central-1/fromOptionsOutput/checkpoint/"}""")) ``` ## def getCatalogSink ``` def getCatalogSink( database : String, tableName : String, redshiftTmpDir : String = "", transformationContext : String = "" additionalOptions: JsonOptions = JsonOptions.empty, catalogId: String = null ) : DataSink ``` 建立 [DataSink](glue-etl-scala-apis-glue-datasink-class.md)，以便寫入 Data Catalog 中定義之資料表中指定的位置。 + `database` —  Data Catalog 中的資料庫名稱。 + `tableName` —  Data Catalog 中的資料表名稱。 + `redshiftTmpDir` — 要與特定資料目的地搭配使用的臨時暫存目錄。設定為 預設為空值。 + `transformationContext` — 與由任務書籤使用之目的地關聯的轉換內容。設定為 預設為空值。 + `additionalOptions` – 提供給 AWS Glue 的額外選項。 + `catalogId` — 要存取之 Data Catalog 的目錄 ID (帳戶 ID)。為 null 時，會使用發起人的預設帳戶 ID。 傳回 `DataSink`。 ## def getCatalogSource ``` def getCatalogSource( database : String, tableName : String, redshiftTmpDir : String = "", transformationContext : String = "" pushDownPredicate : String = " " additionalOptions: JsonOptions = JsonOptions.empty, catalogId: String = null ) : DataSource ``` 建立 [DataSource 特徵](glue-etl-scala-apis-glue-datasource-trait.md)，以便從 Data Catalog 中的資料表定義中讀取資料。 + `database` —  Data Catalog 中的資料庫名稱。 + `tableName` —  Data Catalog 中的資料表名稱。 + `redshiftTmpDir` — 要與特定資料目的地搭配使用的臨時暫存目錄。設定為 預設為空值。 + `transformationContext` — 與由任務書籤使用之目的地關聯的轉換內容。設定為 預設為空值。 + `pushDownPredicate` – 篩選分割區，而無需列出和讀取資料集中的所有檔案。如需詳細資訊，請參閱[使用 pushdown 述詞預先篩選](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-pushdowns)。 + `additionalOptions` – 選擇性的名稱/值對的集合。可能的選項包括 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md) 中列出的項目，除了 `endpointUrl`、`streamName`、`bootstrap.servers`、`security.protocol`、`topicName`、`classification` 以及`delimiter`。另一個支援的選項是 `catalogPartitionPredicate`： `catalogPartitionPredicate` — 您可以傳遞目錄表達式以根據索引欄進行篩選。這會將篩選下推至伺服器端。如需詳細資訊，請參閱 [AWS Glue 分割區索引](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html)。注意 `push_down_predicate` 和 `catalogPartitionPredicate` 使用不同的語法。前者使用 Spark SQL 標準語法，後者使用 JSQL 剖析器。 + `catalogId` — 要存取之 Data Catalog 的目錄 ID (帳戶 ID)。為 null 時，會使用發起人的預設帳戶 ID。 傳回 `DataSource`。 **串流來源範例** ``` val data_frame_datasource0 = glueContext.getCatalogSource( database = "tempdb", tableName = "test-stream-input", redshiftTmpDir = "", transformationContext = "datasource0", additionalOptions = JsonOptions("""{ "startingPosition": "TRIM_HORIZON", "inferSchema": "false"}""") ).getDataFrame() ``` ## def getJDBCSink ``` def getJDBCSink( catalogConnection : String, options : JsonOptions, redshiftTmpDir : String = "", transformationContext : String = "", catalogId: String = null ) : DataSink ``` 建立 [DataSink](glue-etl-scala-apis-glue-datasink-class.md)，以便寫入 Data Catalog 中 `Connection` 物件所指定的 JDBC 資料庫。此 `Connection` 物件擁有用來對 JDBC 目的地連線的資訊 (包括 URL、使用者名稱、密碼、VPC、子網路和安全群組)。 + `catalogConnection` —  Data Catalog 中的連線名稱，其中包含要做為寫入目的地之 JDBC URL。 + `options` — JSON 名稱值組的字串，可提供寫入 JDBC 資料存放區所需的其他資訊。其中包含： + *dbtable* (必要) — JDBC 資料表的名稱。若是支援資料庫內結構描述的 JDBC 資料存放區，請指定 `schema.table-name`。如果未提供結構描述，則會使用預設的 "public" 結構描述。以下範例說明 options 參數，它會指向資料庫 `test_db` 中名為 `test` 的結構描述和名為 `test_table` 的資料表。 ``` options = JsonOptions("""{"dbtable": "test.test_table", "database": "test_db"}""") ``` + *database* (必要) — JDBC 資料庫的名稱。 + 任何其他選項都會直接傳遞至 SparkSQL JDBC 寫入器。如需詳細資訊，請參閱 [Spark 的 Redshift 資料來源](https://github.com/databricks/spark-redshift)。 + `redshiftTmpDir` — 要與特定資料目的地搭配使用的臨時暫存目錄。設定為 預設為空值。 + `transformationContext` — 與由任務書籤使用之目的地關聯的轉換內容。設定為 預設為空值。 + `catalogId` — 要存取之 Data Catalog 的目錄 ID (帳戶 ID)。為 null 時，會使用發起人的預設帳戶 ID。 範例程式碼： ``` getJDBCSink(catalogConnection = "my-connection-name", options = JsonOptions("""{"dbtable": "my-jdbc-table", "database": "my-jdbc-db"}"""), redshiftTmpDir = "", transformationContext = "datasink4") ``` 傳回 `DataSink`。 ## def getSink ``` def getSink( connectionType : String, connectionOptions : JsonOptions, transformationContext : String = "" ) : DataSink ``` 建立 [DataSink](glue-etl-scala-apis-glue-datasink-class.md)，將資料寫入 Amazon Simple Storage Service (Amazon S3)、JDBC 或 AWS Glue Data Catalog 等目的地，或 Apache Kafka 或 Amazon Kinesis 資料串流。 + `connectionType` — 連線的類型。請參閱 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `connectionOptions` — JSON 名稱值組的字串，可提供與資料目的地建立連線的額外資料。請參閱 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `transformationContext` — 與由任務書籤使用之目的地關聯的轉換內容。設定為 預設為空值。 傳回 `DataSink`。 ## def getSinkWithFormat ``` def getSinkWithFormat( connectionType : String, options : JsonOptions, transformationContext : String = "", format : String = null, formatOptions : JsonOptions = JsonOptions.empty ) : DataSink ``` 建立 [DataSink](glue-etl-scala-apis-glue-datasink-class.md)，以將資料寫入至目的地，如 Amazon S3、JDBC、Data Catalog、Apache Kafka 或 Amazon Kinesis 資料串流。亦設定要寫出至目的地的資料格式。 + `connectionType` — 連線的類型。請參閱 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `options` — JSON 名稱值組的字串，可提供與資料目的地建立連線的額外資料。請參閱 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `transformationContext` — 與由任務書籤使用之目的地關聯的轉換內容。設定為 預設為空值。 + `format` — 要從目的地寫出的資料格式。 + `formatOptions` — JSON 名稱值組的字串，會提供在目的地格式化資料的其他選項。請參閱 [資料格式選項](aws-glue-programming-etl-format.md)。 傳回 `DataSink`。 ## def getSource ``` def getSource( connectionType : String, connectionOptions : JsonOptions, transformationContext : String = "" pushDownPredicate ) : DataSource ``` 建立從 Amazon S3、JDBC 或 Glue Data Catalog AWS 等來源[DataSource 特徵](glue-etl-scala-apis-glue-datasource-trait.md)讀取資料的 。也支援 Kafka 和 Kinesis 串流資料來源。 + `connectionType` — 資料來源的類型。請參閱 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `connectionOptions` — JSON 名稱值組的字串，可提供與資料來源建立連線的額外資料。如需詳細資訊，請參閱[AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 Kinesis 串流來源需要下列連線選項：`streamARN`、`startingPosition`、`inferSchema` 及 `classification`。 Kafka 串流來源需要以下連線選項：`connectionName`、`topicName`、`startingOffsets`、`inferSchema` 及 `classification`。 + `transformationContext` — 與由任務書籤使用之目的地關聯的轉換內容。設定為 預設為空值。 + `pushDownPredicate` — 分割區欄上的述詞。 傳回 `DataSource`。 Amazon Kinesis 串流來源範例： ``` val kinesisOptions = jsonOptions() data_frame_datasource0 = glueContext.getSource("kinesis", kinesisOptions).getDataFrame() private def jsonOptions(): JsonOptions = { new JsonOptions( s"""{"streamARN": "arn:aws:kinesis:eu-central-1:123456789012:stream/fromOptionsStream", |"startingPosition": "TRIM_HORIZON", |"inferSchema": "true", |"classification": "json"}""".stripMargin) } ``` Kafka 串流來源範例： ``` val kafkaOptions = jsonOptions() val data_frame_datasource0 = glueContext.getSource("kafka", kafkaOptions).getDataFrame() private def jsonOptions(): JsonOptions = { new JsonOptions( s"""{"connectionName": "ConfluentKafka", |"topicName": "kafka-auth-topic", |"startingOffsets": "earliest", |"inferSchema": "true", |"classification": "json"}""".stripMargin) } ``` ## def getSourceWithFormat ``` def getSourceWithFormat( connectionType : String, options : JsonOptions, transformationContext : String = "", format : String = null, formatOptions : JsonOptions = JsonOptions.empty ) : DataSource ``` 建立從 Amazon S3、JDBC 或 AWS Glue Data Catalog 等來源[DataSource 特徵](glue-etl-scala-apis-glue-datasource-trait.md)讀取資料的 ，也會設定存放在來源中的資料格式。 + `connectionType` – 資料來源的類型。請參閱 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `options` – JSON 名稱值組的字串，可提供與資料來源建立連線的額外資料。請參閱 [AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md)。 + `transformationContext` – 與由任務書籤使用之目的地關聯的轉換內容。設定為 預設為空值。 + `format` – 來源中所存放資料的格式。當 `connectionType` 為「s3」時，您也可以指定 `format`。可以是「avro」、「csv」、「grokLog」、「ion」、「json」、「xml」、「parquet」或「orc」其中之一。 + `formatOptions` – JSON 名稱值組的字串，會提供在來源剖析資料的其他選項。請參閱 [資料格式選項](aws-glue-programming-etl-format.md)。 傳回 `DataSource`。 **範例** 從 Amazon S3 上逗號分隔值 (CSV) 檔案的資料來源建立 DynamicFrame： ``` val datasource0 = glueContext.getSourceWithFormat( connectionType="s3", options =JsonOptions(s"""{"paths": [ "s3://csv/nycflights.csv"]}"""), transformationContext = "datasource0", format = "csv", formatOptions=JsonOptions(s"""{"withHeader":"true","separator": ","}""") ).getDynamicFrame() ``` 從使用 JDBC 連線的 PostgreSQL 資料來源建立 DynamicFrame： ``` val datasource0 = glueContext.getSourceWithFormat( connectionType="postgresql", options =JsonOptions(s"""{ "url":"jdbc:postgresql://databasePostgres-1.rds.amazonaws.com:5432/testdb", "dbtable": "public.company", "redshiftTmpDir":"", "user":"username", "password":"password123" }"""), transformationContext = "datasource0").getDynamicFrame() ``` 從使用 JDBC 連線的 MySQL 資料來源建立 DynamicFrame： ``` val datasource0 = glueContext.getSourceWithFormat( connectionType="mysql", options =JsonOptions(s"""{ "url":"jdbc:mysql://databaseMysql-1.rds.amazonaws.com:3306/testdb", "dbtable": "athenatest_nycflights13_csv", "redshiftTmpDir":"", "user":"username", "password":"password123" }"""), transformationContext = "datasource0").getDynamicFrame() ``` ## def getSparkSession ``` def getSparkSession : SparkSession ``` 取得與此 GlueContext 相關聯的 `SparkSession` 物件。使用此 SparkSession 物件以將資料表與 UDF 註冊為與從 DynamicFrames 建立的 `DataFrame` 搭配使用。 傳回 SparkSession。 ## def startTransaction ``` def startTransaction(readOnly: Boolean):String ``` 開始新交易。內部呼叫 Lake Formation [startTransaction](https://docs.aws.amazon.com/lake-formation/latest/dg/aws-lake-formation-api-aws-lake-formation-api-transactions.html#aws-lake-formation-api-aws-lake-formation-api-transactions-StartTransaction) API。 + `readOnly` – (布林值) 指出此交易應該是唯讀，還是讀取和寫入。使用唯讀交易 ID 進行的寫入將被拒絕。唯讀交易不需要遞交。 傳回交易 ID。 ## def commitTransaction ``` def commitTransaction(transactionId: String, waitForCommit: Boolean): Boolean ``` 嘗試遞交指定的交易。`commitTransaction` 可能會在交易完成遞交之前返回。內部呼叫 Lake Formation [commitTransaction](https://docs.aws.amazon.com/lake-formation/latest/dg/aws-lake-formation-api-aws-lake-formation-api-transactions.html#aws-lake-formation-api-aws-lake-formation-api-transactions-CommitTransaction) API。 + `transactionId` – (字串) 要遞交的交易。 + `waitForCommit` – (布林值) 決定 `commitTransaction` 是否立即傳回。預設值為 true。如為 False，`commitTransaction` 輪詢並等待，直到交易完成遞交。使用指數退避時，等待時間長度限制為 1 分鐘，最多可嘗試 6 次重試。 傳回一個布林值，指示遞交是否完成。 ## def cancelTransaction ``` def cancelTransaction(transactionId: String): Unit ``` 嘗試取消指定的交易。內部呼叫 Lake Formation [CancelTransaction](https://docs.aws.amazon.com/lake-formation/latest/dg/aws-lake-formation-api-aws-lake-formation-api-transactions.html#aws-lake-formation-api-aws-lake-formation-api-transactions-CancelTransaction) API。 + `transactionId` – (字串) 要取消的交易。 如果交易先前已遞交，傳回 `TransactionCommittedException` 例外狀況。 ## def 此 ``` def this( sc : SparkContext, minPartitions : Int, targetPartitions : Int ) ``` 使用指定的 `SparkContext`、最小分割區和分割區目標來建立 `GlueContext` 物件。 + `sc` — `SparkContext`。 + `minPartitions` — 分割區最小數。 + `targetPartitions` — 分割區目標數。 傳回 `GlueContext`。 ## def 此 ``` def this( sc : SparkContext ) ``` 透過提供的 `SparkContext` 建立 `GlueContext` 物件。將分割區的最小值設為 10，目標分割區設為 20。 + `sc` — `SparkContext`。 傳回 `GlueContext`。 ## def 此 ``` def this( sparkContext : JavaSparkContext ) ``` 透過提供的 `JavaSparkContext` 建立 `GlueContext` 物件。將分割區的最小值設為 10，目標分割區設為 20。 + `sparkContext` — `JavaSparkContext`。 傳回 `GlueContext`。 # MappingSpec **Package: com.amazonaws.services.glue** ## MappingSpec 案例類別 ``` case class MappingSpec( sourcePath: SchemaPath, sourceType: DataType, targetPath: SchemaPath, targetType: DataTyp ) extends Product4[String, String, String, String] { override def _1: String = sourcePath.toString override def _2: String = ExtendedTypeName.fromDataType(sourceType) override def _3: String = targetPath.toString override def _4: String = ExtendedTypeName.fromDataType(targetType) } ``` + `sourcePath` — 來源欄位的 `SchemaPath`。 + `sourceType` — 來源欄位的 `DataType`。 + `targetPath` — 目標欄位的 `SchemaPath`。 + `targetType` — 目標欄位的 `DataType`。 `MappingSpec` 指定從來源路徑和來源資料類型到目標路徑和目標資料類型的映射。在來源框架中來源路徑的值會顯示在目標路徑的目標框架中。來源資料類型會轉換到目標資料類型。 它從 `Product4` 擴展，讓您可以處理任何 `Product4` (在 `applyMapping` 介面中)。 ## MappingSpec 物件 ``` object MappingSpec ``` `MappingSpec` 物件具有下列成員： ## Val orderingByTarget ``` val orderingByTarget: Ordering[MappingSpec] ``` ## Def apply ``` def apply( sourcePath : String, sourceType : DataType, targetPath : String, targetType : DataType ) : MappingSpec ``` 建立 `MappingSpec`。 + `sourcePath` — 來源路徑的字串顯示方式。 + `sourceType` — 來源 `DataType`。 + `targetPath` — 目標路徑的字串顯示方式。 + `targetType` — 目標 `DataType`。 傳回 `MappingSpec`。 ## Def apply ``` def apply( sourcePath : String, sourceTypeString : String, targetPath : String, targetTypeString : String ) : MappingSpec ``` 建立 `MappingSpec`。 + `sourcePath` — 來源路徑的字串顯示方式。 + `sourceType` — 來源資料類型的字串顯示方式。 + `targetPath` — 目標路徑的字串顯示方式。 + `targetType` — 目標資料類型的字串顯示方式。 傳回 MappingSpec。 ## Def apply ``` def apply( product : Product4[String, String, String, String] ) : MappingSpec ``` 建立 `MappingSpec`。 + `product` — 來源路徑、來源資料類型、目標路徑和目標資料類型的 `Product4`。 傳回 `MappingSpec`。 # AWS Glue Scala ResolveSpec API **Topics** + [ResolveSpec 物件](#glue-etl-scala-apis-glue-resolvespec-object) + [ResolveSpec 案例類別](#glue-etl-scala-apis-glue-resolvespec-case-class) **Package: com.amazonaws.services.glue** ## ResolveSpec 物件 **ResolveSpec** ``` object ResolveSpec ``` ### Def ``` def apply( path : String, action : String ) : ResolveSpec ``` 建立 `ResolveSpec`。 + `path` — 以字串表示、需要解析的選擇欄位。 + `action` — 解析動作。動作可以是以下其中之一：`Project`、`KeepAsStruct` 或 `Cast`。 傳回 `ResolveSpec`。 ### Def ``` def apply( product : Product2[String, String] ) : ResolveSpec ``` 建立 `ResolveSpec`。 + `product` — 以下項目的 `Product2`：來源路徑、解析動作。 傳回 `ResolveSpec`。 ## ResolveSpec 案例類別 ``` case class ResolveSpec extends Product2[String, String] ( path : SchemaPath, action : String ) ``` 建立 `ResolveSpec`。 + `path` — 需要解析之選擇欄位的 `SchemaPath`。 + `action` — 解析動作。動作可以是以下其中之一：`Project`、`KeepAsStruct` 或 `Cast`。 ### ResolveSpec def 方法 ``` def _1 : String ``` ``` def _2 : String ``` # AWS Glue Scala ArrayNode API **Package:   com.amazonaws.services.glue.types** ## ArrayNode 案例類別 **ArrayNode** ``` case class ArrayNode extends DynamicNode ( value : ArrayBuffer[DynamicNode] ) ``` ### ArrayNode def 方法 ``` def add( node : DynamicNode ) ``` ``` def clone ``` ``` def equals( other : Any ) ``` ``` def get( index : Int ) : Option[DynamicNode] ``` ``` def getValue ``` ``` def hashCode : Int ``` ``` def isEmpty : Boolean ``` ``` def nodeType ``` ``` def remove( index : Int ) ``` ``` def this ``` ``` def toIterator : Iterator[DynamicNode] ``` ``` def toJson : String ``` ``` def update( index : Int, node : DynamicNode ) ``` # AWS Glue Scala BinaryNode API **Package:   com.amazonaws.services.glue.types** ## BinaryNode 案例類別 **BinaryNode** ``` case class BinaryNode extends ScalarNode(value, TypeCode.BINARY) ( value : Array[Byte] ) ``` ### BinaryNode val 欄位 + `ordering` ### BinaryNode def 方法 ``` def clone ``` ``` def equals( other : Any ) ``` ``` def hashCode : Int ``` # AWS Glue Scala BooleanNode API **Package:   com.amazonaws.services.glue.types** ## BooleanNode 案例類別 **BooleanNode** ``` case class BooleanNode extends ScalarNode(value, TypeCode.BOOLEAN) ( value : Boolean ) ``` ### BooleanNode val 欄位 + `ordering` ### BooleanNode def 方法 ``` def equals( other : Any ) ``` # AWS Glue Scala ByteNode API **Package:   com.amazonaws.services.glue.types** ## ByteNode 案例類別 **ByteNode** ``` case class ByteNode extends ScalarNode(value, TypeCode.BYTE) ( value : Byte ) ``` ### ByteNode val 欄位 + `ordering` ### ByteNode def 方法 ``` def equals( other : Any ) ``` # AWS Glue Scala DateNode API **Package:   com.amazonaws.services.glue.types** ## DateNode 案例類別 **DateNode** ``` case class DateNode extends ScalarNode(value, TypeCode.DATE) ( value : Date ) ``` ### DateNode val 欄位 + `ordering` ### DateNode def 方法 ``` def equals( other : Any ) ``` ``` def this( value : Int ) ``` # AWS Glue Scala DecimalNode API **Package:   com.amazonaws.services.glue.types** ## DecimalNode 案例類別 **DecimalNode** ``` case class DecimalNode extends ScalarNode(value, TypeCode.DECIMAL) ( value : BigDecimal ) ``` ### DecimalNode val 欄位 + `ordering` ### DecimalNode def 方法 ``` def equals( other : Any ) ``` ``` def this( value : Decimal ) ``` # AWS Glue Scala DoubleNode API **Package:   com.amazonaws.services.glue.types** ## DoubleNode 案例類別 **DoubleNode** ``` case class DoubleNode extends ScalarNode(value, TypeCode.DOUBLE) ( value : Double ) ``` ### DoubleNode val 欄位 + `ordering` ### DoubleNode def 方法 ``` def equals( other : Any ) ``` # AWS Glue Scala DynamicNode API **Topics** + [DynamicNode 類別](#glue-etl-scala-apis-glue-types-dynamicnode-class) + [DynamicNode 物件](#glue-etl-scala-apis-glue-types-dynamicnode-object) **Package:   com.amazonaws.services.glue.types** ## DynamicNode 類別 **DynamicNode** ``` class DynamicNode extends Serializable with Cloneable ``` ### DynamicNode def 方法 ``` def getValue : Any ``` 取得純值並繫結至目前的記錄： ``` def nodeType : TypeCode ``` ``` def toJson : String ``` 偵錯方式： ``` def toRow( schema : Schema, options : Map[String, ResolveOption] ) : Row ``` ``` def typeName : String ``` ## DynamicNode 物件 **DynamicNode** ``` object DynamicNode ``` ### DynamicNode def 方法 ``` def quote( field : String, useQuotes : Boolean ) : String ``` ``` def quote( node : DynamicNode, useQuotes : Boolean ) : String ``` # EvaluateDataQuality 類別 | | | --- | | AWS Glue Data Quality 為 的預覽版本AWS Glue，可能會有所變更。 | **套件：com.amazonaws.services.glue.dq** ``` object EvaluateDataQuality ``` ## Def apply ``` def apply(frame: DynamicFrame, ruleset: String, publishingOptions: JsonOptions = JsonOptions.empty): DynamicFrame ``` 根據 `DynamicFrame` 評估資料品質規則集，並傳回包含評估結果的新 `DynamicFrame`。若要進一步了解 AWS Glue Data Quality，請參閱 [AWS Glue 資料品質](glue-data-quality.md)。 + `frame` – 您要評估資料品質的 `DynamicFrame`。 + `ruleset` – 字串格式的資料品質定義語言 (DQDL) 規則集。若要進一步了解 DQDL，請參閱 [資料品質定義語言 (DQDL) 參考](dqdl.md) 指南。 + `publishingOptions` – 指定以下用於發佈評估結果和指標的選項的字典： + `dataQualityEvaluationContext` – 指定 Glue AWS 應發佈 Amazon CloudWatch 指標和資料品質結果的命名空間的字串。彙總指標會出現在 CloudWatch 中，而完整結果會出現在 AWS Glue Studio 界面中。 + 必要：否 + 預設值：`default_context` + `enableDataQualityCloudWatchMetrics` – 指定是否應將資料品質評估的結果發佈至 CloudWatch。您可以使用 `dataQualityEvaluationContext` 選項指定指標的命名空間。 + 必要：否 + 預設值：False + `enableDataQualityResultsPublishing` – 指定資料品質結果是否應顯示在 AWS Glue Studio 介面的 **Data Quality** (資料品質) 索引標籤上。 + 必要：否 + 預設值：True + `resultsS3Prefix` – 指定 Glue AWS 可以寫入資料品質評估結果的 Amazon S3 位置。 + 必要：否 + 預設值："" (空字串) ## 範例 下列範例程式碼示範如何在執行 `SelectFields` 轉換之前評估 `DynamicFrame` 的資料品質。指令碼會在嘗試轉換之前驗證所有資料品質規則是否通過。 ``` 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.dq.EvaluateDataQuality 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) // Create DynamicFrame with data val Legislators_Area = glueContext.getCatalogSource(database="legislators", tableName="areas_json", transformationContext="S3bucket_node1").getDynamicFrame() // Define data quality ruleset val DQ_Ruleset = """ Rules = [ColumnExists "id"] """ // Evaluate data quality val DQ_Results = EvaluateDataQuality.apply(frame=Legislators_Area, ruleset=DQ_Ruleset, publishingOptions=JsonOptions("""{"dataQualityEvaluationContext": "Legislators_Area", "enableDataQualityMetrics": "true", "enableDataQualityResultsPublishing": "true"}""")) assert(DQ_Results.filter(_.getField("Outcome").contains("Failed")).count == 0, "Failing DQ rules for Legislators_Area caused the job to fail.") // Script generated for node Select Fields val SelectFields_Results = Legislators_Area.selectFields(paths=Seq("id", "name"), transformationContext="Legislators_Area") Job.commit() } } ``` # AWS Glue Scala FloatNode API **Package:   com.amazonaws.services.glue.types** ## FloatNode 案例類別 **FloatNode** ``` case class FloatNode extends ScalarNode(value, TypeCode.FLOAT) ( value : Float ) ``` ### FloatNode val 欄位 + `ordering` ### FloatNode def 方法 ``` def equals( other : Any ) ``` # FillMissingValues 類別 **套件：com.amazonaws.services.glue.ml** ``` object FillMissingValues ``` ## Def apply ``` def apply(frame: DynamicFrame, missingValuesColumn: String, outputColumn: String = "", transformationContext: String = "", callSite: CallSite = CallSite("Not provided", ""), stageThreshold: Long = 0, totalThreshold: Long = 0): DynamicFrame ``` 在指定的欄中填入動態框架的缺少值，並在新的欄中傳回具有估計值的新框架。對於沒有缺少值的列，指定欄的值將被複製到新欄。 + `frame` — 在其中填入缺少值的 DynamicFrame。必要。 + `missingValuesColumn` — 包含缺少值的欄 (`null` 值和空字串)。必要. + `outputColumn` — 新欄的名稱，該欄將包含所有缺少值的列的估計值。選擇性；預設為 `missingValuesColumn` 的值，字尾為 `"_filled"`。 + `transformationContext` — 用於識別狀態資訊的唯一字串 (選用)。 + `callSite` — 用於提供錯誤報告的內容資訊 (選用)。 + `stageThreshold` — 在錯誤輸出之前，轉換作業中可發生錯誤的次數上限 (選用；預設值為零)。 + `totalThreshold` — 在處理錯誤輸出之前，整體作業可發生錯誤的次數上限 (選用；預設值為零)。 傳回具有一個額外欄的新動態框架，其中包含缺少值的列估計和其他列的目前值。 # FindMatches 類別 **套件：com.amazonaws.services.glue.ml** ``` object FindMatches ``` ## Def apply ``` def apply(frame: DynamicFrame, transformId: String, transformationContext: String = "", callSite: CallSite = CallSite("Not provided", ""), stageThreshold: Long = 0, totalThreshold: Long = 0, enforcedMatches: DynamicFrame = null): DynamicFrame, computeMatchConfidenceScores: Boolean ``` 在輸入框架中尋找相符項目並傳回一個新框架，其中包含每個相符群組唯一 ID 的新欄。 + `frame` — 要在其中尋找相符項目的 DynamicFrame。必要. + `transformId` — 與 FindMatches 轉換相關聯的唯一 ID，以套用於輸入影格。必要. + `transformationContext` — 此 `DynamicFrame` 的識別碼。`transformationContext` 做為在執行之間持續存在之任務書籤狀態的金鑰使用。選用。 + `callSite` — 用於提供錯誤報告的內容資訊。從 Python 呼叫時，會自動設定這些值。選用。 + `stageThreshold` — 此 `DynamicFrame` 運算在擲回例外狀況之前允許的最大錯誤記錄數，不包含於先前 `DynamicFrame` 中存在的記錄。選用。預設為零。 + `totalThreshold` — 在擲回例外狀況之前，最大的錯誤記錄總計 (包括之前框架的數量)。選用。預設為零。 + `enforcedMatches` — 強制相符的框架。選用。預設值為 `null`。 + `computeMatchConfidenceScores` – 布林值，指出是否運算每個相符記錄群組的可信度分數。選用。預設值為 false。 傳回具有指派給每個相符記錄群組之唯一識別碼的新動態框架。 # FindIncrementalMatches 類別 **套件：com.amazonaws.services.glue.ml** ``` object FindIncrementalMatches ``` ## Def apply ``` apply(existingFrame: DynamicFrame, incrementalFrame: DynamicFrame, transformId: String, transformationContext: String = "", callSite: CallSite = CallSite("Not provided", ""), stageThreshold: Long = 0, totalThreshold: Long = 0, enforcedMatches: DynamicFrame = null): DynamicFrame, computeMatchConfidenceScores: Boolean ``` 在現有和增量框架中尋找相符項目，並傳回一個新框架，其中包含每個相符群組唯一 ID 的新欄。 + `existingframe` — 已為每個群組指派相符 ID 的現有框架。必要. + `incrementalframe` — 用來尋找與現有框架相符的增量框架。必要. + `transformId` — 與 FindIncrementalMatches 轉換相關聯的唯一 ID，以套用於輸入影格。必要. + `transformationContext` — 此 `DynamicFrame` 的識別碼。`transformationContext` 做為在執行之間持續存在之任務書籤狀態的金鑰使用。選用。 + `callSite` — 用於提供錯誤報告的內容資訊。從 Python 呼叫時，會自動設定這些值。選用。 + `stageThreshold` — 此 `DynamicFrame` 運算在擲回例外狀況之前允許的最大錯誤記錄數，不包含於先前 `DynamicFrame` 中存在的記錄。選用。預設為零。 + `totalThreshold` — 在擲回例外狀況之前，最大的錯誤記錄總計 (包括之前框架的數量)。選用。預設為零。 + `enforcedMatches` — 強制相符的框架。選用。預設值為 `null`。 + `computeMatchConfidenceScores` – 布林值，指出是否運算每個相符記錄群組的可信度分數。選用。預設值為 false。 傳回具有指派給每個相符記錄群組之唯一識別碼的新動態框架。 # AWS Glue Scala IntegerNode API **Package:   com.amazonaws.services.glue.types** ## IntegerNode 案例類別 **IntegerNode** ``` case class IntegerNode extends ScalarNode(value, TypeCode.INT) ( value : Int ) ``` ### IntegerNode val 欄位 + `ordering` ### IntegerNode def 方法 ``` def equals( other : Any ) ``` # AWS Glue Scala LongNode API **Package:   com.amazonaws.services.glue.types** ## LongNode 案例類別 **LongNode** ``` case class LongNode extends ScalarNode(value, TypeCode.LONG) ( value : Long ) ``` ### LongNode val 欄位 + `ordering` ### LongNode def 方法 ``` def equals( other : Any ) ``` # AWS Glue Scala MapLikeNode API **Package:   com.amazonaws.services.glue.types** ## MapLikeNode 類別 **MapLikeNode ** ``` class MapLikeNode extends DynamicNode ( value : mutable.Map[String, DynamicNode] ) ``` ### MapLikeNode def 方法 ``` def clear : Unit ``` ``` def get( name : String ) : Option[DynamicNode] ``` ``` def getValue ``` ``` def has( name : String ) : Boolean ``` ``` def isEmpty : Boolean ``` ``` def put( name : String, node : DynamicNode ) : Option[DynamicNode] ``` ``` def remove( name : String ) : Option[DynamicNode] ``` ``` def toIterator : Iterator[(String, DynamicNode)] ``` ``` def toJson : String ``` ``` def toJson( useQuotes : Boolean ) : String ``` **範例：**給定此 JSON： ``` {"foo": "bar"} ``` 如果 `useQuotes == true`，`toJson` 會產生 `{"foo": "bar"}`。如果 `useQuotes == false`，`toJson` 會產生 `{foo: bar}` @return。 # AWS Glue Scala MapNode API **Package:   com.amazonaws.services.glue.types** ## MapNode 案例類別 **MapNode** ``` case class MapNode extends MapLikeNode(value) ( value : mutable.Map[String, DynamicNode] ) ``` ### MapNode def 方法 ``` def clone ``` ``` def equals( other : Any ) ``` ``` def hashCode : Int ``` ``` def nodeType ``` ``` def this ``` # AWS Glue Scala NullNode API **Topics** + [NullNode 類別](#glue-etl-scala-apis-glue-types-nullnode-class) + [NullNode 案例物件](#glue-etl-scala-apis-glue-types-nullnode-case-object) **Package:   com.amazonaws.services.glue.types** ## NullNode 類別 **NullNode** ``` class NullNode ``` ## NullNode 案例物件 **NullNode** ``` case object NullNode extends NullNode ``` # AWS Glue Scala ObjectNode API **Topics** + [ObjectNode 物件](#glue-etl-scala-apis-glue-types-objectnode-object) + [ObjectNode 案例類別](#glue-etl-scala-apis-glue-types-objectnode-case-class) **Package:   com.amazonaws.services.glue.types** ## ObjectNode 物件 **ObjectNode** ``` object ObjectNode ``` ### ObjectNode def 方法 ``` def apply( frameKeys : Set[String], v1 : mutable.Map[String, DynamicNode], v2 : mutable.Map[String, DynamicNode], resolveWith : String ) : ObjectNode ``` ## ObjectNode 案例類別 **ObjectNode** ``` case class ObjectNode extends MapLikeNode(value) ( val value : mutable.Map[String, DynamicNode] ) ``` ### ObjectNode def 方法 ``` def clone ``` ``` def equals( other : Any ) ``` ``` def hashCode : Int ``` ``` def nodeType ``` ``` def this ``` # AWS Glue Scala ScalarNode API **Topics** + [ScalarNode 類別](#glue-etl-scala-apis-glue-types-scalarnode-class) + [ScalarNode 物件](#glue-etl-scala-apis-glue-types-scalarnode-object) **Package:   com.amazonaws.services.glue.types** ## ScalarNode 類別 **ScalarNode** ``` class ScalarNode extends DynamicNode ( value : Any, scalarType : TypeCode ) ``` ### ScalarNode def 方法 ``` def compare( other : Any, operator : String ) : Boolean ``` ``` def getValue ``` ``` def hashCode : Int ``` ``` def nodeType ``` ``` def toJson ``` ## ScalarNode 物件 **ScalarNode** ``` object ScalarNode ``` ### ScalarNode def 方法 ``` def apply( v : Any ) : DynamicNode ``` ``` def compare( tv : Ordered[T], other : T, operator : String ) : Boolean ``` ``` def compareAny( v : Any, y : Any, o : String ) ``` ``` def withEscapedSpecialCharacters( jsonToEscape : String ) : String ``` # AWS Glue Scala ShortNode API **Package:   com.amazonaws.services.glue.types** ## ShortNode 案例類別 **ShortNode** ``` case class ShortNode extends ScalarNode(value, TypeCode.SHORT) ( value : Short ) ``` ### ShortNode val 欄位 + `ordering` ### ShortNode def 方法 ``` def equals( other : Any ) ``` # AWS Glue Scala StringNode API **Package:   com.amazonaws.services.glue.types** ## StringNode 案例類別 **StringNode** ``` case class StringNode extends ScalarNode(value, TypeCode.STRING) ( value : String ) ``` ### StringNode val 欄位 + `ordering` ### StringNode def 方法 ``` def equals( other : Any ) ``` ``` def this( value : UTF8String ) ``` # AWS Glue Scala TimestampNode API **Package:   com.amazonaws.services.glue.types** ## TimestampNode 案例類別 **TimestampNode** ``` case class TimestampNode extends ScalarNode(value, TypeCode.TIMESTAMP) ( value : Timestamp ) ``` ### TimestampNode val 欄位 + `ordering` ### TimestampNode def 方法 ``` def equals( other : Any ) ``` ``` def this( value : Long ) ``` # AWS Glue Scala GlueArgParser API **Package:   com.amazonaws.services.glue.util** ## GlueArgParser 物件 **GlueArgParser** ``` object GlueArgParser ``` 此與 `AWSGlueDataplanePython` 套件中的 `utils.getResolvedOptions` Python 版本完全一致。 ### GlueArgParser def 方法 ``` def getResolvedOptions( args : Array[String], options : Array[String] ) : Map[String, String] ``` ``` def initParser( userOptionsSet : mutable.Set[String] ) : ArgumentParser ``` **Example 擷取傳遞至任務的引數** 若要擷取任務引數，您可使用 `getResolvedOptions` 方法。請考慮以下範例，其會擷取名為 `aws_region` 的任務引數。 ``` val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME","aws_region").toArray) Job.init(args("JOB_NAME"), glueContext, args.asJava) val region = args("aws_region") println(region) ``` # AWS Glue Scala 任務 API **Package:   com.amazonaws.services.glue.util** ## 任務物件 **任務** ``` object Job ``` ### Job def 方法 ``` def commit ``` ``` def init( jobName : String, glueContext : GlueContext, args : java.util.Map[String, String] = Map[String, String]().asJava ) : this.type ``` ``` def init( jobName : String, glueContext : GlueContext, endpoint : String, args : java.util.Map[String, String] ) : this.type ``` ``` def isInitialized ``` ``` def reset ``` ``` def runId ``` # 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) + [AWS Spark SQL 任務的 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) | [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 (with MongoDB compatibility)](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 伺服器資料庫 (請參閱 [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。 | | [custom.\$1](#aws-glue-programming-etl-connect-market) | Spark、Athena 或 JDBC 資料存放區 (請參閱 [自訂 and AWS Marketplace connectionType 值](#aws-glue-programming-etl-connect-market) | | [marketplace.\$1](#aws-glue-programming-etl-connect-market) | Spark、Athena 或 JDBC 資料存放區 (請參閱 [自訂 and AWS Marketplace connectionType 值](#aws-glue-programming-etl-connect-market)) | # DynamoDB 連線 您可以使用 AWS Glue for Spark 來讀取和寫入 Glue 中 DynamoDB AWS 中的資料表。您可以使用連接至 Glue 任務的 IAM AWS 許可連線到 DynamoDB。 AWS Glue支援將資料寫入另一個 AWS 帳戶的 DynamoDB 資料表。如需詳細資訊，請參閱[跨帳戶跨區域存取 DynamoDB 資料表](aws-glue-programming-etl-dynamo-db-cross-account.md)。 原始 DynamoDB 連接器使用 Glue DynamicFrame 物件來處理從 DynamoDB 擷取的資料。 AWS Glue 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 物件。 AWS Glue 1.0 或更新版本中會提供 DynamoDB 寫入器。AWS Glue 2.0 或更新版本中會提供 AWS Glue DynamoDB 匯出連接器。新的 DataFrame 型 DynamoDB 連接器可在 AWS Glue 5.0 版或更新版本中使用。 如需 DynamoDB 的詳細資訊，請參閱 [Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) 文件。 **注意** DynamoDB ETL 讀取器不支援篩選條件或下推述詞。 ## 設定 DynamoDB 連線 若要從 Glue AWS 連線至 DynamoDB，請授予與您的 Glue AWS 任務相關聯的 IAM 角色與 DynamoDB 互動的許可。如需有關在 DynamoDB 中進行讀取或寫入所需許可的詳細資訊，請參閱 IAM 文件中的 [DynamoDB 的動作、資源和條件金鑰](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazondynamodb.html)。 在下列情況中，可能需要其他組態： + 使用 DynamoDB 匯出連接器時，將需要設定 IAM，以便工作可以請求 DynamoDB 資料表匯出。此外，您將需要識別匯出的 Amazon S3 儲存貯體，並在 IAM 中提供適當的許可，以便 DynamoDB 寫入它，以及讓 AWS Glue 任務從中讀取它。如需詳細資訊，請參閱[請求在 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 進行讀取和寫入 下列程式碼範例示範如何讀取（透過 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 連接器也支援 DynamoDB 匯出至 Amazon S3 的 AWS KMS 加密。在 Glue AWS 任務組態中提供安全組態，可啟用 DynamoDB 匯出的 AWS KMS 加密。KMS 金鑰必須位於與 Amazon S3 儲存貯體相同的區域中。 請注意，DynamoDB 匯出和 Amazon S3 儲存皆會產生額外費用和成本。在任務運作完成後，Amazon S3 中匯出的資料仍會存在，因此您可以重新使用該資料，無需進行其他 DynamoDB 匯出。使用此連接器的要求為資料表啟用時間點復原 (PITR)。 DynamoDB ETL 連接器或匯出連接器皆不支援要在 DynamoDB 來源中套用的篩選條件或 pushdown 述詞。 以下程式碼範例演示如何讀取 (透過匯出連接器) 及列印分割區數。 ------ #### [ 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`分類的 Glue Data Catalog AWS 資料表列印分割區數量： ------ #### [ 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 的使用 DynamoDB 會使用 AWS Glue DynamoDB 匯出連接器進行匯出，這會產生具有特定巢套結構的 JSON 檔案。如需詳細資訊，請參閱[資料物件](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/S3DataExport.Output.html)。AWS Glue 會提供 DynamicFrame 轉換，其可將這些結構解除巢狀，使其成為下游應用程式更易於使用的形式。 您可以使用兩種方式中的一種來調用此轉換。呼叫要從 DynamoDB 進行讀取的方法時，可以使用值 `"true"` 來設定連線選項 `"dynamodb.simplifyDDBJson"`。您也可以將轉換稱為 Glue AWS 程式庫中獨立提供的方法。 請考慮由 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 連接器的某些參數。調校平行處理參數時，您的目標是充分利用佈建的 Glue AWS 工作者。然後，如果需要更高的效能，建議透過增加 DPU 數量來橫向擴展您的工作。 可以在使用 ETL 連接器時，使用 `dynamodb.splits` 參數來變更 DynamoDB 讀取操作中的平行處理。使用匯出連接器進行讀取時，無需為 Spark 執行器平行處理設定分割數。可以使用 `dynamodb.output.numParallelTasks` 來變更 DynamoDB 寫入操作中的平行處理。 **使用 DynamoDB ETL 連接器進行讀取** 建議您根據工作組態中設定的最大工作者數目和以下 `numSlots` 計算來計算 `dynamodb.splits`。如果進行自動擴展，則實際可用的工作者數量可能會在該上限下變更。如需有關設定工作者數目上限的詳細資訊，請參閱 [在 中設定 Spark 任務的任務屬性 AWS Glue](add-job.md) 中的**工作者數目** (`NumberOfWorkers`)。 + `numExecutors = NumberOfWorkers - 1` 針對內容，為 Spark 驅動程式保留一個執行程式；其他執行程式則用於處理資料。 + `numSlotsPerExecutor =` ------ #### [ AWS Glue 3.0 and later versions ] + `4`，若 `WorkerType` 為 `G.1X` + `8`，若 `WorkerType` 為 `G.2X` + `16`，若 `WorkerType` 為 `G.4X` + `32`，若 `WorkerType` 為 `G.8X` ------ #### [ AWS Glue 2.0 and legacy versions ] + `8`，若 `WorkerType` 為 `G.1X` + `16`，若 `WorkerType` 為 `G.2X` ------ + `numSlots = numSlotsPerExecutor * numExecutors` 建議您將 `dynamodb.splits` 設定為可用插槽的數量 `numSlots`。 **寫入到 DynamoDB** `dynamodb.output.numParallelTasks` 參數使用以下計算來確定每個 Spark 任務的 WCU： `permittedWcuPerTask = ( TableWCU * dynamodb.throughput.write.percent ) / dynamodb.output.numParallelTasks` 如果組態準確地表示寫入到 DynamoDB 的 Spark 任務數目，則 DynamoDB 寫入器的運作效果最佳。在某些情況下，可能需要覆寫預設計算來提高寫入效能。如果不指定此參數，將透過下列公式自動計算每個 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` **注意** 舊版 Glue AWS 版本和使用標準工作者的任務需要不同的方法來計算插槽數量。如果您需要調整這些任務的效能，我們建議您轉換到支援的 Glue AWS 版本。 ## DynamoDB 連線選項參考 指定 Amazon DynamoDB 的連線。 來源連線和接收器連線的連線選項不同。 ### "connectionType": "dynamodb" 搭配 ETL 連接器作為來源 使用 Glue DynamoDB ETL 連接器時，請使用下列連線選項搭配 AWS `"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": "dynamodb" 搭配作為來源的 AWS Glue DynamoDB 匯出連接器 在使用 AWS Glue DynamoDB 匯出連接器時 (該連接器僅可用於 AWS Glue 版本 2.0 和更新版本)，請搭配使用以下連接選項與 "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 Map 類型時使用 `"dynamodb.simplifyDDBJson"` 以獲得更好的行為。如需詳細資訊，請參閱[簡化 DynamoDB 匯出 JSON 的使用](#etl-connect-dynamodb-traversing-structure)。 + `"dynamodb.simplifyDDBJson"`：(選用) 預設值：false。有效值：布林值。如果設為 true，系統會執行轉換，以簡化出現在匯出中的 DynamoDB JSON 結構的結構描述。這與 `"dynamodb.unnestDDBJson"` 選項具有相同的用途，但是對 DynamoDB Map 類型或甚至是 DynamoDB 資料表中的巢狀 Map 類型提供了更好的支援。此選項適用於 AWS Glue 3.0 和更新版本。將 `"dynamodb.unnestDDBJson"` 和 `"dynamodb.simplifyDDBJson"` 同時設定為 true 是錯誤做法。如需詳細資訊，請參閱[簡化 DynamoDB 匯出 JSON 的使用](#etl-connect-dynamodb-traversing-structure)。 + `"dynamodb.s3.bucket"`：（選用）指定要在其中執行 DynamoDB `ExportTableToPointInTime` 程序的 Amazon S3 儲存貯體位置。匯出的檔案格式為 DynamoDB JSON。 + `"dynamodb.s3.prefix"`：（選用）指定 Amazon S3 儲存貯體內的 Amazon S3 前綴位置，DynamoDB `ExportTableToPointInTime` 負載將儲存於其中。如果 `dynamodb.s3.prefix` 和 `dynamodb.s3.bucket` 均未指定，則這些值將預設為 AWS Glue 任務組態中指定的暫時目錄位置。如需詳細資訊，請參閱 [Glue AWS 使用的特殊參數](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-glue-arguments.html)。 + `"dynamodb.s3.bucketOwner"`：指定跨帳戶存取 Amazon S3 所需的儲存貯體擁有者。 + `"dynamodb.sts.roleArn"`：(選用) DynamoDB 資料表的跨帳戶存取和/或跨區域存取所要擔任的 IAM 角色 ARN。注意：相同的 IAM 角色 ARN 將用於存取為 `ExportTableToPointInTime` 要求中指定的 Amazon S3 位置。 + `"dynamodb.sts.roleSessionName"`：(選用) STS 工作階段名稱。預設設定為 "glue-dynamodb-read-sts-session"。 + `"dynamodb.exportTime"` (選用) 有效值：表示 ISO-8601 瞬間的字串。應進行匯出的時間點。 + `"dynamodb.sts.region"`：(如果使用區域端點進行跨區域呼叫，則為必填項) 託管您要讀取的 DynamoDB 資料表的區域。 ### "connectionType": "dynamodb" 搭配 ETL 連接器做為接收器 使用下列有 `"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。下列範例顯示建立名為 `DynamoDBCrossAccessRole` 的角色，具備許可政策 `AmazonDynamoDBFullAccess`。 ## 授予角色存取權 跟隨 *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 任務指令碼中擔任角色 現在，您可以登入帳戶 B 並建立 AWS Glue 任務。若要建立任務，請參閱[在 中設定 Spark 任務的任務屬性 AWS Glue](add-job.md)中的指示。 在任務指令碼中，您需要使用 `dynamodb.sts.roleArn` 參數來擔任 `DynamoDBCrossAccessRole` 角色。擔任此角色可讓您取得臨時憑證，這些憑證需要用於存取帳戶 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 APIs 從 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 連線時，您可以透過 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) ) 或直接在「任務詳細資訊」頁面將其連接至 Glue 任務： ![\[alt text not found\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/dynamodb-dataframe-connector.png) 在確保 DYNAMODB 類型的連線連接至 Glue 任務時，您可以從 DataFrame 型連接器利用下列讀取、寫入和匯出操作。 ## 使用 DataFrame 型連接器從 DynamoDB 讀取和寫入 下列程式碼範例示範如何透過 DataFrame 型連接器讀取和寫入 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 資料表大小，匯出操作會優先於讀取操作。下列程式碼範例示範如何從資料表讀取、匯出至 S3，以及透過以 DataFrame 為基礎的連接器列印分割區數量。 **注意** DynamoDB 匯出功能可透過 Scala `DynamoDBExport` 物件使用。Python 使用者可以透過 Spark 的 JVM 交錯存取它，或使用適用於 Python 的 AWS 開發套件 (boto3) 搭配 DynamoDB `ExportTableToPointInTime` API。 ------ #### [ 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 匯出連接器，在 Glue AWS 任務期間ExportTableToPointInTimeRequet將調用新的連接器。系統將使用從 dynamodb.s3.bucket 和 dynamodb.s3.prefix 傳遞的位置產生新的匯出。如果設定為 s3 啟用 AWS Glue 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 | 指出跨帳戶 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 連線，透過儲存在 Data Catalog 資料表中的資訊讀取和寫入 Amazon Kinesis 資料串流，或透過提供資訊來直接存取資料串流。您可以從 Kinesis 讀取資訊到 Spark DataFrame，然後將其轉換為 AWS Glue DynamicFrame。您可以使用 JSON 格式將 DynamicFrames 寫入 Kinesis。如果您直接存取資料串流，則請使用這些選項來提供如何存取資料串流的相關資訊。 如果您使用 `getCatalogSource` 或 `create_data_frame_from_catalog` 來取用來自 Kinesis 串流來源的記錄，則該任務具有 Data Catalog 資料庫和資料表名稱資訊，並可以使用它來獲取一些從 Kinesis 串流來源讀取的基本參數。如果使用 `getSource`、`getSourceWithFormat`、`createDataFrameFromOptions` 或 `create_data_frame_from_options`，則您必須使用此處描述的連線選項來指定這些基本參數。 您可以使用 `GlueContext` 類別中指定方法的下列引數來指定 Kinesis 的連線選項。 + 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 若要連線到 Glue Spark 任務中的 Kinesis AWS 資料串流，您需要一些先決條件： + 如果讀取，Glue AWS 任務必須具有 Kinesis 資料串流的讀取存取層級 IAM 許可。 + 如果寫入，Glue AWS 任務必須具有 Kinesis 資料串流的寫入存取層級 IAM 許可。 在某些情況下，您需要設定其他先決條件： + 如果您的 AWS Glue 任務設定了**其他網路連線** （通常連接到其他資料集），且其中一個連線提供 Amazon VPC **網路選項**，這將引導您的任務透過 Amazon VPC 進行通訊。在這種情況下，您還需要將 Kinesis 資料串流設定為透過 Amazon VPC 進行通訊。為此，您可以建立 Amazon VPC 與 Kinesis 資料串流之間的介面 VPC 端點。如需詳細資訊，請參閱 [Using Kinesis Data Streams with Interface VPC Endpoints](https://docs.aws.amazon.com//streams/latest/dev/vpc.html)。 + 在另一個帳戶中指定 Amazon Kinesis Data Streams 時，您必須設定角色和政策以允許跨帳戶存取。如需詳細資訊，請參閱[範例：從不同帳戶中的 Kinesis 串流讀取](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"` 或 `yyyy-mm-ddTHH:MM:SSZ` 模式中 UTC 格式的時間戳記字串 (其中 `Z` 代表以 \$1/- 表示的 UTC 時區偏移。例如："2023-04-04T08:00:00-04:00")。預設值為 `"latest"`。注意：僅 AWS Glue 4.0 版或更新版本`"startingPosition"`支援 UTC 格式的時間戳記字串。 + `"failOnDataLoss"`：(選用) 如果有任何作用中的碎片遺失或過期，則任務失敗。預設值為 `"false"`。 + `"awsSTSRoleARN"`：(選用) 用於讀取/寫入。要使用 () 擔任之角色的 Amazon Resource Name AWS Security Token Service (ARN AWS STS)。此角色必須具有描述或讀取 Kinesis 資料串流記錄操作的許可。存取不同帳戶中的資料串流時，您必須使用此參數。搭配 `"awsSTSSessionName"` 使用。 + `"awsSTSSessionName"`：(選用) 用於讀取/寫入。使用 AWS STS擔任角色之工作階段的識別符。存取不同帳戶中的資料串流時，您必須使用此參數。搭配 `"awsSTSRoleARN"` 使用。 + `"awsSTSEndpoint"`：（選用） 使用 擔任的角色連線至 Kinesis 時要使用的 AWS STS 端點。這允許在 VPC 中使用區域 AWS STS 端點，這是預設全域端點無法做到的。 + `"maxFetchTimeInMs"`：(選用) 用於讀取。任務執行器從 Kinesis 資料串流讀取目前批次記錄所花費的最長時間，以毫秒 (ms) 為單位指定。在此期間可以進行多次 `GetRecords` API 呼叫。預設值為 `1000`。 + `"maxFetchRecordsPerShard"`：(選用) 用於讀取。每個微批次的 Kinesis 資料串流中每個碎片要擷取的記錄數目上限。注意：如果串流任務已從 Kinesis 讀取額外的記錄 (在相同的 get-records 呼叫中)，用戶端可以超過此限制。如果 `maxFetchRecordsPerShard` 需要嚴格控制，則其必須是 `maxRecordPerRead` 的倍數。預設值為 `100000`。 + `"maxRecordPerRead"`：(選用) 用於讀取。要從每個 `getRecords` 操作的 Kinesis 資料串流中擷取的記錄數量上限。預設值為 `10000`。 + `"addIdleTimeBetweenReads"`：(選用) 用於讀取。增加兩個連續 `getRecords` 操作之間的時間延遲。預設值為 `"False"`。此選項僅在 Glue 2.0 及更高版本上才可設定。 + `"idleTimeBetweenReadsInMs"`：(選用) 用於讀取。兩個連續 `getRecords` 操作的最小延遲時間，以毫秒為單位指定。預設值為 `1000`。此選項僅在 Glue 2.0 及更高版本上才可設定。 + `"describeShardInterval"`：(選用) 用於讀取。指令碼考慮重新分片的兩個 `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"`：(選用) 用於讀取。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"`：(選用) 用於讀取。Kinesis 串流取用者的 ARN，適用於 `streamARN` 中指定的串流。用於啟用 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 (%)。作為後端限制的百分比來限制從單一生產者 (例如您的任務) 傳送的每個碎片輸送量。 + `"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 中讀取和寫入檔案。 AWS Glue for Spark 支援許多儲存在 Amazon S3 中的常用資料格式，包括 CSV、Avro、JSON、Orc 和 Parquet。如需有關支援資料格式的詳細資訊，請參閱 [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 連線 若要使用 Spark 任務連線至 AWS Glue 中的 Amazon S3，您將需要一些先決條件： + Glue AWS 任務必須具有相關 Amazon S3 儲存貯體的 IAM 許可。 在某些情況下，您需要設定其他先決條件： + 設定跨帳戶存取權時，Amazon S3 儲存貯體上適當的存取權控制。 + 基於安全理由，您可以選擇透過 Amazon VPC 路由 Amazon S3 請求。這個方法可能會帶來頻寬和可用性方面的挑戰。如需詳細資訊，請參閱[Amazon S3 的 VPC 端點](vpc-endpoints-s3.md)。 ## Amazon S3 連線選項參考 指定 Amazon S3 的連線。 Amazon S3 管理檔案而非資料表，因此除了指定本文件中提供的連線屬性之外，您還需要指定有關檔案類型的其他組態。您可以透過資料格式選項指定這些資訊。如需有關格式選項的詳細資訊，請參閱 [AWS Glue for Spark 中的輸入與輸出的資料格式選項](aws-glue-programming-etl-format.md)。您也可以透過整合 AWS Glue Data Catalog 來指定這些資訊。 如需連線選項和格式選項之間區分的範例，請考慮 [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`"：(選用) 指定資料的壓縮方式。將 `"compressionType"` 用於 Amazon S3 來源，以及將 `"compression"` 用於 Amazon S3 目標。一般來說，如果資料具有標準副檔名，則不需要此項目。可能值為 `"gzip"` 和 `"bzip2"`。特定格式可能支援其他壓縮格式。如需有關功能支援的詳細資訊，請參閱資料格式頁面。 + `"groupFiles"`：(選用) 當輸入含有超過 50,000 個檔案時，預設會開啟分組檔案。若要在少於 50,000 個檔案時開啟分組，請將此參數設定為 `"inPartition"`。若要在超過 50,000 個檔案時停用分組，請將此參數設定為 `"none"`。 + `"groupSize"`：(選用) 目標群組大小 (以位元組為單位)。系統會根據輸入資料大小和叢集大小來計算預設值。當輸入檔案數少於 50,000 個時，`"groupFiles"` 必須設定為 `"inPartition"` 才能讓此設定生效。 + `"recurse"`：(選用) 如果設定為 true，則會遞迴讀取指定路徑下所有子目錄中的檔案。 + `"maxBand"`：(選用，進階) 此選項可控制 `s3` 清單可能會在多長時間 (以毫秒為單位) 後變得一致。使用 `JobBookmarks` 來考量 Amazon S3 最終一致性時，會特別追蹤修改時間戳記落在最後 `maxBand` 毫秒內的檔案。使用者大多不需要設定此選項。預設值為 900000 毫秒或 15 分鐘。 + `"maxFilesInBand"`：(選用、進階) 此選項會指定從最後 `maxBand` 秒內所要儲存的檔案數上限。如果超過此數量，系統就會略過額外的檔案，等下一個任務執行到來再處理。使用者大多不需要設定此選項。 + `"isFailFast"`：(選用) 此選項決定 AWS Glue ETL 任務是否擲回讀取器剖析例外狀況。如果設定為 `true`，則如果 Spark 任務的四次重試都無法正確剖析資料，任務就會快速失敗。 + `"catalogPartitionPredicate"`：(選用) 用於讀取。SQL `WHERE` 子句的內容。從具有大量分割區的資料目錄資料表讀取時使用。從資料目錄索引擷取相符的分割區。與 `push_down_predicate` 一起使用，這是 [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) 方法 (和其他類似方法) 上的一個選項。如需詳細資訊，請參閱[使用目錄分割述詞的伺服器端篩選](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-cat-predicates)。 + `"partitionKeys"`：(選用) 用於寫入。資料欄標籤字串的陣列。 AWS Glue 會依此組態所指定來分割您的資料。如需詳細資訊，請參閱[寫入分割區](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-writing)。 + `"excludeStorageClasses"`：(選用) 用於讀取。指定 Amazon S3 儲存類別的字串陣列。 AWS Glue 會根據此組態排除 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 最佳化資料列單欄式 (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 儲存體方案 如果您執行的 AWS Glue ETL 任務會從 Amazon Simple Storage Service (Amazon S3) 讀取檔案或分割區，則您可排除部分 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 開發人員指南*中的[還原封存物件](https://docs.aws.amazon.com/AmazonS3/latest/dev/restoring-objects.html)。) 透過使用儲存體方案排除功能，您即可確保 AWS Glue 任務會在具有這些儲存體方案分割區的資料表上執行。如果沒有進行排除，則從這些方案中讀取資料的任務就會失敗，並出現以下錯誤訊息：AmazonS3Exception: The operation is not valid for the object's storage class (AmazonS3Exception：本操作不適用於該物件的儲存體方案)。 在 AWS Glue 中篩選 Amazon S3 儲存類別有幾種不同方法。 **Topics** + [在建立動態框架時排除 Amazon S3 儲存體方案](#aws-glue-programming-etl-storage-classes-dynamic-frame) + [在資料目錄資料表上排除 Amazon S3 儲存體方案](#aws-glue-programming-etl-storage-classes-table) ## 在建立動態框架時排除 Amazon S3 儲存體方案 若要在建立動態框架時排除 Amazon S3 儲存類別，請使用 `additionalOptions` 中的 `excludeStorageClasses`。AWS Glue 會自動使用自己的 Amazon S3 `Lister` 實作來列出對應至特定儲存體方案的檔案，並加以排除。 下列 Python 和 Scala 範例會示範在建立動態框架時，排除 `GLACIER` 和 `DEEP_ARCHIVE` 儲存體方案的方法。 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() ``` ## 在資料目錄資料表上排除 Amazon S3 儲存體方案 您可以在 Glue Data Catalog AWS Glue 中指定 ETL AWS 任務用作資料表參數的儲存類別排除。您可以使用 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 管理主控台 並在 https：//[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/) 開啟 AWS Glue主控台。 1. 在左側的導覽窗格中，選擇 **Tables (資料表)**。 1. 在清單中選擇資料表名稱，然後選擇 **Edit table (編輯資料表)**。 1. 在 **Table properties (資料表屬性)** 中，新增 **excludeStorageClasses** 做為索引鍵，並將 **[\$1"GLACIER\$1",\$1"DEEP\$1ARCHIVE\$1"]** 做為值。 1. 選擇**套用**。 # 在 AWS Glue 中管理適用於 ETL 輸出的分割區 分割區是組織資料集的一項重要技術，您可以有效率地對它們進行查詢。分割區會根據一或多個欄位的不同值來組織階層目錄結構組織中的資料。 例如，您可以決定在 Amazon Simple Storage Service (Amazon S3) 中以日期來分割應用程式日誌，並依年、月和天來劃分。與單一天資料對應的檔案會放在字首 (例如 `s3://my_bucket/logs/year=2018/month=01/day=23/`)。系統 (如 Amazon Athena、Amazon Redshift Spectrum 與現在的 AWS Glue) 可以使用這些分割區來依分割區值篩選資料，而不必從 Amazon S3 讀取所有基礎資料。 爬蟲程式不僅推斷檔案類型和結構描述，還會在填入 Glue Data Catalog AWS 時自動識別資料集的分割區結構。產生的分割區資料行可用於在 AWS Glue ETL 任務中查詢，或查詢 Amazon Athena 之類的引擎。 在您編目資料表後，您可以查看爬蟲程式建立的分割區。在 AWS Glue 主控台，於左側導覽窗格選擇 **Tables** (資料表)。選擇爬蟲程式建立的資料表，然後選擇 **View Partitions (檢視分割區)**。 對於樣式為 `key=val` 的 Apache Hive 樣式分割區路徑，爬蟲程式會自動使用金鑰名稱填入欄位名稱。否則，它會使用預設名稱，如 `partition_0`、`partition_1`，以此類推。您可以在主控台上變更預設名稱。請導覽至資料表執行此操作。在**索引**索引標籤下檢查索引是否存在。如果存在，您需要刪除索引才能繼續 (之後可以使用新資料欄名稱重新建立索引)。然後，選擇**編輯結構描述**，並在該處修改分割區資料欄的名稱。 在您的 ETL 指令碼中，所以您可以在分割區欄上篩選。因為分割區資訊儲存在 Data Catalog 中，請使用 `from_catalog` API 呼叫，以將分割區欄包含在 `DynamicFrame` 中。例如，使用 `create_dynamic_frame.from_catalog` 代替 `create_dynamic_frame.from_options`。 磁碟分割是減少資料掃描的最佳化技術。如需有關識別此技術何時適當之程序的詳細資訊，請參閱 AWS 《 方案指南》中的*效能調校 AWS Glue for Apache Spark 任務最佳實務*指南》中的[減少資料掃描量](https://docs.aws.amazon.com/prescriptive-guidance/latest/tuning-aws-glue-for-apache-spark/reduce-data-scan.html)。 ## 使用 pushdown 述詞預先篩選 在許多情況下，您可以使用 pushdown 述詞來在分割區上篩選，而無需列出和讀取資料集中的所有檔案。您不須在 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) ``` 此會建立在 Data Catalog 中載入並滿足述詞表達式的 DynamicFrame。根據您載入的資料子集大小，這可以節省大量的處理時間。 述詞表達式可以是 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 中的這些分割區的檔案之前套用。如果您有資料表的很多分割區，目錄分割區列表仍會產生額外的時間負荷。若要解決此額外負荷，您可以使用伺服器端分割區剔除搭配 Glue Data Catalog AWS 中使用[分割區索引](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html)`catalogPartitionPredicate`的選項。當您在一個資料表中有數百萬個分割區時，這會使分割區篩選速度更快。如果您的 `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") ``` # 讀取在大型群組中的輸入檔案 您可以設定資料表的屬性，來啟用 AWS Glue ETL 任務，以讓檔案從 Amazon S3 資料存放區進行讀取時進行分組。這些屬性可讓每個 ETL 任務將一組輸入檔案輸入到單一記憶體分割區，這在 Amazon S3 資料存放區中有大量小型檔案時特別有用。在您設定特定屬性時，您會指示 AWS Glue 以在 Amazon S3 資料分割區中分組檔案並設定要讀取的群組大小。您也可以在從 Amazon S3 資料存放區讀取時，使用 `create_dynamic_frame.from_options` 方法設定這些選項。 若要啟用資料表分組檔案，您須在資料表結構的參數欄位中設定金鑰值對。使用 JSON 符號來設定資料表的參數欄位值。關於編輯資料表屬性的詳細資訊，請參閱 [檢視與管理資料表詳細資訊](tables-described.md#console-tables-details)。 您可以使用此方法，以啟用在 Data Catalog 中與 Amazon S3 資料存放區的資料表群組。 **groupFiles** 將 **groupFiles** 設為 `inPartition`，可將檔案分組在 Amazon S3 資料分割區中。如果超過 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':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`從以下資料格式建立的 DynamicFrames 支援：csv、ion、grokLog、json 和 xml。avro、parquet 和 orc 不支援此選項。 # Amazon S3 的 VPC 端點 基於安全考量，許多 AWS 客戶會在 Amazon Virtual Private Cloud 環境 (Amazon VPC) 中執行其應用程式。運用 Amazon VPC，您可以將 Amazon EC2 執行個體啟動到 Virtual Private Cloud 上，此 Virtual Private Cloud 與其他網路 (包括公有網際網路) 在邏輯上隔離。使用 Amazon VPC，您可以控制其 IP 位址範圍、子網路、路由表、網路閘道及安全設定。 **注意** 如果您在 2013-12-04 之後建立 AWS 帳戶，則每個 AWS 區域都已有一個預設 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 端點時，區域 (例如 *s3.us-west-2.amazonaws.com*) 內傳送到 Amazon S3 端點的所有要求，都會轉傳到 Amazon 網路中的私有 Amazon S3 端點。您不需要修改 VPC 中在 Amazon EC2 執行個體上執行的應用程式，端點的名稱會保持不變，但轉傳至 Amazon S3 的作業會完全在 Amazon 網路中進行，不會存取公有的網際網路。 如需 VPC 端點的完整資訊，請參閱《Amazon VPC 使用者指南》中的 [VPC 端點](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints.html)。 下圖顯示 AWS Glue 可如何使用 VPC 端點來存取 Amazon S3。 ![\[顯示 VPC 與 Amazon S3 之間連線的網路傳輸流量。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/PopulateCatalog-vpc-endpoint.png) **設定 Amazon S3 的存取** 1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)：// 開啟 Amazon VPC 主控台。 1. 在左側導覽窗格中選擇 **Endpoints** (端點)。 1. 選擇 **Create Endpoint** (建立端點)，然後按照步驟來建立閘道類型的 Amazon S3 VPC 端點。 # Amazon DocumentDB 連線 您可以使用 AWS Glue for Spark 來讀取和寫入 Amazon DocumentDB 中的資料表。您可以使用 AWS Secrets Manager 透過 Glue 連線儲存在 中的登入資料來連線至 AWS Amazon DocumentDB。 如需 Amazon DocumentDB 的詳細資訊，請參閱 [Amazon DocumentDB 文件](https://docs.aws.amazon.com/documentdb/latest/developerguide/what-is.html)。 **注意** 使用 Glue 連接器時，目前不支援 Amazon DocumentDB AWS 彈性叢集。如需有關彈性叢集的詳細資訊，請參閱 [Using Amazon DocumentDB elastic clusters](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 時，在某些情況下 `retryWrites` 必須設定為 false，例如當編寫的文件指定 `_id` 時。如需詳細資訊，請參閱 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 (with MongoDB compatibility) 的連線。 來源連線和接收器連線的連線選項不同。 ### "connectionType": "Documentdb" as source 使用下列有 `"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` （預設） (Glue AWS 4.0 不支援） + `MongoSamplePartitioner` (Glue 4.0 AWS 不支援） + `MongoShardedPartitioner` + `MongoSplitVectorPartitioner` + `MongoPaginateByCountPartitioner` + `MongoPaginateBySizePartitioner` (Glue AWS 4.0 不支援） + `"partitionerOptions"` (選用)：指定分割區的選項。每個分割區都支援下列選項： + `MongoSamplePartitioner`: `partitionKey`, `partitionSizeMB`, `samplesPerPartition` + `MongoShardedPartitioner`: `shardkey` + `MongoSplitVectorPartitioner`：`partitionKey`，partitionSizeMB + `MongoPaginateByCountPartitioner`: `partitionKey`, `numberOfPartitions` + `MongoPaginateBySizePartitioner`：`partitionKey`，partitionSizeMB 如需有關這些選項的詳細資訊，請參閱 MongoDB 文件中的[分割區組態](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 遇到網路錯誤，則一次自動重試特定寫入操作。 # OpenSearch Service 連線 您可以使用 AWS Glue for Spark 在 Glue 4.0 AWS 和更新版本中讀取和寫入 OpenSearch Service 中的資料表。您可以使用 OpenSearch 查詢定義要從 OpenSearch Service 讀取的內容。您可以使用 AWS Secrets Manager 透過 Glue 連線儲存在 中的 HTTP AWS 基本身分驗證登入資料來連線至 OpenSearch Service。此功能與 OpenSearch Service Serverless 不相容。 如需有關 OpenSearch Service 的詳細資訊，請參閱 [Amazon OpenSearch Service 文件](https://docs.aws.amazon.com/opensearch-service/)。 ## 設定 OpenSearch Service 連線 若要從 Glue AWS 連線至 OpenSearch Service，您需要在 AWS Secrets Manager 秘密中建立和存放 OpenSearch Service 登入資料，然後將該秘密與 OpenSearch Service AWS Glue 連線建立關聯。 **先決條件：** + 依照 Amazon OpenSearch Service 文件中的說明，識別您想要讀取的網域端點 *aosEndpoint* 和連接埠 *aosPort* 或建立資源。如需有關建立網域的詳細資訊，請參閱《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*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *aosUser* 值來建立 `USERNAME` 金鑰對。 + 在選取**鍵/值組**時，請使用 *aosPassword* 值來建立 `PASSWORD` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線後，請保留連線名稱 *connectionName*，以供未來在 Glue AWS 中使用。 + 選取**連線類型**時，請選取 OpenSearch Service。 + 選取網域端點時，請提供 *aosEndpoint*。 + 選取連接埠時，請提供 *aosPort*。 + 選取 **AWS 機密**時，請提供 *secretName*。 建立 AWS Glue OpenSearch Service 連線後，您必須先執行下列步驟，才能執行 Glue AWS 任務： + 授予與您的 Glue 任務相關聯的 IAM AWS 角色讀取 *secretName* 的許可。 + 在您的 AWS Glue 任務組態中，提供 *connectionName* 作為**其他網路連線**。 ## 從 OpenSearch Service 索引讀取 **先決條件：** + 您想要讀取的 OpenSearch Service 索引 *aosIndex*。 + 設定為提供身分驗證和網路位置資訊的 AWS Glue OpenSearch Service 連線。若要取得此功能，請完成上一個程序*設定 OpenSearch Service 的連線*中的步驟。您需要 Glue AWS 連線的名稱 *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 查詢參數字串，請在查詢前面加上 `?q=` 字首 (如同您會在完整 URL 中加上字首)。若要提供查詢 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 的連線*中的步驟。您將需要 Glue AWS 連線的名稱 *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 資料庫中讀取和寫入資料表。連線至 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 使用者更輕鬆地遷移到 Glue AWS 以進行無伺服器資料整合和 ETL。 [![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 連線 若要在 Glue AWS 中使用 Amazon Redshift 叢集，您需要一些先決條件： + 從資料庫讀取和寫入資料庫時用於暫存空間的 Amazon S3 目錄。 + 啟用 Amazon Redshift 叢集、Glue AWS 任務和 Amazon S3 目錄之間通訊的 Amazon VPC。 + Glue 任務和 Amazon Redshift AWS 叢集的適當 IAM 許可。 ### 設定 IAM 角色 **設定 Amazon Redshift 叢集的角色** 您的 Amazon Redshift 叢集需要能夠讀取和寫入 Amazon S3，才能與 Glue AWS 任務整合。若要允許這項功能，您可以將 IAM 角色與想要連線的 Amazon Redshift 叢集建立關聯。您的角色應具有允許從 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 - Customizable」。 + 當系統要求您附加政策時，請選擇您先前定義的政策。 **注意** 如需設定 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/zh_tw/glue/latest/dg/images/RS-role-config.png) **注意** 根據預設， AWS Glue 任務會傳遞使用您指定執行任務的角色建立的 Amazon Redshift 臨時登入資料。我們不建議使用這些憑證。基於安全考量，這些憑證會在 1 小時後過期。 **設定 Glue AWS 任務的角色** Glue AWS 任務需要角色才能存取 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. 在左側導覽窗格中選擇**叢集**。 1. 選擇您想要從 AWS Glue 存取的叢集名稱。 1. 在 **Cluster Properties (叢集屬性)** 區段中，選擇 **VPC security groups (VPC 安全群組)** 中的安全群組，以允許 AWS Glue 使用。記錄所選的安全群組名稱，供日後參考。選擇安全群組後，將開啟 Amazon EC2 主控台**安全群組**清單。 1. 選擇要修改的安全群組並導覽至 **Inbound** (傳入) 索引標籤。 1. 新增自我參考規則，以允許 AWS Glue 元件進行通訊。具體來說，新增或確認有**類型** `All TCP`、**通訊協定**為 `TCP`，**連接埠範圍**包含所有連接埠，且其**來源**與**群組 ID** 為相同安全群組名稱的規則。 傳入規則類似如下： **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/aws-glue-programming-etl-connect-redshift-home.html) 例如： ![\[自我參考的傳入規則範例。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/SetupSecurityGroup-Start.png) 1. 同時新增一個規則，以用於傳出流量。您可以開啟傳出流量到所有連接埠，例如： **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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 規則。安全群組規則需 *s3-prefix-list-id*，以允許該 VPC 至 Amazon S3 VPC 端點間的流量。 例如： **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/aws-glue-programming-etl-connect-redshift-home.html) ### 設定 AWS Glue 您需要建立提供 AWS Amazon VPC 連線資訊的 Glue Data Catalog 連線。 **在主控台中設定 Amazon Redshift Amazon VPC 與 Glue AWS 的連線** 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* (在帳戶 *role-account-id* 中) 的 Amazon S3 URI。 ------ #### [ 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 Serverless 時，請參閱 Amazon Redshift 文件中的 [Connecting to 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` 地圖中。 將密碼硬式編碼到 Glue AWS 指令碼是不好的做法。請考慮將密碼儲存在 中 AWS Secrets Manager ，並使用適用於 Python 的 SDK (Boto3) 擷取指令碼中的密碼。 ``` 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* (在帳戶 *role-account-id* 中) 的 Amazon S3 URI。您還需要一個 `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 連線選項參考 用於所有 AWS Glue JDBC 連線的基本連線選項，用於設定 等資訊`url`，`user`且在所有 JDBC 類型之間`password`保持一致。如需有關標準 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。Glue AWS 任務會將此角色傳遞給 Amazon Redshift 叢集，以授予完成任務指示所需的叢集許可。 ### Glue 4.0\$1 AWS 中可用的其他連線選項 您也可以透過 Glue AWS 連線選項，傳遞新 Amazon Redshift 連接器的選項。如需支援的連接器選項完整清單，請參閱 [Amazon Redshift integration for Apache Spark](https://docs.aws.amazon.com/redshift/latest/mgmt/spark-redshift-connector.html) (Apache Spark 的 Amazon Redshift 整合) 中的 *Spark SQL 參數*部分。 為方便起見，我們在此重申某些新選項： | 名稱 | 必要 | 預設 | Description | | --- | --- | --- | --- | | autopushdown | 否 | TRUE | 擷取和分析 SQL 操作的 Spark 邏輯計畫，以套用述詞和查詢下推。這些操作會轉換成 SQL 查詢，然後在 Amazon Redshift 中執行以提高效能。 | | autopushdown.s3\$1result\$1cache | 否 | FALSE | 快取 SQL 查詢以卸載記憶體中 Amazon S3 路徑對應的資料，因此不需要在相同的 Spark 工作階段中再次執行相同的查詢。僅在啟用 `autopushdown` 時提供支援。 | | unload\$1s3\$1format | 否 | PARQUET | PARQUET – 以 Parquet 格式卸載查詢結果。 TEXT – 以管道分隔的文字格式卸載查詢結果。 | | sse\$1kms\$1key | 否 | N/A | 在`UNLOAD`操作期間用於加密的 AWS SSE-KMS 金鑰，而非預設加密 AWS。 | | extracopyoptions | 否 | N/A | 載入資料時要附加至 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) 的客戶受管金鑰來加密您的資料，您可以在`("sse_kms_key" → kmsKey)`其中設定 ksmKey 是[金鑰 ID AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/find-cmk-id-arn.html)，而不是 3.0 AWS Glue版`("extraunloadoptions" → s"ENCRYPTED KMS_KEY_ID '$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 中，ETL 任務可存取新的 Amazon Redshift Spark 連接器和具有不同選項和組態的新 JDBC 驅動程式。新 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 資料表名稱的要求更加嚴格。如需詳細資訊，請參閱 [Names and identifiers](https://docs.aws.amazon.com/redshift/latest/dg/r_names.html) (名稱和識別符) 以定義您的 Amazon Redshift 資料表名稱。任務書籤工作流程可能無法使用不符合規則和具有特定字元 (例如空格) 的資料表名稱。 如果舊版資料表名稱不符合[名稱和識別符](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)。 **Dataframe 中的預設 tempformat 變更** AWS Glue 3.0 版 Spark 連接器在寫入 Amazon Redshift 時將 `tempformat` 預設為 CSV。為了保持一致，在 AWS Glue 3.0 版本中，` DynamicFrame` 仍然將 `tempformat` 預設為使用 `CSV`。如果之前已將 Spark Dataframe API 直接與 Amazon Redshift Spark 連接器搭配使用，您可以在 `DataframeReader`/`Writer` 選項中將 `tempformat` 明確設定為 CSV。否則，`tempformat` 會在新 Spark 連接器中預設為 `AVRO`。 **行為變更：將 Amazon Redshift 資料類型 REAL 映射到 Spark 資料類型 FLOAT 而不是 DOUBLE** 在 AWS Glue 3.0 版本中，Amazon Redshift `REAL` 會轉換為 Spark ` DOUBLE` 類型。新的 Amazon Redshift Spark 連接器已經更新行為，以便 Amazon Redshift ` REAL` 類型轉換為 Spark `FLOAT` 類型，並轉換回來。如果您仍有希望將 Amazon Redshift `REAL` 類型映射至 Spark `DOUBLE` 類型的舊版使用案例，則可以使用下列因應措施： + 對於 `DynamicFrame`，將 `Float` 類型映射至具有 `DynamicFrame.ApplyMapping` 的 `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` 資料類型。若要解決此限制，您可以[建立 Redshift 檢視](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_VIEW.html)，以將 `VARBYTE` 資料欄轉換為支援的資料類型。然後，使用新的連接器從該檢視而不是原始資料表載入資料，這確保了相容性，同時保持對 `VARBYTE` 資料的存取。 Redshift 查詢的範例： ``` CREATE VIEW view_name AS SELECT FROM_VARBYTE(varbyte_column, 'hex') FROM table_name ``` # Kafka 連線 您可以使用 Kafka 連線來讀取和寫入 Kafka 資料串流，方法是使用儲存在 Data Catalog 資料表中的資訊，或提供資訊以直接存取資料串流。連線支援 Kafka 叢集或 Amazon Managed Streaming for Apache Kafka 叢集。您可以從 Kafka 讀取資訊到 Spark DataFrame，然後將其轉換為 AWS Glue DynamicFrame。您可以使用 JSON 格式將 DynamicFrames 寫入 Kafka。如果您直接存取資料串流，則請使用這些選項來提供如何存取資料串流的相關資訊。 如果您使用 `getCatalogSource` 或 `create_data_frame_from_catalog` 來取用來自 Kinesis 串流來源的記錄，或者使用 `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 組態。您需要建立提供 AWS Amazon VPC 連線資訊的 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 呼叫中指定，或在 Data Catalog 的資料表中繼資料中定義。 + `"security.protocol"`(必要) 用來與代理程式通訊的協定。可能的值為 `"SSL"` 或 `"PLAINTEXT"`。 + `"topicName"` (必要) 要訂閱的主題清單 (以逗號分隔)。您必須指定 `"topicName"`、`"assign"` 或 `"subscribePattern"` 其中一個。 + `"assign"`：(必要) JSON 字串，指定要消耗的特定 `TopicPartitions`。您必須指定 `"topicName"`、`"assign"` 或 `"subscribePattern"` 其中一個。 範例：'\$1"topicA":[0,1],"topicB":[2,4]\$1' + `"subscribePattern"`：(必要) 識別要訂閱的主題清單的 Java regex 字串。您必須指定 `"topicName"`、`"assign"` 或 `"subscribePattern"` 其中一個。 範例：'topic.\$1' + `"classification"` (必要) 記錄中資料使用的檔案格式。除非透過資料目錄提供，否則為必要。 + `"delimiter"` (選用) 當 `classification` 為 CSV 時使用的值分隔符號。預設值為 "`,`"。 + `"startingOffsets"`：(選用) 要從中讀取資料的 Kafka 主題的起始位置。可能的值為 `"earliest"` 或 `"latest"`。預設值為 `"latest"`。 + `"startingTimestamp"`：（選用，僅支援 AWS Glue 4.0 版或更新版本） Kafka 主題中要讀取資料的 記錄時間戳記。可能的值是 `yyyy-mm-ddTHH:MM:SSZ` 模式中 UTC 格式的時間戳記字串 (其中 `Z` 代表以 \$1/- 表示的 UTC 時區偏移。例如："2023-04-04T08:00:00-04:00")。 注意：Glue 串流指令碼的連線選項清單中只能有其中一個 'startingOffsets' AWS 或 '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"` （必要） AWS 用來連線至 Kafka 叢集的 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 接收器。請注意，連線選項上沒有允許清單，所有金鑰值對都按原樣保留在接收器上。 但是，有一個不會生效的小型拒絕選項清單。如需詳細資訊，請參閱 [Kafka 特定的組態](https://spark.apache.org/docs/latest/structured-streaming-kafka-integration.html)。 # Azure Cosmos DB 連線 您可以使用 AWS Glue for Spark，在 Glue 4.0 和更新版本中使用 NoSQL API AWS 從 Azure Cosmos 資料庫讀取和寫入現有容器。您可以使用 SQL 查詢定義要從 Azure Cosmos DB 讀取的內容。您可以使用 AWS Secrets Manager 透過 Glue AWS 連線存放在 中的 Azure Cosmos 資料庫金鑰來連線至 Azure Cosmos 資料庫。 如需有關 Azure Cosmos DB for NoSQL 的詳細資訊，請參閱 [Azure 文件](https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/)。 ## 設定 Azure Cosmos DB 連線 若要從 Glue AWS 連線至 Azure Cosmos 資料庫，您需要建立 Azure Cosmos 資料庫金鑰並將其存放在 AWS Secrets Manager 秘密中，然後將該秘密與 Azure Cosmos 資料庫 AWS Glue 連線建立關聯。 **先決條件：** + 在 Azure 中，您將需要識別或產生 Azure Cosmos 資料庫金鑰，以供 AWS Glue、 使用`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 資料庫金鑰建立秘密。若要在 Secrets Manager 中建立秘密，請遵循 AWS Secrets Manager 文件中[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中提供的教學課程。建立機密之後，請保留機密名稱 *secretName*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *cosmosKey* 值來建立 `spark.cosmos.accountKey` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線後，請保留連線名稱 *connectionName*，以供未來在 Glue AWS 中使用。 + 選取**連線類型**時，請選取 Azure Cosmos DB。 + 選取 **AWS 機密**時，請提供 *secretName*。 建立 AWS Glue Azure Cosmos 資料庫連線後，您必須先執行下列步驟，才能執行 Glue AWS 任務： + 授予與您的 Glue 任務相關聯的 IAM AWS 角色讀取 *secretName* 的許可。 + 在您的 AWS Glue 任務組態中，提供 *connectionName* 作為**其他網路連線**。 ## 從 Azure Cosmos DB for NoSQL 容器讀取 **先決條件：** + 您想要讀取的 Azure Cosmos DB for NoSQL 容器。您將需要容器的識別資訊。 An Azure Cosmos NoSQL 容器由資料庫和容器識別。連線至 Azure Cosmos for NoSQL API 時，您必須提供資料庫名稱 *cosmosDBName* 和容器名稱 *cosmosContainerName*。 + 設定為提供身分驗證和網路位置資訊的 AWS Glue Azure Cosmos 資料庫連線。若要取得此功能，請完成上一個程序*設定連至 Azure Cosmos DB 的連線*中的步驟。您需要 Glue AWS 連線的名稱 *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 資料表。您將需要容器的識別資訊。**您必須先建立容器，再呼叫連線方法。** An Azure Cosmos NoSQL 容器由資料庫和容器識別。連線至 Azure Cosmos for NoSQL API 時，您必須提供資料庫名稱 *cosmosDBName* 和容器名稱 *cosmosContainerName*。 + 設定為提供身分驗證和網路位置資訊的 AWS Glue Azure Cosmos 資料庫連線。若要取得此功能，請完成上一個程序*設定連至 Azure Cosmos DB 的連線*中的步驟。您需要 Glue AWS 連線的名稱 *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 資料庫連線名稱。 + `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 來讀取和寫入 Glue 4.0 AWS 及更新版本的 Azure SQL 受管執行個體上的資料表。您可以使用 SQL 查詢定義要從 Azure SQL 讀取的內容。您可以使用 AWS Secrets Manager 透過 Glue AWS 連線存放在 中的使用者和密碼登入資料來連線至 Azure SQL。 如需有關 Azure SQL 的詳細資訊，請參閱 [Azure SQL 文件](https://azure.microsoft.com/en-us/products/azure-sql)。 ## 設定 Azure SQL 連線 若要從 Glue AWS 連線至 Azure SQL，您需要在 AWS Secrets Manager 秘密中建立和存放 Azure SQL 登入資料，然後將該秘密與 Azure SQL Glue AWS 連線建立關聯。 **設定連至 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*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *azuresqlUsername* 值來建立 `user` 金鑰對。 + 在選取**鍵/值組**時，請使用 *azuresqlPassword* 值來建立 `password` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線後，請保留連線名稱 *connectionName*，以供未來在 Glue AWS 中使用。 + 選取**連線類型**時，請選取 Azure SQL。 + 提供 **Azure SQL URL**時，請提供 JDBC 端點 URL。 此 URL 必須採用下列格式：`jdbc:sqlserver://databaseServerName:databasePort;databaseName=azuresqlDBname;`。 AWS Glue 需要下列 URL 屬性： + `databaseName`：要連線之 Azure SQL 的預設資料庫。 如需有關 Azure SQL 受控執行個體之 JDBC URL 的詳細資訊，請參閱 [Microsoft 文件](https://learn.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=azuresqldb-mi-current)。 + 選取 **AWS 機密**時，請提供 *secretName*。 建立 AWS Glue Azure SQL 連線後，您必須先執行下列步驟，才能執行 Glue AWS 任務： + 授予與您的 Glue 任務相關聯的 IAM AWS 角色讀取 *secretName* 的許可。 + 在您的 AWS Glue 任務組態中，提供 *connectionName* 作為**其他網路連線**。 ## 從 Azure SQL 資料表讀取 **先決條件：** + 您想要讀取的 Azure SQL 資料表。您將需要資料表的識別資訊 *databaseName* 和 *tableIdentifier*。 Azure SQL 資料表由資料庫、結構描述及資料表名稱識別。連線至 Azure SQL 時，您必須提供資料庫名稱和資料表名稱。如果結構描述不是預設的 "public"，您也必須提供結構描述。資料庫會透過 *connectionName* 中的 URL 屬性提供，而結構描述和資料表名稱會透過 `dbtable` 提供。 + 設定為提供身分驗證資訊的 AWS Glue Azure SQL 連線。完成上一個程序*設定連至 Azure SQL 的連線*的步驟，以設定驗證資訊。您需要 Glue AWS 連線的名稱 *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 在 Glue 4.0 AWS 和更新版本中讀取和寫入 Google BigQuery 中的資料表。您可以使用 Google SQL 查詢，從 BigQuery 讀取。您可以使用 AWS Secrets Manager 透過 Glue 連線儲存在 AWS 中的登入資料來連線至 BigQuery。 如需有關 Google BigQuery 的詳細資訊，請參閱 [Google Cloud BigQuery 網站](https://cloud.google.com/bigquery)。 ## 設定 BigQuery 連線 若要從 Glue AWS 連線至 Google BigQuery，您需要在 AWS Secrets Manager 秘密中建立和存放 Google Cloud Platform 登入資料，然後將該秘密與 Google BigQuery AWS Glue 連線建立關聯。 **設定連至 BigQuery 的連線：** 1. 在 Google Cloud Platform 中建立並識別相關資源： + 建立或識別 GCP 專案，其中應包含您要連線之 BigQuery 資料表。 + 啟用 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 憑證精靈來加速此步驟：[Create credentials](https://console.cloud.google.com/apis/credentials/wizard?api=bigquery.googleapis.com)。 若要在 GCP 中建立服務帳戶，請依照 [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create) 中提供的教學課程進行操作。 + 在選取**專案**時，請選取包含您 BigQuery 資料表的專案。 + 在為您的服務帳戶選取 GCP IAM 角色時，請新增或建立角色，其會授予供執行 BigQuery 任務的適當許可，以讀取、寫入或建立 BigQuery 資料表。 若要為您的服務帳戶建立憑證，請依照 [Create a service account key](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 Data Catalog 中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線之後，請保留連線名稱 *connectionName*，以便進行下一個步驟。 + 選取**連線類型**時，請選取 Google BigQuery。 + 選取 **AWS 機密**時，請提供 *secretName*。 1. 授予與您的 Glue 任務相關聯的 IAM AWS 角色讀取 *secretName* 的許可。 1. 在您的 AWS Glue 任務組態中，提供 *connectionName* 作為**其他網路連線**。 ## 從 BigQuery 資料表讀取 **先決條件：** + 您要從中讀取的 BigQuery 資料表。您將會需要 BigQuery 資料表和資料集名稱，形式為 `[dataset].[table]`。我們稱此為 *tableName*。 + BigQuery 資料表的計費專案。您將會需要專案的名稱，*parentProject*。若無計費父系專案，請使用包含資料表的專案。 + BigQuery 身分驗證資訊。完成步驟 *使用 Glue AWS 管理您的連線憑證*，以設定您的身分驗證資訊。您將會需要 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 資料集 *materializationDataset*，BigQuery 才能為您的查詢寫入具體化視觀表。 您將需授予適當的 GCP IAM 許可給您的服務帳戶，以在 *materializationDataset* 中建立資料表。 ``` 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 資料表。您將會需要 BigQuery 資料表和資料集名稱，形式為 `[dataset].[table]`。您也可以提供自動建立的新資料表名稱。我們稱此為 *tableName*。 + BigQuery 資料表的計費專案。您將會需要專案的名稱，*parentProject*。若無計費父系專案，請使用包含資料表的專案。 + BigQuery 身分驗證資訊。完成步驟 *使用 Glue AWS 管理您的連線憑證*，以設定您的身分驗證資訊。您將會需要 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`：(必要) 用於讀取/寫入。BigQuery 資料表的名稱，格式為 `[[project:]dataset.]`。 + `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 Storage，然後將資料複製至 Google BigQuery。 **先決條件：** 您將需要一個臨時的 Google Cloud Storage 儲存貯體，*temporaryBucket*。 Glue 的 GCP AWS 服務帳戶的 GCP IAM 角色將需要適當的 GCS 許可才能存取 *temporaryBucket*。 **其他組態：** **使用 BigQuery 設定間接寫入：** 1. 評估 [設定 BigQuery 連線](#aws-glue-programming-etl-connect-bigquery-configure) 並找出或重新下載您的 GCP 憑證 JSON 檔案。識別 *secretName*，這是任務中使用的 Google BigQuery AWS Glue 連線的 AWS Secrets Manager 秘密。 1. 將您的憑證 JSON 檔案上傳至適當安全的 Amazon S3 位置。保留前往該檔案的路徑，*s3secretpath*，以供後續步驟使用。 1. 編輯 *secretName*，新增 `spark.hadoop.google.cloud.auth.service.account.json.keyfile` 金鑰。將值設定為 *s3secretpath*。 1. 授予 AWS Glue 任務 Amazon S3 IAM 存取 *s3secretpath* 的許可。 您現在可將暫時 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/) 文件。 AWS Glue 原生支援透過其 JDBC 連接器連線至特定資料庫 - JDBC 程式庫在 Glue Spark AWS 任務中提供。使用 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)。 下表列出 Glue 支援的 JDBC AWS 驅動程式版本。 | 產品 | 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 版和更新版本的 Glue with Spark AWS 任務中，適用於 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)。 若要將 Amazon VPC 設定為使用 JDBC 連線到 Amazon RDS 資料存放區，請參閱 [針對從 AWS Glue 到 Amazon RDS 資料存放區的 JDBC 連線設定 Amazon VPC](setup-vpc-for-glue-access.md)。 **注意** AWS 在執行期間，Glue 任務只會與一個子網路相關聯。這可能會影響您透過相同的任務連線至多個資料來源的能力。此行為不限於 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、使用者和密碼；因此您不需要在程式碼中將其指定為連線選項。Glue AWS 3.0 及更新版本提供此功能。若要這樣做，請使用下列連線屬性： + `"useConnectionProperties"`：將其設定為 "true"，以指示您想要使用連線中的組態。 + `"connectionName"`：輸入要從中擷取組態的連線名稱，連線必須在與任務相同的區域中定義。 將下列連線選項與 JDBC 連線搭配使用： + `"url"`：(必要) 資料庫的 JDBC URL。 + `"dbtable"`：(必要) 要讀取的資料庫資料表。若是支援資料庫內結構描述的 JDBC 資料存放區，請指定 `schema.table-name`。如果未提供結構描述，則會使用預設的 "public" 結構描述。 + `"user"`：(必要) 連線時所要使用的使用者名稱。 + `"password"`：(必要) 連線時所要使用的密碼。 + (選用) 下列選項可讓您提供自訂 JDBC 驅動程式。如果您必須使用 AWS Glue 原生不支援的驅動程式，請使用這些選項。 ETL 任務可以對資料來源和目標使用不同的 JDBC 驅動程式版本，即使來源和目標是相同的資料庫產品。這可讓您在不同版本的來源和目標資料庫之間移轉資料。若要使用這些選項，您必須先將 JDBC 驅動程式的 JAR 檔案上傳到 Amazon S3。 + `"customJdbcDriverS3Path"`：自訂 JDBC 驅動程式的 Amazon S3 路徑。 + `"customJdbcDriverClassName"`：JDBC 驅動程式的類別名稱。 + `"bulkSize"`：(選用) 用於設定平行插入，以加速 JDBC 目標的大量載入。指定寫入或插入資料時要使用之平行處理程度的整數值。此選項有助於改善寫入資料庫 (例如 Arch 使用者儲存庫 (AUR)) 的效能。 + `"hashfield"` (選用) 一個字串，用於指定 JDBC 資料表中的資料欄名稱，以便在從 JDBC 資料表平行讀取時將資料劃分為分割區。提供 "hashfield" 或 "hashexpression"。如需詳細資訊，請參閱[從 JDBC 資料表中平行讀取](run-jdbc-parallel-read-job.md)。 + `"hashexpression"` (選用) 傳回整數的 SQL 選取子句。用於在從 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， `sampleQuery`必須以 "where" 或 "and" 結尾，Glue AWS 才能附加分割條件。**如需詳細資訊，請參閱[使用 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 通常只需用於效能目的。如果您嘗試預覽資料集的幾個資料列，請考慮使用 [顯示](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 不會預期大量輸送量，因此會在單一執行器上執行您的查詢。為了限制您提供的資料而不會導致效能問題，我們建議您向 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` 進行一些更改。 搭配 使用 JDBC 分割時`sampleQuery`，您的查詢必須以 "where" 或 "and" 結尾，Glue AWS 才能附加分割條件。 如果您想要在從 JDBC 資料表平行讀取時限制 SampleQuery 的結果數量，請設定 `"sampleSize"` 參數，而不是指定 `LIMIT` 子句。 **Example 搭配使用 sampleQuery 與 JDBC 分區** 以下程式碼範例顯示如何搭配使用 `sampleQuery` 與 JDBC 分區。 ``` //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 資料庫。這些範例示範讀取一個版本的資料庫產品並寫入相同產品的更高版本。 ------ #### [ 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 資料表中平行讀取 您可以設定 JDBC 資料表的屬性，讓 AWS Glue 平行讀取資料。設定特定屬性時，您指示 AWS Glue 來對資料的邏輯分割區執行平行 SQL 查詢。您可以透過設定雜湊欄位或雜湊表達式來控制分割。您也可以控制平行讀取的數量，這些讀取會用來存取您的資料。 並行讀取 JDBC 資料表是一種可以提高性能的最佳化技術。如需識別此技術何時適當之程序的詳細資訊，請參閱 AWS 《 方案指南》中的 *Apache Spark AWS Glue 任務效能調校最佳實務*指南》中的[減少資料掃描量](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** 將 `hashfield` 設為 JDBC 資料表中的欄位名稱，該 JDBC 資料表將用來將資料分配至分割區中。為獲得最佳結果，此欄位應擁有平均的分散值來將資料分散在分割區中。此欄位可以是任何資料類型。AWS Glue 會產生無重疊的查詢，這些查詢會平行執行，以讀取此欄位所分割的資料。例如，如果您的資料依月份平均分散，您可以使用 `month` 欄位來平行讀取每個月的資料： ``` 'hashfield': 'month' ``` AWS Glue 建立查詢來將欄位值湊雜為分割區編號， 並針對所有分割區平行執行查詢。若要使用您自己的查詢來分割資料表讀取， 請提供 `hashexpression` 而非 `hashfield`。 **hashexpression** 將 `hashexpression` 設定為 SQL 表達式 (符合 JDBC 資料庫引擎文法)，此表達式會傳回一個整數。簡單表達式是資料表中任何數值欄位的名稱。AWS Glue 會產生 SQL 查詢來使用 `hashexpression` 子句中的 `WHERE` 來平行讀取 JDBC 資料以分割資料。 例如，使用數值欄位 `customerID` 來讀取依客戶編號分割的資料： ``` 'hashexpression': 'customerID' ``` 若要讓 AWS Glue 控制分割，請提供 `hashfield` 而非 `hashexpression`。 **hashpartitions** 將 `hashpartitions` 設定為 JDBC 資料表的平行讀取數。如果未設定該屬性，預設值為 7。 例如，將平行讀取數設定為 `5`，讓 AWS Glue 使用五個 (或更少) 查詢來讀取資料： ``` '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 管理主控台 ，並在 [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/)：// 開啟 Amazon RDS 主控台。 1. 在 Amazon RDS 主控台中，識別用來控制 Amazon RDS 資料庫存取的安全群組。 在左側導覽窗格中，選擇**資料庫**，然後從主窗格清單中選取要連接的執行個體。 在資料庫詳細資訊頁面的**連線與安全**索引標籤中，找到 **VPC 安全群組**。 1. 根據您的網路架構，識別最適合修改的關聯安全群組，以允許 Glue AWS 服務的存取。儲存其名稱 *database-security-group* 以供日後參考。如果沒有適當的安全群組，請遵循 Amazon RDS 文件中的指示，[透過建立安全群組來存取 VPC 中的資料庫執行個體](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_SettingUp.html)。 1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)：// 開啟 Amazon VPC 主控台。 1. 在 Amazon VPC 主控台中，識別如何更新 *database-security-group*。 在左側導覽窗格中，選擇**安全群組**，然後從主窗格清單中選取 *database-security-group*。 1. 找到 *database-security-group* 的安全群組 ID，*database-sg-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/zh_tw/glue/latest/dg/setup-vpc-for-glue-access.html) 1. 新增傳出流量的規則。 在安全群組詳細資訊頁面中，選取**編輯傳出規則**。 如果安全群組允許所有傳出流量，則不需要單獨的規則。例如： **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/setup-vpc-for-glue-access.html) 如果網路架構旨在限制傳出流量，請建立下列傳出規則： 建立自我參考規則，其中**類型**為 `All TCP`，**通訊協定**為 `TCP`，**連接埠範圍**包含所有連接埠，**目的地**為 *database-sg-id*。確認您為**目的地**輸入的安全群組與您編輯的安全群組相同。 如果使用 Amazon S3 VPC 端點，則請新增 HTTPS 規則，以允許從 VPC 到 Amazon S3 的流量。建立一個規則，其中**類型**為 `HTTPS`，**通訊協定**為 `TCP`，**連接埠範圍**為 `443`，**目的地**為 Amazon S3 閘道端點受管字首清單的 ID *s3-prefix-list-id*。如需字首清單和 Amazon S3 閘道端點的詳細資訊，請參閱 Amazon VPC 文件中的 [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/zh_tw/glue/latest/dg/setup-vpc-for-glue-access.html) # MongoDB 連線 您可以使用 AWS Glue for Spark 來讀取和寫入 Glue 4.0 和更新版本的 MongoDB AWS 和 MongoDB Atlas 中的資料表。您可以使用 AWS Secrets Manager 透過 Glue 連線儲存在 AWS 中的使用者名稱和密碼登入資料來連線至 MongoDB。 如需有關 MongoDB 的詳細資訊，請參閱 [MongoDB 文件](https://www.mongodb.com/docs/)。 ## 設定 MongoDB 連線 若要從 Glue AWS 連線至 MongoDB，您需要 MongoDB 登入資料 *mongodbUser* 和 *mongodbPass*。 若要從 Glue AWS 連線至 MongoDB，您可能需要一些先決條件： + 如果您的 MongoDB 執行個體位於 Amazon VPC 中，請將 Amazon VPC 設定為允許 Glue AWS 任務與 MongoDB 執行個體通訊，而不會讓流量周遊公有網際網路。 在 Amazon VPC 中，識別或建立 Glue AWS 在執行任務時將使用的 **VPC**、**子網路**和**安全群組**。此外，您也需要確保 Amazon VPC 已完成設定，以允許 MongoDB 執行個體與此位置之間的網路流量。根據您的網路配置，這可能需要變更安全群組規則、網路 ACL、NAT 閘道及對等連線。 然後，您可以繼續設定 AWS Glue 以與 MongoDB 搭配使用。 **設定連至 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*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *mongodbUser* 值來建立 `username` 金鑰對。 在選取**鍵/值組**時，請使用 *mongodbPass* 值來建立 `password` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線後，請保留連線名稱 *connectionName*，以供未來在 Glue AWS 中使用。 + 選取**連線類型**時，請選取 **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 執行個體 + 您需要提供 Amazon VPC 連線資訊給定義 MongoDB 安全登入資料的 AWS Glue 連線。建立或更新連線時，請在**網路選項**中設定 **VPC**、**子網路**及**安全群組**。 建立 AWS Glue MongoDB 連線後，您需要先執行下列動作，才能呼叫連線方法： + 如果您選擇建立 Secrets Manager 秘密，請授予與 Glue 任務相關聯的 IAM AWS 角色讀取 *secretName* 的許可。 + 在您的 AWS Glue 任務組態中，提供 *connectionName* 作為**其他網路連線**。 若要在 AWS Glue for Spark AWS 中使用 Glue MongoDB 連線，請在連線方法呼叫中提供 `connectionName`選項。或者，您可以遵循 中的步驟[在 ETL 任務中使用 MongoDB 連線](integrate-with-mongo-db.md)，將連線與 Glue Data Catalog AWS 搭配使用。 ## 使用 Glue 連線從 MongoDB AWS 讀取 **先決條件：** + 您想要讀取的 MongoDB 集合。您將需要集合的識別資訊。 MongoDB 集合由資料庫名稱與集合名稱 *mongodbName*、*mongodbCollection* 識別。 + 設定為提供身分驗證資訊的 AWS Glue MongoDB 連線。完成上一個程序*設定連至 MongoDB 的連線*的步驟，以設定驗證資訊。您需要 Glue AWS 連線的名稱 *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 的連線*的步驟，以設定驗證資訊。您需要 Glue AWS 連線的名稱 *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 連線名稱。如上一節所述設定 AWS Glue 連線時，[設定 MongoDB 連線](#aws-glue-programming-etl-connect-mongodb-configure)提供 `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" as Source 使用下列有 `"connectionType": "mongodb"` 的連線選項作為來源： + `"ssl"`：(選用) 如果 `true`，則啟用 SSL 連線。預設值為 `false`。 + `"ssl.domain_match"`：(選用) 如果 `true` 和 `ssl` 為 `true`，則執行網域符合檢查。預設值為 `true`。 + `"batchSize"`：(選用)：每個批次傳回的文件數目，於內部批次的游標內使用。 + `"partitioner"`：(選用)：從 MongoDB 讀取輸入資料的分割區類別名稱。連接器提供下列分割區： + `MongoDefaultPartitioner` （預設） (Glue AWS 4.0 不支援） + `MongoSamplePartitioner` （需要 MongoDB 3.2 或更新版本） (Glue AWS 4.0 不支援） + `MongoShardedPartitioner` (Glue 4.0 AWS 不支援） + `MongoSplitVectorPartitioner` (Glue 4.0 AWS 不支援） + `MongoPaginateByCountPartitioner` (Glue 4.0 AWS 不支援） + `MongoPaginateBySizePartitioner` (Glue 4.0 AWS 不支援） + `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 文件中的[分割區組態](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 遇到網路錯誤，則一次自動重試特定寫入操作。 # SAP HANA 連線 您可以使用 AWS Glue for Spark 在 Glue 4.0 AWS 和更新版本中讀取和寫入 SAP HANA 中的資料表。您可以使用 SQL 查詢定義要從 SAP HANA 讀取的內容。您可以使用 AWS Secrets Manager 透過 Glue SAP HANA 連線儲存在 AWS 中的 JDBC 登入資料來連線至 SAP HANA。 如需有關 SAP HANA JDBC 的詳細資訊，請參閱 [SAP HANA 文件](https://help.sap.com/docs/SAP_HANA_PLATFORM/0eec0d68141541d1b07893a39944924e/ff15928cf5594d78b841fbbe649f04b4.html)。 ## 設定 SAP HANA 連線 若要從 Glue AWS 連線至 SAP HANA，您需要在 AWS Secrets Manager 秘密中建立和存放 SAP HANA 登入資料，然後將該秘密與 SAP HANA AWS Glue 連線建立關聯。您需要設定 SAP HANA 服務與 Glue AWS 之間的網路連線。 若要連線至 SAP HANA，您可能需要部分先決條件： + 如果您的 SAP HANA 服務位於 Amazon VPC 中，請將 Amazon VPC 設定為允許 Glue AWS 任務與 SAP HANA 服務通訊，而不會讓流量周遊公有網際網路。 在 Amazon VPC 中，識別或建立 Glue AWS 在執行任務時將使用的 **VPC**、**子網路**和**安全群組**。此外，您也需要確保 Amazon VPC 已完成設定，以允許 SAP HANA 端點與此位置之間的網路流量。您的任務將需要與 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*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *saphanaUsername* 值來建立 `username/USERNAME` 金鑰對。 + 在選取**鍵/值組**時，請使用 *saphanaPassword* 值來建立 `password/PASSWORD` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線後，請保留連線名稱 *connectionName*，以供未來在 Glue AWS 中使用。 + 選取**連線類型**時，請選取 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 機密**時，請提供 *secretName*。 建立 AWS Glue SAP HANA 連線後，您必須先執行下列步驟，才能執行 Glue AWS 任務： + 授予與您的 Glue 任務相關聯的 IAM AWS 角色讀取 *secretName* 的許可。 + 在您的 AWS Glue 任務組態中，提供 *connectionName* 作為**其他網路連線**。 ## 從 SAP HANA 資料表讀取 **先決條件：** + 您想要讀取的 SAP HANA 資料表。您將需要資料表的識別資訊。 您可以在表單 `schemaName.tableName` 中使用 SAP HANA 資料表名稱和結構描述名稱來指定資料表。如果資料表位於預設結構描述 "public" 中，則不需要結構描述名稱和 "." 分隔符號。呼叫此 *tableIdentifier*。請注意，在 `connectionName` 中，資料庫會以 JDBC URL 參數形式提供。 + 設定為提供身分驗證資訊的 AWS Glue SAP HANA 連線。完成上一個程序中的步驟*設定連至 SAP HANA 的連線*，以設定驗證資訊。您需要 Glue AWS 連線的名稱 *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 資料表。 您可以在表單 `schemaName.tableName` 中使用 SAP HANA 資料表名稱和結構描述名稱來指定資料表。如果資料表位於預設結構描述 "public" 中，則不需要結構描述名稱和 "." 分隔符號。呼叫此 *tableIdentifier*。請注意，在 `connectionName` 中，資料庫會以 JDBC URL 參數形式提供。 + SAP HANA 驗證資訊。完成上一個程序中的步驟*設定連至 SAP HANA 的連線*，以設定驗證資訊。您需要 Glue AWS 連線的名稱 *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 在 Glue 4.0 AWS 和更新版本中讀取和寫入 Snowflake 中的資料表。您可以使用 SQL 查詢從 Snowflake 讀取。您可以使用使用者和密碼連線至 Snowflake。您可以透過 Glue Data Catalog 參考存放在 AWS Secrets Manager 中的 Snowflake AWS 登入資料。Glue for Spark AWS 的 Data Catalog Snowflake 登入資料與爬蟲程式的 Data Catalog Snowflake 登入資料分開存放。您必須選擇 `SNOWFLAKE` 類型連線，而不是設定為連線至 Snowflake 的 `JDBC` 類型連線。 如需有關 Snowflake 的詳細資訊，請參閱 [Snowflake 網站](https://www.snowflake.com/)。如需 Snowflake on 的詳細資訊 AWS，請參閱 [Amazon Web Services 上的 Snowflake Data Warehouse](https://aws.amazon.com/financial-services/partner-solutions/snowflake/)。 ## 設定 Snowflake 連線 透過網際網路連線至 Snowflake 資料庫沒有 AWS 先決條件。 或者，您可以執行下列組態，以使用 Glue AWS 管理您的連線憑證。 **使用 Glue AWS 管理您的連線憑證** 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 Data Catalog 中，選擇連線，然後選擇建立**連線**來**建立連線**。請遵循連線精靈中的步驟完成程序： + 選取**資料來源**時，選取 Snowflake，然後選擇**下一步**。 + 輸入連線詳細資訊，例如主機和連接埠。輸入主機 **Snowflake URL** 時，提供 Snowflake 執行個體的 URL。該 URL 通常使用 `account_identifier.snowflakecomputing.com` 格式的主機名稱。不過，URL 格式可能會因您的 Snowflake 帳戶類型 （例如 AWS，Azure 或 Snowflake 託管） 而有所不同。 + 選取 IAM 服務角色時，從下拉式功能表中選擇。這是您帳戶中的 IAM 角色，如果指定 VPC，將用於存取 AWS Secrets Manager 和指派 IP。 + 選取 **AWS 機密**時，請提供 *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)。 + 您將需要適當的 Glue Amazon VPC AWS 組態。 [配置 AWS Glue (AWS PrivateLink) 的介面 VPC 端點 (AWS PrivateLink)](vpc-interface-endpoints.md) + 您將需要建立提供 Amazon VPC 連線資訊的 AWS Glue Data Catalog 連線 （除了定義 Snowflake 安全登入資料的 AWS Secrets Manager 秘密 ID 之外）。您的 URL 在使用時會變更 AWS PrivateLink，如上一個項目中連結的 Snowflake 文件所述。 + 您需要任務組態，才能將資料目錄連線納入為**其他網路連線**。 ## 從 Snowflake 資料表讀取 **先決條件：**您想要讀取的 Snowflake 資料表。您需要 Snowflake 資料表名稱 *tableName*。您需要 Snowflake url *snowflakeUrl*、使用者名稱 *snowflakeUser* 和密碼 *snowflakePassword*。如果您的 Snowflake 使用者沒有預設的命名空間集，您將需要 Snowflake 資料庫名稱 *databaseName* 和結構描述名稱 *schemaName*。此外，如果您的 Snowflake 使用者沒有預設的倉儲集，您將需要倉儲名稱 *warehouseName*。 例如： **其他先決條件：**完成步驟 *使用 Glue AWS 管理您的連線憑證*，以設定 *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*。 例如： **其他先決條件：**完成步驟 *使用 Glue AWS 管理您的連線憑證*，以設定 *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` 來完成此操作。 您可以使用 參數從 AWS Secrets Manager 秘密擷取連線`secretId`參數。使用 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. Data Catalog 連線屬性 1. AWS Secrets Manager 秘密值 `secretId` （指定 時） 1. Snowflake 使用者預設值 連線到 Snowflake 時，通常使用以下參數。 + `sfDatabase`：未在 Snowflake 中設定使用者預設值時需要。用於讀取/寫入。連線後用於工作階段的資料庫。 + `sfSchema`：未在 Snowflake 中設定使用者預設值時需要。用於讀取/寫入。連線後用於工作階段的結構描述。 + `sfWarehouse`：未在 Snowflake 中設定使用者預設值時需要。用於讀取/寫入。連線後用於工作階段的預設虛擬倉儲。 + `sfRole`：未在 Snowflake 中設定使用者預設值時需要。用於讀取/寫入。連線後用於工作階段的預設安全角色。 + `sfUrl`：(必要) 用於讀取/寫入。以下列格式指定帳戶的主機名稱：`account_identifier.snowflakecomputing.com`。如需有關帳戶識別碼的詳細資訊，請參閱 Snowflake 文件中的 [Account Identifiers](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 陳述式會在 Glue AWS 和 Snowflake 之間傳輸資料後執行。如果陳述式包含 `%s`，則 `%s` 會以操作參考的資料表名稱取代。 + `autopushdown`：預設：`"on"`。有效值：`"on"`、`"off"`。此參數控制是否啟用自動查詢下推。如果下推已啟用，則在 Spark 上執行查詢時，若查詢的一部分可以「向下推」到 Snowflake 伺服器，它便會被下推。這可改善某些查詢的效能。如需有關是否可以下推查詢的資訊，請參閱 Snowflake 文件中的 [Pushdown](https://docs.snowflake.com/en/user-guide/spark-connector-use#pushdown)。 此外，Glue AWS 可能支援 Snowflake Spark 連接器上的一些選項。如需有關 Snowflake Spark 連接器上可用選項的詳細資訊，請參閱 Snowflake 文件中的 [Setting Configuration Options for the Connector](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` 參數不是必需的。 這兩種身分驗證方法都完全受支援，並且可以使用連線選項、Data Catalog 連線或 AWS Secrets Manager 秘密的任意組合進行設定。 ## Snowflake 連接器限制 使用 Glue for Spark AWS 連線至 Snowflake 受下列限制約束。 + 此連接器不支援任務書籤。如需有關任務書籤的詳細資訊，請參閱 [使用任務書籤追蹤處理的資料](monitor-continuations.md)。 + 此連接器不支援 Snowflake 使用 和 `create_dynamic_frame.from_catalog``write_dynamic_frame.from_catalog`方法來讀取和寫入 AWS Glue Data Catalog 中的資料表。 + 此連接器支援使用者名稱/密碼身分驗證和金鑰對身分驗證。目前不支援其他身分驗證方法 (例如 OAuth 或 SAML)。 + 串流任務不支援此連接器。 + 擷取資訊 (例如使用 `query` 參數擷取) 時，此連接器支援 `SELECT` 陳述式型查詢。不支援其他類型的查詢 (例如 `SHOW`、`DESC` 或 DML 陳述式)。 + Snowflake 會將透過 Snowflake 用戶端提交的查詢文字 (例如 SQL 陳述式) 的大小限制為每個陳述式 1 MB。如需詳細資訊，請參閱 [Limits on Query Text Size](https://docs.snowflake.com/en/user-guide/query-size-limits)。 # Teradata Vantage 連線 您可以使用 AWS Glue for Spark 從 Glue 4.0 和更新版本中的 Teradata Vantage AWS 中讀取和寫入現有資料表。您可以使用 SQL 查詢定義要從 Teradata 讀取的內容。您可以使用 AWS Secrets Manager 透過 Glue 連線儲存在 AWS 中的使用者名稱和密碼登入資料來連線至 Teradata。 如需有關 Teradata 的詳細資訊，請參閱 [Teradata 文件](https://docs.teradata.com/)。 ## 設定 Teradata 連線 若要從 Glue AWS 連線至 Teradata，您需要在 AWS Secrets Manager 秘密中建立和存放 Teradata 登入資料，然後將該秘密與 Glue Teradata AWS 連線建立關聯。如果您的 Teradata 執行個體位於 Amazon VPC 中，您也需要為 Glue Teradata AWS 連線提供聯網選項。 若要從 Glue AWS 連線至 Teradata，您可能需要一些先決條件： + 如果您透過 Amazon VPC 存取 Teradata 環境，請設定 Amazon VPC 以允許 Glue AWS 任務與 Teradata 環境通訊。我們不建議透過公有網際網路存取 Teradata 環境。 在 Amazon VPC 中，識別或建立 Glue AWS 在執行任務時將使用的 **VPC**、**子網路**和**安全群組**。此外，您也需要確保 Amazon VPC 已完成設定，以允許 Teradata 執行個體與此位置之間的網路流量。您的任務將需要與 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 組態中，識別或建立 Glue AWS 將與 *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*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *teradataUsername* 值來建立 `user` 金鑰對。 + 在選取**鍵/值組**時，請使用 *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 執行個體 + 您需要將 Amazon VPC 連線資訊提供給定義 Teradata 安全登入資料的 AWS Glue 連線。建立或更新連線時，請在**網路選項**中設定 **VPC**、**子網路**及**安全群組**。 建立 AWS Glue Teradata 連線後，您需要先執行下列步驟，才能呼叫連線方法。 + 授予與您的 Glue 任務相關聯的 IAM AWS 角色讀取 *secretName* 的許可。 + 在您的 AWS Glue 任務組態中，提供 *connectionName* 作為**其他網路連線**。 ## 從 Teradata 中讀取 **先決條件：** + 您想要讀取的 Teradata 資料表。您將需要資料表名稱 *tableName*。 + 設定為提供身分驗證資訊的 AWS Glue Teradata 連線。完成步驟*設定連至 Teradata 的連線*，以設定身份驗證資訊。您需要 Glue AWS 連線的名稱 *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 (原生物件存放區) 連線是 Teradata Vantage 的新連接，其利用 Teradata WRITE\$1NOS 查詢從現有資料表中讀取資料，並利用 READ\$1NOS 查詢寫入資料表。這些查詢使用 Amazon S3 作為暫存型錄，因此 Teradata NOS 連接器比現有的 Teradata 連接器 (以 JDBC 為基礎) 更快，特別是在處理大量資料時。 您可以使用 AWS Glue for Spark 中的 Teradata NOS 連線，在 AWS Glue 5.0 版和更新版本中讀取和寫入 Teradata Vantage 中的現有資料表。您可以使用 SQL 查詢定義要從 Teradata 讀取的內容。您可以使用 AWS Secrets Manager 透過連線儲存在 中的使用者名稱和密碼登入資料來 AWS Glue 連線至 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 連線 若要從 連線至 Teradata NOS AWS Glue，您需要在 AWS Secrets Manager 秘密中建立和存放 Teradata 登入資料，然後將該秘密與 AWS Glue Teradata NOS 連線建立關聯。如果您的 Teradata 執行個體位於 Amazon VPC 中，您也需要為 AWS Glue Teradata NOS 連線提供聯網選項。 **先決條件：** + 如果您透過 Amazon VPC 存取 Teradata 環境，請將 Amazon VPC 設定為允許 AWS Glue 任務與 Teradata 環境通訊。我們不建議透過公有網際網路存取 Teradata 環境。 + 在 Amazon VPC 中，識別或建立 AWS Glue 將在執行任務時使用的 VPC、子網路和安全群組。此外，您也需要確保 Amazon VPC 已完成設定，以允許 Teradata 執行個體與此位置之間的網路流量。您的任務將需要與 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 組態中，識別或建立將使用其來連線的 *teradataUsername* 和 *teradataPassword* AWS Glue 。如需詳細資訊，請參閱 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*，以便進行下一個步驟。 + 在選取金鑰/值對時，使用 *teradataUsername* 值來建立金鑰 USERNAME 的對。 + 在選取金鑰/值對時，使用 *teradataPassword* 值來建立金鑰 PASSWORD 的對。 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 執行個體，您需要提供 Amazon VPC 連線資訊給定義 Teradata 安全憑證的 AWS Glue 連線。建立或更新連線時，在**網路選項**中設定 **VPC**、**子網路**及**安全群組**。 建立 AWS Glue Teradata Vantage NOS 連線後，您需要先執行下列步驟，才能呼叫連線方法。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 *secretName* 的許可。 1. 在您的 AWS Glue 任務組態中，提供 *connectionName* 做為**連線**下**的其他網路連線**。 ## 從 Teradata 資料表中讀取 ### 事前準備： + 您想要讀取的 Teradata 資料表。您將需要資料表名稱 *tableName*。 + Teradata 環境具有 `staging_fs_url` 選項 *stagingFsUrl* 所指定 Amazon S3 路徑的寫入存取權。 + 與 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` 選項 *stagingFsUrl* 所指定 Amazon S3 位置的讀取存取權。 + 與 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 資料表或者變更主要索引) 時很有用。請注意，create table 指令碼中使用的資料表名稱應與 `dbtable` 選項中指定的資料表名稱相符。 + `partition_size_in_mb` - 選用。用於讀取。讀取暫存 Amazon S3 物件時 Spark 分區的大小上限 (以 MB 為單位)。預設值為 128。 您可以在建立 Teradata 節點時提供進階選項。這些選項與 AWS Glue Spark 指令碼程式設計時可用的選項相同。 請參閱 [Teradata Vantage 連線](aws-glue-programming-etl-connect-teradata-home.md)。 **授權選項：** 以下是用於提供 AWS 帳戶登入資料的選項，供連接器用來存取預備 Amazon S3 儲存貯體。您可以選擇 (1) 完全不提供任何授權選項，並使用從 AWS Glue 執行角色產生的臨時登入資料；或 (2) 提供`auth_object`您所建立的授權物件；或 (3) `aws_access_key_id and aws_secret_access_key` 如果使用長期登入資料，則提供 ，`aws_session_token`如果使用臨時登入資料`aws_secret_access_key`，則提供 `aws_access_key`、 和 。 + `auth_object` - 選用。用於存取暫存 Amazon S3 儲存貯體。在 Teradata 執行個體中建立的授權物件字串。如果提供，連接器將使用此授權物件來存取暫存 Amazon S3 儲存貯體。如果未提供 和 `aws_secret_access_key` ，也未提供 `aws_access_key_id`和 ，則會從 AWS Glue 執行角色擷取臨時登入資料，並由連接器使用。與此授權物件相關聯的 AWS 帳戶必須與您的 AWS Glue 任務和臨時 Amazon S3 儲存貯體位於相同區域，或使用跨帳戶信任設定。 + `aws_access_key_id` - 選用。用於存取暫存 Amazon S3 儲存貯體。 AWS 帳戶安全登入資料的一部分。如果未提供 `auth_object`，且隨 `aws_secret_access_key` 提供 `aws_access_key_id`，連接器將使用其來存取暫存 Amazon S3 儲存貯體。與此存取金鑰相關聯的 AWS 帳戶必須與您的 AWS Glue 任務和臨時 Amazon S3 儲存貯體位於相同區域，或使用跨帳戶信任設定。 + `aws_secret_access_key` - 選用。用於存取暫存 Amazon S3 儲存貯體。 AWS 帳戶安全登入資料的一部分。如果未提供 `auth_object`，且隨 `aws_access_key_id` 提供 `aws_secret_access_key`，連接器將使用其來存取暫存 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/zh_tw/glue/latest/dg/images/teradata-nos-vantage-connection-options.png) # Vertica 連線 您可以使用 AWS Glue for Spark 從 Vertica 中的 Glue 4.0 AWS 及更新版本讀取和寫入資料表。您可以使用 SQL 查詢定義要從 Vertica 讀取的內容。您可以使用 AWS Secrets Manager 透過 Glue 連線儲存在 AWS 中的使用者名稱和密碼登入資料來連線至 Vertica。 如需有關 Vertica 的詳細資訊，請參閱 [Vertica 文件](https://www.vertica.com/docs/9.3.x/HTML/Content/Authoring/UsingVerticaOnAWS/UsingVerticaOnAWS.htm)。 ## 設定 Vertica 連線 若要從 Glue AWS 連線至 Vertica，您需要在 AWS Secrets Manager 秘密中建立並存放 Vertica 登入資料，然後將該秘密與 Vertica AWS Glue 連線建立關聯。如果您的 Vertica 執行個體位於 Amazon VPC 中，您也需要提供聯網選項給 AWS Glue Vertica 連線。從資料庫讀取和寫入資料庫時，您將需要用於暫存空間的 Amazon S3 儲存貯體或資料夾。 若要從 Glue AWS 連線至 Vertica，您將需要一些先決條件： + 從資料庫讀取和寫入資料庫時用於暫存空間的 Amazon S3 儲存貯體或資料夾 (稱為 *tempS3Path*)。 **注意** 在 Glue AWS 任務資料預覽中使用 Vertica 時，可能不會自動從 *tempS3Path* 中移除暫存檔案。若要確保移除暫存檔案，請選擇**資料預覽**窗格中的**結束工作階段**，直接結束資料預覽工作階段。 如果無法保證資料預覽工作階段會直接結束，請考慮設定 Amazon S3 生命週期組態以移除舊資料。根據最長任務執行期和餘裕，我們建議移除超過 49 小時的資料。如需有關設定 Amazon S3 生命週期的詳細資訊，請參閱《Amazon S3 文件》中的[管理您的儲存空間生命週期](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)。 + 具有 Amazon S3 路徑適當許可的 IAM 政策，可與 Glue AWS 任務角色建立關聯。 + 如果您的 Vertica 執行個體位於 Amazon VPC 中，請設定 Amazon VPC 以允許 Glue AWS 任務與 Vertica 執行個體通訊，而不會讓流量周遊公有網際網路。 在 Amazon VPC 中，識別或建立 Glue AWS 在執行任務時將使用的 **VPC**、**子網路**和**安全群組**。此外，您也需要確保 Amazon VPC 已完成設定，以允許 Vertica 執行個體與此位置之間的網路流量。您的任務將需要與 Vertica 用戶端連接埠建立 TCP 連線 (預設 5433)。根據您的網路配置，這可能需要變更安全群組規則、網路 ACL、NAT 閘道及對等連線。 然後，您可以繼續設定 AWS Glue 以搭配 Vertica 使用。 **設定連至 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*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *verticaUsername* 值來建立 `user` 金鑰對。 + 在選取**鍵/值組**時，請使用 *verticaPassword* 值來建立 `password` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線之後，請保留連線名稱 *connectionName*，以便進行下一個步驟。 + 選取**連線類型**時，請選取 Vertica。 + 選取 **Vertica 主機**後，請提供 Vertica 安裝的主機名稱。 + 選取 **Vertica 連接埠**時，您可透過該連接埠安裝 Vertica。 + 選取 **AWS 機密**時，請提供 *secretName*。 1. 在下列情況中，您可能需要其他組態： + 對於 Amazon VPC AWS 中託管於 的 Vertica 執行個體 + 將 Amazon VPC 連線資訊提供給定義 Vertica 安全登入資料的 AWS Glue 連線。建立或更新連線時，請在**網路選項**中設定 **VPC**、**子網路**及**安全群組**。 建立 AWS Glue Vertica 連線後，您需要先執行下列步驟，才能呼叫連線方法。 + 將與您的 Glue AWS 任務許可相關聯的 IAM 角色授予 *tempS3Path*。 + 授予與您的 Glue 任務相關聯的 IAM AWS 角色讀取 *secretName* 的許可。 + 在您的 AWS Glue 任務組態中，提供 *connectionName* 作為**其他網路連線**。 ## 從 Vertica 讀取 **先決條件：** + 您想要讀取的 Vertica 資料表。您將需要 Vertica 資料庫名稱 *dbName* 和資料表名稱 *tableName*。 + 設定為提供身分驗證資訊的 AWS Glue Vertica 連線。完成上一個程序*設定連至 Vertica 的連線*的步驟，以設定驗證資訊。您需要 Glue AWS 連線的名稱 *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 的連線*的步驟，以設定驗證資訊。您需要 Glue AWS 連線的名稱 *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。 ## Glue 5.0 for Spark 中 ETL AWS 的 DataFrame 選項 DataFrame 是一種類似於資料表的、以具名資料欄組織的資料集，支援功能樣式 (對應/減少/篩選/等) 操作和 SQL 操作 (選取、專案、彙總)。 若要為 Glue 支援的資料來源建立 DataFrame，需要下列項目： + 資料來源連接器 `ClassName` + 資料來源連線 `Options` 同樣地，若要將 DataFrame 寫入 Glue 支援的資料接收器，也需要相同的資料： + 資料接收器連接器 `ClassName` + 資料接收器連線 `Options` 請注意，DataFrame `connectionName` 不支援 Glue AWS 功能，例如任務書籤和 DynamicFrame 選項，例如 。如需 DataFrame 和支援操作的詳細資訊，請參閱 [DataFrame](https://spark.apache.org/docs/3.5.2/api/python/reference/pyspark.sql/dataframe.html) 的 Spark 文件。 ### 指定連接器 ClassName 若要指定資料來源/接收器的 `ClassName`，請使用 `.format` 選項來提供定義資料來源/接收器的對應連接器 `ClassName`。 **JDBC 連接器** 對於 JDBC 連接器，將 `jdbc` 指定為 `.format` 選項的值，並在 `driver` 選項中提供 JDBC 驅動程式 `ClassName`。 ``` df = spark.read.format("jdbc").option("driver", "")... df.write.format("jdbc").option("driver", "")... ``` 下表列出 Glue for DataFrames `ClassName` 中支援資料來源的 JDBC AWS 驅動程式。 | 資料來源 | 驅動程式類別名稱 | | --- |--- | | 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 連接器** 對於 Spark 連接器，將連接器的 `ClassName` 指定為 `.format` 選項的值。 ``` df = spark.read.format("")... df.write.format("")... ``` 下表列出 Glue for DataFrames AWS 中支援資料來源`ClassName`的 Spark 連接器。 | 資料來源 | 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() ``` ## 自訂 and 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 和資料集指南*中的 [JDBC 至其他資料庫](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"`，則透過使用 `AND` 和使用分割區欄的表達式擴展 `WHERE` 子句來測試查詢。 + `lowerBound` - 整數、選用，用來決定分割區步幅的 `partitionColumn` 最小值。 + `upperBound` - 整數、選用，用來決定分割區步幅的 `partitionColumn` 最大值。 + `numPartitions` - 整數、選用，分割區數目。這個值，搭配 `lowerBound` (包含) 及 `upperBound` (不含)，形成用於分割 `partitionColumn` 而產生之 `WHERE` 子句表達式的分割區步幅。 **重要** 請小心分割區的數目，因為太多的分割區可能會造成外部資料庫系統的問題。 + `filterPredicate` - 字串、選用，額外條件子句，用於篩選來源的資料。例如： ``` BillingCity='Mountain View' ``` 當您使用*查詢*，而不是*資料表*名稱，您應該驗證查詢是否適用於指定的 `filterPredicate`。例如： + 如果您的查詢格式為 `"SELECT col1 FROM table1"`，則透過在使用篩選述詞的查詢結尾附加 `WHERE` 子句來測試查詢。 + 如果您的查詢格式為 `"SELECT col1 FROM table1 WHERE col2=val"`，則透過使用 `AND` 和使用篩選述詞的表達式擴展 `WHERE` 子句來測試查詢。 + `dataTypeMapping` - 字典、選用、自訂資料類型映射，用於建構從 **JDBC** 資料類型到 **Glue** 資料類型的映射。例如，選項 `"dataTypeMapping":{"FLOAT":"STRING"}` 會將 JDBC 類型 `FLOAT` 的資料欄位映射至 Java `String` 類型中，方法是呼叫驅動程式的 `ResultSet.getString()` 方法，並使用它來建構 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 程式碼範例示範如何使用 JDBC 驅動程式從 AWS Marketplace 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 連接器由兩個類別組成：中繼資料處理常式和記錄處理常式。如果您在此處提供通用字首，則 API 會根據該字首載入正確的類別。 + `tableName` – 字串、必要，要讀取的 CloudWatch 日誌串流名稱。此程式碼片段使用特殊檢視名稱 `all_log_streams`，這表示傳回的動態資料框架將包含來自日誌群組中所有日誌資料串流的資料。 + `schemaName` – 字串、必要，要讀取的 CloudWatch 日誌群組。例如 `/aws-glue/jobs/output`。 + `connectionName` – 字串、必要，與連接器相關聯之連線的名稱。 如需此連接器的其他選項，請參閱 [Amazon Athena CloudWatch 連接器讀我](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` – 字串、必要，與連接器相關聯之連線的名稱。 + 其他選項視資料存放區而定。例如，OpenSearch 組態選項以字首 `es` 開頭，如 [Elasticsearch for Apache Hadoop](https://www.elastic.co/guide/en/elasticsearch/hadoop/current/configuration.html) 文件中所述。Spark 連接到 Snowflake 使用選項，例如 `sfUser` 和 `sfPassword`，如*連接到 Snowflake* 指南中的[使用 Spark Connector](https://docs.snowflake.com/en/user-guide/spark-connector-use.html) 所述。 下列 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 儲存貯體內容時管理記憶體效能。如需詳細資訊，請參閱[最佳化 Glue AWS 中的記憶體管理](https://aws.amazon.com/blogs/big-data/optimize-memory-management-in-aws-glue/)。 # AWS Glue for Spark 中的輸入與輸出的資料格式選項 這些頁面提供有關 AWS Glue for Spark 支援的資料格式之功能支援和組態參數的資訊。有關此信息的用法和適用性的說明，請參閱以下內容。 ## Glue AWS 中跨資料格式的功能支援 每個資料格式可能支援不同的 AWS Glue 功能。根據您的格式類型，可能會或可能不支持以下常見功能。請參閱資料格式的文件，瞭解如何運用我們的功能來滿足您的需求。 | | | | --- |--- | | 讀取 | AWS Glue 無需連接器等其他資源即可識別和解譯此資料格式。 | | 寫入 | AWS Glue 可以以此格式寫入資料，無需其他資源。您可以在工作中包含協力廠商程式庫，並使用標準 Apache Spark 函數來寫入資料，就像在其他 Spark 環境中一樣。如需這些程式庫的詳細資訊，請參閱 [搭配 Glue 使用 Python AWS 程式庫](aws-glue-programming-python-libraries.md)。 | | 串流讀取 | AWS Glue 可以從 Apache Kafka、Amazon Managed Streaming for Apache Kafka 或 Amazon Kinesis 訊息串流辨識和解譯此資料格式。我們希望流以一致的格式呈現數據，因此它們被讀為DataFrames。 | | 對小型檔案進行分組 | AWS Glue 可以將檔案分組，以在執行 Glue AWS 轉換時傳送至每個節點的批次工作。如此可大幅改善涉及大量小型檔案的工作負載的效能。如需詳細資訊，請參閱[讀取在大型群組中的輸入檔案](grouping-input-files.md)。 | | 任務書籤 | AWS Glue 可以使用任務書籤追蹤在任務執行期間對相同資料集執行相同工作的轉換進度。這可以提高工作負載的效能，涉及自上次作業執行以來只需在新資料上完成工作的資料集。如需詳細資訊，請參閱[使用任務書籤追蹤處理的資料](monitor-continuations.md)。 | ## 用來與 Glue AWS 中的資料格式互動的參數 某些 AWS Glue 連線類型支援多種`format`類型，要求您在使用 等方法時，使用 `format_options` 物件指定資料格式的相關資訊`GlueContext.write_dynamic_frame.from_options`。 + `s3` – 如需詳細資訊，請參閱 Glue 中 ETL AWS 的連線類型和選項：[S3 連線參數](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)。您也可以檢視促進此連線類型之方法的文件：[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)在 Python 和相應的斯卡拉方法[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` – 如需詳細資訊，請參閱 Glue 中 ETL AWS 的連線類型和選項：[Kinesis 連線參數](aws-glue-programming-etl-connect-kinesis-home.md#aws-glue-programming-etl-connect-kinesis)。您也可以檢視促進此連線類型的方法文件：[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)和相應的斯卡拉方法[def createDataFrameFromOptions](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-createDataFrameFromOptions)。 + `kafka` – 如需詳細資訊，請參閱 Glue 中 ETL AWS 的連線類型和選項：[Kafka 連線參數](aws-glue-programming-etl-connect-kafka-home.md#aws-glue-programming-etl-connect-kafka)。您也可以檢視促進此連線類型的方法文件：[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)和相應的斯卡拉方法[def createDataFrameFromOptions](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-createDataFrameFromOptions)。 某些連線類型不需要`format_options`。例如，在正常使用中，與關聯式資料庫的 JDBC 連線將以一致的表格式擷取資料。因此，從 JDBC 連接讀取不需要`format_options`。 在膠水中讀取和寫入數據的某些方法不需要`format_options`。例如，使用 `GlueContext.create_dynamic_frame.from_catalog`搭配 AWS Glue 爬蟲程式。爬蟲確定數據的形狀。使用爬蟲程式時，Glue AWS 分類器會檢查您的資料，以做出如何代表資料格式的明智決策。然後，它會將資料的表示法存放在 AWS Glue Data Catalog 中，可用於 Glue ETL AWS 指令碼，以 `GlueContext.create_dynamic_frame.from_catalog`方法擷取您的資料。檢索器無需手動指定有關數據格式的信息。 對於存取 AWS Lake Formation 受管資料表的任務， AWS Glue支援讀取和寫入 Lake Formation 受管資料表支援的所有格式。如需受 AWS Lake Formation 管資料表支援的最新格式清單，請參閱《 *AWS Lake Formation 開發人員指南*》中的[受管資料表的注意事項和限制](https://docs.aws.amazon.com/lake-formation/latest/dg/governed-table-restrictions.html)。 **注意** 對於寫入 Apache Parquet，AWS Glue ETL 只支援透過指定為動態框架優化的自訂 Parquet 寫入器類型的選項寫入受管控資料表。使用 `parquet` 格式寫入受管控資料表時，您應該在表參數中新增值為 `true` 的金鑰 `useGlueParquetWriter`。 **Topics** + [Glue AWS 中跨資料格式的功能支援](#aws-glue-programming-etl-format-features) + [用來與 Glue AWS 中的資料格式互動的參數](#aws-glue-programming-etl-format-parameters) + [在 Glue AWS 中使用 CSV 格式](aws-glue-programming-etl-format-csv-home.md) + [在 Glue AWS 中使用 Parquet 格式](aws-glue-programming-etl-format-parquet-home.md) + [在 Glue AWS 中使用 XML 格式](aws-glue-programming-etl-format-xml-home.md) + [在 Glue AWS 中使用 Avro 格式](aws-glue-programming-etl-format-avro-home.md) + [在 Glue AWS 中使用 grokLog 格式](aws-glue-programming-etl-format-grokLog-home.md) + [在 Glue AWS 中使用 Ion 格式](aws-glue-programming-etl-format-ion-home.md) + [在 Glue AWS 中使用 JSON 格式](aws-glue-programming-etl-format-json-home.md) + [在 Glue AWS 中使用 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) # 在 Glue AWS 中使用 CSV 格式 AWS Glue 會從來源擷取資料，並將資料寫入以各種資料格式存放和傳輸的目標。如果您的資料是以 CSV 資料格式存放或傳輸，本文件會介紹在 Glue AWS 中使用資料的可用功能。 AWS Glue 支援使用逗號分隔值 (CSV) 格式。此格式是一種極小的、以列為基礎的資料格式。CSV 通常不會嚴格符合標準，但您可以參閱 [RFC 4180](https://tools.ietf.org/html/rfc4180) 和 [RFC 7111](https://tools.ietf.org/html/rfc7111) 來了解詳細資訊。 您可以使用 AWS Glue 從 Amazon S3 和串流來源讀取 CSVs，以及將 CSVs 寫入 Amazon S3。您可以讀取和寫入來自 S3 的包含 CSV 檔案的 `bzip` 和 `gzip` 封存。您可以在 [S3 連線參數](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上設定壓縮行為，而不是在本頁討論的組態中設定。 下表顯示哪些常見的 AWS Glue 功能支援 CSV 格式選項。 | 讀取 | 寫入 | 串流讀取 | 對小型檔案進行分組 | 任務書籤 | | --- | --- | --- | --- | --- | | 支援 | 支援 | 支援 | 支援 | 支援 | ## 範例：從 S3 讀取 CSV 檔案或資料夾 **先決條件：**您需要指向希望讀取的 CSV 檔案或資料夾的 S3 路徑 (`s3path`)。 **組態：**在您的函數選項中，指定 `format="csv"`。在您的 `connection_options` 中，使用 `paths` 鍵來指定 `s3path`。您可以在 `connection_options` 中設定讀取器與 S3 互動的方式。如需詳細資訊，請參閱 Glue 中 ETL AWS 的連線類型和選項：[S3 連線參數](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)。您可以在 `format_options` 中設定讀取器解譯 CSV 的方式。如需詳細資訊，請參閱 [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, }, ) ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.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() } } ``` 您也可以在指令碼中使用 DataFrames (`org.apache.spark.sql.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`。您可以在 `connection_options` 中設定寫入器與 S3 的互動方式。如需詳細資訊，請參閱 Glue 中 ETL AWS 的連線類型和選項：[S3 連線參數](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)。您可以在 `format_options` 中設定操作如何寫入檔案內容。如需詳細資訊，請參閱 [CSV 組態參考](#aws-glue-programming-etl-format-csv-reference)。以下 AWS Glue ETL 指令碼顯示將 CSV 檔案和資料夾寫入 S3 的流程。 ------ #### [ 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, }, ) ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.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) } } ``` 您也可以在指令碼中使用 DataFrames (`org.apache.spark.sql.DataFrame`)。 ``` dataFrame.write .format("csv") .option("quote", null) .mode("Append") .save("s3://s3path") ``` ------ ## CSV 組態參考 只要 Glue AWS 程式庫指定 `format_options`，您就可以使用下列項目`format="csv"`： + `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\$1。 + **類型：**布林值，**預設：**`false` + `strictCheckForQuoting`：寫入 CSV 時，Glue 可能會在解讀為字串的值中加上引號。這樣做是為了防止寫出的內容模糊。為了節省時間，決定要寫入的內容時，Glue 可能會在不需要引號的某些情況下進行引用。啟用嚴格檢查將執行更密集的運算，並且僅在必要時引用。僅適用於 AWS Glue 3.0\$1。 + **類型：**布林值，**預設：**`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。 + 它不支援建立具有[錯誤記錄](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 檔案。 # 在 Glue AWS 中使用 Parquet 格式 AWS Glue 從來源擷取資料，並將資料寫入以各種資料格式存放和傳輸的目標。如果您的資料是以 Parquet 資料格式存放或傳輸，本文件會介紹在 Glue AWS 中使用資料的可用功能。 AWS Glue 支援使用 Parquet 格式。此格式是效能導向、以資料行為基礎的資料格式。如需標準授權單位的格式簡介，請參閱 [Apache Parquet Documentation Overview](https://parquet.apache.org/docs/overview/) (Apache Parquet 文件概觀)。 您可以使用 AWS Glue 從 Amazon S3 和串流來源讀取 Parquet 檔案，以及將 Parquet 檔案寫入 Amazon S3。您可以從 S3 讀取和寫入包含 Parquet 檔案的 `bzip` 和 `gzip` 封存檔。您可以在 [S3 連線參數](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上設定壓縮行為，而不是在本頁討論的組態中設定。 下表顯示哪些常見的 AWS Glue 功能支援 Parquet 格式選項。 | 讀取 | 寫入 | 串流讀取 | 對小型檔案進行分組 | 任務書籤 | | --- | --- | --- | --- | --- | | 支援 | 支援 | 支援 | 不支援 | 支援\$1 | \$1 Glue AWS 1.0\$1 版支援 ## 範例：從 S3 讀取 Parquet 檔案或資料夾 **先決條件：**您需要指向希望讀取的 Parquet 檔案或資料夾的 S3 路徑 (`s3path`)。 **組態：**在您的函數選項中，指定 `format="parquet"`。在您的 `connection_options` 中，使用 `paths` 索引鍵指定 `s3path`。 您可以在 `connection_options` 中設定讀取器與 S3 的互動方式。如需詳細資訊，請參閱 Glue 中 ETL AWS 的連線類型和選項：[S3 連線參數](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)。 您可以在 `format_options` 中設定讀取器解譯 Parquet 檔案的方式。如需詳細資訊，請參閱 [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" ) ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.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() } } ``` 您也可以在指令碼中使用 DataFrames (`org.apache.spark.sql.DataFrame`)。 ``` spark.read.parquet("s3://s3path/") ``` ------ ## 範例：將 Parquet 檔案和資料夾寫入 S3 **先決條件：**您需要初始化 DataFrame (`dataFrame`) 或 DynamicFrame (`dynamicFrame`)。您還需要預期的 S3 輸出路徑 `s3path`。 **組態：**在您的函數選項中，指定 `format="parquet"`。在您的 `connection_options` 中，使用 `paths` 鍵來指定 `s3path`。 您可以在 `connection_options` 中進一步更改寫入器與 S3 的互動方式。如需詳細資訊，請參閱 Glue 中 ETL AWS 的連線類型和選項：[S3 連線參數](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)。您可以在 `format_options` 中設定操作如何寫入檔案內容。如需詳細資訊，請參閱 [Parquet 組態參考](#aws-glue-programming-etl-format-parquet-reference)。 下列 AWS Glue ETL 指令碼顯示將 Parquet 檔案和資料夾寫入 S3 的程序。 我們透過 `useGlueParquetWriter` 組態鍵為自訂 Parquet 寫入器提供 DynamicFrames 的效能最佳化。若要判斷此寫入器是否適合您的工作負載，請參閱 [Glue Parquet 寫入器](#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, }, ) ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.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) } } ``` 您也可以在指令碼中使用 DataFrames (`org.apache.spark.sql.DataFrame`)。 ``` df.write.parquet("s3://s3path/") ``` ------ ## Parquet 組態參考 只要 Glue AWS 程式庫指定 `format_options`，您就可以使用下列項目`format="parquet"`： + `useGlueParquetWriter` – 指定使用具有 DynamicFrame 工作流程效能最佳化的自訂 Parquet 寫入器。如需用量詳細資訊，請參閱 [Glue Parquet 寫入器](#aws-glue-programming-etl-format-glue-parquet-writer)。 + **類型：**布林值，**預設：**`false` + `compression` – 指定使用的壓縮轉碼器。值與 `org.apache.parquet.hadoop.metadata.CompressionCodecName` 完全相容。 + **類型：**列舉文字，**預設：**`"snappy"` + 值：`"uncompressed"`、`"snappy"`、`"gzip"` 和 `"lzo"` + `blockSize` – 指定記憶體中將緩衝處理資料列群組的大小，以位元組為單位。您可以使用該值來調校效能。大小應完全分為多個 MB 單位。 + **類型：**數值，**預設：**`134217728` + 預設值等於 128 MB。 + `pageSize` – 指定分頁的大小，以位元組為單位。您可以使用該值來調校效能。分頁是必須完整讀取才能存取單一記錄之最小單位。 + **類型：**數值，**預設：**`1048576` + 預設值等於 1 MB。 **注意** 此外，任何底層的 SparkSQL 程式碼所接受的選項均可透過 `connection_options` 對應參數傳送。例如，可為 AWS Glue Spark 讀取器設定 [mergeSchema](https://spark.apache.org/docs/latest/sql-data-sources-parquet.html#schema-merging) 等 Spark 組態以合併所有檔案的結構描述。 ## 使用 AWS Glue Parquet 寫入器最佳化寫入效能 **注意** 過去已透過`glueparquet`格式類型存取 AWS Glue Parquet 寫入器。但現在不再提倡這種存取模式。請改用已啟用 `useGlueParquetWriter` 的 `parquet` 類型。 AWS Glue Parquet 寫入器具有效能增強功能，允許更快速的 Parquet 檔案寫入。傳統的寫入器會在寫入之前計算結構描述。Parquet 格式不會以可供快速擷取的方式存放結構描述，因此這可能需要一些時間。使用 AWS Glue Parquet 寫入器時，不需要預先計算的結構描述。當資料送達時，寫入器會動態地計算並修改結構描述。 指定 `useGlueParquetWriter` 時，請注意以下限制： + 寫入器僅支援結構描述演變 (例如新增或移除資料行)，但不會變更資料行類型，例如使用 `ResolveChoice`。 + 寫入器不支援寫入空白的 DataFrame，例如，寫入只含結構描述的檔案。透過設定 AWS 與 Glue Data Catalog 整合時`enableUpdateCatalog=True`，嘗試寫入空的 DataFrame 不會更新 Data Catalog。而會在資料目錄建立不含結構描述的資料表。 如果您的轉換不需要這些限制，開啟 AWS Glue Parquet 寫入器應該會提高效能。 # 在 Glue AWS 中使用 XML 格式 AWS Glue 從來源擷取資料，並將資料寫入以各種資料格式存放和傳輸的目標。如果您的資料是以 XML 資料格式存放或傳輸，本文件會介紹在 Glue AWS 中使用資料的可用功能。 AWS Glue 支援使用 XML 格式。此格式表示並非基於資料列或資料行的、高度可設定且嚴格定義的資料結構。XML 是高度標準化的。如需標準授權單位的格式簡介，請參閱 [XML Essentials](https://www.w3.org/standards/xml/core) (XML 基礎知識)。 您可以使用 AWS Glue 從 Amazon S3 讀取 XML 檔案，以及包含 XML 檔案的 `bzip`和 `gzip`封存。您可以在 [S3 連線參數](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上設定壓縮行為，而不是在本頁討論的組態中設定。 下表顯示哪些常見的 AWS Glue 功能支援 XML 格式選項。 | 讀取 | 寫入 | 串流讀取 | 對小型檔案進行分組 | 任務書籤 | | --- | --- | --- | --- | --- | | 支援 | 不支援 | 不支援 | 支援 | 支援 | ## 範例：從 S3 讀取 XML XML 讀取器接受 XML 標籤名稱。它會檢查其輸入中包含該標籤的元素，以推斷結構描述，並使用對應的值填入 DynamicFrame。Glue XML AWS 功能的行為類似於 [Apache Spark 的 XML 資料來源](https://github.com/databricks/spark-xml)。您可以透過比較此讀取器與該專案的文件，來獲得基本行為相關的洞見。 **先決條件：**您需要指向希望讀取的 XML 檔案或資料夾的 S3 路徑 (`s3path`) 以及有关 XML 檔案的部分資訊。您還需要希望讀取的 XML 元素的標籤，`xmlTag`。 **組態：**在您的函數選項中，指定 `format="xml"`。在您的 `connection_options` 中，使用 `paths` 鍵來指定 `s3path`。您可以在 `connection_options` 中进一步設定讀取器與 S3 的互動方式。如需詳細資訊，請參閱 Glue 中 ETL AWS 的連線類型和選項：[S3 連線參數](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)。在您的 `format_options` 中，使用 `rowTag` 鍵來指定 `xmlTag`。您可以在 `format_options` 中进一步設定讀取器解譯 XML 檔案的方式。如需詳細資訊，請參閱 [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"}, ) ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.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() } ``` 您也可以在指令碼中使用 DataFrames (`org.apache.spark.sql.DataFrame`)。 ``` val dataFrame = spark.read .option("rowTag", "xmlTag") .format("xml") .load("s3://s3path“) ``` ------ ## XML 組態參考 只要 Glue AWS 程式庫指定 `format_options`，您就可以使用下列項目`format="xml"`： + `rowTag` – 指定要將其當做一列的檔案中的 XML 標籤。Row 標籤不能自動關閉。 + **類型：**文字，**必要** + `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 結構描述範例** 這是使用 `withSchema` 格式選項來指定 XML 資料結構描述的範例。 ``` 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 = "" ) ``` # 在 Glue AWS 中使用 Avro 格式 AWS Glue 從來源擷取資料，並將資料寫入以各種資料格式存放和傳輸的目標。如果您的資料是以 Avro 資料格式存放或傳輸，本文件會介紹在 Glue AWS 中使用資料的可用功能。 AWS Glue 支援使用 Avro 格式。此格式是效能導向、以資料列為基礎的資料格式。如需標準授權單位的格式簡介，請參閱 [Apache Avro 1.8.2 Documentation](https://avro.apache.org/docs/1.8.2/)。 您可以使用 AWS Glue 從 Amazon S3 和串流來源讀取 Avro 檔案，以及將 Avro 檔案寫入 Amazon S3。您可以讀取和寫入來自 S3 的包含 Avro 檔案的 `bzip2` 和 `gzip` 封存。此外，您可以寫入 `deflate`、`snappy` 和包含 Avro 檔案的 `xz` 封存。您可以在 [S3 連線參數](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上設定壓縮行為，而不是在本頁討論的組態中設定。 下表顯示哪些常見的 AWS Glue 操作支援 Avro 格式選項。 | 讀取 | 寫入 | 串流讀取 | 對小型檔案進行分組 | 任務書籤 | | --- | --- | --- | --- | --- | | 支援 | 支援 | 支援\$1 | 不支援 | 支援 | \$1 表示支援，但有所限制。如需詳細資訊，請參閱 [Avro 串流來源的注意事項與限制](add-job-streaming.md#streaming-avro-notes)。 ## 範例：從 S3 讀取 Avro 檔案或資料夾 **先決條件：**您需要指向希望讀取的 Avro 檔案或資料夾的 S3 路徑 (`s3path`)。 **組態：**在您的函數選項中，指定 `format="avro"`。在您的 `connection_options` 中，使用 `paths` 鍵來指定 `s3path`。您可以在 `connection_options` 中設定讀取器與 S3 的互動方式。如需詳細資訊，請參閱 Glue 中 ETL AWS 輸入和輸出的資料格式選項：[Amazon S3 連線選項參考](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)。您可以在 `format_options` 中設定讀取器解譯 Avro 的方式。如需詳細資訊，請參閱 [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`。您可以在 `connection_options` 中進一步更改寫入器與 S3 的互動方式。如需詳細資訊，請參閱 Glue 中 ETL AWS 輸入和輸出的資料格式選項：[Amazon S3 連線選項參考](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)。您可以在 `format_options` 中更改寫入器解譯 Avro 檔案的方式。如需詳細資訊，請參閱 [Avro 組態參考](#aws-glue-programming-etl-format-avro-reference)。 下列 AWS Glue ETL 指令碼顯示將 Avro 檔案或資料夾寫入 S3 的程序。 ------ #### [ 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 組態參考 無論 Glue AWS 程式庫在何處指定 ，您都可以使用下列`format_options`值`format="avro"`： + `version` — 指定 Apache Avro Reader/Writer 格式支援的版本。預設值為 "1.7"。您可以指定 `format_options={"version": “1.8”}`，以啟用 Avro 邏輯類型的讀取和寫入。如需詳細資訊，請參閱 [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 Reader 1.7 和 1.8 的 Avro 資料類型 (邏輯類型與 Avro 基本類型) 與 AWS Glue `DynamicFrame` 資料類型之間的轉換。 | Avro 資料類型：邏輯類型 | Avro 資料類型：Avro 基本類型 | GlueDynamicFrame 資料類型：Avro Reader 1.7 | GlueDynamicFrame 資料類型：Avro Reader 1.8 | | --- | --- | --- | --- | | Decimal (小數) | 位元組 | BINARY | Decimal (小數) | | Decimal (小數) | 固定 | BINARY | Decimal (小數) | | Date | int | INT | Date | | 時間 (毫秒) | int | INT | INT | | 時間 (微秒) | long | LONG | LONG | | 時間戳記 (毫秒) | long | LONG | 時間戳記 | | 時間戳記 (微秒) | long | LONG | LONG | | 持續時間 (不是邏輯類型) | 12 (固定) | BINARY | BINARY | 對於寫入器：此表顯示適用於 Avro Writer 1.7 和 1.8 的 AWS Glue `DynamicFrame` 資料類型與 Avro 資料類型之間的轉換。 | AWS Glue `DynamicFrame` 資料類型 | Avro 資料類型：Avro Writer 1.7 | Avro 資料類型：Avro Writer 1.8 | | --- | --- | --- | | Decimal (小數) | String | decimal | | Date | String | date | | 時間戳記 | String | timestamp-micros | ## Avro Spark DataFrame 支援 為了從 Spark DataFrame API 使用Avro，您需要為相應的 Spark 版本安裝 Spark Avro 外掛程式。任務中可用的 Spark 版本取決於您的 Glue AWS 版本。如需 Spark 版本的詳細資訊，請參閱 [AWS Glue 版本](release-notes.md)。這個外掛程式是由 Apache 維護，我們不作出具體的支援保證。 在 AWS Glue 2.0 中 - 使用 Spark Avro 外掛程式的 2.4.3 版。您可以在 Maven Central 找到此 JAR，請參閱 [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 版。您可以在 Maven Central 找到此 JAR，請參閱 [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)。 若要在 Glue ETL AWS 任務中包含額外的 JARs，請使用 `--extra-jars`任務參數。如需有關任務參數的詳細資訊，請參閱 [在 Glue AWS 任務中使用任務參數](aws-glue-programming-etl-glue-arguments.md)。您也可以在 AWS 管理主控台中設定此參數。 # 在 Glue AWS 中使用 grokLog 格式 AWS Glue 從來源擷取資料，並將資料寫入以各種資料格式存放和傳輸的目標。如果您的資料是以結構鬆散的純文字格式存放或傳輸，本文件會介紹透過 Grok 模式在 Glue AWS 中使用資料的可用功能。 AWS Glue 支援使用 Grok 模式。Grok 模式類似於規則表達式擷取群組。它們辨識純文字檔案中字元序列的模式，並為其提供類型和用途。在 AWS Glue 中，其主要目的是讀取日誌。有關作者對 Grok 的介紹，請參閱 [Logstash Reference: Grok filter plugin](https://www.elastic.co/guide/en/logstash/current/plugins-filters-grok.html)。 | 讀取 | 寫入 | 串流讀取 | 對小型檔案進行分組 | 任務書籤 | | --- | --- | --- | --- | --- | | 支援 | 不適用 | 支援 | 支援 | 不支援 | ## grokLog 組態參考 可以使用下列的 `format_options` 值搭配 `format="grokLog"`： + `logFormat` — 指定符合記錄格式的 Grok 模式。 + `customPatterns` — 指定此處使用的其他 Grok 模式。 + `MISSING` — 指定用於識別遺漏值的訊號。預設值為 `'-'`。 + `LineCount` — 指定各個日誌記錄中的行數。預設為 `'1'`，目前也只支援單行記錄。 + `StrictMode` — 布林值，指定是否要開啟嚴格模式。在嚴格模式下，讀者不可自動轉換類型或復原。預設值為 `"false"`。 # 在 Glue AWS 中使用 Ion 格式 AWS Glue 從來源擷取資料，並將資料寫入以各種資料格式存放和傳輸的目標。如果您的資料是以 Ion 資料格式存放或傳輸，本文件會介紹在 Glue AWS 中使用資料的可用功能。 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 檔案。您可以讀取 `bzip` 和 `gzip` 來自 S3 的包含 Ion 檔案的封存。您可以在 [S3 連線參數](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上設定壓縮行為，而不是在本頁討論的組態中設定。 下表顯示哪些常見的 AWS Glue 操作支援 Ion 格式選項。 | 讀取 | 寫入 | 串流讀取 | 對小型檔案進行分組 | 任務書籤 | | --- | --- | --- | --- | --- | | 支援 | 不支援 | 不支援 | 支援 | 不支援 | ## 範例：從 S3 讀取 Ion 檔案或資料夾 **先決條件：**您需要指向希望讀取的 Ion 檔案或資料夾的 S3 路徑 (`s3path`)。 **組態：**在您的函數選項中，指定 `format="json"`。在您的 `connection_options` 中，使用 `paths` 索引鍵指定 `s3path`。您可以在 `connection_options` 中設定讀取器與 S3 的互動方式。如需詳細資訊，請參閱 Glue 中 ETL AWS 的連線類型和選項：[Amazon S3 連線選項參考](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)。 下列 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` 值。 # 在 Glue AWS 中使用 JSON 格式 AWS Glue 從來源擷取資料，並將資料寫入以各種資料格式存放和傳輸的目標。如果您的資料是以 JSON 資料格式存放或傳輸，本文件會向您介紹在 Glue AWS 中使用資料的可用功能。 AWS Glue 支援使用 JSON 格式。此格式表示具有一致形狀但內容靈活、且非基於資料列或資料行的資料結構。JSON 是由多個機構發佈的平行標準所定義的，其中之一是 ECMA-404。如需常用參考來源的格式簡介，請參閱 [JSON 簡介](https://www.json.org/)。 您可以使用 AWS Glue 從 Amazon S3 讀取 JSON 檔案，以及 `bzip`和`gzip`壓縮的 JSON 檔案。您可以在 [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)。您可以在 `format_options` 中設定讀取器解譯 JSON 的方式。如需詳細資訊，請參閱 [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 } ) ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.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() } } ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.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`。您可以在 `connection_options` 中進一步更改寫入器與 S3 的互動方式。如需詳細資訊，請參閱 Glue AWS 中 ETL 輸入和輸出的資料格式選項：[Amazon S3 連線選項參考](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)。您可以在 `format_options` 中設定寫入器解譯 JSON 的方式。如需詳細資訊，請參閱 [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" ) ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.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) } } ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.DataFrame`)。 ``` df.write.json("s3://s3path") ``` ------ ## Json 組態參考 可以使用下列的 `format_options` 值搭配 `format="json"`： + `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` 使用。 ## 使用向量化 SIMD JSON 讀取器搭配 Apache Arrow 直欄式格式 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, }) ``` 如需在 Glue 程式庫中建置 *SchemaString* AWS 的詳細資訊，請參閱 [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 檔案。 # 在 Glue AWS 中使用 ORC 格式 AWS Glue 從來源擷取資料，並將資料寫入以各種資料格式存放和傳輸的目標。如果您的資料是以 ORC 資料格式存放或傳輸，本文件會介紹在 Glue AWS 中使用資料的可用功能。 AWS Glue 支援使用 ORC 格式。此格式是效能導向、以資料行為基礎的資料格式。如需標準授權單位的格式簡介，請參閱 [Apache Orc](https://orc.apache.org/docs/)。 您可以使用 AWS Glue 從 Amazon S3 和串流來源讀取 ORC 檔案，以及將 ORC 檔案寫入 Amazon S3。您可以讀取和寫入來自 S3 的包含 ORC 檔案的 `bzip` 和 `gzip` 封存。您可以在 [S3 連線參數](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3) 上設定壓縮行為，而不是在本頁討論的組態中設定。 下表顯示哪些常見的 AWS Glue 操作支援 ORC 格式選項。 | 讀取 | 寫入 | 串流讀取 | 對小型檔案進行分組 | 任務書籤 | | --- | --- | --- | --- | --- | | 支援 | 支援 | 支援 | 不支援 | 支援\$1 | \$1Glue AWS 1.0\$1 版支援 ## 範例：從 S3 讀取 ORC 檔案或資料夾 **先決條件：**您需要指向希望讀取的 ORC 檔案或資料夾的 S3 路徑 (`s3path`)。 **組態：**在您的函數選項中，指定 `format="orc"`。在您的 `connection_options` 中，使用 `paths` 索引鍵指定 `s3path`。您可以在 `connection_options` 中設定讀取器與 S3 的互動方式。如需詳細資訊，請參閱 Glue 中 ETL AWS 的連線類型和選項：[Amazon S3 連線選項參考](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)。 下列 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" ) ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.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() } } ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.DataFrame`)。 ``` val dataFrame = spark.read .orc("s3://s3path") ``` ------ ## 範例：將 ORC 檔案和資料夾寫入 S3 **先決條件：**您需要初始化 DataFrame (`dataFrame`) 或 DynamicFrame (`dynamicFrame`)。您還需要預期的 S3 輸出路徑 `s3path`。 **組態：**在您的函數選項中，指定 `format="orc"`。在您的連線選項中，使用 `paths` 鍵指定 `s3path`。您可以在 `connection_options` 中進一步更改寫入器與 S3 的互動方式。如需詳細資訊，請參閱 Glue 中 ETL AWS 輸入和輸出的資料格式選項：[Amazon S3 連線選項參考](aws-glue-programming-etl-connect-s3-home.md#aws-glue-programming-etl-connect-s3)。下列程式碼範例顯示了此程序： ------ #### [ 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" } ) ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.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) } } ``` 您也可以在指令碼中使用 DataFrames (`pyspark.sql.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，您可以使用 AWS Glue Spark DataFrames 來讀取和寫入資料湖資料表。您也可以使用 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) + [在 Glue 中使用 Hudi AWS 架構](aws-glue-programming-etl-format-hudi.md) + [在 Glue AWS 中使用 Delta Lake 架構](aws-glue-programming-etl-format-delta-lake.md) + [在 Glue AWS 中使用 Iceberg 架構](aws-glue-programming-etl-format-iceberg.md) # 限制 在搭配 使用資料湖架構之前，請考慮下列限制 AWS Glue。 + 下列 AWS Glue `GlueContext` DynamicFrame 方法不支援讀取和寫入資料湖架構資料表。改用適用於 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 讀取時合併 (MoR) 資料表。 + `ALTER TABLE … RENAME TO` 不適用於 Apache Iceberg 0.13.1 for AWS Glue 3.0。 ## 由 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) **注意** 只有 4.0 AWS Glue 版支援透過 Lake Formation 整合 AWS Glue ETL 的 Apache Hudi、Apache Iceberg 和 Delta Lake 許可。 Apache Iceberg 透過 Lake Formation 許可與 AWS Glue ETL 提供最佳整合。其支援幾乎所有操作 (包含 SQL 支援)。 Hudi 支援大多數基本操作 (除管理操作外)。這是因為這些選項通常會透過 DataFrame 寫入完成，並透過 `additional_options` 指定。您需要使用 AWS Glue APIs為您的操作建立 DataFrames，因為 SparkSQL 不受支援。 Delta Lake 僅支援讀取、附加及覆寫資料表資料。Delta Lake 需要使用自有的程式庫才可執行不同任務 (例如，更新)。 下列功能不適用於 Lake Formation 權限管理的 Iceberg 資料表。 + 使用 AWS Glue ETL 壓縮 + 透過 AWS Glue ETL 的 Spark SQL 支援 下列為 Lake Formation 權限管理的 Hudi 資料表限制： + 移除遺棄的檔案 下列為 Lake Formation 權限管理的 Delta Lake 資料表限制： + 插入 Delta Lake 資料表和從其中讀取以外的所有功能。 # 在 Glue 中使用 Hudi AWS 架構 AWS Glue 3.0 和更新版本支援資料湖的 Apache Hudi 架構。Hudi 是開放原始碼資料湖儲存架構，可簡化增量資料處理與資料管道開發。本主題涵蓋在 Hudi AWS 資料表中傳輸或存放資料時，在 Glue 中使用資料的可用功能。若要進一步了解 Hudi，請參閱官方 [Apache Hudi 文件](https://hudi.apache.org/docs/overview/)。 您可以使用 AWS Glue 在 Amazon S3 中的 Hudi 資料表上執行讀取和寫入操作，或使用 Glue Data Catalog 使用 Hudi AWS 資料表。還支援其他操作，包括插入、更新和所有 [Apache Spark 操作](https://hudi.apache.org/docs/quick-start-guide/)。 **注意** Glue 5.0 中的 Apache Hudi AWS 0.15.0 實作會在內部還原 [HUDI-7001](https://github.com/apache/hudi/pull/9936)。當記錄金鑰包含單一欄位時，不會顯示與複雜金鑰產生相關的迴歸。但是，此行為與 OSS Apache Hudi 0.15.0 不同。 Apache Hudi 0.10.1 for AWS Glue 3.0 不支援 Hudi 讀取時合併 (MoR) 資料表。 下表列出每個 Glue 版本中包含的 Hudi AWS 版本。 **** | 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 若要啟用 Hudi for AWS Glue，請完成下列任務： + 指定 `hudi` 作為 `--datalake-formats` 任務參數的值。如需詳細資訊，請參閱[在 Glue AWS 任務中使用任務參數](aws-glue-programming-etl-glue-arguments.md)。 + 為您的 Glue 任務建立名為 AWS `--conf`的金鑰，並將其設定為下列值。您也可以選擇在指令碼中使用 `SparkConf` 設定以下組態。這些設定有助於 Apache Spark 正確處理 Hudi 資料表。 ``` spark.serializer=org.apache.spark.serializer.KryoSerializer ``` + Glue 4.0 預設會啟用 Hudi AWS 的 Lake Formation 許可支援。讀取/寫入 Lake Formation 註冊的 Hudi 資料表時，不需要其他組態。若要讀取已註冊的 Hudi 資料表，Glue AWS 任務 IAM 角色必須具有 SELECT 許可。若要寫入已註冊的 Hudi 資料表，Glue AWS 任務 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`任務參數指定您自己的 Hudi JAR 檔案。請勿包括 `hudi` 作為 `--datalake-formats` 任務參數的值。如果您使用 AWS Glue 5.0 或更新版本，則必須設定`--user-jars-first true`任務參數。 ## 範例：將 Hudi 資料表寫入 Amazon S3，並在 AWS Glue Data Catalog 中註冊 此範例指令碼示範如何將 Hudi 資料表寫入 Amazon S3，並將資料表註冊至 AWS Glue Data Catalog。此範例使用 Hudi [Hive 同步工具](https://hudi.apache.org/docs/syncing_metastore/)來註冊該資料表。 **注意** 此範例需要您設定`--enable-glue-datacatalog`任務參數，才能使用 AWS Glue Data Catalog 做為 Apache Spark Hive 中繼存放區。如需詳細資訊，請參閱 [在 Glue AWS 任務中使用任務參數](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() ``` ------ ## 範例：使用 Glue Data Catalog 從 Amazon S3 AWS 讀取 Hudi 資料表 此範例會讀取您從 Amazon S3 在 [範例：將 Hudi 資料表寫入 Amazon S3，並在 AWS Glue Data Catalog 中註冊](#aws-glue-programming-etl-format-hudi-write) 中建立的 Hudi 資料表。 **注意** 此範例需要您設定`--enable-glue-datacatalog`任務參數，才能使用 AWS Glue Data Catalog 做為 Apache Spark Hive 中繼存放區。如需詳細資訊，請參閱 [在 Glue AWS 任務中使用任務參數](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() } } ``` ------ ## 範例：在 Amazon S3 中更新 `DataFrame` 並將其插入到 Hudi 資料表中 此範例使用 AWS Glue Data Catalog 將 DataFrame 插入您在 中建立的 Hudi 資料表[範例：將 Hudi 資料表寫入 Amazon S3，並在 AWS Glue Data Catalog 中註冊](#aws-glue-programming-etl-format-hudi-write)。 **注意** 此範例需要您設定`--enable-glue-datacatalog`任務參數，才能使用 AWS Glue Data Catalog 做為 Apache Spark Hive 中繼存放區。如需詳細資訊，請參閱 [在 Glue AWS 任務中使用任務參數](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://") ``` ------ ## 範例：使用 Spark 將 Hudi 資料表寫入 Amazon S3 此範例使用 Spark 將 Hudi 資料表寫入 Amazon S3。 ------ #### [ 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 權限控制，您將需要先在 Lake Formation 中註冊資料表 Amazon S3 路徑。如需詳細資訊，請參閱 [Registering an Amazon S3 location](https://docs.aws.amazon.com/lake-formation/latest/dg/register-location.html) (註冊 Amazon S3 位置)。您可以從 Lake Formation 主控台或使用 CLI AWS 註冊： ``` 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. 將 Lake Formation 許可授予 AWS Glue 任務 IAM 角色。您可以從 Lake Formation 主控台授予許可，或使用 AWS CLI。如需詳細資訊，請參閱[使用 Lake Formation 主控台和具名資源方法授予資料表權限](https://docs.aws.amazon.com/lake-formation/latest/dg/granting-table-permissions.html)。 1. 讀取在 Lake Formation 中註冊的 Hudi 資料表。該程式碼與讀取未註冊之 Hudi 資料表的程式碼相同。請注意，Glue AWS 任務 IAM 角色需要具有 SELECT 許可才能成功讀取。 ``` val dataFrame = glueContext.getCatalogSource( database = "", tableName = "" ).getDataFrame() ``` 1. 寫入在 Lake Formation 中註冊的 Hudi 資料表。該程式碼與寫入未註冊之 Hudi 資料表的程式碼相同。請注意，Glue AWS 任務 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) ``` # 在 Glue AWS 中使用 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)。 您可以使用 AWS Glue 在 Amazon S3 中的 Delta Lake 資料表上執行讀取和寫入操作，或使用 Glue Data Catalog 使用 Delta Lake AWS 資料表。插入、更新和[資料表批次讀取和寫入](https://docs.delta.io/0.7.0/api/python/index.html)等操作也受到支援。使用 Delta Lake 資料表時，您還可以選擇使用 Delta Lake Python 程式庫中的方法，例如 `DeltaTable.forPath`。如需有關 Delta Lake Python 程式庫的詳細資訊，請參閱 Delta Lake 的 Python 文件。 下表列出每個 Glue 版本中包含的 Delta Lake AWS 版本。 **** | AWS Glue 版本 | 支援的 Delta Lake 版本 | | --- | --- | | 5.1 | 3.3.2 | | 5.0 | 3.3.0 | | 4.0 | 2.1.0 | | 3.0 | 1.0.0 | 若要進一步了解 Glue AWS 支援的資料湖架構，請參閱 [搭配 AWS Glue ETL 任務使用資料湖架構](aws-glue-programming-etl-datalake-native-frameworks.md)。 ## 啟用 Delta Lake for AWS Glue 若要啟用 Delta Lake for AWS Glue，請完成下列任務： + 指定 `delta` 作為 `--datalake-formats` 任務參數的值。如需詳細資訊，請參閱[在 Glue AWS 任務中使用任務參數](aws-glue-programming-etl-glue-arguments.md)。 + 為您的 Glue 任務建立名為 AWS `--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 ``` + Glue 4.0 預設會啟用 Delta 資料表的 Lake Formation AWS 許可支援。讀取/寫入 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 檔案。請勿包括 `delta` 作為 `--datalake-formats` 任務參數的值。如果您使用 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 Data Catalog 下列 AWS Glue ETL 指令碼示範如何將 Delta Lake 資料表寫入 Amazon S3，並將資料表註冊至 AWS Glue Data Catalog。 ------ #### [ 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(".") ``` ------ ## 範例：使用 Glue Data Catalog 從 Amazon S3 AWS 讀取 Delta Lake 資料表 下列 AWS Glue ETL 指令碼會讀取您在 中建立的 Delta Lake 資料表[範例：將 Delta Lake 資料表寫入 Amazon S3，並將其註冊到 AWS Glue Data Catalog](#aws-glue-programming-etl-format-delta-lake-write)。 ------ #### [ 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() } } ``` ------ ## 範例：使用 Glue Data Catalog 將 插入 Amazon S3 中的 `DataFrame` Delta Lake AWS 資料表 此範例會將資料插入您在 [範例：將 Delta Lake 資料表寫入 Amazon S3，並將其註冊到 AWS Glue Data Catalog](#aws-glue-programming-etl-format-delta-lake-write) 中建立的 Delta Lake 資料表中。 **注意** 此範例需要您設定`--enable-glue-datacatalog`任務參數，才能使用 AWS Glue Data Catalog 做為 Apache Spark Hive 中繼存放區。如需詳細資訊，請參閱 [在 Glue AWS 任務中使用任務參數](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 將 Delta Lake 資料表寫入 Amazon S3 此範例會使用 Spark 將 Delta Lake 資料表寫入 Amazon S3。 ------ #### [ 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 權限控制，您將需要先在 Lake Formation 中註冊資料表 Amazon S3 路徑。如需詳細資訊，請參閱 [Registering an Amazon S3 location](https://docs.aws.amazon.com/lake-formation/latest/dg/register-location.html) (註冊 Amazon S3 位置)。您可以從 Lake Formation 主控台或使用 CLI AWS 註冊： ``` 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 目錄資料表。如需詳細資訊，請參閱[使用 Glue 爬蟲程式介紹原生 Delta Lake AWS 資料表支援](https://aws.amazon.com/blogs/big-data/introducing-native-delta-lake-table-support-with-aws-glue-crawlers/)。 您也可以透過 Glue `CreateTable` API AWS 手動建立資料表。 1. 將 Lake Formation 許可授予 AWS Glue 任務 IAM 角色。您可以從 Lake Formation 主控台或使用 AWS CLI 授予許可。如需詳細資訊，請參閱[使用 Lake Formation 主控台和具名資源方法授予資料表權限](https://docs.aws.amazon.com/lake-formation/latest/dg/granting-table-permissions.html)。 1. 讀取在 Lake Formation 中註冊的 Delta 資料表。該程式碼與讀取未註冊之 Delta 資料表的程式碼相同。請注意，Glue AWS 任務 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 資料表的程式碼相同。請注意，Glue AWS 任務 IAM 角色需要具有 SUPER 許可才能成功寫入。 根據預設，Glue AWS 會使用 `Append`做為 saveMode。您可以透過設定 `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 ) ``` # 在 Glue AWS 中使用 Iceberg 架構 AWS Glue 3.0 和更新版本支援資料湖的 Apache Iceberg 架構。Iceberg 提供高效能的資料表格式，其運作方式就像 SQL 資料表一樣。本主題涵蓋在 Iceberg AWS 資料表中傳輸或存放資料時，在 Glue 中使用資料的可用功能。若要進一步了解 Iceberg，請參閱官方 [Apache Iceberg 文件](https://iceberg.apache.org/docs/latest/)。 您可以使用 AWS Glue 在 Amazon S3 中的 Iceberg 資料表上執行讀取和寫入操作，或使用 Glue Data Catalog 使用 Iceberg AWS 資料表。還支援包括插入和所有 [Spark 查詢](https://iceberg.apache.org/docs/latest/spark-queries/) [Spark 寫入](https://iceberg.apache.org/docs/latest/spark-writes/)在內的其他操作。Iceberg 資料表不支援更新。 **注意** `ALTER TABLE … RENAME TO` 不適用於 AWS Glue 3.0 的 Apache Iceberg 0.13.1。 下表列出每個 Glue 版本中包含的 Iceberg AWS 版本。 **** | 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 架構 若要啟用 Iceberg for AWS Glue，請完成下列任務： + 指定 `iceberg` 作為 `--datalake-formats` 任務參數的值。如需詳細資訊，請參閱[在 Glue AWS 任務中使用任務參數](aws-glue-programming-etl-glue-arguments.md)。 + 為您的 Glue 任務建立名為 AWS `--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 鎖定管理員以確保原子交易。 AWS Glue 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 檔案。請勿包括 `iceberg` 作為 `--datalake-formats` 參數的值。如果您使用 AWS Glue 5.0 或更新版本，則必須設定`--user-jars-first true`任務參數。 **啟用 Iceberg 資料表的加密** **注意** Iceberg 資料表具有自己的機制來啟用伺服器端加密。除了 Glue AWS 的安全組態之外，您應該啟用此組態。 若要在 Iceberg 資料表上啟用伺服器端加密，請檢閱 [Iceberg 文件](https://iceberg.apache.org/docs/latest/aws/#s3-server-side-encryption)中的指引。 **新增 Iceberg 跨區域的 Spark 組態** 若要使用 Glue Data Catalog 為 Iceberg 跨區域資料表存取新增額外的 Spark AWS 組態 AWS Lake Formation，請遵循下列步驟： 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 ----- ``` ## 範例：將 Iceberg 資料表寫入 Amazon S3，並將其註冊到 AWS Glue Data Catalog 此範例指令碼示範如何將 Iceberg 資料表寫入 Amazon S3。此範例使用 [Iceberg AWS 整合](https://iceberg.apache.org/docs/latest/aws/)將資料表註冊至 AWS Glue Data Catalog。 ------ #### [ 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 方法將 Iceberg 資料表寫入 Amazon S3 和 Data Catalog。 先決條件：您需要佈建目錄才能使用 Iceberg 程式庫。使用 AWS Glue Data Catalog 時， AWS Glue 會直接執行此操作。Glue Data Catalog AWS 已預先設定為供 Spark 程式庫使用，做為 `glue_catalog`。資料目錄資料表由 *databaseName* 和 *tableName* 識別。如需 AWS Glue Data Catalog 的詳細資訊，請參閱 [中的資料探索和目錄編製 AWS Glue](catalog-and-crawler.md)。 如果您不是使用 AWS Glue Data Catalog，則需要透過 Spark APIs佈建目錄。如需詳細資訊，請參閱 Iceberg 文件中的 [Spark 組態](https://iceberg.apache.org/docs/latest/spark-configuration/)。 此範例使用 Spark 將 Iceberg 資料表寫入至 Amazon S3 和 Data Catalog。 ------ #### [ 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() ``` ------ ## 範例：使用 Glue Data Catalog 從 Amazon S3 AWS 讀取 Iceberg 資料表 此範例會讀取您在 [範例：將 Iceberg 資料表寫入 Amazon S3，並將其註冊到 AWS Glue Data Catalog](#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() } } ``` ------ ## 範例：使用 Glue Data Catalog 將 `DataFrame`插入 Amazon S3 中的 Iceberg AWS 資料表 此範例會將資料插入您在 [範例：將 Iceberg 資料表寫入 Amazon S3，並將其註冊到 AWS Glue Data Catalog](#aws-glue-programming-etl-format-iceberg-write) 中建立的 Iceberg 資料表中。 **注意** 此範例需要您設定`--enable-glue-datacatalog`任務參數，才能使用 AWS Glue Data Catalog 做為 Apache Spark Hive 中繼存放區。如需詳細資訊，請參閱 [在 Glue AWS 任務中使用任務參數](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 從 Amazon S3 讀取 Iceberg 資料表 先決條件：您需要佈建目錄才能使用 Iceberg 程式庫。使用 AWS Glue Data Catalog 時， AWS Glue 會直接執行此操作。Glue Data Catalog AWS 已預先設定為供 Spark 程式庫使用，做為 `glue_catalog`。資料目錄資料表由 *databaseName* 和 *tableName* 識別。如需 AWS Glue Data Catalog 的詳細資訊，請參閱 [中的資料探索和目錄編製 AWS Glue](catalog-and-crawler.md)。 如果您不是使用 AWS Glue Data Catalog，則需要透過 Spark APIs佈建目錄。如需詳細資訊，請參閱 Iceberg 文件中的 [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 權限控制，您將需要先在 Lake Formation 中註冊資料表 Amazon S3 路徑。如需詳細資訊，請參閱 [Registering an Amazon S3 location](https://docs.aws.amazon.com/lake-formation/latest/dg/register-location.html) (註冊 Amazon S3 位置)。您可以從 Lake Formation 主控台或使用 CLI AWS 註冊： ``` 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) ``` 您也可以透過 Glue `CreateTable` API AWS 手動建立資料表。如需詳細資訊，請參閱[建立 Apache Iceberg 資料表](https://docs.aws.amazon.com/lake-formation/latest/dg/creating-iceberg-tables.html)。 **注意** `UpdateTable` API 目前不支援 Iceberg 資料表格式作為操作的輸入。 1. 將 Lake Formation 權限授予任務 IAM 角色。您可以從 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`：以適當格式作為資料欄名稱使用的字串。如果您提供此選項，記錄的來源檔案修改時間會附加到記錄中。參數值將用作資料欄名稱。 # AWS Spark SQL 任務的 Glue Data Catalog 支援 AWS Glue Data Catalog 是 Apache Hive 中繼存放區相容的目錄。您可以設定您的 AWS Glue 任務和開發端點，使其使用 Data Catalog 作為外部 Apache Hive 中繼存放區。然後，您就可以直接對存放於 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 中設定特定的組態，進而可使用 Data Catalog 做為外部 Hive 中繼存放區。它也會在 AWS Glue 任務或開發端點中建立的 `SparkSession` 物件中[啟用 Hive 支援](https://spark.apache.org/docs/latest/api/java/org/apache/spark/sql/SparkSession.Builder.html#enableHiveSupport--)。 若要啟用 Data Catalog 存取，請在主控台的**新增任務**或**新增端點**頁面上，勾選**目錄選項**群組中的**使用 AWS Glue Data Catalog 做為 Hive 中繼存放**區核取方塊。請注意，用於此任務或開發端點的 IAM 角色應該擁有 `glue:CreateDatabase` 許可。稱為 "`default`" 的資料庫隨即在 Data Catalog 中建立 (如當時該資料庫尚未存在)。 讓我們從下面範例，了解您可以如何在 Spark SQL 任務中應用這項功能。下面範例是假設您已分類過下列網址提供的美國國會議員資料集，`s3://awsglue-datasets/examples/us-legislators`。 若要從 Glue Data Catalog AWS 中定義的資料表序列化/還原序列化資料，Spark SQL 需要 [Hive SerDe](https://cwiki.apache.org/confluence/display/Hive/SerDe) 類別，以符合 Spark 任務 classpath 中 AWS Glue Data Catalog 中定義的格式。 特定通用格式的 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 。如需詳細資訊，請參閱[在 Glue AWS 任務中使用任務參數](aws-glue-programming-etl-glue-arguments.md)。 下面範例是輸入 JSON，建立啟用 Data Catalog 進行 Spark SQL 的開發端點。 ``` { "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...| +--------------------+ ``` 雖然 DynamicFrames 已針對 ETL 操作經過最佳化處理，但在執行複雜 SQL 陳述式或轉運現有應用程式方面，啟用 Spark SQL 來直接存取 Data Catalog 卻是最簡潔的方法。 # 使用任務書籤 AWS Glue for Spark 使用任務書籤追蹤已處理的資料。如需任務書籤功能及其支援內容的摘要，請參閱 [使用任務書籤追蹤處理的資料](monitor-continuations.md)。使用書籤編寫 AWS Glue 任務時，您可以存取視覺化任務中無法使用的彈性。 + 從 JDBC 讀取時，您可以指定要用作 AWS Glue 指令碼中書籤索引鍵的欄 （多個）。 + 您可以選擇要將哪個 `transformation_ctx` 套用至每個方法呼叫。 *使用正確設定的參數，一律在指令碼開頭呼叫 `job.init`，在指令碼結尾呼叫 `job.commit`*。這兩個函數會初始化書籤服務並更新服務的狀態變更。如果沒有呼叫書籤，書籤將不會運作。 ## 指定書籤索引鍵 對於 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` 參數，則不會針對方法中使用的動態框架或資料表啟用任務書籤。例如，如果您有一個讀取和加入兩個 Amazon S3 來源的 ETL 任務，您可以選擇將 `transformation_ctx` 參數僅傳入您想要啟用書籤的這些方法。如果您重設任務的任務書籤，則不論所使用的 `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 任務中提供兩個 APIs。它們是 `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") ``` 您可以使用 `detect()` API 來識別 AWS 受管 PII 類型和自訂實體類型。系統會自動建立包含偵測結果的新欄。該 `classifyColumns()` API 傳回一個映射，其中索引鍵是資料欄名稱，值是偵測到的實體類型的清單。`SampleFraction` 指示掃描 PII 實體時要採樣的資料部分，而 `ThresholdFraction` 指示為了將資料欄標識為 PII 資料而必須滿足的資料部分。 ### 資料列層級偵測 在此範例中，任務正在使用 `detect()` 和 `classifyColumns()` API 執行下列動作： + 從 儲存 Amazon S3 貯體讀取資料，並將其轉換為 dynamicFrame + 偵測 dynamicFrame 中的 "Email" 和 "Credit Card" 執行個體 + 傳回具有原始值的 dynamicFrame 外加一個資料欄，其中包含每列的偵測結果 + 在另一個 Amazon S3 路徑中寫入傳回的 dynamicFrame ``` 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” + 傳回具有修改遮罩值的 dynamicFrame 與一個資料欄，其中包含每列的偵測結果 + 在其他 Amazon S3 路徑中寫入傳回的 DynamicFrame 與上述 `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% 的儲存格中，並設定為 "LOW" 敏感度，則標示為已偵測。 + 傳回一個對應，其中金鑰為資料欄名稱，而值為偵測到的實體類型清單 + 在其他 Amazon S3 路徑中寫入傳回的 DynamicFrame ``` 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`。 如果您的資料中有特定敏感資料類型 (例如「員工識別碼」)，您可以呼叫 `CreateCustomEntityType()` API 來建立自訂實體。下列範例使用請求參數為 `CreateCustomEntityType()` API 定義自訂實體類型 EMPLOYEE\$1ID： ``` { "name": "EMPLOYEE_ID", "regexString": "\d{4}-\d{3}", "contextWords": ["employee"] } ``` 然後，將自訂實體類型 (EMPLOYE\$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`，選項："LOW" 或 "HIGH"，預設："LOW") 指定偵測程序的敏感度。有效選項為 "LOW" 或 "HIGH"。如果未提供，則預設敏感度會設定為 "LOW"。 `outputColumnName` 設定： 資料欄的名稱，其中偵測到的實體將會受到儲存。如果未提供，則預設資料欄名稱為 "DetectedEntities"。針對輸出資料欄中的每一列，補充資料欄會包含資料欄名稱至偵測到之實體中繼資料的對應，其中包含下列鍵值組： + **entityType**：偵測到的實體類型。 + **start**：原始資料中偵測到的實體起始位置。 + **start**：原始資料中偵測到的實體結束位置。 + **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`，選項："LOW" 或 "HIGH"，預設："LOW") 指定偵測程序的敏感度。有效選項為 "LOW" 或 "HIGH"。如果未提供，則預設敏感度會設定為 "LOW"。 `detectionParameters` 設定 如果未包含任何設定，則會使用預設值。 + **action**：(類型：`String`，選項："DETECT"、"REDACT"、"PARTIAL\$1REDACT"、"SHA256\$1HASH") 指定要在實體中執行的動作。必要. 請注意，執行遮罩的動作 (除了 "DETECT" 以外的所有動作) 僅可在每個資料欄執行一個動作。此為遮罩合併實體的預防措施。 + **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`) 適用於部分遮蔽的 Regex 模式。無法與 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`，選項："LOW" 或 "HIGH"，預設："LOW") 指定偵測程序的敏感度。有效選項為 "LOW" 或 "HIGH"。如果未提供，則預設敏感度會設定為 "LOW"。 # 受管敏感資料類型 **全域實體** | 資料類型 | 類別 | 描述 | | --- | --- | --- | | PERSON\$1NAME | Universal | 人員姓名。 | | EMAIL | 個人 | 電子郵件地址。 | | IP\$1ADDRESS | Computer | IP 地址 | | MAC\$1ADDRESS | 個人 | MAC 地址。 | **美國資料類型** | 資料類型 | Description | | --- | --- | | BANK\$1ACCOUNT | 銀行帳戶號碼。不是特定於某個國家或區域，但目前僅偵測到美國和加拿大的帳戶格式。 | | CREDIT\$1CARD | 信用卡號碼。 | | PHONE\$1NUMBER | 電話號碼。不是特定於某個國家或區域，但目前僅偵測到美國和加拿大的電話號碼。 | | USA\$1ATIN | 美國國稅局核發的美國領養納稅人識別號碼。 | | 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 | 美國國稅局核發的美國報稅人稅務識別號碼。 | | USA\$1SSN | 社會安全號碼 (適用於美國人)。 | **阿根廷資料類型** | 資料類型 | Description | | --- | --- | | ARGENTINA\$1TAX\$1IDENTIFICATION\$1NUMBER | 阿根廷稅務識別號碼。也稱為 CUIT 或 CUIL。 | **澳洲資料類型** | 資料類型 | Description | | --- | --- | | AUSTRALIA\$1BUSINESS\$1NUMBER | 澳洲企業編號 (ABN)。由澳洲商業登記處 (ABR) 核發的唯一識別碼，用於向政府和社群識別企業。 | | AUSTRALIA\$1COMPANY\$1NUMBER | 澳洲公司編號 (ACN)。由澳洲證券與投資委員會核發的唯一識別碼。 | | AUSTRALIA\$1DRIVING\$1LICENSE | 澳洲駕照號碼。 | | AUSTRALIA\$1MEDICARE\$1NUMBER | 澳洲醫療保險號碼。由澳洲健康保險委員會核發的個人識別碼。 | | AUSTRALIA\$1PASSPORT\$1NUMBER | 澳洲護照號碼。 | | AUSTRALIA\$1TAX\$1FILE\$1NUMBER | 澳洲稅務檔案號碼 (TFN)。由澳洲稅務局 (ATO) 核發給納稅人 (個人、公司等) 進行稅務交易。 | **奧地利資料類型** | 資料類型 | Description | | --- | --- | | AUSTRIA\$1DRIVING\$1LICENSE | 駕照號碼 (奧地利特定)。 | | AUSTRIA\$1PASSPORT\$1NUMBER | 護照號碼 (奧地利特定)。 | | AUSTRIA\$1SSN | 社會安全號碼 (適用於奧地利人)。 | | AUSTRIA\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (奧地利特定)。 | | AUSTRIA\$1VALUE\$1ADDED\$1TAX | 增值稅 (奧地利特定)。 | **巴爾幹資料類型** | 資料類型 | Description | | --- | --- | | BOSNIA\$1UNIQUE\$1MASTER\$1CITIZEN\$1NUMBER | 波士尼亞與赫塞哥維納公民的唯一主公民號碼 (JMBG)。 | | 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)。 | **比利時資料類型** | 資料類型 | Description | | --- | --- | | BELGIUM\$1DRIVING\$1LICENSE | 駕照號碼 (比利時特定)。 | | BELGIUM\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 比利時國家號碼 (BNN)。 | | BELGIUM\$1PASSPORT\$1NUMBER | 護照號碼 (比利時特定)。 | | BELGIUM\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (比利時特定)。 | | BELGIUM\$1VALUE\$1ADDED\$1TAX | 增值稅 (比利時特定)。 | **巴西資料類型** | 資料類型 | Description | | --- | --- | | BRAZIL\$1BANK\$1ACCOUNT | 銀行帳號 (巴西特定)。 | | BRAZIL\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 國家識別碼 (巴西特定)。 | | BRAZIL\$1NATIONAL\$1REGISTRY\$1OF\$1LEGAL\$1ENTITIES\$1NUMBER | 核發給公司 (巴西特定) 的識別號碼，也稱為 CNPJ。 | | BRAZIL\$1NATURAL\$1PERSON\$1REGISTRY\$1NUMBER | 自然人登記號碼，也稱為 CPF。 | **保加利亞資料類型** | 資料類型 | Description | | --- | --- | | BULGARIA\$1DRIVING\$1LICENSE | 駕照號碼 (保加利亞特定)。 | | BULGARIA\$1UNIFORM\$1CIVIL\$1NUMBER | 統一公民號碼 (EGN)，作為國家識別號碼。 | | BULGARIA\$1VALUE\$1ADDED\$1TAX | 增值稅 (保加利亞特定)。 | **加拿大資料類型** | 資料類型 | Description | | --- | --- | | 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)。 | **智利資料類型** | 資料類型 | Description | | --- | --- | | CHILE\$1DRIVING\$1LICENSE | 駕照號碼 (智利特定)。 | | CHILE\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 智利國家識別碼，也稱為 RUT 或 RUN。 | **中國、香港、澳門和臺灣資料類型** | 資料類型 | Description | | --- | --- | | 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 | 澳門居民身分證 (BIR) 是由澳門身分證明局核發的正式身分證。 | | TAIWAN\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 國家識別碼 (臺灣特定) | | TAIWAN\$1PASSPORT\$1NUMBER | 護照號碼 (臺灣特定)。 | **哥倫比亞資料類型** | 資料類型 | Description | | --- | --- | | COLOMBIA\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 哥倫比亞人出生時指派到的唯一識別碼。 | | COLOMBIA\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (哥倫比亞特定)。 | **克羅埃西亞資料類型** | 資料類型 | Description | | --- | --- | | CROATIA\$1DRIVING\$1LICENSE | 駕照號碼 (克羅埃西亞特定)。 | | CROATIA\$1IDENTITY\$1NUMBER | 國家識別碼 (克羅埃西亞特定)。 | | CROATIA\$1PASSPORT\$1NUMBER | 護照號碼 (克羅埃西亞特定)。 | | CROATIA\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別號碼 (OIB)。 | **賽普勒斯資料類型** | 資料類型 | Description | | --- | --- | | CYPRUS\$1DRIVING\$1LICENSE | 駕照號碼 (賽普勒斯特定)。 | | CYPRUS\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 賽普勒斯身分證。 | | CYPRUS\$1PASSPORT\$1NUMBER | 護照號碼 (賽普勒斯特定)。 | | CYPRUS\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (賽普勒斯特定)。 | | CYPRUS\$1VALUE\$1ADDED\$1TAX | 增值稅 (賽普勒斯特定)。 | **捷克資料類型** | 資料類型 | Description | | --- | --- | | CZECHIA\$1DRIVING\$1LICENSE | 駕照號碼 (捷克特定)。 | | CZECHIA\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別號碼 (捷克特定)。 | | CZECHIA\$1VALUE\$1ADDED\$1TAX | 增值稅 (捷克特定)。 | **丹麥資料類型** | 資料類型 | Description | | --- | --- | | DENMARK\$1DRIVING\$1LICENSE | 駕照號碼 (丹麥特定)。 | | DENMARK\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別號碼 (丹麥特定)。 | | DENMARK\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (丹麥特定)。 | | DENMARK\$1VALUE\$1ADDED\$1TAX | 增值稅 (丹麥特定)。 | **愛沙尼亞資料類型** | 資料類型 | Description | | --- | --- | | ESTONIA\$1DRIVING\$1LICENSE | 駕照號碼 (愛沙尼亞特定)。 | | ESTONIA\$1PASSPORT\$1NUMBER | 護照號碼 (愛沙尼亞特定)。 | | ESTONIA\$1PERSONAL\$1IDENTIFICATION\$1CODE | 個人識別號碼 (愛沙尼亞特定)。 | | ESTONIA\$1VALUE\$1ADDED\$1TAX | 增值稅 (愛沙尼亞特定)。 | **芬蘭資料類型** | 資料類型 | Description | | --- | --- | | FINLAND\$1DRIVING\$1LICENSE | 駕照號碼 (芬蘭特定)。 | | FINLAND\$1HEALTH\$1INSURANCE\$1NUMBER | 健康保險號碼 (芬蘭特定)。 | | FINLAND\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 國家識別號碼 (芬蘭特定)。 | | FINLAND\$1PASSPORT\$1NUMBER | 護照號碼 (芬蘭特定)。 | | FINLAND\$1VALUE\$1ADDED\$1TAX | 增值稅 (芬蘭特定)。 | **法國資料類型** | 資料類型 | Description | | --- | --- | | 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 | 增值稅 (法國特定)。 | **德國資料類型** | 資料類型 | Description | | --- | --- | | GERMANY\$1BANK\$1ACCOUNT | 銀行帳號 (德國特定)。 | | GERMANY\$1DRIVING\$1LICENSE | 駕照號碼 (德國特定)。 | | GERMANY\$1PASSPORT\$1NUMBER | 護照號碼 (德國特定)。 | | GERMANY\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別號碼 (德國特定)。 | | GERMANY\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (德國特定)。 | | GERMANY\$1VALUE\$1ADDED\$1TAX | 增值稅 (德國特定)。 | **希臘資料類型** | 資料類型 | Description | | --- | --- | | GREECE\$1DRIVING\$1LICENSE | 駕照號碼 (希臘特定)。 | | GREECE\$1PASSPORT\$1NUMBER | 護照號碼 (希臘特定)。 | | GREECE\$1SSN | 社會安全號碼 (適用於希臘人)。 | | GREECE\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (希臘特定)。 | | GREECE\$1VALUE\$1ADDED\$1TAX | 增值稅 (希臘特定)。 | **匈牙利資料類型** | 資料類型 | Description | | --- | --- | | HUNGARY\$1DRIVING\$1LICENSE | 駕照號碼 (匈牙利特定)。 | | HUNGARY\$1PASSPORT\$1NUMBER | 護照號碼 (匈牙利特定)。 | | HUNGARY\$1SSN | 社會安全號碼 (適用於匈牙利人)。 | | HUNGARY\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (匈牙利特定)。 | | HUNGARY\$1VALUE\$1ADDED\$1TAX | 增值稅 (匈牙利特定)。 | **冰島資料類型** | 資料類型 | Description | | --- | --- | | ICELAND\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 國家識別碼 (冰島特定)。 | | ICELAND\$1PASSPORT\$1NUMBER | 護照號碼 (冰島特定)。 | | ICELAND\$1VALUE\$1ADDED\$1TAX | 增值稅 (冰島特定)。 | **印度資料類型** | 資料類型 | Description | | --- | --- | | INDIA\$1AADHAAR\$1NUMBER | 印度唯一身分識別機構核發的數位身份證識別號碼。 | | INDIA\$1PERMANENT\$1ACCOUNT\$1NUMBER | 印度永久帳號 (PAN)。 | **印尼資料類型** | 資料類型 | Description | | --- | --- | | INDONESIA\$1IDENTITY\$1CARD\$1NUMBER | 國家識別碼 (印尼特定)。 | **愛爾蘭資料類型** | 資料類型 | Description | | --- | --- | | IRELAND\$1DRIVING\$1LICENSE | 駕照號碼 (愛爾蘭特定)。 | | IRELAND\$1PASSPORT\$1NUMBER | 護照號碼 (愛爾蘭特定)。 | | IRELAND\$1PERSONAL\$1PUBLIC\$1SERVICE\$1NUMBER | 愛爾蘭個人公共服務號碼 (PPS)。 | | IRELAND\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (愛爾蘭特定)。 | | IRELAND\$1VALUE\$1ADDED\$1TAX | 增值稅 (愛爾蘭特定)。 | **以色列資料類型** | 資料類型 | Description | | --- | --- | | ISRAEL\$1IDENTIFICATION\$1NUMBER | 國家識別碼 (以色列特定)。 | **義大利資料類型** | 資料類型 | Description | | --- | --- | | ITALY\$1BANK\$1ACCOUNT | 銀行帳號 (義大利特定)。 | | ITALY\$1DRIVING\$1LICENSE | 駕照號碼 (義大利特定)。 | | ITALY\$1FISCAL\$1CODE | 識別號碼，也稱為義大利稅務號碼 (Italian Codice Fiscale)。 | | ITALY\$1PASSPORT\$1NUMBER | 護照號碼 (義大利特定)。 | | ITALY\$1VALUE\$1ADDED\$1TAX | 增值稅 (義大利特定)。 | **日本資料類型** | 資料類型 | Description | | --- | --- | | JAPAN\$1BANK\$1ACCOUNT | 日本銀行帳戶。 | | JAPAN\$1DRIVING\$1LICENSE | 日本駕照號碼。 | | JAPAN\$1MY\$1NUMBER | 用於稅務管理、社會保障管理和災害響應的日本公民或法人的唯一識別碼 | | JAPAN\$1PASSPORT\$1NUMBER | 日本護照號碼。 | **韓國資料類型** | 資料類型 | Description | | --- | --- | | KOREA\$1PASSPORT\$1NUMBER | 護照號碼 (韓國特定)。 | | KOREA\$1RESIDENCE\$1REGISTRATION\$1NUMBER\$1FOR\$1CITIZENS | 韓國居民的居住登記號碼。 | | KOREA\$1RESIDENCE\$1REGISTRATION\$1NUMBER\$1FOR\$1FOREIGNERS | 韓國外國人的居住登記號碼。 | **拉脫維亞資料類型** | 資料類型 | Description | | --- | --- | | LATVIA\$1DRIVING\$1LICENSE | 駕照號碼 (拉脫維亞特定)。 | | LATVIA\$1PASSPORT\$1NUMBER | 護照號碼 (拉脫維亞特定)。 | | LATVIA\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別號碼 (拉脫維亞特定)。 | | LATVIA\$1VALUE\$1ADDED\$1TAX | 增值稅 (拉脫維亞特定)。 | **列支敦斯登資料類型** | 資料類型 | Description | | --- | --- | | LIECHTENSTEIN\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 國家識別碼 (列支敦斯登特定)。 | | LIECHTENSTEIN\$1PASSPORT\$1NUMBER | 護照號碼 (列支敦斯登特定)。 | | LIECHTENSTEIN\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (列支敦斯登特定)。 | **立陶宛資料類型** | 資料類型 | Description | | --- | --- | | LITHUANIA\$1DRIVING\$1LICENSE | 駕照號碼 (立陶宛特定)。 | | LITHUANIA\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別號碼 (立陶宛特定)。 | | LITHUANIA\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (立陶宛特定)。 | | LITHUANIA\$1VALUE\$1ADDED\$1TAX | 增值稅 (立陶宛特定)。 | **盧森堡資料類型** | 資料類型 | Description | | --- | --- | | LUXEMBOURG\$1DRIVING\$1LICENSE | 駕照號碼 (盧森堡特定)。 | | LUXEMBOURG\$1NATIONAL\$1INDIVIDUAL\$1NUMBER | 國家識別碼 (盧森堡特定)。 | | LUXEMBOURG\$1PASSPORT\$1NUMBER | 護照號碼 (盧森堡特定)。 | | LUXEMBOURG\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (盧森堡特定)。 | | LUXEMBOURG\$1VALUE\$1ADDED\$1TAX | 增值稅 (盧森堡特定)。 | **馬來西亞資料類型** | 資料類型 | Description | | --- | --- | | MALAYSIA\$1MYKAD\$1NUMBER | 國家識別碼 (馬來西亞特定)。 | | MALAYSIA\$1PASSPORT\$1NUMBER | 護照號碼 (馬來西亞特定)。 | **馬爾他資料類型** | 資料類型 | Description | | --- | --- | | MALTA\$1DRIVING\$1LICENSE | 駕照號碼 (馬爾他特定)。 | | MALTA\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 國家識別碼 (馬爾他特定)。 | | MALTA\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (馬爾他特定)。 | | MALTA\$1VALUE\$1ADDED\$1TAX | 增值稅 (馬爾他特定)。 | **墨西哥資料類型** | 資料類型 | Description | | --- | --- | | 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) 墨西哥的唯一識別碼。 | **荷蘭資料類型** | 資料類型 | Description | | --- | --- | | NETHERLANDS\$1CITIZEN\$1SERVICE\$1NUMBER | 荷蘭公民號碼 (BSN，burgerservicenummer)。 | | NETHERLANDS\$1DRIVING\$1LICENSE | 駕照號碼 (荷蘭特定)。 | | NETHERLANDS\$1PASSPORT\$1NUMBER | 護照號碼 (荷蘭特定)。 | | NETHERLANDS\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (荷蘭特定)。 | | NETHERLANDS\$1VALUE\$1ADDED\$1TAX | 增值稅 (荷蘭特定)。 | | NETHERLANDS\$1BANK\$1ACCOUNT | 銀行帳號 (荷蘭特定)。 | **紐西蘭資料類型** | 資料類型 | Description | | --- | --- | | NEW\$1ZEALAND\$1DRIVING\$1LICENSE | 駕照號碼 (紐西蘭特定)。 | | NEW\$1ZEALAND\$1NATIONAL\$1HEALTH\$1INDEX\$1NUMBER | 紐西蘭國家健康指數號碼。 | | NEW\$1ZEALAND\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼，也稱為稅務號碼 (紐西蘭特定)。 | **挪威資料類型** | 資料類型 | Description | | --- | --- | | NORWAY\$1BIRTH\$1NUMBER | 挪威國民身分證號碼。 | | NORWAY\$1DRIVING\$1LICENSE | 駕照號碼 (挪威特定)。 | | NORWAY\$1HEALTH\$1INSURANCE\$1NUMBER | 挪威健康保險號碼。 | | NORWAY\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 國家識別號碼 (挪威特定)。 | | NORWAY\$1VALUE\$1ADDED\$1TAX | 增值稅 (挪威特定)。 | **菲律賓資料類型** | 資料類型 | Description | | --- | --- | | PHILIPPINES\$1DRIVING\$1LICENSE | 駕照號碼 (菲律賓特定)。 | | PHILIPPINES\$1PASSPORT\$1NUMBER | 護照號碼 (菲律賓特定)。 | **波蘭資料類型** | 資料類型 | Description | | --- | --- | | POLAND\$1DRIVING\$1LICENSE | 駕照號碼 (波蘭特定)。 | | POLAND\$1IDENTIFICATION\$1NUMBER | 波蘭識別碼。 | | POLAND\$1PASSPORT\$1NUMBER | 護照號碼 (波蘭特定)。 | | POLAND\$1REGON\$1NUMBER | REGON 識別號碼，也稱為統計識別碼。 | | POLAND\$1SSN | 社會安全號碼 (適用於波蘭人)。 | | POLAND\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (波蘭特定)。 | | POLAND\$1VALUE\$1ADDED\$1TAX | 增值稅 (波蘭特定)。 | **葡萄牙資料類型** | 資料類型 | Description | | --- | --- | | PORTUGAL\$1DRIVING\$1LICENSE | 駕照號碼 (葡萄牙特定)。 | | PORTUGAL\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 國家識別號碼 (葡萄牙特定)。 | | PORTUGAL\$1PASSPORT\$1NUMBER | 護照號碼 (葡萄牙特定)。 | | PORTUGAL\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (葡萄牙特定)。 | | PORTUGAL\$1VALUE\$1ADDED\$1TAX | 增值稅 (葡萄牙特定)。 | **羅馬尼亞資料類型** | 資料類型 | Description | | --- | --- | | ROMANIA\$1DRIVING\$1LICENSE | 駕照號碼 (羅馬尼亞特定)。 | | ROMANIA\$1NUMERICAL\$1PERSONAL\$1CODE | 個人識別號碼 (羅馬尼亞特定)。 | | ROMANIA\$1PASSPORT\$1NUMBER | 護照號碼 (羅馬尼亞特定)。 | | ROMANIA\$1VALUE\$1ADDED\$1TAX | 增值稅 (羅馬尼亞特定)。 | **新加坡資料類型** | 資料類型 | Description | | --- | --- | | SINGAPORE\$1DRIVING\$1LICENSE | 駕照號碼 (新加坡特定)。 | | SINGAPORE\$1NATIONAL\$1REGISTRY\$1IDENTIFICATION\$1NUMBER | 新加坡國民登記身分證。 | | SINGAPORE\$1PASSPORT\$1NUMBER | 護照號碼 (新加坡特定)。 | | SINGAPORE\$1UNIQUE\$1ENTITY\$1NUMBER | 新加坡唯一實體編號。 | **斯洛伐克資料類型** | 資料類型 | Description | | --- | --- | | SLOVAKIA\$1DRIVING\$1LICENSE | 駕照號碼 (斯洛伐克特定)。 | | SLOVAKIA\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 國家識別號碼 (斯洛伐克特定)。 | | SLOVAKIA\$1PASSPORT\$1NUMBER | 護照號碼 (斯洛伐克特定)。 | | SLOVAKIA\$1VALUE\$1ADDED\$1TAX | 增值稅 (斯洛伐克特定)。 | **斯洛維尼亞資料類型** | 資料類型 | Description | | --- | --- | | SLOVENIA\$1DRIVING\$1LICENSE | 駕照號碼 (斯洛維尼亞特定)。 | | SLOVENIA\$1PASSPORT\$1NUMBER | 護照號碼 (斯洛維尼亞特定)。 | | SLOVENIA\$1TAX\$1IDENTIFICATION\$1NUMBER | 稅務識別號碼 (斯洛維尼亞特定)。 | | SLOVENIA\$1UNIQUE\$1MASTER\$1CITIZEN\$1NUMBER | 斯洛維尼亞公民的唯一主公民號碼 (JMBG)。 | | SLOVENIA\$1VALUE\$1ADDED\$1TAX | 增值稅 (斯洛維尼亞特定)。 | **南非資料類型** | 資料類型 | Description | | --- | --- | | SOUTH\$1AFRICA\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別號碼 (南非特定)。 | **西班牙資料類型** | 資料類型 | Description | | --- | --- | | SPAIN\$1BANK\$1ACCOUNT | 銀行帳號 (西班牙特定)。 | | SPAIN\$1DNI | 西班牙國民身分證 (身分證明文件)。 | | SPAIN\$1DRIVING\$1LICENSE | 駕照號碼 (西班牙特定)。 | | SPAIN\$1NIE | 外國人身分證號碼 (西班牙特定)，也稱為 NIE。 | | SPAIN\$1NIF | 稅務識別號碼 (西班牙特定)，也稱為 NIF。 | | SPAIN\$1PASSPORT\$1NUMBER | 護照號碼 (西班牙特定)。 | | SPAIN\$1SSN | 社會安全號碼 (適用於西班牙人)。 | | SPAIN\$1VALUE\$1ADDED\$1TAX | 增值稅 (西班牙特定)。 | **斯里蘭卡資料類型** | 資料類型 | Description | | --- | --- | | SRI\$1LANKA\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 國家識別碼編號 (斯里蘭卡特定)。 | **瑞典資料類型** | 資料類型 | Description | | --- | --- | | SWEDEN\$1DRIVING\$1LICENSE | 駕照號碼 (瑞典特定)。 | | SWEDEN\$1PASSPORT\$1NUMBER | 護照號碼 (瑞典特定)。 | | SWEDEN\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 國家識別號碼 (瑞典特定)。 | | SWEDEN\$1TAX\$1IDENTIFICATION\$1NUMBER | 瑞典稅務識別號碼 (personnummer)。 | | SWEDEN\$1VALUE\$1ADDED\$1TAX | 增值稅 (瑞典特定)。 | **瑞士資料類型** | 資料類型 | Description | | --- | --- | | SWITZERLAND\$1AHV | 瑞士人的社會安全號碼 (AHV)。 | | SWITZERLAND\$1HEALTH\$1INSURANCE\$1NUMBER | 瑞士健康保險號碼。 | | SWITZERLAND\$1PASSPORT\$1NUMBER | 護照號碼 (瑞士特定)。 | | SWITZERLAND\$1VALUE\$1ADDED\$1TAX | 增值稅 (瑞士特定)。 | **泰國資料類型** | 資料類型 | Description | | --- | --- | | THAILAND\$1PASSPORT\$1NUMBER | 護照號碼 (泰國特定)。 | | THAILAND\$1PERSONAL\$1IDENTIFICATION\$1NUMBER | 個人識別號碼 (泰國特定)。 | **土耳其資料類型** | 資料類型 | Description | | --- | --- | | TURKEY\$1NATIONAL\$1IDENTIFICATION\$1NUMBER | 國家識別號碼 (土耳其特定)。 | | TURKEY\$1PASSPORT\$1NUMBER | 護照號碼 (土耳其特定)。 | | TURKEY\$1VALUE\$1ADDED\$1TAX | 增值稅 (土耳其特定)。 | **烏克蘭資料類型** | 資料類型 | Description | | --- | --- | | UKRAINE\$1INDIVIDUAL\$1IDENTIFICATION\$1NUMBER | 唯一識別碼 (烏克蘭特定)。 | | UKRAINE\$1PASSPORT\$1NUMBER\$1DOMESTIC | 國內護照號碼 (烏克蘭特定)。 | | UKRAINE\$1PASSPORT\$1NUMBER\$1INTERNATIONAL | 國際護照號碼 (烏克蘭特定)。 | **阿拉伯聯合大公國 (UAE) 資料類型** | 資料類型 | Description | | --- | --- | | UNITED\$1ARAB\$1EMIRATES\$1PERSONAL\$1NUMBER | 個人識別號碼 (阿拉伯聯合大公國特定)。 | **英國資料類型** | 資料類型 | Description | | --- | --- | | 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) 是英國 (UK) 用於識別國家保險計畫或社會保障系統之個人的號碼。該號碼有時稱為 NI No 或 NINO。 | | UK\$1PASSPORT\$1NUMBER | 英國 (UK) 護照號碼。 | | UK\$1UNIQUE\$1TAXPAYER\$1REFERENCE\$1NUMBER | 英國 (UK) 唯一納稅人參考 (UTR) 號碼。英國政府用來管理稅務系統的識別碼。 | | UK\$1VALUE\$1ADDED\$1TAX | 增值稅是由最終消費者承擔的消費稅。製造和分銷過程中的每筆交易都要支付增值稅。對於英國，增值稅號碼由開展業務所在區域的增值稅辦公室核發。 | | UK\$1PHONE\$1NUMBER | 英國 (UK) 電話號碼。 | **委內瑞拉資料類型** | 資料類型 | Description | | --- | --- | | 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 敏感資料轉換可讓您偵測、遮罩或移除您定義或由 Glue AWS 預先定義的實體。微調動作可讓您進一步針對每個實體套用特定動作。其他優點包括： + 系統偵測到資料後會隨即套用動作，使效能獲得改善。 + 可選擇包含或排除特定資料欄。 + 可使用部分遮罩。這可讓您部分遮罩偵測到的敏感資料實體，而非遮罩整個字串。支援具有位移和 regex 的兩種簡易參數。 以下為用於下一節引用之範例任務的敏感資料偵測 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`，會發現範例任務中具有三種實體類型。這三種類型為 `Phone Number`、`USA_PASSPORT_NUMBER` 及 `USA_DRIVING_LICENSE`。對於這些實體類型，Glue AWS 將執行不同的動作，即 `PARTIAL_REDACT`、`REDACT`、 `SHA256_HASH`和 `DETECT`。每個實體類型也會具有要套用的 `sourceColumns` 和/或 `sourceColumnsToExclude` (如果偵測到)。 **注意** 每資料欄僅能使用一個就地編輯動作 (`PARTIAL_REDACT`、`SHA256_HASH`、或 `REDACT`)，但 `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# ` 經偵測為美國駕照號碼，因此遭遮蔽為 “USA\$1DL” (如 `detectionParameters` 中所述)。 **注意** 由於 API 的性質，因此 classifyColumns API 無法與微調動作搭配使用。此 API 會執行資料欄取樣 (可依使用者調整，但具有預設值)，以加快執行偵測速度。由於此原因，微調動作將需要針對每個值進行反覆運算。 ### 持續稽核日誌 全新引進具有微調動作的功能 (但在使用一般 API 時亦適用) 為產生持續稽核日誌。目前執行 detect API 將會新增其他資料欄 (預設為 `DetectedEntities`，但可透過 `outputColumnName` 自訂) 參數，其中包含 PII 偵測中繼資料。現在這樣會產生 "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 } ] } ``` 即使客戶使用不具有微調動作的 API (例如，`detect(entityTypesToDetect, outputColumnName)`)，仍會在產生的 DataFrame 中看見這項持續稽核日誌。 使用具有微調動作之 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 提供一個 API，允許客戶使用 AWS Glue API 從 JSON 物件建立資料整合，而該使用來自代表視覺化步驟工作流程之 的 。然後，客戶可以使用 AWS Glue Studio 中的視覺化編輯器處理這些任務。 如需有關視覺化任務 API 資料類型的詳細資訊，請參閱[視覺化任務 API](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-visual-job-api.html)。 **Topics** + [API 設計和 CRUD API](#visual-job-api-design) + [開始使用](#getting-started-visual-job-api) + [視覺化任務限制](#visual-job-limitations) ## API 設計和 CRUD API CreateJob 和 UpdateJob [API](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-jobs-job.html) 現已支援一個額外的選用參數，即 codeGenConfigurationNodes。為此欄位提供非空白的 JSON 結構將導致在 AWS Glue Studio 中為建立的任務和正在產生的相關程式碼註冊 DAG。系統將忽略任務建立時此欄位的空值或空字串。 透過 UpdateJob AWS Glue API，會以與 CreateJob 類似的方式更新 codeGenConfigurationNodes 欄位。應該在 UpdateJob 中指定整個欄位，其中 DAG 已視需要變更。系統會忽略所提供的空值，且不會對 DAG 執行任何更新。空的結構或字串 codeGenConfigurationNodes 設定為空白，並移除任何先前的 DAG。GetJob API 將會傳回 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` 請求輸入會有一個額外欄位 "codeGenConfigurationNodes"，讓您可在其中指定 JSON 中的 DAG 物件。 需要謹記的事項： + ‘codeGenConfigurationNodes’ 是節點的 nodeId 映射。 + 每個節點都以識別其類型的索引鍵開頭。 + 節點只能是一種類型，因此只能指定一個索引鍵。 + 輸入欄位包含當前節點的父節點。 以下為 **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"] } ] } } } ``` **更新及取得任務** 由於 *UpdateJob* 也將會有 "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) 動作。 ## 視覺化任務限制 由於 ‘codeGenConfigurationNodes’ 參數已新增至現有的 API 中，這些 API 中的任何限制將得到繼承。此外，codeGenConfigurationNodes 和某些節點的大小會受到限制。請參閱[任務結構](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-jobs-job.html#aws-glue-api-jobs-job-Job)以了解詳細資訊。