搭配 Cloud Storage 使用 Iceberg REST 目錄

授予 IAM 角色

如要允許 Managed Service for Apache Spark PySpark 工作和 Lakehouse 執行階段目錄使用 Cloud Storage 和 BigQuery，請將必要角色授予對應的主體：

1. 在 Google Cloud 控制台點選「Activate Cloud Shell」(啟用 Cloud Shell)。

   啟用 Cloud Shell

2. 按一下 [授權]。

3. 將「Dataproc Worker」角色授予專案的 Compute Engine 預設服務帳戶，Managed Service for Apache Spark 預設會使用這個帳戶，詳情請參閱「Managed Service for Apache Spark 服務帳戶」。

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')-compute@developer.gserviceaccount.com" \
       --role="roles/dataproc.worker"

4. 將「服務使用情形用戶」角色授予專案的 Compute Engine 預設服務帳戶。

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')-compute@developer.gserviceaccount.com" \
       --role="roles/serviceusage.serviceUsageConsumer"

5. 將「BigLake 編輯者」角色授予專案的 Compute Engine 預設服務帳戶。

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')-compute@developer.gserviceaccount.com" \
       --role="roles/biglake.editor"

6. 將「BigQuery 資料編輯者」角色授予專案的 Compute Engine 預設服務帳戶。

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')-compute@developer.gserviceaccount.com" \
       --role="roles/bigquery.dataEditor"

   更改下列內容：

   • PROJECT_ID：您的 Google Cloud 專案 ID

建立 Lakehouse 執行階段目錄

建立 Lakehouse 執行階段目錄，管理 Iceberg 資料表的中繼資料。您可以在 PySpark 工作中連線至這個目錄。

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

   前往 Lakehouse

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

   「建立目錄」頁面隨即開啟。

3. 選取「Iceberg REST catalog」(Iceberg REST 目錄)，然後選取「Cloud Storage bucket」(Cloud Storage bucket)。

4. 在「選取 Cloud Storage bucket」中，按一下「瀏覽」，然後按一下「建立新的 bucket」。

5. 輸入 bucket 的專屬名稱。

   重要事項

   請記下 bucket 名稱，系統也會自動將其做為 Lakehouse 目錄名稱。這項設定無法變更。如要將名稱儲存在變數中，以便在本教學課程稍後使用，現在可以在這裡新增名稱。

   LAKEHOUSE_CATALOG_ID

   如果值區位於多地區 (例如 us、eu)，請使用相同地理位置的地區，例如 us-east1 或 europe-west4。您可以將區域儲存在這個變數中，以供後續使用：

   REGION

   請記下建立 bucket 的區域。在本教學課程中，您稍後必須使用相同的區域，才能使用 dataproc batches submit pyspark 指令執行 PySpark 工作。如果您在多地區 (例如 us、eu) 建立值區，則應使用相同地理位置的區域，例如 us-east1 或 europe-west4。如要將名稱儲存在變數中，以便在本教學課程稍後使用，現在可以在這裡新增名稱。

   REGION

6. 從 bucket 清單中選取 bucket，然後按一下「選取」。

7. 在「Authentication method」部分，選取「Credential vending mode」。

8. 點選「建立」。

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

9. 在「驗證方式」下方，按一下「設定 bucket 權限」。

10. 在對話方塊中，按一下「確認」。

    這會驗證目錄的服務帳戶是否具備儲存空間 bucket 的「Storage 物件使用者」角色。

建立及執行 PySpark 工作

如要建立及查詢 Iceberg 資料表，請先使用必要的 Spark SQL 陳述式建立 PySpark 工作。然後使用 Managed Service for Apache Spark 執行工作。

使用命名空間和表格建立 PySpark 指令碼

在文字編輯器中，建立名為 quickstart.py 的檔案，並加入下列內容。

這個 PySpark 指令碼會初始化 Spark 工作階段，以便對 Iceberg 目錄執行多項作業。如果命名空間不存在，指令碼會先建立命名空間。然後建立名為 quickstart_table 的 Iceberg 資料表，並使用基本結構定義。資料表建立完成後，指令碼會插入三列資料。最後，它會查詢資料表，擷取所有插入的記錄。

您在下一個步驟中執行 gcloud dataproc batches submit pyspark 工作時，會使用這些值。

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("quickstart").getOrCreate()

# Create a namespace (dataset) if it doesn't exist
spark.sql("CREATE NAMESPACE IF NOT EXISTS `quickstart_catalog`.quickstart_namespace")

# Create the table
spark.sql("""
    CREATE OR REPLACE TABLE `quickstart_catalog`.quickstart_namespace.quickstart_table (
        id INT,
        name STRING
    )
    USING iceberg
""")

