建立筆記本

本文說明如何在 BigQuery 中建立 Colab Enterprise 筆記本。Notebooks 是 BigQuery Studio 程式碼資產，採用 Dataform 技術。

事前準備

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, Dataform, and Compute Engine APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, Dataform, and Compute Engine APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

所需權限

設定適當權限，以便建立、編輯或查看筆記本。

凡是具備 Dataform 管理員角色 (roles/dataform.admin) 的使用者，都擁有專案中所有筆記本的擁有者存取權。

如要進一步瞭解 BigQuery Identity and Access Management (IAM)，請參閱「使用 IAM 控管存取權」。

建立 Notebook 的權限

如要取得建立及執行筆記本所需的權限，請要求管理員授予您專案的 BigQuery Studio 使用者 (roles/bigquery.studioUser) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

注意： 在專案中獲派程式碼建立者角色的使用者，可以使用 Dataform API 或 Dataform 指令列介面 (CLI)，列出該專案中的程式碼資產名稱。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。如要查看建立及執行 Notebook 的確切必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

• 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.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

注意： 建立筆記本時，BigQuery 會授予您該筆記本的 Dataform 管理員角色 (roles/dataform.admin)。凡是具備 Google Cloud 專案 Dataform 管理員角色的使用者，都擁有該專案中所有 Notebook 的擁有者權限。如要覆寫這項行為，請參閱「在建立資源時授予特定角色」。

編輯 Notebook 的角色

如要編輯及執行 Notebook，您必須具備下列 IAM 角色：

• BigQuery 工作使用者 (roles/bigquery.jobUser)
• BigQuery 讀取工作階段使用者 (roles/bigquery.readSessionUser)
• Notebook 執行階段使用者 (roles/aiplatform.notebookRuntimeUser)
• 程式碼編輯器 (roles/dataform.codeEditor)

查看 Notebook 的角色

如要查看及執行筆記本，您必須具備下列 IAM 角色：

• BigQuery 工作使用者 (roles/bigquery.jobUser)
• BigQuery 讀取工作階段使用者 (roles/bigquery.readSessionUser)
• Notebook 執行階段使用者 (roles/aiplatform.notebookRuntimeUser)
• 程式碼檢視者 (roles/dataform.codeViewer)

Notebook 的安全性考量

BigQuery 中的程式碼資產是由 Dataform 提供，因此請考量下列安全性影響，再授予使用者這些資產的存取權：

• 程式碼資產的瀏覽權限由專案層級的 Dataform 權限控管。使用者只要具備 dataform.repositories.list 權限 (包含在標準 BigQuery 角色中，例如 BigQuery 工作使用者、BigQuery Studio 使用者和 BigQuery 使用者)，就能在 Google Cloud 專案的「Explorer」面板中查看所有程式碼資產，無論這些資產是否由他們建立或與他們共用。如要限制瀏覽權限，可以建立不含 dataform.repositories.list 權限的自訂角色。
• 凡是與 Dataform 服務代理共用的 Secret，可編輯這些資產的使用者都有可能存取。為確保憑證安全，請限制只有信任的使用者才能建立及編輯權限，並限制 Dataform 服務代理可存取的密鑰。詳情請參閱「在套件安裝期間存取 Secret」。

詳情請參閱「Dataform 權限的安全性考量」。

建立筆記本

請參閱下列各節，瞭解如何建立筆記本。

設定程式碼資產的預設區域

Google Cloud 專案中的所有新程式碼資產都會使用預設區域。資產建立後，就無法變更區域。

重要事項： 如果在建立程式碼資產時變更區域，該區域會成為後續所有程式碼資產的預設區域。現有程式碼資產不受影響。

如要設定新程式碼資產的預設區域，請按照下列步驟操作：

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在左側窗格中，按一下「 Files」(檔案)，開啟檔案瀏覽器：

   

3. 按一下專案名稱旁的 「View files panel actions」(查看檔案面板動作) >「Switch code region」(切換程式碼區域)。

4. 選取要設為預設值的程式碼區域。

5. 按一下 [儲存]。

如要查看支援的地區清單，請參閱「BigQuery Studio 位置」。

使用筆記本庫建立筆記本

BigQuery Google Cloud 控制台中的筆記本庫是探索及使用預先建構筆記本範本的中心。

如要使用筆記本庫中的範本建立筆記本，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery Studio」。

   前往 BigQuery Studio

2. 如要開啟筆記本庫，請在編輯器窗格的分頁列中，按一下「SQL 查詢」 旁的 箭頭，然後依序點選「筆記本」>「所有範本」。

3. 在筆記本庫中選取範本。例如，您可以選取「開始使用 BigQuery DataFrames」。

   新的筆記本隨即開啟，其中包含的儲存格會顯示針對 bigquery-public-data.ml_datasets.penguins 公開資料集的範例查詢。

4. 或者，您也可以點選「SQL 查詢」 旁邊的 箭頭，然後依序點選 「Notebook」>「空白筆記本」、 「Notebook」>「BigQuery 範本」或 「Notebook」>「Spark 範本」，開啟這些特定範本。

5. 如要從範本建立可執行的筆記本，請按一下「Use this template」(使用這個範本)。

6. 選用：如要查看筆記本詳細資料或版本記錄、新增註解、回覆或取得現有註解的連結，請使用下列工具列：

   

   「Comments」(註解) 工具列功能目前為預先發布版。如要提供意見或尋求支援，請傳送電子郵件至 [e-mail]。

