本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 為 Jupyter 和 AWS Glue Studio 筆記本設定 AWS Glue 互動式工作階段 ## Jupyter 魔術命令簡介 Jupyter 魔術命令是可在儲存格的開頭或作為整個儲存格內文執行的命令。行魔術命令的開頭為 `%`，而儲存格魔術命令開頭為 `%%`。行魔術命令，如 `%region` 和 `%connections`，可在儲存格搭配多個魔術命令執行，或者像以下範列那樣搭配包含在儲存格內文中的程式碼。 ``` %region us-east-2 %connections my_rds_connection dy_f = glue_context.create_dynamic_frame.from_catalog(database='rds_tables', table_name='sales_table') ``` 儲存格魔術命令必須使用整個儲存格，並且可以使命令跨越多行。`%%sql` 的範例位於下方。 ``` %%sql select * from rds_tables.sales_table ``` ## 適用於 Jupyter 的 AWS Glue 互動式工作階段支援的魔術命令 以下是可以與適用於 Jupyter 筆記本的 AWS Glue 互動式工作階段搭配使用的魔術命令。 **Sessions magics** (工作階段魔術命令) | 名稱 | 類型 | 說明 | | --- | --- | --- | | %help | N/A | 傳回所有魔術命令的描述和輸入類型清單。 | | %profile | String | 在您的 AWS 組態中指定設定檔，以用作登入資料提供者。 | | %region | String | 指定 AWS 區域；在其中初始化工作階段。預設來自 `~/.aws/configure.` 範例：`%region us-west-1` | | %idle\$1timeout | Int | 在執行儲存格後工作階段逾時之前的閒置分鐘數。預設的 Spark ETL 工作階段閒置逾時值為預設的逾時值，即 2880 分鐘 (48 小時)。針對其他工作階段類型，請參閱該工作階段類型的相關文件。 範例：`%idle_timeout 3000` | | %session\$1id | N/A | 傳回執行中工作階段的工作階段 ID。 | | %session\$1id\$1prefix | String | 定義一個字串，該字串將放在所有工作階段 ID 之前，格式為 **[session\$1id\$1prefix]-[session\$1id]**。如果未提供工作階段 ID，則會產生隨機 UUID。當您在 AWS Glue Studio中執行 Jupyter 筆記本時，不支援此魔術命令。 範例：`%session_id_prefix 001` | | %status | | 傳回當前 AWS Glue 工作階段的狀態，包括其持續時間、組態和執行使用者/角色。 | | %stop\$1session | | 停止目前的工作階段。 | | %list\$1sessions | | 依名稱和 ID 列出所有目前執行中的工作階段。 | | %session\$1type | String | 將工作階段類型設為「串流」、「ETL」或「Ray」的其中之一。 範例：`%session_type Streaming` | | %glue\$1version | String | 此工作階段要使用的 AWS Glue 版本。 範例：`%glue_version 3.0` | **用於選取任務類型的魔術命令** | 名稱 | 類型 | Description | | --- | --- | --- | | %streaming | String | 將工作階段類型變更為 AWS Glue 串流。 | | %etl | String | 將工作階段類型變更為 AWS Glue ETL。 | | %glue\$1ray | String | 將工作階段類型變更為 AWS Glue for Ray。請參閱 [Ray AWS Glue 互動式工作階段支援的魔術](https://docs.aws.amazon.com/glue/latest/dg/is-using-ray-configuration)。 | **AWS Glue for Spark 組態魔術命令** `%%configure` 魔術命令是由工作階段的所有組態參數組成的 JSON 格式字典。可以在此處或透過個別魔術命令來指定每個參數。 | 名稱 | 類型 | 描述 | | --- | --- | --- | | %%configure | 字典 | 指定由工作階段的所有組態參數組成的 JSON 格式字典。可以在此處或透過個別魔術命令來指定每個參數。 如需參數清單以及如何使用 `%%configure` 的範例，請參閱[%%configure 儲存格魔術命令引數](#interactive-sessions-magics-configure-arguments)。 | | %iam\$1role | String | 指定用來執行工作階段的 IAM 角色 ARN。預設來自 \$1/.aws/configure。 範例：`%iam_role AWSGlueServiceRole` | | %number\$1of\$1workers | Int | 當任務執行時所分配的已定義 worker\$1type 的工作者數目。還必須設定 `worker_type`。預設的 `number_of_workers` 為 5。 範例：`%number_of_workers 2` | | %additional\$1python\$1modules | 清單 | 要包含在叢集中的以逗號分隔的其他 Python 模組清單 (可以來自 PyPI 或 S3)。 範例：`%additional_python_modules pandas, numpy`。 | | %%tags | String | 將標籤新增至工作階段。指定大括號 \$1\$1 內的標籤。每個標籤名稱配對均以括號 (" ") 括住，並以逗號 (,) 區隔。 
%%tags
{"billing":"Data-Platform", "team":"analytics"}
使用 `%status` 魔術命令來檢視與工作階段相關聯的標籤。 
%status
Session ID: 
 Status: READY
 Role: 
 CreatedOn: 2023-05-26 11:12:17.056000-07:00
 GlueVersion: 3.0
 Job Type: glueetl
 Tags: {'owner':'example-owner', 'team':'analytics', 'billing':'Data-Platform'}
 Worker Type: G.4X
 Number of Workers: 5
 Region: us-west-2
 Applying the following default arguments:
 --glue_kernel_version 0.38.0
 --enable-glue-datacatalog true
 Arguments Passed: ['--glue_kernel_version: 0.38.0', '--enable-glue-datacatalog: true']
