创建笔记本

注意：BigQuery Studio 笔记本将于 2024 年 4 月 11 日之后在正式版中开始收费。您将开始在账单中看到 BigQuery Studio 笔记本基于用量的费用。

本文档介绍了如何创建 BigQuery 中的 Colab Enterprise 笔记本。笔记本是由 Dataform 提供支持的 BigQuery Studio 代码资源。

须知事项

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the BigQuery API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the BigQuery API.

   Enable the API

启用 BigQuery Studio

按照启用 BigQuery Studio 进行资产管理中的说明以保存、共享和管理代码资产（例如笔记本）版本。

重要提示：2024 年 3 月，系统将自动为所有 BigQuery 项目启用支持 BigQuery Studio 功能的 API。如需了解详情，请参阅自动启用 BigQuery Studio API。

所需权限

设置适当的权限以创建、修改或查看笔记本。

具有 Dataform Admin (roles/dataform.admin) 角色的所有用户都可以访问在项目中创建的所有笔记本。

如需详细了解 BigQuery Identity and Access Management (IAM)，请参阅使用 IAM 进行访问权限控制。

创建笔记本的权限

如需创建和运行笔记本，您需要以下 IAM 权限：

• resourcemanager.projects.get
• resourcemanager.projects.list
• bigquery.config.get
• bigquery.jobs.create
• bigquery.readsessions.create
• bigquery.readsessions.getData
• bigquery.readsessions.update
• resourcemanager.projects.get
• resourcemanager.projects.list
• dataform.locations.get
• dataform.locations.list

• dataform.repositories.create

  注意：拥有 dataform.repositories.create 权限的用户可以使用默认的 Dataform 服务账号和授予该服务账号的所有权限来执行代码。如需了解详情，请参阅 Dataform 权限的安全注意事项。

• dataform.repositories.list

• dataform.collections.create

• dataform.collections.list

• aiplatform.notebookRuntimeTemplates.apply

• aiplatform.notebookRuntimeTemplates.get

• aiplatform.notebookRuntimeTemplates.list

• aiplatform.notebookRuntimeTemplates.getIamPolicy

• aiplatform.notebookRuntimes.assign

• aiplatform.notebookRuntimes.get

• aiplatform.notebookRuntimes.list

• aiplatform.operations.list

您可以从以下 IAM 角色获取这些权限：

• BigQuery Read Session User (roles/bigquery.readSessionUser)

• BigQuery Studio User (roles/bigquery.studioUser)

  BigQuery Studio User 角色包含以下 IAM 角色：

  • BigQuery Job User (roles/bigquery.jobUser)
  • Notebook Runtime User (roles/aiplatform.notebookRuntimeUser)

  • Code Creator (roles/dataform.codeCreator)

    注意：在项目中分配了 Code Creator 角色的用户可以使用 Dataform API 或 Dataform 命令行界面 (CLI) 列出该项目中代码资源的名称。使用 BigQuery Studio 的非管理员只能看到他们创建或与他们共享的代码资产。

修改笔记本的权限

如需编辑和运行笔记本，您需要以下 IAM 角色：

• BigQuery Job User (roles/bigquery.jobUser)
• BigQuery Read Session User (roles/bigquery.readSessionUser)
• Notebook Runtime User (roles/aiplatform.notebookRuntimeUser)
• Code Editor (roles/dataform.codeEditor)

查看笔记本的权限

如需查看和运行笔记本，您需要以下 IAM 角色：

• BigQuery Job User (roles/bigquery.jobUser)
• BigQuery Read Session User (roles/bigquery.readSessionUser)
• Notebook Runtime User (roles/aiplatform.notebookRuntimeUser)
• Code Viewer (roles/dataform.codeViewer)

创建笔记本

请参阅以下部分，了解如何创建笔记本。

设置代码资源的默认区域

如果这是您第一次创建代码资源，请设置代码资源的默认区域。代码资源创建后，便无法更改该区域。