# Insert data into the table
spark.sql("""
    INSERT INTO `quickstart_catalog`.quickstart_namespace.quickstart_table
    VALUES (1, 'one'), (2, 'two'), (3, 'three')
""")

將指令碼上傳至 Cloud Storage 值區

建立 quickstart.py 指令碼後，請將其上傳至 Cloud Storage 值區。

1. 前往 Google Cloud 控制台的「Cloud Storage bucket」。

   前往「Buckets」(值區) 頁面

2. 按一下 bucket 名稱。

3. 在「物件」分頁，依序點選「上傳」 >「上傳檔案」。

4. 在檔案瀏覽器中選取 quickstart.py 檔案，然後按一下「開啟」。

執行 PySpark 工作

上傳 quickstart.py 指令碼後，請以 Managed Service for Apache Spark 批次工作形式執行。

1. 在 Cloud Shell 中，使用 quickstart.py 指令碼執行下列 Managed Service for Apache Spark 批次工作。

   gcloud dataproc batches submit pyspark gs://LAKEHOUSE_CATALOG_ID/quickstart.py \
       --project=PROJECT_ID \
       --region=REGION \
       --version=2.2 \
       --properties="\
   spark.sql.defaultCatalog=quickstart_catalog,\
   spark.sql.catalog.quickstart_catalog=org.apache.iceberg.spark.SparkCatalog,\
   spark.sql.catalog.quickstart_catalog.type=rest,\
   spark.sql.catalog.quickstart_catalog.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
   spark.sql.catalog.quickstart_catalog.warehouse=gs://LAKEHOUSE_CATALOG_ID,\
   spark.sql.catalog.quickstart_catalog.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
   spark.sql.catalog.quickstart_catalog.header.x-goog-user-project=PROJECT_ID,\
   spark.sql.catalog.quickstart_catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
   spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
   spark.sql.catalog.quickstart_catalog.header.X-Iceberg-Access-Delegation=vended-credentials,\
   spark.sql.catalog.quickstart_catalog.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token"

   更改下列內容：

   • LAKEHOUSE_CATALOG_ID：包含 PySpark 應用程式檔案的 Cloud Storage bucket 名稱。

     重要事項：

     這個 ID 也是目錄的名稱。舉例來說，如果您建立值區來儲存目錄，並將其命名為 iceberg-bucket，則目錄名稱和值區名稱都是 iceberg-bucket。稍後在 BigQuery 中使用 P.C.N.T 語法查詢目錄時，會用到這個名稱。例如 my-project.biglake-catalog-id-name.quickstart_namespace.quickstart_table。

   • PROJECT_ID：您的 Google Cloud 專案 ID。

   • REGION：執行 Managed Service for Apache Spark 批次工作負載的區域。

   工作完成後，畫面會顯示類似以下的輸出內容：

   Batch [cb9d84e9489d408baca4f9e7ab4c64ff] finished.
   metadata:
   '@type': type.googleapis.com/google.cloud.dataproc.v1.BatchOperationMetadata
   batch: projects/your-project/locations/us-central1/batches/cb9d84e9489d408baca4f9e7ab4c64ff
   batchUuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9
   createTime: '2026-01-24T00:10:50.224097Z'
   description: Batch
   labels:
       goog-dataproc-batch-id: cb9d84e9489d408baca4f9e7ab4c64ff
       goog-dataproc-batch-uuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9
       goog-dataproc-drz-resource-uuid: batch-54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9
       goog-dataproc-location: us-central1
   operationType: BATCH
   name: projects/your-project/regions/us-central1/operations/32287926-5f61-3572-b54a-fbad8940d6ef
   

從 BigQuery 查詢資料表

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

   前往「BigQuery」

2. 在查詢編輯器中輸入下列陳述式，查詢會使用 project.catalog.namespace.table 語法。

   SELECT * FROM `PROJECT_ID.LAKEHOUSE_CATALOG_ID.quickstart_namespace.quickstart_table`;
   

   更改項目：

   • PROJECT_ID：您的 Google Cloud 專案 ID。

   • LAKEHOUSE_CATALOG_ID：要在 BigQuery 查詢中使用的目錄 ID。

     重要事項

     這個 ID 也是 Cloud Storage bucket 的名稱。

     舉例來說，假設你建立的 bucket 是用來儲存目錄，並將其命名為 iceberg-bucket，則目錄名稱和 bucket 名稱都會是 iceberg-bucket。稍後在 BigQuery 中查詢目錄時，會使用 P.C.N.T 語法。例如 my-project.biglake-catalog-id-name.quickstart_namespace.quickstart_table。

3. 按一下「執行」。

   查詢結果會顯示您透過 PySpark 工作插入的資料。