安排 SQL 脚本和笔记本

通过安排 SQL 脚本和笔记本，您可以将在数据探索工作台（探索）中创建的资源付诸使用。

安排 SQL 脚本或笔记本会创建一个在预定时间运行一次或定期运行的 Dataplex 任务。每次运行时，系统会创建一个作业来捕获执行元数据，例如执行开始时间和结束时间、执行状态、日志和生成的输出。

当已安排的 SQL 脚本或笔记本触发运行作业时，系统会执行该笔记本或 SQL 脚本的当前版本。这意味着，如果您安排了一个笔记本或 SQL 脚本，并在稍后更新其内容，则更新也会反映在笔记本或 SQL 脚本的计划运行作业中。

费用

预定的 SQL 脚本和预定的笔记本会使用 Dataproc Serverless 触发作业执行。用量根据 Dataproc 价格模式收费，费用显示在 Dataproc（而非 Dataplex）下。

准备工作

请查看并完成以下文档中所述的前提条件：

• 使用数据探索工作台的准备工作部分

• 安排自定义 Spark 和 SparkSQL 任务的准备工作部分

  注意 ：与安排自定义 Spark 和 SparkSQL 任务中所述的任务服务帐号相关的说明适用于 SQL 脚本和笔记本，并且适用于用于安排 SQL 脚本和笔记本的服务帐号。
  
  安排自定义 Spark 和 SparkSQL 任务中所述的启用专用 Google 访问通道的说明与用于安排 SQL 脚本和笔记本的网络相关。使用 Google Cloud Console 安排 SQL 脚本或笔记本时，您只能使用默认子网。如需了解详情，请参阅已知限制。

如果 SQL 脚本或笔记本时间表使用 BigQuery API，您必须向服务帐号授予 Service Usage Consumer 角色 (roles/serviceusage.serviceUsageConsumer)。

已知限制

• 使用 Google Cloud 控制台安排笔记本时，在所选环境中配置的其他 Python 软件包将在运行时不适用于已安排的笔记本。如需在运行时使用它们，您必须创建笔记本时间表，引用包含所需额外软件包的容器映像。如需了解详情，请参阅使用自定义软件包调度笔记本。

• 安排笔记本时，不支持使用 Google Cloud 控制台引用自定义容器映像。请改用 gcloud CLI。

• 时间表一旦创建，便无法修改。如需更新时间表参数，您必须使用新参数重新创建时间表。

• 您无法定义要在时间表中使用的 SQL 脚本或笔记本的特定版本。触发时间表后，系统将使用 SQL 脚本或笔记本的当前版本。

• 使用 Google Cloud 控制台安排 SQL 脚本和笔记本时，系统会使用默认子网。如需指定其他网络或子网，请使用 gcloud CLI。

此外，请查看“探索”的已知限制。

创建和管理 SQL 脚本的时间表

已安排的 SQL 脚本的运行时配置

安排好 SQL 脚本后，该脚本将作为 Dataplex 任务运行。使用 Google Cloud 控制台创建时间表时，系统会根据以下映射从该 SQL 脚本的环境继承已安排的 SQL 脚本的相应任务运行时参数：

环境配置参数	计划 SQL 脚本任务配置参数
主磁盘大小	容器映像 / 属性：    spark.dataproc.driver.disk.size    spark.dataproc.executor.disk.size
节点数量	批处理 / 执行器计数
节点数上限	批处理 / 最大执行器数量
映像版本	未继承
JAR 文件	容器映像 / Java JARS
Python 软件包	未继承
更多属性	容器映像 / 属性

安排 SQL 脚本

控制台

1. 在 Google Cloud 控制台中，转到 Dataplex 探索页面。

   转到 Dataplex 探索

2. 选择您要安排的 SQL 脚本，方法是从 Spark SQL 脚本列表中选择单个 SQL 脚本，或者在 Spark SQL 编辑器中打开 SQL 脚本。

3. 在时间表菜单中，点击创建时间表。

4. 在时间表名称字段中，输入计划实例的名称。

5. 在时间表选项部分中，选择是只运行一次 SQL 脚本
   还是定期运行该脚本：

   1. 如果选择运行一次，请使用开始菜单中的选项指定是立即运行 SQL 脚本还是在预定的时间运行 SQL 脚本。对于预定的运行作业，请指定开始日期和运行时间。

   2. 如果选择重复，请指定您希望每天、每周、每月还是按照使用 Cron 表达式指定的自定义时间表运行 SQL 脚本。此外，请指定首次安排的运行的开始日期和运行时间。

6. 在结果的目标部分中，执行以下操作：

   1. 在输出文件夹名称字段中，点击浏览，然后选择要在 Cloud Storage 存储桶中存储脚本输出的文件夹。

   2. 点击选择。

   3. 选择脚本输出格式。支持的格式包括 CSV、JSON、ORC 和 Parquet。