注意：如果您创建了一个已保存查询，并选择了与用于代码资源的区域不同的默认区域，例如在已使用 us-central1 的情况下选择了 us-west1，则默认情况下，该查询和您后续创建的所有代码资源都将使用该新区域。现有代码资源将继续使用在创建时为其分配的区域。

从 BigQuery 编辑器创建笔记本

如需创建包含给定表的默认查询的笔记本，请按照以下步骤操作：

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在编辑器窗格的标签页栏中，点击 + 号旁边的 下拉箭头，然后点击编写新的 Python 笔记本。

   系统会打开新的笔记本，其中包含显示针对 bigquery-public-data.ml_datasets.penguins 公共数据集的查询示例的单元格。

从表创建笔记本

如需创建包含特定表的默认查询的笔记本，请按照以下步骤操作：

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目并找到要查询的表。

3. 点击表旁边的查看操作，然后点击查询位置 > Python 笔记本。

   系统会打开新的笔记本，其中包含显示针对所选表的查询示例的单元格。

创建笔记本以探索查询结果集

如需创建笔记本以探索查询结果集，请按照以下步骤操作：

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在编辑器窗格中，运行一个生成查询结果的查询。

3. 在查询结果窗格中，点击探索数据，然后点击使用 Python 笔记本探索。

   系统会打开新笔记本，其中的单元格含有用于返回查询 SQL 和查询结果的代码。

通过现有笔记本创建笔记本

如需将现有笔记本的任何版本作为新笔记本打开，请按照以下步骤操作：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和笔记本文件夹，然后根据需要展开共享笔记本文件夹。选择笔记本。

3. 选择活动窗格。

4. 点击笔记本版本旁边的 查看操作，然后点击作为新 Python 笔记本打开。

   笔记本的副本将作为新笔记本打开。

上传笔记本

您可以上传本地笔记本，以便在 BigQuery Studio 中使用。上传的笔记本随后会显示在 Google Cloud 控制台的 BigQuery 页面中。

如需上传笔记本，请按照以下步骤操作：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目，然后执行以下操作之一：

   • 在笔记本旁边，点击 查看操作 > 上传到笔记本。
   • 在 Google Cloud 项目名称旁边，点击 查看操作 > 上传到项目 > Python 笔记本。

3. 在上传笔记本对话框的笔记本字段中，点击浏览，然后选择您要上传的笔记本。

4. 可选：在笔记本名称字段中，修改笔记本的名称。

5. 在区域字段中，选择要在其中上传笔记本的区域。

6. 点击上传。

您的笔记本会显示在探索器窗格中。

连接到运行时

请参阅以下部分，了解如何将笔记本连接到 Vertex AI 运行时。运行时是运行笔记本中代码的计算资源。

连接到默认运行时

默认运行时是一个需要最低设置的预设运行时。

如需连接到默认运行时，请按照以下步骤操作：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和笔记本文件夹，然后根据需要展开共享笔记本文件夹。点击笔记本的名称将其打开。

3. 在笔记本中，点击连接，或运行笔记本中的任何单元。

   如果尚无活跃运行时，则可能需要几分钟时间才能连接到默认运行时。

连接到非默认运行时

如果要使用默认运行时以外的运行时，则必须在 Vertex AI 中创建该额外运行时。

如需连接到非默认运行时，请按照以下步骤操作：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和笔记本文件夹，然后根据需要展开共享笔记本文件夹。点击笔记本的名称将其打开。

3. 在笔记本中，点击连接旁边的 下拉列表，然后点击连接到运行时。

4. 点击连接到现有运行时。

5. 在运行时中，选择要使用的运行时。

6. 点击连接。

连接到新的运行时

如需连接到新的运行时，请按照以下步骤操作：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和笔记本文件夹，然后根据需要展开共享笔记本文件夹。点击笔记本的名称将其打开。

3. 在笔记本中，点击连接旁边的 下拉列表，然后点击连接到运行时。

4. 点击新建运行时。

5. 在运行时模板中，选择要使用的 Vertex AI 运行时模板。

6. 在运行时名称中，输入运行时的名称。

