本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 在 EMR Studio 中使用 magic 命令增强内核 ## 概述 EMR Studio 和 EMR Notebooks 支持命令。magic *Magic*命令或 *magics* 是 IPython 内核提供的增强功能，可帮助您运行和分析数据。 IPython是一个使用 Python 构建的交互式外壳环境。 Amazon EMR 还支持一个程序包Sparkmagic，该程序包为与 Spark 相关的内核（PySpark、SparkR 和 Scala 内核）提供magic特定命令，并在集群上使用 Livy 提交 Spark 任务。 只要您的 EMR Notebooks 中有 Python 内核，就可以使用 magic 命令。同样，任何与 Spark 相关的内核都支持 Sparkmagic 命令。 Magic 命令也称作 *magics*，共有两类： + **行 magics`%`：此类 ** 命令用单个 magic 前缀表示，并在单行代码上运行 + **单元格 magics**：此类 magic 命令用双 `%%` 前缀表示，并在多行代码上运行 有关所有可用的 magics，请参阅 [列出 magic 和 Sparkmagic 命令](#accessing-all-magic-commands)。 ## 注意事项和限制 + EMR Serverless 不支持使用 `%%sh` 来运行 `spark-submit`，也不支持 EMR Notebooks magics。 + Amazon EMR on EKS 集群不支持将 Sparkmagic 命令用于 EMR Studio。这是因为拥有托管式端点的 Spark 内核属于 Kubernetes 内置的内核，不支持 Sparkmagic 和 Livy。您可以将 Spark 配置直接设置到 SparkContext 对象中作为解决方法，如以下示例所示。 ``` spark.conf.set("spark.driver.maxResultSize", '6g') ``` + 禁止以下magic命令和操作 AWS： + `%alias` + `%alias_magic` + `%automagic` + `%macro` + 使用 `%configure` 修改 `proxy_user` + 使用 `%env` 或 `%set_env` 修改 `KERNEL_USERNAME` ## 列出 magic 和 Sparkmagic 命令 使用以下命令列出可用的 magic 命令： + `%lsmagic` 会列出当前可用的所有 magic 函数。 + `%%help` 会列出 Sparkmagic 软件包提供的当前可用 Spark 相关 magic 函数。 ## 使用 `%%configure` 来配置 Spark Sparkmagic 最有用的命令之一是 `%%configure` 命令，该命令可配置会话创建参数。借助 `conf` 设置，您可以配置 [Apache Spark 配置文档](https://spark.apache.org/docs/latest/configuration.html) 中提及的任何 Spark 配置。 **Example 将外部 JAR 文件从 Maven 存储库或 Amazon S3 添加到 EMR Notebooks** 您可以使用以下方法将外部 JAR 文件依赖项添加到 Sparkmagic 支持的任何 Spark 相关内核中。 ``` %%configure -f {"conf": { "spark.jars.packages": "com.jsuereth:scala-arm_2.11:2.0,ml.combust.bundle:bundle-ml_2.11:0.13.0,com.databricks:dbutils-api_2.11:0.0.3", "spark.jars": "s3://amzn-s3-demo-bucket/my-jar.jar" } } ``` **Example : 配置 Hudi** 您可以使用 Notebook 编辑器来配置 EMR Notebook 以使用 Hudi。 ``` %%configure { "conf": { "spark.jars": "hdfs://apps/hudi/lib/hudi-spark-bundle.jar,hdfs:///apps/hudi/lib/spark-spark-avro.jar", "spark.serializer": "org.apache.spark.serializer.KryoSerializer", "spark.sql.hive.convertMetastoreParquet":"false" } } ``` ## 使用 `%%sh` 运行 `spark-submit` 在附加的集群实例上，`%%sh` magic 会通过子进程来运行 Shell 命令。通常，您需要使用其中一个 Spark 相关的内核在附加的集群上运行 Spark 应用程序。但如果要使用 Python 内核提交 Spark 应用程序，可以使用以下 magic，并将存储桶名称替换为小写的储桶名称。 ``` %%sh spark-submit --master yarn --deploy-mode cluster s3://amzn-s3-demo-bucket/test.py ``` 在此示例中，集群需要访问 `s3://amzn-s3-demo-bucket/test.py` 的位置，否则该命令将失败。 您可以将 `%%sh` magic 与任何 Linux 命令结合使用。如果您要运行任何 Spark 或 YARN 命令，请使用以下选项之一创建 `emr-notebook` Hadoop 用户，并授予用户运行这些命令的权限。 + 您可以通过运行以下命令显式创建新用户。 ``` hadoop fs -mkdir /user/emr-notebook hadoop fs -chown emr-notebook /user/emr-notebook ``` + 您可以在 Livy 中启用用户模拟功能，从而自动创建用户。请参阅[启用用户模拟以监控 Spark 用户和任务活动](emr-managed-notebooks-spark-monitor.md)了解更多信息。 ## 使用 `%%display` 可视化显示 Spark 数据框 您可以使用 `%%display` magic 来可视化显示 Spark 数据框。要使用此 magic，请运行以下命令。 ``` %%display df ``` 选择以表格格式查看结果，如下图所示。 ![\[使用 %%display magic 的输出，以表格格式显示结果。\]](http://docs.aws.amazon.com/zh_cn/emr/latest/ManagementGuide/images/magic-display-table.png) 您也可以选择使用五种类型的图表来可视化数据。您的选项包括饼图、散点图、折线图、面积图和条形图。 ![\[使用 %%display magic 的输出，以图表格式显示结果。\]](http://docs.aws.amazon.com/zh_cn/emr/latest/ManagementGuide/images/magic-display-chart.png) ## 使用 EMR Notebooks magics Amazon EMR 提供了以下 EMR Notebooks magics，您可以将这些命令用于 Python3 和基于 Spark 的内核： + `%mount_workspace_dir`：将 Workspace 目录挂载到集群，以便您可以从 Workspace 中的其他文件导入和运行代码 **注意** 使用 `%mount_workspace_dir` 时，只有 Python 3 内核可以访问本地文件系统。Spark 执行器将无法使用此内核访问挂载的目录。 + `%umount_workspace_dir` - 从集群中卸载 Workspace 目录 + `%generate_s3_download_url` - 在 Notebook 输出中为 Amazon S3 对象生成临时下载链接 ### 先决条件 您需要完成以下任务后才能安装 EMR Notebooks magics： + 确保您的 [集群 EC2 实例（EC2 实例配置文件）的服务角色](emr-iam-role-for-ec2.md) 拥有 Amazon S3 的读取访问权限。使用 `AmazonElasticMapReduceforEC2Role` 托管策略的 `EMR_EC2_DefaultRole` 满足此要求。如果您使用自定义角色或策略，请确保它拥有必要的 S3 权限。 **注意** EMR Notebooks magics 以 Notebook 实例用户身份在集群上运行，并使用 EC2 实例配置文件与 Amazon S3 进行交互。在 EMR 集群上挂载 Workspace 目录时，拥有附加到该集群权限的所有 Workspace 和 EMR Notebooks 都可以访问已挂载的目录。 预设情况下，目录将以只读方式挂载。虽然 `s3fs-fuse` 和 `goofys` 允许读-写挂载，但我们强烈建议您不要将挂载参数修改为以读-写模式挂载目录。如果您允许写入权限，则对目录所做的任何更改都将写入 S3 存储桶。为避免意外删除或覆盖，您可以为 S3 存储桶启用版本控制。要了解更多信息，请参阅[在 S3 存储桶中使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 + 在集群上运行以下脚本中的一种，从而安装 EMR Notebooks magics 的依赖项。要运行脚本，您可以 [使用自定义引导操作](emr-plan-bootstrap.md#bootstrapCustom)，或当您已经有正在运行的集群时，按照[在 Amazon EMR 集群上运行命令和脚本](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-commandrunner.html)中的说明进行操作。 您可以选择要安装哪个依赖项。[s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse) 和 [goofys](https://github.com/kahing/goofys) 都是 FUSE（用户空间中的文件系统）工具，这些工具允许您将 Amazon S3 存储桶作为本地文件系统挂载到集群上。`s3fs` 工具可提供类似于 POSIX 的体验。当您更喜欢性能而不是符合 POSIX 标准的文件系统时，`goofys` 工具是不错的选择。 Amazon EMR 7.x 系列使用 Amazon Linux 2023，该版本不支持 EPEL 存储库。如果你运行的是亚马逊 EMR 7.x，请按照 [s3fs-fuse GitHub](https://github.com/s3fs-fuse/s3fs-fuse/blob/master/COMPILATION.md) 的说明进行安装。`s3fs-fuse`如果使用 5.x 或 6.x 系列，请使用以下命令安装 `s3fs-fuse`。 ``` #!/bin/sh # Install the s3fs dependency for EMR Notebooks magics sudo amazon-linux-extras install epel -y sudo yum install s3fs-fuse -y ``` **或者** ``` #!/bin/sh # Install the goofys dependency for EMR Notebooks magics sudo wget https://github.com/kahing/goofys/releases/latest/download/goofys -P /usr/bin/ sudo chmod ugo+x /usr/bin/goofys ``` ### 安装 EMR Notebooks magics **注意** 在 Amazon EMR 发行版 6.0 到 6.9.0 和 5.0 到 5.36.0 中，只有 `emr-notebooks-magics` 程序包版本 0.2.0 及更高版本支持 `%mount_workspace_dir` magic。 完成以下步骤以安装 EMR Notebooks magics。 1. 在您的 Notebook 中，运行下面的命令以安装 [https://pypi.org/project/emr-notebooks-magics/](https://pypi.org/project/emr-notebooks-magics/) 程序包。 ``` %pip install boto3 --upgrade %pip install botocore --upgrade %pip install emr-notebooks-magics --upgrade ``` 1. 重启内核以加载 EMR Notebooks magics。 1. 使用下面的命令验证安装，该命令应该显示用于 `%mount_workspace_dir` 的输出帮助文本。 ``` %mount_workspace_dir? ``` ### 使用 `%mount_workspace_dir` 挂载 Workspace 目录 您可以借助 `%mount_workspace_dir` magic 将 Workspace 目录挂载到 EMR 集群上，以便您能导入和运行存储在目录中的其他文件、模块或程序包。 下面的示例将整个 Workspace 目录挂载到集群上，并指定可选的 *`<--fuse-type>`* 参数，以使用 goofys 挂载目录。 ``` %mount_workspace_dir . <--fuse-type goofys> ``` 要验证您的 Workspace 目录是否已挂载，请使用下面的示例，借助 `ls` 命令来显示当前的工作目录。输出结果应该显示 Workspace 中的所有文件。 ``` %%sh ls ``` 在 Workspace 中完成更改后，可以使用下面的命令卸载 Workspace 目录： **注意** 即使 Workspace 已停止或已分离，您的 Workspace 目录仍会保持挂载到集群上。您必须显式卸载 Workspace 目录。 ``` %umount_workspace_dir ``` ### 使用 `%generate_s3_download_url` 下载 Amazon S3 对象 `generate_s3_download_url` 命令可为存储在 Amazon S3 中的对象创建预签名 URL。您可以使用该预签名 URL 将对象下载到本地计算机。例如，您可以运行 `generate_s3_download_url` 下载代码写入 Amazon S3 的 SQL 查询的结果。 预设情况下，预签名 URL 的有效期为 60 分钟。您可以通过指定 `--expires-in` 标志的秒数来更改过期时间。例如，`--expires-in 1800` 创建一个有效期为 30 分钟的 URL。 下面的示例通过指定完整的 Amazon S3 路径来为对象生成下载链接：`s3://EXAMPLE-DOC-BUCKET/path/to/my/object`。 ``` %generate_s3_download_url s3://EXAMPLE-DOC-BUCKET/path/to/my/object ``` 要了解有关使用 `generate_s3_download_url` 的更多信息，请运行下面的命令以显示帮助文本。 ``` %generate_s3_download_url? ``` ### 使用 `%execute_notebook` 在无头模式下运行 Notebook 您可以使用 `%execute_notebook` magic 在无头模式下运行另一个 Notebook 实例，并查看运行的每个单元格的输出。此 magic 命令需要拥有 Amazon EMR 和 Amazon EC2 共享的实例角色的额外权限。有关如何授予额外权限的更多信息，请运行命令 `%execute_notebook?`。 如果有长时间运行的任务，系统可能会因为不活动而进入睡眠状态，也可能暂时失去互联网连接。这可能会中断浏览器与 Jupyter 服务器之间的连接。如果出现这种情况，您可能会丢失自己运行的单元格和 Jupyter 服务器发送的单元格的输出内容。 如果使用 `%execute_notebook` magic 在无头模式下运行 Notebook 实例，即使本地网络出现中断，EMR Notebooks 也会捕获已运行单元格的输出。EMR Notebooks 将输出以增量方式保存在与您运行的 Notebook 同名的新 Notebook 中。然后，EMR Notebooks 将 Notebook 放入 Workspace 内的新文件夹。无头运行发生在同一个集群上并使用 `EMR_Notebook_DefaultRole` 服务角色，但其他参数可能会更改默认值。 要在无头模式下运行 Notebook，请使用以下命令： ``` %execute_notebook ``` 要为无头运行指定集群 ID 和服务角色，请使用以下命令： ``` %execute_notebook .ipynb --cluster-id --service-role ``` 当 Amazon EMR 和 Amazon EC2 共享一个实例角色时，该角色需要以下额外权限： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "elasticmapreduce:StartNotebookExecution", "elasticmapreduce:DescribeNotebookExecution", "ec2:DescribeInstances" ], "Resource": [ "*" ], "Sid": "AllowELASTICMAPREDUCEStartnotebookexecution" }, { "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": [ "arn:aws:iam::123456789012:role/EMR_Notebooks_DefaultRole" ], "Sid": "AllowIAMPassrole" } ] } ``` ------ **注意** 要使用 `%execute_notebook` magic，请安装 `emr-notebooks-magics` 程序包版本 0.2.3 或更高版本。