7. 在计划脚本凭据部分，从用户服务账号菜单中选择一个服务帐号。

8. 点击计划。

gcloud

如需了解如何使用 gcloud CLI 安排 SQL 脚本，请参阅安排 SparkSQL 任务。

注意 ：在安排 SparkSQL 任务部分中，--spark-sql-script-file 参数的说明指出，此参数的值可以是 Cloud Storage 的 URI。不支持此操作。 您只能为 --spark-sql-script-file 参数指定 SQL 脚本内容的路径。

REST

使用 API Explorer 创建任务。

注意 ：在 REST 参考文档中，SparkTaskConfig 资源的说明指出，sqlScriptFile 字段的值可以是 Cloud Storage 的 URI。不支持此操作。您只能为 sqlScriptFile 字段指定 SQL 脚本内容的路径。

管理 SQL 脚本时间表

控制台

打开包含所有 SQL 脚本时间表的列表

1. 在 Google Cloud 控制台中，转到 Dataplex 流程页面。

2. 点击计划查询标签页以查看 SQL 脚本时间表列表。

打开包含特定 SQL 脚本的所有时间表的列表

1. 在 Google Cloud 控制台中，转到 Dataplex 探索页面。

2. 选择所需的 SQL 脚本。

3. 在时间表菜单中，点击查看时间表。

   计划查询标签页随即会打开，其中包含按所选 SQL 脚本过滤的 SQL 脚本时间表列表。

查看 SQL 脚本时间表的详细信息

1. 转到计划查询标签页，然后选择所需的 SQL 脚本时间表。

2. 点击详细信息标签页，以查看 SQL 脚本时间表的详细信息和预定的 SQL 脚本内容预览。

激活和停用 SQL 脚本时间表

1. 转到计划查询标签页，然后选择所需的 SQL 脚本时间表。

2. 点击停用以停用有效的 SQL 脚本时间表。

3. 点击启用以激活处于非活动状态的 SQL 脚本时间表。

删除现有 SQL 脚本时间表

1. 转到计划查询标签页，然后选择所需的 SQL 脚本时间表。

2. 点击删除，永久删除现有的 SQL 脚本时间表。

查看日志和管理 SQL 脚本时间表

1. 转到计划查询标签页，然后选择所需的 SQL 脚本时间表。

2. 点击作业标签页，然后点击要查看的已安排 SQL 脚本运行的作业 ID。

3. 点击查看日志，查看与 Cloud Logging 中运行的选定预定 SQL 脚本相关的日志。

4. 点击 Dataproc 批次 ID，打开 Google Cloud 控制台中的 Dataproc 页面。 访问相应 Dataproc 无服务器会话的详细信息。

5. 点击输出标签旁边的在 Cloud Storage 中管理，打开 Google Cloud 控制台中的 Cloud Storage 页面。访问包含 SQL 脚本执行输出的相应 Cloud Storage 存储桶的详细信息。

gcloud

如需了解如何使用 gcloud CLI 监控预定的 SQL 脚本，请参阅监控您的任务中的 gcloud 标签页。

如需了解如何使用 gcloud CLI 管理计划 SQL 脚本，请参阅管理时间表中的 gcloud 标签页。

REST

如需了解如何使用 REST 监控预定 SQL 脚本，请参阅监控任务中的 REST 标签页。

如需了解如何使用 REST 管理计划 SQL 脚本，请参阅管理时间表中的 REST 标签页。

预定 SQL 脚本的输出

每次执行计划 SQL 脚本时，输出结果存储在您为 Cloud Storage 文件夹指定的位置，具体采用以下结构：

CLOUD_STORAGE_FOLDER_LOCATION/projects/PROJECT_ID/locations/LOCATION_ID/lakes/LAKE_ID/tasks/TASK_ID/JOB_ID/QUERY_NUMBER

为笔记本创建和管理时间表

已安排的笔记本的运行时配置

笔记本被调度后，它会作为 Dataplex 任务运行。使用 Google Cloud 控制台创建时间表时，系统会根据以下映射从该笔记本的环境继承计划笔记本的相应任务运行时参数：

环境配置参数	计划笔记本任务配置参数
主磁盘大小	容器映像 / 属性：    spark.dataproc.driver.disk.size    spark.dataproc.executor.disk.size
节点数量	批处理 / 执行器计数
节点数上限	批处理 / 最大执行器数量
映像版本	未继承
JAR 文件	容器映像 / Java JARS
Python 软件包	未继承
更多属性	容器映像 / 属性

注意 ：安排笔记本时，相应的 Dataplex 任务参数将根据原始环境配置固定。更改原始笔记本环境的参数不会影响相应 Dataplex 任务的配置。

使用自定义软件包调度笔记本