7. 点击连接。

授予对笔记本的访问权限

若要向其他用户授予对笔记本的访问权限，请将这些用户添加到相应的 IAM 角色。

重要提示：有权访问笔记本的用户可以查看由笔记本中的代码生成的所有输出，即使此输出包含他们无权访问的表中的数据也是如此。如需禁止共享保存的输出，请停用笔记本输出保存。

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和笔记本文件夹，然后根据需要展开共享笔记本文件夹。找到您要授予其访问权限的笔记本。

3. 点击笔记本旁边的 查看操作，然后点击共享 > 管理权限。

4. 在管理权限窗格中，点击添加用户/群组。

5. 在新的主账号字段中，输入主账号。

6. 在角色列表中，选择以下角色之一：

   • Code Owner：可以对笔记本执行任何操作，包括删除或共享笔记本。
   • Code Editor：可以修改笔记本。
   • Code Viewer：可以查看笔记本。
   注意：主账号还必须拥有 Notebook Runtime User (roles/aiplatform.notebookRuntimeUser) 和 BigQuery User (roles/bigquery.user) 角色才能运行笔记本。

7. 可选：如需查看角色和高级共享设置的完整列表，请点击高级共享。

8. 点击保存。

9. 如需返回笔记本信息页面，请点击关闭。

共享笔记本

如需与其他用户共享笔记本，您可以生成并共享该笔记本的链接。如需让其他用户查看您共享的笔记本，您必须先授予对笔记本的访问权限。

如需运行笔记本，用户必须有权访问笔记本所访问的数据。如需了解详情，请参阅授予对数据集的访问权限。

重要提示：有权访问笔记本的用户可以查看由笔记本中的代码生成的所有输出，即使此输出包含他们无权访问的表中的数据也是如此。如需禁止共享保存的输出，请停用笔记本输出保存。

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和笔记本文件夹，然后根据需要展开共享笔记本文件夹。找到您要共享的笔记本。

3. 点击笔记本旁边的 查看操作，然后点击共享 > 复制链接。

4. 与其他用户共享该链接。

停用笔记本输出保存

您可以通过停用笔记本输出保存来阻止与有权访问笔记本文件的其他用户共享保存的笔记本输出。

为所选笔记本停用输出保存功能后，BigQuery 会删除笔记本文件中保存的所有输出，且不会保存后续运行的输出。

但是，具有笔记本访问权限的用户仍可以通过以下方式查看其输出：

• 运行笔记本以查看其当前输出。此输出不保存。
• 在修订历史记录中查看笔记本的归档版本及其输出。

如需为所选笔记本停用输出保存功能，请按以下步骤操作：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和笔记本文件夹，然后选择要对其停用保存输出功能的笔记本。

3. 点击 显示/隐藏标题 > 修改 > 笔记本设置。

4. 在笔记本设置窗口中，选择保存此笔记本时忽略代码单元格输出项。

5. 点击保存。

6. 点击重新加载。

解决冲突

如果您和其他用户在笔记本中进行了有冲突的更改，该服务会引发错误 Automatic saving failed. This file was updated remotely or in another tab.，并提供 Show diff 链接。要解决此冲突，请按以下步骤操作：

1. 点击 Show diff 链接。此时会打开查看远程更改对话框。
2. 可选：如需比较笔记本源代码，请选中原始源代码复选框。
3. 可选：如需以内嵌方式（而不是在单独的窗格中）比较版本，请选中内嵌差异复选框。
4. 查看这些更改并决定保留哪个更改，如有必要，则修改您的输入。
5. 点击保存更改。

重命名笔记本

要重命名笔记本，请按以下步骤操作：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和笔记本文件夹，然后根据需要展开共享笔记本文件夹。找到您要重命名的笔记本。

3. 点击笔记本旁边的 查看操作，然后点击重命名。

4. 输入笔记本的名称，然后点击重命名。

问题排查

如需了解详情，请参阅排查 Colab Enterprise 问题。

后续步骤

• 了解如何管理笔记本。