建立目錄

您可以使用 Lakehouse 執行階段目錄，在無邊界 Lakehouse 中建立目錄端點。

目錄端點會指向基礎 Cloud Storage bucket，並提供中繼資料層，讓查詢引擎和開放原始碼工作負載直接與資料表互動。建立目錄端點時，您可以選擇使用者憑證或憑證臨時配發模式，委派儲存空間存取權。

事前準備

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, if it is 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 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, if it is 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 API

必要的角色

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

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

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

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

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

建立目錄

請按照下列步驟，根據偏好的憑證模式和 bucket 類型建立目錄。如要進一步瞭解不同的目錄類型，請參閱「關於 Apache Iceberg REST 目錄端點」。

注意： 在 Google Cloud 建立或管理多值區目錄時，請為預設和受限儲存位置指定 Cloud Storage 路徑 (gs://)。bl://projects/PROJECT_ID/catalogs/CATALOG_ID URI 格式僅用於用戶端設定，以便在從查詢引擎 (例如 Spark 或 Trino) 連線時識別目錄倉儲。

控制台

建立多 bucket 目錄 (建議做法)

這項設定可讓目錄與多個 bucket 建立關聯，並讓您獨立命名目錄，不受任何 bucket 名稱影響。

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

   前往 Lakehouse

2. 按一下「建立目錄」。

3. 在「Catalog type」(目錄類型) 部分，選取「Iceberg Rest Catalog」(Iceberg REST 目錄)。

4. 在「Lakehouse catalog bucket options」(Lakehouse 目錄 bucket 選項)，選取「Multiple bucket catalog」(多個 bucket 目錄)。

5. 在「Default Catalog Cloud Storage path」(預設目錄 Cloud Storage 路徑)，輸入或瀏覽要與目錄搭配使用的 Cloud Storage 路徑。

6. 在「Catalog ID」(目錄 ID) 中，輸入目錄的自訂名稱。

7. 在「主要位置」部分選取位置。位置必須靠近主要 bucket 的區域。

8. 按一下「繼續」。

9. 在「資料路徑」步驟中，視需要新增其他 Cloud Storage 路徑。

10. 按一下「繼續」。

11. 在「驗證方式」部分，選取「使用者憑證」或「憑證臨時配發模式」。

12. 點選「建立」。

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

13. 如果選取「Credential vending mode」(憑證臨時配發模式)，請執行下列額外步驟：

    1. 在「驗證方式」下方，點選「設定 bucket 權限」。
    2. 在對話方塊中，點選「確認」。

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

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

1. 在「Catalog type」(目錄類型) 部分，選取「Iceberg Rest Catalog」(Iceberg REST 目錄) 或「Hive Metastore」。
2. 在「Lakehouse 目錄 bucket 選項」部分，選取「單一 bucket 目錄」。
3. 在「Default Catalog Cloud Storage path」(預設目錄 Cloud Storage 路徑) 中，輸入或瀏覽要用於目錄的 Cloud Storage 路徑。 (如果是單一 bucket (gs://) 目錄，每個 bucket 只能有一個目錄，且目錄名稱與 bucket 名稱相符)。
4. 按一下「繼續」。
5. 在「驗證方式」部分，選取「使用者憑證」或「憑證臨時配發模式」。
6. 點選「建立」。
7. 如果您選取「Credential vending mode」(憑證臨時配發模式)，請執行下列額外步驟：
   1. 在「驗證方式」下方，按一下「設定 bucket 權限」。
   2. 在對話方塊中，按一下「確認」。

gcloud

建立多值區目錄 (建議做法)

這項設定可讓目錄與多個 bucket 建立關聯，並讓您命名目錄，不受任何 bucket 名稱影響。

如要建立多值區目錄 (建議做法)，請執行 gcloud biglake iceberg catalogs create 指令。

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    --credential-mode CREDENTIAL_MODE \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    [--primary-location LOCATION]

更改下列內容：

• CATALOG_NAME：目錄名稱。如果是多 bucket 目錄 (建議)，這是您的自訂目錄名稱。
• PROJECT_ID：您的 Google Cloud專案 ID。
• DEFAULT_LOCATION：指定目錄的預設儲存位置。您可以指定 bucket (gs://my-bucket) 或子路徑 (gs://my-bucket/path)。目錄中的所有命名空間和表格都必須位於指定路徑下。舉例來說，如果您指定 gs://my-bucket/path，就無法在 gs://my-bucket/another/path 下方建立命名空間或資料表。

• CREDENTIAL_MODE：驗證方式。如要使用使用者憑證，請使用 end-user；如要使用憑證臨時配發模式，請使用 vended-credentials。

  注意：如果您使用憑證販售模式，請務必在所有相關聯的儲存空間 bucket 上，將Storage 物件使用者角色 (roles/storage.objectUser) 授予目錄的自動佈建 Lakehouse 執行階段目錄服務帳戶。

• RESTRICTED_LOCATIONS：(選用) 以半形逗號分隔的額外允許儲存位置清單，格式為 gs://my-bucket-1/...,gs://my-bucket-2/...。如果您指定路徑 (例如 gs://my-bucket/path)，該 bucket 中的任何命名空間或資料表都必須位於該路徑下。預設位置和受限制位置的所有 Cloud Storage 位置，都必須位於相同的地理區域群組或管轄區 (例如美國、歐洲、加拿大或亞洲)。舉例來說，您無法將美國的 bucket 與歐洲的 bucket 混合。如需支援的位置清單，請參閱「Lakehouse 位置」。

  警告：請避免設定與其他目錄重疊的路徑，以免未經授權的憑證曝光。詳情請參閱「多個 bucket 的儲存空間」。

• LOCATION：(選用) 目錄的主要區域，確保與 BigQuery 的互通性。如果是美國區域 (例如 US 或 us-central1) 或歐盟區域 (例如 EU 或 europe-west4) 的 Cloud Storage bucket，請分別指定 US 或 EU，確保可從對應的 BigQuery 多區域存取及查詢目錄。詳情請參閱「值區和目錄區域」。

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

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

如要建立單一 bucket (gs://) 目錄，請執行下列指令：

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode CREDENTIAL_MODE

更改下列內容：

• CATALOG_NAME：目錄名稱。如果是單一 bucket (gs://) 目錄，這會與 REST 目錄使用的 Cloud Storage bucket ID 相符。
• 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 bucket 和驗證模式。

更改下列內容：

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