Lakehouse 區域端點

本文說明如何使用Private Service Connect 區域端點，存取 Lakehouse 執行階段目錄中的資源。區域端點可讓您以符合資料駐留和資料主權要求的方式執行工作負載，要求流量會直接傳送至端點中指定的區域。

總覽

區域端點會限制要求，只有在受影響的目錄資源位於端點指定的地區時，要求才能繼續。舉例來說，如果您使用端點 https://biglake.us-central1.rep.googleapis.com 存取目錄、命名空間或資料表，則只有在目錄位於 us-central1 時，要求才會繼續。

與全域端點不同，區域端點會將要求限制在資源所在的端點指定位置，而全域端點可將要求傳送至資源所在位置以外的其他位置。區域端點會終止從網際網路、其他 Google Cloud 資源 (例如 Compute Engine 虛擬機器)、使用 Cloud VPN 或 Cloud Interconnect 的地端部署服務，以及虛擬私有雲 (VPC) 收到的要求，並在端點指定的位址終止傳輸層安全標準 (TLS) 工作階段。

區域端點可確保資料落地，讓目錄要求在傳輸期間，只會留在端點指定的區域。如要進一步瞭解服務中繼資料的處理方式，請參閱「服務資料注意事項」。

Lakehouse 執行階段目錄中的下列目錄端點可用於區域端點：

目錄端點 區域端點網址 參考資料
Apache Iceberg REST 目錄端點 https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog REST
Apache Hive 目錄端點 (預覽版) https://biglake.LOCATION.rep.googleapis.com/hive/v1 REST

支援的地區

您可以在下列位置搭配 Lakehouse 執行階段目錄使用區域端點：

  • 亞太地區

    • 德里 asia-south2
    • 孟買 asia-south1

  • 歐洲

    • 比利時 europe-west1
    • 法蘭克福 europe-west3
    • 倫敦 europe-west2
    • 米蘭 europe-west8
    • 荷蘭 europe-west4
    • 巴黎 europe-west9
    • 蘇黎世 europe-west6

  • 中東

    • 達曼 me-central2

  • 美洲

    • 俄亥俄州哥倫布市 us-east5
    • 達拉斯 us-south1
    • 愛荷華州 us-central1
    • 拉斯維加斯 us-west4
    • 洛杉磯 us-west2
    • 蒙特婁 northamerica-northeast1
    • 北維吉尼亞州 us-east4
    • 奧勒岡州 us-west1
    • 鹽湖城 us-west3
    • 南卡羅來納州 us-east1
    • 多倫多 northamerica-northeast2

支援的作業和儲存位置

區域端點只能用於執行作業，存取或變動端點指定位置中複製的目錄資源：

  • 區域目錄隔離：透過 https://biglake.LOCATION.rep.googleapis.com 列出目錄時，只會傳回位於 LOCATION 的目錄。如果要求取得、更新或刪除 LOCATION 以外的目錄、命名空間或表格，系統會傳回 404 NOT_FOUND 錯誤。
  • 預設儲存位置：使用區域端點建立目錄時，多 bucket 目錄 (CATALOG_TYPE_BIGLAKE) 中指定的 Cloud Storage bucket (default_location)，或與單一 bucket 目錄 (CATALOG_TYPE_GCS_BUCKET) 相關聯的 bucket，必須位於 LOCATION。
  • 多個 bucket 目錄的受限位置：如果是多個 bucket 目錄，只要這些 bucket 與 LOCATION 位於相同地理管轄區 (例如美國或歐洲)，您就可以在 restricted_locations 中設定其他 Cloud Storage bucket。詳情請參閱「多值區目錄」。

限制和規定

區域端點無法用於執行下列作業：

  • 讀取或修改端點指定區域以外的目錄、命名空間或表格。
  • 多區域端點路由 (例如 US 或 EU)。區域端點必須指定單一區域。

使用區域端點時，請注意下列限制：

設定工具和查詢引擎

您可以設定 Google Cloud CLI、Apache Spark、Trino 和直接 REST API 要求，以使用區域端點。

gcloud CLI

如要設定 gcloud CLI，以便透過 gcloud biglake 指令使用區域端點，請將 api_endpoint_overrides/biglake 屬性設為要使用的區域端點：

gcloud config set api_endpoint_overrides/biglake https://biglake.LOCATION.rep.googleapis.com/

或者，您也可以為個別指令設定 CLOUDSDK_API_ENDPOINT_OVERRIDES_BIGLAKE 環境變數：

CLOUDSDK_API_ENDPOINT_OVERRIDES_BIGLAKE=https://biglake.LOCATION.rep.googleapis.com/ \
    gcloud biglake iceberg catalogs list --project=PROJECT_ID

更改下列內容：

  • LOCATION：目錄的支援的地區 (例如 us-central1)。
  • PROJECT_ID：您的 Google Cloud 專案 ID。

Apache Spark

設定 Spark 工作階段以連線至 Apache Iceberg REST 目錄端點時，請將 spark.sql.catalog.CATALOG_NAME.uri 屬性設為區域端點網址：

from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
    .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
    .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
    .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
    .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog') \
    .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'bl://projects/PROJECT_ID/catalogs/CATALOG_ID') \
    .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
    .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
    .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
    .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation', 'vended-credentials') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .getOrCreate()

更改下列內容：

  • CATALOG_NAME：本機 Spark 目錄的名稱 (例如 my_catalog)。
  • APP_NAME：Spark 會話名稱。
  • LOCATION：目錄所在的支援的地區 (例如 us-central1)。
  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • CATALOG_ID：多值區目錄的 ID。

如需更多設定選項，請參閱「設定 Apache Iceberg REST 目錄端點」。

Trino

使用 Trino 元件建立 Managed Service for Apache Spark 叢集時，請將 trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri 設為區域端點網址：

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=LOCATION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=bl://projects/PROJECT_ID/catalogs/CATALOG_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

更改下列內容：

  • CLUSTER_NAME：叢集名稱。
  • LOCATION：叢集和目錄的支援的地區。
  • DATAPROC_VERSION：Managed Service for Apache Spark 映像檔版本 (例如 2.2)。
  • NETWORK_ID：叢集網路 ID。
  • CATALOG_NAME：Trino 目錄的名稱。
  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • CATALOG_ID：多值區目錄的 ID。

REST API

請勿將 REST 要求傳送至全域端點 (https://biglake.googleapis.com)，而是傳送至區域端點，格式如下： https://biglake.LOCATION.rep.googleapis.com。

舉例來說，如要使用 Apache Iceberg REST 目錄端點擴充功能 API 列出 LOCATION 中的目錄，請執行下列操作：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    "https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs"

限制全域 API 端點用量

如要強制使用區域端點，請使用 constraints/gcp.restrictEndpointUsage 組織政策限制，封鎖對全域 API 端點 (biglake.googleapis.com) 的要求。詳情請參閱「限制端點用量」。

以下範例組織政策 YAML 檔案會拒絕對全域 biglake.googleapis.com 端點的要求，但允許對區域端點的要求：

name: projects/PROJECT_ID/policies/gcp.restrictEndpointUsage
spec:
  rules:
  - values:
      deniedValues:
      - under:services/biglake.googleapis.com

後續步驟