建立目錄

建立目錄端點 (例如 Apache Iceberg REST 目錄端點或 Apache Hive 目錄端點) 會在 Lakehouse 執行階段目錄中建立管理端點。

這個端點指向基礎 Cloud Storage 值區，提供中繼資料層，讓查詢引擎和開放原始碼工作負載直接與資料表互動。

為 Lakehouse for Apache Iceberg 建立目錄端點時，您可以選擇使用使用者憑證或憑證販售模式，委派儲存空間存取權。

事前準備

1. 請參閱「關於 Lakehouse 執行階段目錄」，瞭解 Lakehouse 執行階段目錄的運作方式和服務限制。
登入 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 BigLake 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 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 BigLake 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

必要的角色

如要取得建立目錄和註冊表格所需的權限，請要求管理員授予您下列 IAM 角色：

• 建立目錄：
  • 專案的 BigLake 管理員 (roles/biglake.admin)
  • 專案的儲存空間管理員 (roles/storage.admin)
• 註冊資料表： 專案的 BigLake 管理員 (roles/biglake.admin) 。在多儲存空間目錄中註冊資料表時，需要具備特定資料表註冊權限 (biglake.tables.register)，這項權限包含在 BigLake 管理員角色中。
• 在憑證販售模式中，使用自動佈建的目錄服務帳戶： 目標 Cloud Storage bucket 的「Storage 物件使用者」 (roles/storage.objectUser)。建立目錄後，請明確將儲存空間 bucket 的「Storage 物件使用者」角色 (roles/storage.objectUser) 授予自動佈建的服務帳戶。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

注意： 自動佈建的目錄服務帳戶建立作業具有最終一致性。也就是說，服務帳戶需要一段時間才能在系統中傳播。如果您在建立服務帳戶後立即嘗試授予角色，要求可能會失敗。如要瞭解存取權變更平均需要多久才會生效，請參閱「存取權變更生效」一文。

建立目錄

建立目錄。

控制台

建立多 bucket 目錄 (建議做法) (bl://)

注意： Google Cloud 控制台不支援多 bucket (bl://) 目錄 (建議使用)。如要更新這類目錄，請使用 gcloud 或 REST API。

建立單一 bucket (gs://) 目錄

1. 在 Google Cloud 控制台中開啟「Lakehouse」Lakehouse頁面。

   前往 Lakehouse

2. 選取 「建立目錄」。「建立目錄」頁面隨即開啟。

3. 選取目錄設定：

   • 如要建立 Apache Iceberg REST 目錄，請選取「Iceberg REST 目錄」。

4. 設定目錄：

   • 如果選擇「Iceberg REST catalog」(Iceberg REST 目錄)，請選取目錄類型的「Cloud Storage bucket」(Cloud Storage bucket)，然後選取要與目錄搭配使用的 Cloud Storage bucket。
   • 如果選擇「Hive catalog」(Hive 目錄)，請輸入不重複的目錄名稱，然後選取相關聯的 Cloud Storage 路徑。

5. 在「驗證方法」中，選取「使用者憑證」或「憑證臨時配發模式」。

   如果選取「憑證販售模式」，自動佈建的 Lakehouse 執行階段目錄服務帳戶必須在所有相關聯的 Cloud Storage bucket 上，明確具備「Storage 物件使用者」角色 (roles/storage.objectUser)。根據預設，這項設定完全沒有存取權。如果沒有這個角色，供應的憑證範圍不足，無法執行儲存空間寫入作業。

6. 選取「建立」。

   目錄建立完成後，系統會開啟「目錄詳細資料」頁面。

7. 在「驗證方式」下方，選取「設定值區權限」。

8. 在對話方塊中選取「確認」。

   這會驗證目錄的服務帳戶是否在所有相關聯的儲存空間 bucket 中，都具備「Storage 物件使用者」角色 (roles/storage.objectUser)。如果您使用 gcloud 或 Terraform 建立目錄，則必須手動授予這項角色。

gcloud

建立多 bucket 目錄 (建議做法) (bl://)

gcloud biglake iceberg catalogs create CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="biglake" \
    --default-location="DEFAULT_LOCATION" \
    [--restricted-locations="RESTRICTED_LOCATIONS"] \
    [--credential-mode="CREDENTIAL_MODE"] \
    [--primary-location="PRIMARY_LOCATION"]

更改下列內容：

• CATALOG_ID：Lakehouse 執行階段目錄的 ID。
• PROJECT_ID：您的 Google Cloud 專案 ID。
• DEFAULT_LOCATION：目錄資料和中繼資料的 Cloud Storage 基本路徑，格式為 gs://my-bucket/path 或 gs://my-bucket。目錄中的所有命名空間和資料表都必須位於這個路徑下。舉例來說，如果您指定 gs://my-bucket/path，就無法在 gs://my-bucket/another/path 底下代管命名空間或資料表。
• RESTRICTED_LOCATIONS：(選用) 以半形逗號分隔的額外允許儲存空間值區或路徑清單。同樣地，如果您指定路徑 (例如 gs://my-bucket/path)，則該路徑 bucket 下建立的所有命名空間和資料表都必須位於該路徑內。安全警告：請避免設定與其他目錄重疊的路徑，以免憑證遭到未經授權的曝光。詳情請參閱「跨多個值區的儲存空間」。
• CREDENTIAL_MODE：驗證方式。使用 end-user 取得使用者憑證，或使用 vended-credentials 取得憑證臨時配發模式。
• PRIMARY_LOCATION：(選用) 目錄的主要區域 (例如 US 或 EU)，確保與 BigQuery 相容。

建立單一 bucket (gs://) 目錄

注意： 單一 bucket 目錄。強烈建議不要在新專案中使用單一 bucket 設定。這項設定會將目錄限制為單一 bucket，並將目錄名稱鎖定為 bucket 名稱。

如要建立單一 bucket (gs://) 目錄，請將 --catalog-type 設為 gcs-bucket：

gcloud biglake iceberg catalogs create CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="gcs-bucket" \
    [--credential-mode="CREDENTIAL_MODE"]

更改下列內容：

• CATALOG_ID：Lakehouse 執行階段目錄的 ID。如果是單一 bucket (gs://) 目錄，這必須與 Cloud Storage bucket 的名稱相符。
• PROJECT_ID：您的 Google Cloud 專案 ID。
• CREDENTIAL_MODE：驗證方式。使用 end-user 取得使用者憑證，或使用 vended-credentials 取得憑證臨時配發模式。

REST

建立 Iceberg REST 目錄

如要使用 REST API 建立目錄管理端點，請向 CreateIcebergCatalog 端點發出 POST 要求：

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?icebergCatalogId=CATALOG_ID

要求內文必須包含 IcebergCatalog JSON 酬載，定義目錄設定，例如基礎 Cloud Storage 儲存空間和驗證模式。

更改下列內容：

• PROJECT_ID：您的 Google Cloud 專案 ID。
• CATALOG_ID：Lakehouse 執行階段目錄的 ID。