对于交互式笔记本，在配置环境时，Dataplex 允许您指定要在为环境预配的用户会话中安装的自定义 Python 软件包。安排此类笔记本后，在其环境中配置的自定义 Python 软件包在运行时将不适用于排定的笔记本，并且默认运行时环境仅包含 Dataproc Serverless Spark 运行时版本 1.0 的组件。如需在运行时为已安排的笔记本提供自定义 Python 软件包，请提供包含必要的自定义软件包的自定义容器映像。

不支持在使用 Google Cloud 控制台安排笔记本时指定自定义容器映像。请改用 gcloud CLI。如需了解详情，请参阅安排笔记本。

如果您安排笔记本的环境配置了自定义软件包，则会收到以下警告：

Selected environment  has additional Python packages configured.
These packages will not be available in the default runtime for the scheduled notebook
when scheduling in the Console. To make the required additional Python packages
available in the runtime, please create Notebook Schedule using gcloud command
instead, referencing a container image with required additional packages.

为已安排的笔记本构建自定义容器映像

如需了解如何为已安排的笔记本建立容器映像，并在容器映像 dockerfile 中安装所需的自定义 Python 软件包，请参阅为 Dataproc Serverless for Spark 构建自定义容器映像。

确保您已在容器映像中安装了以下 conda 软件包：

• gcsfs
• google-cloud-bigquery
• google-cloud-storage
• google-auth
• ipykernel
• papermill

注意 ：除 google-auth、ipykernel 和 papermill 以外的软件包位于为 Dataproc Serverless for Spark 构建自定义容器映像中所述的示例 dockerfile 中。

如需在容器映像中安装 gcloud 组件，请打开容器映像 dockerfile 并完成以下步骤：

1. 将 google-cloud-sdk 软件包添加到要安装的 conda 软件包列表中。

2. 在 conda 软件包安装步骤之后添加以下几行代码：

   # (Optional) Installing gcloud components
   RUN gcloud components install alpha beta bq gsutil
   

安排笔记本

控制台

1. 在 Google Cloud 控制台中，转到 Dataplex 探索页面。

   转到 Dataplex 探索

2. 选择要安排的笔记本，方法是在笔记本视图中选择一个笔记本，或在笔记本详细信息页面中打开笔记本。

3. 在时间表菜单中，点击创建时间表。

4. 在时间表名称字段中，输入计划实例的名称。

5. 在时间表选项部分中，选择是只运行一次笔记本还是定期运行该笔记本：

   1. 如果选择运行一次，请使用开始菜单中的选项指定是立即运行笔记本还是在计划的时间运行笔记本。对于预定的运行作业，请指定开始日期和运行时间。

   2. 如果选择重复，请指定您希望每天、每周、每月还是按照使用 Cron 表达式指定的自定义时间表运行笔记本。此外，请指定首次安排的运行作业的开始日期和运行时间。

6. 在结果的目标位置部分，选择要存储笔记本输出的位置：

   1. 在输出文件夹名称字段中，点击浏览，然后在 Cloud Storage 存储桶中选择要存储笔记本输出的文件夹。

   2. 点击选择。

   3. 选择脚本输出格式。支持的格式包括 CSV、JSON、ORC 和 Parquet。

7. 在计划的笔记本凭据部分，从用户服务帐号菜单中选择一个服务帐号。

8. 在参数部分中，点击新增，将笔记本的执行参数添加为键值对。

9. 点击计划。

gcloud

使用以下额外参数运行安排 Spark（Java 或 Python）任务中所述的 gcloud CLI 命令：

参数	说明
--notebook	输入笔记本的笔记本内容的路径。执行参数可作为环境变量访问。例如 TASK_key=value。 注意:在介绍如何将笔记本调度为任务的 gcloud 参考文档中，提到 --notebook 参数的值可以是笔记本文件的 Cloud Storage URI。不支持此操作。您只能为 --notebook 参数指定笔记本内容的路径。
--notebook-archive-uris	要提取到每个执行程序工作目录中的归档的 Cloud Storage URI。支持的文件类型包括 JAR、tar、tar.gz、tgz 和 zip。
--notebook-file-uris	要放置在每个执行器的工作目录中的文件的 Google Cloud Storage URI。
使用 Dataproc Serverless 时任务所需的计算资源
--notebook-batch-executors-count	作业执行程序的数量。
--notebook-batch-max-executors-count	可配置执行器数量上限。 如果 notebook-batch-max-executors-count 大于 notebook-batch-executors-count，则启用自动扩缩。
容器映像运行时配置
--notebook-container-image	可选：作业的自定义容器映像。
--notebook-container-image-java-jars	要添加到类路径的 Java JAR 的列表。有效输入包含 JAR 二进制文件的 Cloud Storage URI。例如 gs://BUCKET_NAME/my/path/to/file.jar。
--notebook-container-image-properties	要在守护程序配置文件中设置的属性。 属性键以 prefix:property 格式指定。例如 : core:hadoop.tmp.dir。 如需了解详情，请参阅集群属性。
用于运行基础架构的 Cloud VPC 网络
--notebook-vpc-network-tags	要应用于作业的网络标记的列表。
Cloud VPC 网络标识符。您最多可以指定下列其中一项。
--notebook-vpc-network-name	运行作业的 Cloud VPC 网络。默认使用项目中名为 Default 的 Cloud VPC 网络。
--notebook-vpc-sub-network-name	运行作业的 Cloud VPC 子网。
笔记本输出的位置
--execution-args	对于笔记本任务，以下参数是强制性参数，需要作为 TASK_ARGS 传递。
	--execution-args=^::^TASK_ARGS="--output_location,CLOUD_STORAGE_URI_OF_OUTPUT_DIRECTORY"