| | %%assume\$1role | 字典 | 指定 JSON 格式的字典或 IAM 角色 ARN 字串，以建立可取得跨帳戶存取權的工作階段。 使用 ARN 的範例： 
%%assume_role
{
  'arn:aws:iam::XXXXXXXXXXXX:role/AWSGlueServiceRole'
}
使用憑證的範例： 
 %%assume_role
{{
    "aws_access_key_id" = "XXXXXXXXXXXX",
    "aws_secret_access_key" = "XXXXXXXXXXXX",
    "aws_session_token" = "XXXXXXXXXXXX"
}}
| ### %%configure 儲存格魔術命令引數 `%%configure` 魔術命令是由工作階段的所有組態參數組成的 JSON 格式字典。可以在此處或透過個別魔術命令來指定每個參數。如需 `%%configure` 儲存格魔術命令支援的引數範例，請參閱以下內容。將 `--` 字首用於為任務指定的執行引數。範例： ``` %%configure { "--user-jars-first": "true", "--enable-glue-datacatalog": "false" } ``` 如需任務參數的詳細資訊，請參閱[工作參數](aws-glue-programming-etl-glue-arguments.md)。 **工作階段組態** | 參數 | 類型 | 說明 | | --- | --- | --- | | max\$1retries | Int | 如果此任務失敗，可重試的次數上限。 
%%configure
{
  "max_retries": "0"
}
| | max\$1concurrent\$1runs | Int | 一項任務可同時執行的數量上限。範例： 
%%configure
{
  "max_concurrent_runs": "3"
}
| **工作階段參數** | 參數 | 類型 | 描述 | | --- | --- | --- | | --enable-spark-ui | 布林值 | 啟用 Spark UI 以監控和偵錯 AWS Glue ETL 任務。
%%configure
{
  "--enable-spark-ui": "true"
}
| | --spark-event-logs-path | String | 指定 Amazon S3 路徑。使用 Spark UI 監控功能時。範例： 
%%configure
{
  "--spark-event-logs-path": "s3://path/to/event/logs/"
}
| | --script\$1location | String | 指定執行任務的指令碼 S3 路徑。範例：
%%configure 
{
  "script_location": "s3://new-folder-here"
}
| | --SECURITY\$1CONFIGURATION | String | AWS Glue 安全組態的名稱 範例： 
%%configure
{
    "--security_configuration": {
"encryption_type": "kms",
"kms_key_id": "YOUR_KMS_KEY_ARN"
}
}
| | --job-language | String | 指令碼程式設計語言。接受 'scala' 或 'python' 的值。預設為 'python'。範例： 
%%configure 
{
  "--job-language": "scala"
}
| | --class | String | 可作為您的 Scala 指令碼進入點的 Scala 類別。預設為 Null。範例： 
%%configure 
{
  "--class": "className"
}
| | --user-jars-first | 布林值 | 在 classpath 中優先採用客戶的額外 JAR 檔案。預設為 Null。範例： 
%%configure 
{
  "--user-jars-first": "true"
}
| | --use-postgres-driver | 布林值 | 優先考慮類別路徑中的 Postgres JDBC 驅動程式，以避免與 Amazon Redshift JDBC 驅動程式衝突。預設為 Null。範例： 
%%configure 
{
  "--use-postgres-driver": "true"
}
| | --extra-files | List(string) | 組態檔案等其他檔案的 Amazon S3 路徑；在 AWS Glue 執行您的指令碼前，即會將其複製至指令碼的工作目錄。範例： 
%%configure 
{
  "--extra-files": "s3://path/to/additional/files/"
}
| | --job-bookmark-option | String | 控制任務書籤的行為。接受 'job-bookmark-enable'、'job-bookmark-disable' 或 'job-bookmark-pause' 的值。預設為 'job-bookmark-disable'。範例： 
%%configure
{
  "--job-bookmark-option": "job-bookmark-enable"
}
| | --TempDir | String | 指定儲存貯體的 Amazon S3 路徑做為任務的暫時目錄。預設為 Null。範例： 
%%configure 
{
  "--TempDir": "s3://path/to/temp/dir"
}
| | --enable-s3-parquet-optimized-committer | 布林值 | 啟用 EMRFS Amazon S3 最佳化遞交者，以將 Parquet 資料寫入 Amazon S3。預設為 'true'。範例： 
%%configure 
{
  "--enable-s3-parquet-optimized-committer": "false"
}
| | --enable-rename-algorithm-v2 | 布林值 | 將 EMRFS 重新命名演算法版本設定為第 2 版。預設為 'true'。範例： 
%%configure 
{
  "--enable-rename-algorithm-v2": "true"
}
| | --enable-glue-datacatalog | 布林值 | 可讓您使用 AWS Glue Data Catalog 作為 Apache Spark Hive 中繼存放區。範例： 
%%configure 
{
  "--enable-glue-datacatalog": "true"
}
| | --enable-metrics | 布林值 | 針對任務執行啟用任務分析的指標集合。預設為 'false'。範例： 
%%configure 
{
  "--enable-metrics": "true"
}
| | --enable-continuous-cloudwatch-log | 布林值 | 啟用即時、持續的 AWS Glue 任務記錄。預設為 'false'。範例： 
%%configure 
{
  "--enable-continuous-cloudwatch-log": "true"
}
| | --enable-continuous-log-filter | 布林值 | 當您建立或編輯已啟用持續記錄的任務時，指定標準篩選條件或無篩選條件。預設為 'true'。範例： 
%%configure 
{
  "--enable-continuous-log-filter": "true"
}
| | --continuous-log-stream-prefix | String | 為啟用持續記錄的任務指定自訂 Amazon CloudWatch 日誌串流字首。預設為 Null。範例： 
%%configure 
{
  "--continuous-log-stream-prefix": "prefix"
}
| | --continuous-log-conversionPattern | String | 為啟用連續記錄的任務指定自訂轉換日誌模式。預設為 Null。範例： 
%%configure 
{
  "--continuous-log-conversionPattern": "pattern"
}
| | --conf | String | 控制 Spark 組態參數。適用於進階使用案例。在每個參數之前使用 --conf。範例：
%%configure
{
    "--conf": "spark.hadoop.hive.metastore.glue.catalogid=123456789012 --conf hive.metastore.client.factory.class=com.amazonaws.glue.catalog.metastore.AWSGlueDataCatalogHiveClientFactory --conf hive.metastore.schema.verification=false"
}
| | timeout | Int | 確定 Spark 工作階段在終止陳述式之前，應等待陳述式完成的時間上限。
%%configure 
{
  "timeout": "30"
}
| | 自動擴展 | Boolean | 確定是否使用自動擴展。
%%configure 
{
  "––enable-auto-scaling": "true"
}
| ### Spark 任務 (ETL 與串流) 魔術命令 | 名稱 | 類型 | Description | | --- | --- | --- | | %worker\$1type | String | 也必須number\$1of\$1workers設定標準、G.1X、G.2X、G.4X、G.8X、G.12X、G.16X、R.1X、R.2X、R.4X 或 R.8X。預設 worker\$1type 是 G.1X。 | | %connections | List | 指定以逗號分隔的清單，其中列出要在工作階段中使用的連線。 範例： 
%connections my_rds_connection
                    dy_f = glue_context.create_dynamic_frame.from_catalog(database='rds_tables', table_name='sales_table')
