# 为 Jupyter 和 Amazon Glue Studio 笔记本配置 Amazon 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 的 Amazon Glue 交互式会话支持魔术命令 以下是您可以与 Jupyter notebook 的 Amazon Glue 交互式会话搭配使用的魔术命令。 **会话魔术命令** | 名称 | Type | 说明 | | --- | --- | --- | | %help | 不适用 | 返回所有魔术命令的描述和输入类型列表。 | | %profile | 字符串 | 在 Amazon 配置中指定要用作凭证提供程序的配置文件。 | | %region | 字符串 | 指定 Amazon Web Services 区域；在其中初始化会话。`~/.aws/configure.` 的默认值 示例：`%region us-west-1` | | %idle\$1timeout | Int | 执行单元格后，非活动的分钟数，在此之后会话将超时。Spark ETL 会话的默认空闲超时值是默认超时，2880 分钟（48小时）。对于其他会话类型，请查阅该会话类型的文档。 示例：`%idle_timeout 3000` | | %session\$1id | 不适用 | 返回正在运行的会话的会话 ID。 | | %session\$1id\$1prefix | 字符串 | 以格式 **[session\$1id\$1prefix]-[session\$1id]** 定义在所有会话 ID 之前的字符串。如果未提供会话 ID，则将生成随机 UUID。当您在 Amazon Glue Studio 中运行 Jupyter Notebook 时，不支持此魔术命令。 示例：`%session_id_prefix 001` | | %status | | 返回当前 Amazon Glue 会话的状态，包括其持续时间、配置和执行用户/角色。 | | %stop\$1session | | 停止当前会话。 | | %list\$1sessions | | 按名称和 ID 列出当前正在运行的所有会话。 | | %session\$1type | 字符串 | 将会话类型设置为流媒体、ETL 或 Ray 中的一种。 示例：`%session_type Streaming` | | %glue\$1version | 字符串 | 此会话使用的 Amazon Glue 版本。 示例：`%glue_version 3.0` | **选择作业类型的魔术命令** | 名称 | Type | 说明 | | --- | --- | --- | | %streaming | 字符串 | 将会话类型更改为 Amazon Glue 串流。 | | %etl | 字符串 | 将会话类型更改为 Amazon Glue ETL。 | | %glue\$1ray | 字符串 | 将会话类型更改为 Amazon Glue for Ray。请参阅 [Magics supported by Amazon Glue Ray interactive sessions](https://docs.amazonaws.cn/glue/latest/dg/is-using-ray-configuration)。 | **Amazon Glue for Spark 配置魔术命令** `%%configure` 魔术命令指定一个 json 格式的字典，其中包含会话的所有配置参数。每个参数可以在此处指定，也可以通过单独的魔术命令指定。 | 名称 | Type | 说明 | | --- | --- | --- | | %%configure | 字典 | 指定一个 JSON 格式的字典，其中包含会话的所有配置参数。每个参数可以在此处指定，也可以通过单独的魔术命令指定。 有关如何使用 `%%configure` 的参数和示例列表，请参阅 [%%configure 单元格魔术命令参数](#interactive-sessions-magics-configure-arguments)。 | | %iam\$1role | 字符串 | 指定用于执行会话的 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 | 字符串 | 为会话添加标签。在大括号 \$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 用户界面来监控和调试 Amazon Glue ETL 作业。
%%configure
{
  "--enable-spark-ui": "true"
}
| | --spark-event-logs-path | 字符串 | 指定 Amazon S3 路径。使用 Spark 用户界面监控功能时。示例： 
%%configure
{
  "--spark-event-logs-path": "s3://path/to/event/logs/"
}
| | --script\$1location | 字符串 | 指定执行作业的脚本的 S3 路径。示例：
%%configure 
{
  "script_location": "s3://new-folder-here"
}
| | --SECURITY\$1CONFIGURATION | 字符串 | Amazon Glue 安全配置的名称 示例： 
%%configure
{
    "--security_configuration": {
"encryption_type": "kms",
"kms_key_id": "YOUR_KMS_KEY_ARN"
}
}
| | --job-language | 字符串 | 脚本编程语言。接受“scala”或“python”的值。默认值为“python”。示例： 
%%configure 
{
  "--job-language": "scala"
}
| | --class | 字符串 | 用作 Scala 脚本之入口点的 Scala 类。默认值为 null。示例： 
%%configure 
{
  "--class": "className"
}
| | --user-jars-first | 布尔值 | 优先考虑类路径中的客户额外 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 Glue 复制到脚本工作目录中的其他文件（如配置文件）的 Amazon S3 路径。示例： 
%%configure 
{
  "--extra-files": "s3://path/to/additional/files/"
}
| | --job-bookmark-option | 字符串 | 控制作业书签的行为。接受“job-bookmark-enable”、“job-bookmark-disable”或“job-bookmark-pause”的值。默认值为“job-bookmark-disable”。示例： 
%%configure
{
  "--job-bookmark-option": "job-bookmark-enable"
}
| | --TempDir | 字符串 | 指定可用作任务的临时目录的存储桶的 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 | 布尔值 | 支持您将 Amazon Glue Data Catalog 用作 Apache Spark Hive 元存储。示例： 
%%configure 
{
  "--enable-glue-datacatalog": "true"
}
| | --enable-metrics | 布尔值 | 为作业运行启用作业分析指标的集合。默认值为“false”。示例： 
%%configure 
{
  "--enable-metrics": "true"
}
| | --enable-continuous-cloudwatch-log | 布尔值 | 允许对 Amazon Glue 作业进行实时的连续日志记录。默认值为“false”。示例： 
%%configure 
{
  "--enable-continuous-cloudwatch-log": "true"
}
| | --enable-continuous-log-filter | 布尔值 | 在创建或编辑为连续日志记录启用的作业时，指定标准筛选器或无筛选器。默认值为“true”。示例： 
%%configure 
{
  "--enable-continuous-log-filter": "true"
}
| | --continuous-log-stream-prefix | 字符串 | 为已启用连续日志记录的作业指定自定义 Amazon CloudWatch 日志流前缀。默认值为 null。示例： 
%%configure 
{
  "--continuous-log-stream-prefix": "prefix"
}
| | --continuous-log-conversionPattern | 字符串 | 为已启用连续日志记录的作业指定自定义转换日志模式。默认值为 null。示例： 
%%configure 
{
  "--continuous-log-conversionPattern": "pattern"
}
| | --conf | 字符串 | 控制 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"
}
| | 自动扩缩 | 布尔值 | 确定是否使用自动扩缩。
%%configure 
{
  "––enable-auto-scaling": "true"
}
| ### Spark 作业（ETL 和流传输）魔术命令 | 名称 | Type | 说明 | | --- | --- | --- | | %worker\$1type | 字符串 | 标准、G.1X、G.2X、G.4X、G.8X、G.12X、G.16X、R.1X、R.2X、R.4X 或 R.8X。还必须设置 number\$1of\$1workers。worker\$1type 默认为 G.1X。 | | %connections | 列表 | 指定要在会话中使用的连接的逗号分隔列表。 示例： 
%connections my_rds_connection
                    dy_f = glue_context.create_dynamic_frame.from_catalog(database='rds_tables', table_name='sales_table')
