安排 SQL 脚本和笔记本

注意： Dataplex 探索功能 已弃用， 2025 年 7 月 1 日及之后提供支持。我们建议您将素材资源 使用 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 脚本任务配置参数
主磁盘大小	容器映像 / 属性： 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 脚本内容的路径。

<ph type="x-smartling-placeholder">

</ph>

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 控制台中。访问相应 Cloud Storage 的详细信息 此存储桶包含 SQL 脚本执行输出。

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

。

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

如需在容器映像中安装 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 参数的值可以是 笔记本文件。系统不支持此操作。您只能指定笔记本的路径 --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 二进制文件。例如 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 任务设置提醒和通知。