| | %extra\$1py\$1files | 清單 | 列出來自 Amazon S3 的以逗號分隔的其他 Python 檔案清單。 | | %extra\$1jars | 清單 | 列出要包含在叢集中的以逗號分隔的其他 jar 清單。 | | %spark\$1conf | String | 為您的工作階段指定自訂 Spark 組態。例如 %spark\$1conf spark.serializer=org.apache.spark.serializer.KryoSerializer。 | ### 適用於 Ray 任務的魔術命令 | 名稱 | 類型 | 說明 | | --- | --- | --- | | %min\$1workers | Int | 分配給 Ray 任務的工作者數量下限。預設：1。 範例：`%min_workers 2` | | %object\$1memory\$1head | Int | 暖啟動後執行個體前端節點上可用記憶體的百分比。下限：0。上限：100。範例：`%object_memory_head 100` | | %object\$1memory\$1worker | Int | 暖啟動後執行個體工作節點上可用記憶體的百分比。下限：0。上限：100。範例：`%object_memory_worker 100` | ### Action magics (動作魔術命令) | 名稱 | 類型 | Description | | --- | --- | --- | | %%sql | String | 執行 SQL 程式碼。初始 `%%sql` 魔術命令之後的所有行都將作為 SQL 程式碼的一部分傳遞。 範例：`%%sql select * from rds_tables.sales_table` | | %matplot | Matplotlib 圖 | 使用 matplotlib 程式庫視覺化資料。 範例： 
import matplotlib.pyplot as plt