| | %extra\$1py\$1files | 列表 | Simple Storage Service (Amazon S3) 中其他 Python 文件的逗号分隔列表。 | | %extra\$1jars | 列表 | 要包含在集群中的其他 Jar 的逗号分隔列表。 | | %spark\$1conf | 字符串 | 为您的会话指定自定义 Spark 配置。例如 %spark\$1conf spark.serializer=org.apache.spark.serializer.KryoSerializer。 | ### 适用于 Ray 作业的魔术命令 | 名称 | Type | 说明 | | --- | --- | --- | | %min\$1workers | Int | 分配给 Ray 作业的工作线程的最小数量。默认值：1。 示例：`%min_workers 2` | | %object\$1memory\$1head | Int | 热启动后实例头节点上可用内存的百分比。最小值：0。最大值：100。示例：`%object_memory_head 100` | | %object\$1memory\$1worker | Int | 热启动后实例 Worker 节点上可用内存的百分比。最小值：0。最大值：100。示例：`%object_memory_worker 100` | ### 操作魔术命令 | 名称 | Type | 说明 | | --- | --- | --- | | %%sql | 字符串 | 运行 SQL 代码。首次 `%%sql` 魔术命令之后的所有行将作为 SQL 代码的一部分传递。 示例：`%%sql select * from rds_tables.sales_table` | | %matplot | Matplotlib figure | 使用 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 figure | 使用 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
| ## 命名会话 Amazon Glue 交互式会话是 Amazon 资源并需要一个名称。每个会话的名称应是唯一的，并且可能会受到您的 IAM 管理员的限制。有关更多信息，请参阅 [使用 IAM 的交互式会话](glue-is-security.md)。Jupyter 内核会自动为您生成唯一的会话名称。但是，可以通过两种方式手动命名会话： 1. 使用位于 `~.aws/config` 的 Amazon Command Line Interface 配置文件。请参阅[使用 Amazon Command Line Interface 设置 Amazon 配置](https://docs.amazonaws.cn/config/latest/developerguide/gs-cli.html)。 1. 使用 `%session_id_prefix` 魔术命令。请参阅[Jupyter 的 Amazon Glue 交互式会话支持魔术命令](#interactive-sessions-supported-magics)。 会话名称的生成方式如下： + 提供前缀和 session\$1id 时：会话名称将为 \$1前缀\$1-\$1UUID\$1。 + 未提供任何内容时：会话名称将为 \$1UUID\$1。 为会话名称添加前缀后，您能够在将会话列入 Amazon CLI 或控制台中时识别它们。 ## 为交互式会话指定 IAM 角色 您必须指定 Amazon Identity and Access Management (IAM) 角色与使用交互式会话运行的 Amazon Glue ETL 代码一起使用。 该角色所需的IAM 权限与运行 Amazon Glue 任务所需的 IAM 权限相同。有关为 Amazon Glue 任务和交互式会话创建角色的更多信息，请参阅[为 Amazon Glue 创建 IAM 角色](https://docs.amazonaws.cn/glue/latest/dg/create-an-iam-role.html)。 可通过以下两种方式指定 IAM 角色： + 使用位于 `~.aws/config` 的 Amazon Command Line Interface 配置文件（推荐使用）。更多相关信息，请参阅[使用 \$1/.aws/config 配置会话](https://docs.amazonaws.cn/glue/latest/ug/interactive-sessions-magics.html#interactive-sessions-named-profiles)。 **注意** 使用 `%profile` 魔术命令时，将优先采用该配置文件的 `glue_iam_role` 配置。 + 使用 %iam\$1role 魔术命令。有关更多信息，请参阅 [Jupyter 的 Amazon Glue 交互式会话支持魔术命令](#interactive-sessions-supported-magics)。 ## 使用命名配置文件配置会话 Amazon Glue 交互式会话使用的凭证与 Amazon Command Line Interface 或 boto3 使用的凭证相同。交互式会话遵守并使用 `~/.aws/config`（Linux 和 MacOS）或 `%USERPROFILE%\.aws\config`（Windows）中的 Amazon CLI 类似的命名配置文件。有关更多信息，请参阅 [Using named profiles](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles)。 交互式会话允许在配置文件中指定 Amazon 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= ``` 如果您有生成凭证的自定义方法，还可以将配置文件配置为使用 `credential_process` 文件中的 `~/.aws/config` 参数。例如： ``` [profile developer] region=us-east-1 credential_process = "/Users/Dave/generate_my_credentials.sh" --username helen ``` 您可以找到有关通过 `credential_process` 参数获取凭证的更多详情，请参阅此处：[使用外部进程获取凭证](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-sourcing-external.html)。 如果在使用的配置文件中未设置区域或 `iam_role`，则必须在运行的第一个单元格中使用 `%region` 和 `%iam_role` 魔术命令进行指定。