建立筆記本

本文說明如何在 BigQuery 中建立 Colab Enterprise 筆記本。筆記本是 BigQuery Studio 程式碼資產，由 Dataform 提供支援。

事前準備

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.

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 (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 API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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 (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 API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

所需權限

設定適當權限，即可建立、編輯或查看記事本。

所有具備Dataform 管理員 (roles/dataform.admin) 角色的使用者，都能以擁有者身分存取專案中建立的所有筆記本。

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

建立筆記本的權限

如要取得建立及執行筆記本所需的權限，請要求管理員授予下列 IAM 角色：

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

• BigQuery Studio 使用者 (roles/bigquery.studioUser) 「BigQuery Studio 使用者」角色結合了下列 IAM 角色：

  • BigQuery Job User (roles/bigquery.jobUser)
  • 筆記本執行階段使用者 (roles/aiplatform.notebookRuntimeUser)

  • 程式碼建立工具 (roles/dataform.codeCreator)

    注意： 在專案中獲派程式碼建立者角色的使用者，可以使用 Dataform API 或 Dataform 指令列介面 (CLI)，列出該專案中的程式碼資產名稱。使用 BigQuery Studio 的非管理員只能查看自己建立或與自己共用的程式碼資產。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。如要查看建立及執行筆記本所需的確切權限，請展開「必要權限」部分：

所需權限

• 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 Job User (roles/bigquery.jobUser)
• BigQuery Read Session User (roles/bigquery.readSessionUser)
• 筆記本執行階段使用者 (roles/aiplatform.notebookRuntimeUser)
• 程式碼編輯器 (roles/dataform.codeEditor)

可查看筆記本的角色

如要查看及執行筆記本，您需要下列 IAM 角色：

• BigQuery Job User (roles/bigquery.jobUser)
• BigQuery Read Session User (roles/bigquery.readSessionUser)
• 筆記本執行階段使用者 (roles/aiplatform.notebookRuntimeUser)
• 程式碼檢視器 (roles/dataform.codeViewer)

建立筆記本

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

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

如果您是第一次建立程式碼資產，請設定程式碼資產的預設區域。程式碼資產建立後，就無法變更區域。

注意： 如果您建立筆記本，並選擇與程式碼資產所用預設區域不同的區域 (例如選擇 us-west1，但您一直使用 us-central1)，則該筆記本和您之後建立的所有程式碼資產，預設都會使用這個新區域。現有程式碼資產會繼續使用建立時指派的區域。

BigQuery Studio 中的所有程式碼資產都使用相同的預設區域。如要設定程式碼資產的預設區域，請按照下列步驟操作：

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在「Explorer」窗格中，找出已啟用程式碼資產的專案。

3. 按一下專案旁的 「View actions」(查看動作)，然後點選「Change my default code region」(變更預設程式碼區域)。

4. 在「區域」中，選取要用於程式碼資產的區域。

5. 按一下「選取」。

如需支援的區域清單，請參閱「BigQuery Studio 位置」。

使用筆記本庫建立筆記本

預先發布版

這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

注意： 如要提供意見回饋或要求產品改善，請傳送電子郵件至 [e-mail]。

BigQuery 的 Google Cloud 控制台筆記本庫是集中式中樞，可供您探索及使用預先建構的筆記本範本。

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

1. 前往「BigQuery」頁面

   前往「BigQuery」

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

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

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

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

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

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

   

   「詳細資料」、「版本記錄」和「註解」工具列功能位於「預覽」中。如要提供意見回饋或尋求這些功能的支援，請傳送電子郵件至 [e-mail]。

7. 選用：在工具列中，您可以使用「參考」面板預覽資料表、快照、檢視區塊或具體化檢視區塊的結構定義詳細資料，或是在新分頁中開啟這些項目。面板也會列出最近和已加星號的資源。

從表格建立筆記本

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

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在左側窗格中，按一下「Explorer」：

   

   如果沒有看到左側窗格，請按一下「展開左側窗格」圖示 開啟窗格。

3. 在「Explorer」窗格中展開專案，按一下「Datasets」，然後按一下資料集。

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

5. 依序點選資料表旁的 「動作」和「在 Python 筆記本中開啟」>。

   系統會開啟新筆記本，其中包含的儲存格會顯示針對所選表格的範例查詢。

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

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

1. 前往「BigQuery」頁面

   前往「BigQuery」

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

3. 在「Query results」(查詢結果) 窗格中，依序點選「Open in」(開啟方式) >「Notebook」(筆記本)。

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

從現有筆記本建立筆記本

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

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

   前往「BigQuery」

2. 在左側窗格中，按一下「Explorer」：

   

3. 在「Explorer」窗格中展開專案，然後按一下「Notebooks」。

4. 選取筆記本。

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

6. 依序點選筆記本版本旁的 「查看動作」和「開啟為新的 Python 筆記本」。

   筆記本副本會以新筆記本的形式開啟。

上傳筆記本

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

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

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

   前往「BigQuery」

2. 在左側窗格中，按一下「Explorer」：

   

3. 在「Explorer」窗格中展開專案，然後執行下列其中一個步驟：

   • 按一下「筆記本」旁的 依序點選「查看動作」>「上傳至筆記本」。
   • 在 Google Cloud 專案名稱旁，依序點選 「查看動作」>「上傳至專案」>「筆記本」。

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

5. 選用：在「筆記本名稱」欄位中編輯筆記本名稱。

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

7. 按一下「上傳」。

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

連線至執行階段

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

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

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

連線至預設執行階段

預設執行階段是預先設定的執行階段，只需要最少的設定。

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

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

   前往「BigQuery」

2. 在左側窗格中，按一下「Explorer」：

   

3. 在「Explorer」窗格中展開專案，然後按一下「Notebooks」。

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

5. 在筆記本中，按一下「連線」，或執行筆記本中的任何儲存格。

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

連線至非預設執行階段

如要使用預設執行階段以外的執行階段，請先在 Vertex AI 中建立該額外執行階段。

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

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

   前往「BigQuery」

2. 在左側窗格中，按一下「Explorer」：

   

3. 在「Explorer」窗格中展開專案，然後按一下「Notebooks」。

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

5. 在筆記本中，按一下「連線」旁的下拉式選單 ，然後按一下「連線到執行階段」。

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

7. 在「執行階段」中，選取要使用的執行階段。執行階段必須與筆記本位於相同位置。

8. 按一下「連線」。

連線至新的執行階段

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

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

   前往「BigQuery」

2. 在左側窗格中，按一下「Explorer」：

   

3. 在「Explorer」窗格中展開專案，然後按一下「Notebooks」。

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

5. 在筆記本中，按一下「連線」旁的下拉式選單 ，然後按一下「連線到執行階段」。

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

7. 在「執行階段範本」中，選取要使用的 Vertex AI 執行階段範本。

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

9. 按一下「連線」。

瞭解儲存格

筆記本是由可編輯的儲存格組成。系統支援下列類型的儲存格：

• 文字儲存格：使用文字儲存格，以 Markdown 格式在筆記本中加入說明和圖片。
• 程式碼儲存格：使用程式碼儲存格將 Python 新增至筆記本。您可以個別執行每個程式碼儲存格。程式碼儲存格可以參照您已執行的其他儲存格中建立的任何變數。

• SQL 儲存格 (預覽版)：使用 SQL 儲存格執行 GoogleSQL 查詢。查詢的輸出內容會自動儲存為 DataFrame，名稱與儲存格標題相同。您可以在單一 SQL 儲存格中執行多個 SQL 陳述式，但只有最後一個陳述式的結果會儲存至 DataFrame。

  您可以在運算式中參照 Python 變數，或將 BigQuery DataFrames 做為查詢中的資料表，方法是將變數名稱放在大括號 ({ }) 中：

  # Refer to the Python variable my_threshold in a SQL expression.
  SELECT * FROM my_dataset.my_table WHERE x > {my_threshold};
  
  # Reference previous query results to iterate on your queries.
  SELECT * FROM {df};
  

授予筆記本存取權

如要授權其他使用者存取筆記本，請將這些使用者加入適當的 IAM 角色。

重要事項： 只要使用者具備筆記本存取權，即可查看筆記本中程式碼產生的所有輸出內容，即便內含使用者無權存取的資料表內容也一樣。如要禁止共用已儲存的輸出內容，請停用筆記本輸出內容儲存功能。

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

   前往「BigQuery」

2. 在左側窗格中，按一下「Explorer」：

   

   如果沒有看到左側窗格，請按一下「展開左側窗格」圖示 開啟窗格。

3. 在「Explorer」窗格中展開專案，然後按一下「Notebooks」。

4. 找出要授予存取權的記事本。

5. 按一下筆記本旁的「開啟動作」，然後按一下「共用」。

6. 在「分享權限」窗格中，按一下「新增使用者/群組」。

7. 在「New principals」(新增主體) 欄位中輸入主體。

8. 在「角色」清單中，選取下列其中一個角色：

   • 程式碼擁有者：可以對筆記本執行任何動作，包括刪除或共用筆記本。
   • 程式碼編輯器：可編輯筆記本。
   • 程式碼檢視者：可以查看筆記本。
   注意： 主體也必須具備筆記本執行階段使用者 (roles/aiplatform.notebookRuntimeUser) 和 BigQuery 使用者 (roles/bigquery.user)角色，才能執行筆記本。

9. 選用：如要查看完整的角色清單和進階共用設定，請按一下「進階共用設定」。

10. 按一下 [儲存]。

11. 如要返回筆記本資訊頁面，請按一下「關閉」。

共用筆記本

如要與其他使用者共用筆記本，可以產生並分享筆記本連結。如要讓其他使用者查看您共用的筆記本，請先授予筆記本存取權。

如要執行 Notebook，使用者必須能存取 Notebook 所存取的資料。詳情請參閱「授予資料集存取權」。

重要事項： 只要使用者具備筆記本存取權，即可查看筆記本中程式碼產生的所有輸出內容，即便內含使用者無權存取的資料表內容也一樣。如要禁止共用已儲存的輸出內容，請停用筆記本輸出內容儲存功能。

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

   前往「BigQuery」

2. 在左側窗格中，按一下「Explorer」：

   

   如果沒有看到左側窗格，請按一下「展開左側窗格」圖示 開啟窗格。

3. 在「Explorer」窗格中展開專案，然後按一下「Notebooks」。

4. 找出要共用的記事本。你可以使用搜尋功能或篩選器尋找筆記本。

5. 按一下筆記本旁邊的「查看動作」，然後依序點選「分享」>「複製連結」。

6. 將連結分享給其他使用者。

停用筆記本輸出內容儲存功能

如要禁止與其他有權存取筆記本檔案的使用者共用已儲存的筆記本輸出內容，請停用筆記本輸出內容儲存功能。

停用所選筆記本的輸出內容儲存功能後，BigQuery 會刪除筆記本檔案中儲存的所有輸出內容，且不會儲存後續執行的輸出內容。

不過，有權存取筆記本的使用者仍可透過下列方式查看輸出內容：

• 執行筆記本，即可查看目前的輸出內容。系統不會儲存這項輸出內容。
• 在修訂版本記錄中查看筆記本的封存版本和輸出內容。

如要停用所選筆記本的輸出內容儲存功能，請按照下列步驟操作：

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

   前往「BigQuery」

2. 在左側窗格中，按一下「Explorer」：

   

   如果沒有看到左側窗格，請按一下「展開左側窗格」圖示 開啟窗格。

3. 在「Explorer」窗格中展開專案，然後按一下「Notebooks」。

4. 按一下要停用儲存輸出的筆記本。

5. 如要展開選單列，請按一下「keyboard_arrow_down」keyboard_arrow_down「切換標題顯示設定」。

6. 依序點選「編輯」>「記事本設定」。

7. 在「筆記本設定」視窗中，選取「儲存這個筆記本時，忽略程式碼儲存格輸出內容」。

8. 按一下 [儲存]。

9. 按一下「重新載入」。

解決衝突

如果您和其他使用者在筆記本中進行衝突的變更，服務會引發 Automatic saving failed. This file was updated remotely or in another tab. 錯誤，並提供 Show diff 連結。如要解決衝突，請按照下列步驟操作：

1. 按一下 Show diff 連結。系統會開啟「查看遠端變更」對話方塊。
2. 選用：如要比較筆記本原始碼，請勾選「原始碼」核取方塊。
3. 選用步驟：如要直接比較版本，而非在個別窗格中比較，請勾選「Inline diff」核取方塊。
4. 查看變更並決定要保留哪些變更，必要時請修正輸入內容。
5. 按一下「儲存變更」。

重新命名筆記本

如要重新命名筆記本，請按照下列步驟操作：

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

   前往「BigQuery」

2. 在左側窗格中，按一下「Explorer」：

   

3. 在「Explorer」窗格中展開專案，然後按一下「Notebooks」。

4. 按一下要重新命名的記事本。

5. 按一下 keyboard_arrow_down「切換標題顯示設定」 即可展開選單列。

6. 依序點選「檔案」>「重新命名」。

7. 在「Rename notebook」(重新命名筆記本) 對話方塊中輸入筆記本名稱，然後按一下「Rename」(重新命名)。

疑難排解

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

後續步驟

• 瞭解如何管理記事本。
• 瞭解如何排定筆記本執行時間。