# Set X-axis and Y-axis values
x = [5, 2, 8, 4, 9]
y = [10, 4, 8, 5, 2]
  
# Create a bar chart 
plt.bar(x, y)
  
# Show the plot
%matplot plt
| | %plotly | Plotly 圖 | 使用 plotly 程式庫視覺化資料。 範例： 
import plotly.express as px
                  
#Create a graphical figure
fig = px.line(x=["a","b","c"], y=[1,3,2], title="sample figure")

#Show the figure
%plotly fig
| ## 命名工作階段 AWS Glue 互動式工作階段是 AWS 資源，需要名稱。每個工作階段的名稱應是唯一的，且可能受 IAM 管理員的限制。如需詳細資訊，請參閱[具備 IAM 的互動式工作階段](glue-is-security.md)。Jupyter 核心會為您自動產生唯一的工作階段名稱。但是，可以透過兩種方式手動命名工作階段： 1. 使用位於 AWS Command Line Interface 的組態檔案`~.aws/config`。請參閱[使用 AWS 設定組態 AWS Command Line Interface](https://docs.aws.amazon.com/config/latest/developerguide/gs-cli.html)。 1. 使用 `%session_id_prefix` 魔術命令。請參閱 [適用於 Jupyter 的 AWS Glue 互動式工作階段支援的魔術命令](#interactive-sessions-supported-magics)。 產生的工作階段名稱如下： + 當提供字首和 session\$1id 時：工作階段名稱將是 \$1prefix\$1-\$1UUID\$1。 + 如果未提供任何資料：工作階段名稱將是 \$1UUID\$1。 在 AWS CLI 或 主控台中列出工作階段時，字首工作階段名稱可讓您識別工作階段。 ## 指定互動式工作階段的 IAM 角色 您必須指定 AWS Identity and Access Management (IAM) 角色，以與您透過互動式工作階段執行的 AWS Glue ETL 程式碼搭配使用。 角色需要擁有執行 AWS Glue 任務所需的相同 IAM 許可。如需為 AWS Glue 任務和互動式工作階段建立角色的詳細資訊，請參閱《[為 AWS Glue 建立 IAM 角色](https://docs.aws.amazon.com/glue/latest/dg/create-an-iam-role.html)》。 IAM 角色可以使用兩種方式指定： + 使用位於 AWS Command Line Interface 的組態檔案 `~.aws/config`（建議）。如需詳細資訊，請參閱[使用 \$1/.aws/config 設定工作階段](https://docs.aws.amazon.com/glue/latest/ug/interactive-sessions-magics.html#interactive-sessions-named-profiles)。 **注意** 使用 `%profile` 魔術命令時，該設定檔的 `glue_iam_role` 組態會被接受。 + 使用 %iam\$1role 魔術命令。如需詳細資訊，請參閱[適用於 Jupyter 的 AWS Glue 互動式工作階段支援的魔術命令](#interactive-sessions-supported-magics)。 ## 使用命名設定檔設定工作階段 AWS Glue 互動式工作階段使用與 AWS Command Line Interface 或 boto3 相同的登入資料，而互動式工作階段遵守和使用具名設定檔，例如 AWS CLI `~/.aws/config`(Linux 和 MacOS) 或 `%USERPROFILE%\.aws\config`(Windows) 中找到的 。如需詳細資訊，請參閱[使用命名設定檔](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles)。 互動式工作階段透過允許在設定檔中指定 AWS Glue 服務角色和工作階段 ID 字首，來利用命名設定檔。若要設定設定檔角色，請為 `iam_role` 金鑰和/或 `session_id_prefix ` 在命名設定檔中新增一行，如下所示。`session_id_prefix` 不需要引號。例如，若您想要新增 ` session_id_prefix`，請輸入 `session_id_prefix=myprefix` 的值。 ``` [default] region=us-east-1 aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY glue_iam_role=arn:aws:iam:::role/ session_id_prefix= [user1] region=eu-west-1 aws_access_key_id=AKIAI44QH8DHBEXAMPLE aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY glue_iam_role=arn:aws:iam:::role/ session_id_prefix= ``` 如果您有產生憑證的自訂方法，您也可以在 `~/.aws/config` 檔案中將設定檔設定為使用 `credential_process` 參數。例如： ``` [profile developer] region=us-east-1 credential_process = "/Users/Dave/generate_my_credentials.sh" --username helen ``` 您可以透過此處的 `credential_process` 參數找到有關取得憑證的詳細資訊：[透過外部程序取得憑證](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html)。 如果區域或 `iam_role` 未在您使用的設定檔中設定，則您必須在執行的第一個儲存格中使用 `%region` 和 `%iam_role` 魔術命令來指定它們。