以下是用于安排笔记本的 gcloud 命令的示例：

gcloud dataplex tasks create sample-task --project=sample-project --location=us-central1 --lake=my-lake --trigger-type=ON_DEMAND --notebook="projects/my-project-id/locations/us-central1/lakes/my-lake/content/my-notebook.ipynb" --execution-service-account=[e-mail]  --execution-args=^::^TASK_ARGS="--output_location,gs://my-bucket/Demo" --notebook-batch-executors-count=2 --notebook-batch-max-executors-count=5 --notebook-container-image=container-image --notebook-container-image-java-jars=java-jar1,java-jar-2

REST

使用 API Explorer 创建任务。

注意 ：在 REST 参考文档中，NotebookTaskConfig 资源的说明指出，notebook 字段的值可以是 Cloud Storage 的 URI。不支持此操作。您只能为 notebook 参数指定笔记本内容的路径。

管理笔记本时间表

控制台

打开包含所有笔记本时间表的列表

1. 在 Google Cloud 控制台中，转到 Dataplex 流程页面。

2. 点击计划笔记本标签页以查看 SQL 脚本时间表列表。

打开特定笔记本的所有时间表的列表

1. 在 Google Cloud 控制台中，转到 Dataplex 探索页面。

2. 选择所需的笔记本。

3. 在时间表菜单中，点击查看时间表。

   计划查询标签页随即会打开，其中列出了按所选笔记本过滤的笔记本时间表。

查看笔记本时间表的详细信息

1. 转到已安排的笔记本标签页，然后选择所需的笔记本时间表。

2. 点击笔记本时间表的详细信息详细信息和已安排的笔记本内容的预览。

启用和停用笔记本时间表

1. 前往已安排的笔记本标签页，然后选择所需的笔记本时间表。

2. 点击停用以停用有效的笔记本时间表。

3. 点击启用，激活处于非活跃状态的笔记本时间表。

删除现有笔记本时间表

1. 前往已安排的笔记本标签页，然后选择所需的笔记本时间表。

2. 点击删除，永久删除现有笔记本时间表。

查看日志和管理笔记本时间表

1. 前往已安排的笔记本标签页，然后选择所需的笔记本时间表。

2. 点击作业标签页，然后点击要查看的已安排笔记本运行的作业 ID。

3. 在预览输出部分中，查看笔记本运行的输出。

4. 点击查看日志，查看与 Cloud Logging 中选定的已排定笔记本运行的日志相关的日志。

5. 点击 Dataproc 批次 ID，打开 Google Cloud 控制台中的 Dataproc 页面。 访问相应 Dataproc 无服务器会话的详细信息。

6. 点击输出标签旁边的在 Cloud Storage 中管理，打开 Google Cloud 控制台中的 Cloud Storage 页面。访问包含笔记本执行输出的相应 Cloud Storage 存储桶的详细信息。

gcloud

如需了解如何使用 gcloud CLI 监控已安排的笔记本，请参阅监控您的任务中的 gcloud 标签页。

如需了解如何使用 gcloud CLI 管理已安排的笔记本，请参阅管理时间表中的 gcloud 标签页。

REST

如需了解如何使用 REST 监控已安排的笔记本，请参阅监控任务中的 REST 标签页。

如需了解如何使用 REST 管理已安排的笔记本，请参阅管理时间表中的 REST 标签页。

已安排的笔记本的输出

计划笔记本每次运行的输出都会存储在您为 Cloud Storage 文件夹指定的位置，具体结构如下：

CLOUD_STORAGE_FOLDER_LOCATION/projects/PROJECT_ID/locations/LOCATION_ID/lakes/LAKE_ID/tasks/TASK_ID/JOB_ID/QUERY_NUMBER

后续步骤

• 安排自定义 Spark 和 SparkSQL 任务。
• 为 Dataplex 任务设置提醒和通知。