7. 選用：在「Comments」(註解) 工具列中，您可以使用「Reference」(參考資料) 面板預覽資料表、快照、檢視表或 materialized view 的結構定義詳細資料，或在新分頁中開啟。面板也會列出最近和已加星號的資源。

從資料表建立筆記本

如要建立含有特定資料表預設查詢的筆記本，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 點選左側窗格中的 「Explorer」。

   

   如果沒有看到左側窗格，請按一下 「Expand left pane」(展開左側窗格)，開啟窗格。

3. 在「Explorer」窗格中展開專案，依序點選「Datasets」(資料集) 和資料集。

4. 依序點選「總覽」 > 「資料表」，然後找出要查詢的資料表。

5. 依序點選資料表旁的 「Actions」(動作) 和「Open in」(開啟方式) >「Python notebook」(Python 筆記本)。

   新的筆記本隨即開啟，其中包含顯示所選資料表範例查詢的儲存格。

建立筆記本，探索查詢結果集

如要建立筆記本來探索查詢結果集，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在編輯器窗格中執行查詢，產生查詢結果。

3. 在「查詢結果」窗格中，依序點選「開啟方式」>「Notebook」。

   新的筆記本會開啟，其中包含程式碼儲存格，可傳回查詢 SQL 和查詢結果。

根據現有筆記本建立筆記本

如要將現有筆記本的任何版本開啟為新筆記本，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 點選左側窗格中的 「Explorer」。

   

3. 在「Explorer」窗格中展開專案，然後點選「Notebooks」。

4. 選取筆記本。

5. 按一下 「版本記錄」。

6. 按一下筆記本版本旁的 「View actions」(查看動作)，然後點選「Open as new Python notebook」(開啟為新的 Python 筆記本)。

   系統會開啟筆記本副本，做為新的筆記本。

上傳筆記本

您可以上傳本機筆記本，在 BigQuery Studio 中使用。上傳的筆記本會顯示在 Google Cloud 控制台的 BigQuery 頁面中。

如要上傳筆記本，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 點選左側窗格中的 「Explorer」。

   

3. 在「Explorer」窗格中展開專案，然後執行下列任一操作：

   • 按一下「筆記本」旁的 「查看動作」>「上傳筆記本」。
   • 按一下 Google Cloud 專案名稱旁的「查看動作」「上傳至專案」「Notebook」。

4. 在「Upload Notebook」(上傳筆記本) 對話方塊的「Notebook」(筆記本) 欄位中，按一下「Browse」(瀏覽)，然後選取要上傳的筆記本。

5. 選用：在「Notebook name」(筆記本名稱) 欄位中，編輯筆記本名稱。

6. 在「Region」(區域) 欄位，選取要上傳筆記本的區域。

7. 按一下「上傳」。

您可以透過「Explorer」窗格存取筆記本。

連線到執行階段

請參閱下列各節，瞭解如何將筆記本連結至 Gemini Enterprise Agent Platform 執行階段。執行階段是運算資源，用於執行筆記本中的程式碼。執行階段必須與筆記本位於相同區域。

如要進一步瞭解執行階段，請參閱「執行階段和執行階段範本」。

注意： 如果您使用 VPC Service Controls，請務必先設定 Private Google Access 搭配 VPC Service Controls，再連線至執行階段。否則，服務會傳回錯誤 Failed to connect to Runtime Network projects/projectid/global/networks/default' was not found.

連線至預設執行階段

預設執行階段是預設的執行階段，只需進行最基本的設定。

如要連線至預設執行階段，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 點選左側窗格中的 「Explorer」。

   

3. 在「Explorer」窗格中展開專案，然後點選「Notebooks」。

4. 按一下筆記本名稱即可開啟。

5. 在筆記本中，點選「Connect」，或執行筆記本中的任何儲存格。

   如果沒有啟用的執行階段，可能需要幾分鐘才能連線至預設執行階段。

連線至非預設執行階段

如要使用預設以外的執行階段，請先在 Agent Platform 建立該執行階段。

如要連線至非預設執行階段，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 點選左側窗格中的 「Explorer」。

   

3. 在「Explorer」窗格中展開專案，然後點選「Notebooks」。

4. 按一下筆記本名稱即可開啟。

5. 在筆記本中，按一下「Connect」(連線) 旁邊的 下拉式選單，然後點選「Connect to a runtime」(連線至執行階段)。

6. 按一下「連線至現有的執行階段」。

7. 在「Runtimes」(執行階段) 中，選取要使用的執行階段。執行階段必須與 Notebook 位於相同位置。

8. 點選「連線」。

連線至新的執行階段

如要連線至新的執行階段，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 點選左側窗格中的 「Explorer」。

   

3. 在「Explorer」窗格中展開專案，然後點選「Notebooks」。

4. 按一下筆記本名稱即可開啟。

5. 在筆記本中，按一下「Connect」(連線) 旁邊的 下拉式選單，然後點選「Connect to a runtime」(連線至執行階段)。

6. 按一下「建立新的執行階段」。

7. 在「Runtime Template」(執行階段範本) 中，選取要使用的 Agent Platform 執行階段範本。

8. 在「Runtime name」(執行階段名稱) 中，輸入執行階段的名稱。

9. 點選「連線」。

疑難排解

詳情請參閱「排解 Colab Enterprise 問題」。

後續步驟

• 瞭解如何管理筆記本。
• 瞭解如何排定筆記本執行作業。
• 瞭解如何存取 BigQuery Studio Git 存放區掛接中的筆記本檔案。