建立目錄

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

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

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

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)。建立目錄後，請明確將儲存空間 bucket 的「Storage 物件使用者」角色 (roles/storage.objectUser) 授予自動佈建的服務帳戶。

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

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

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

建立目錄

建立目錄。

建立目錄

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

控制台

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

這項設定可讓目錄關聯多個值區，並獨立於任何值區名稱命名目錄。

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

   前往 Lakehouse

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

3. 在「目錄類型」部分，選取「Iceberg Rest 目錄」。

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

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

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

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

8. 按一下「繼續」。

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

10. 按一下「繼續」。

11. 在「Authentication method」部分，選取「End-user credentials」或「Credential vending mode」。

12. 點選「建立」。

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

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

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

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

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

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

gcloud

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

這項設定可讓目錄關聯多個值區，並獨立於任何值區名稱命名目錄。

如要建立多個 bucket (bl://) 目錄 (建議做法)，請執行 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 (bl://) 目錄 (建議)，這是您的自訂目錄名稱。
• 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 上，明確授予目錄的自動佈建 Lakehouse 執行階段目錄服務帳戶「Storage 物件使用者」角色 (roles/storage.objectUser)。

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

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

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