安排 SQL 脚本和笔记本

注意：Dataplex Explore 已弃用。对 Explore 的支持将于 2025 年 6 月 30 日结束。我们建议您将资产迁移到 BigQuery Studio，以便在 Google Cloud 的所有分析工具中获得简化的数据探索体验。请参阅从“探索”迁移到 BigQuery Studio。

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

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

为已安排的 SQL 脚本或笔记本触发运行时，系统会执行笔记本或 SQL 脚本的当前版本。这意味着，如果您安排运行笔记本或 SQL 脚本，之后又更新了其内容，那么更新也会反映在笔记本或 SQL 脚本的定期运行中。

费用

计划 SQL 脚本和计划笔记本会使用 Dataproc Serverless 触发作业执行。 系统会根据 Dataproc 价格模式收取使用费，费用会显示在 Dataproc 下，而不是 Dataplex 下。

准备工作

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

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

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

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

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

已知限制

• 使用 Google Cloud 控制台安排笔记本时，其他 Python 软件包 在所选环境中配置的功能在运行时不可用 已安排的笔记本如需在运行时使用这些软件包，您必须创建一个笔记本时间表，并引用包含所需其他软件包的容器映像。如需了解详情，请参阅使用自定义软件包安排笔记本运行时间。

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

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

• 您无法定义要在时间表中使用的 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 脚本还是在安排的时间运行。对于预定的运行 指定开始日期和运行时间。

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

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. 点击查看日志，查看与所选预定 SQL 相关的日志 脚本在 Cloud Logging 中运行。

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

5. 点击输出标签旁边的在 Cloud Storage 中管理，以打开“Cloud Storage”页面 Google Cloud 控制台中。访问包含 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

注意：为 Dataproc Serverless for Spark 构建自定义容器映像中介绍的示例 Dockerfile 中包含 google-auth、ipykernel 和 papermill 以外的软件包。

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

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

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

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

安排笔记本

控制台

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

   转到 Dataplex 的“探索”页面

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

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

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

5. 在时间表选项部分，选择您希望仅运行一次还是周期性运行该笔记本：

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

   2. 如果您选择重复，请指定您希望笔记本每天、每周、每月运行，还是按使用 cron 表达式指定的自定义时间表运行。此外，请指定初始计划运行的开始日期和运行时间。

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

   1. 在 Output folder name（输出文件夹名称）字段中，点击 Browse（浏览），然后在 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 Executor。支持的文件类型包括 JAR、tar、tar.gz、tgz 和 zip。
--notebook-file-uris	要放入各个执行程序的工作目录中的文件的 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 网络。默认情况下，名为 使用项目中的默认值。
--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 中管理，以打开“Cloud Storage”页面 Google Cloud 控制台中。访问包含笔记本执行输出的相应 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 任务设置提醒和通知。