自 2026 年 4 月 20 日起，BigLake 將改名為 Lakehouse for Apache Iceberg。BigLake metastore 現在稱為 Lakehouse 執行階段目錄。湖倉 API、用戶端程式庫、CLI 指令和 IAM 名稱維持不變，仍會參照 BigLake。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

為 Snowflake Horizon Catalog 設定跨雲端連線

本文說明如何設定跨雲端連線，直接在Google Cloud中查詢 Snowflake Horizon Catalog 的資料。這項功能可整合外部資料來源與現有 Google Cloud環境，統一進行資料分析。

之後，您可以使用無邊界湖倉管理同盟資料的存取權。

事前準備

請參閱 Lakehouse 總覽，瞭解 Lakehouse 如何管理資料存取權。
請參閱存取跨雲端資料一文，瞭解運作方式。
請參閱支援的目錄，確認支援的設定。
瞭解如何使用區域性 Secret Manager 密鑰。使用密碼型驗證設定 Lakehouse 時，必須使用 Snowflake Horizon Catalog。
選用：如果您打算透過 Google Cloud VPC 與遠端雲端供應商的 VPC (例如 AWS) 之間的私有互連網路，路由查詢，請確保您在遠端供應商擁有有效帳戶，並佈建專屬跨雲端互連或合作夥伴跨雲端互連，與 Cloud Router 建立 BGP 工作階段，以及確認您在兩個雲端環境中都擁有必要的 IAM 權限。

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake, Secret Manager APIs.

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 APIs

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake, Secret Manager APIs.

Roles required to enable APIs

Enable the APIs

必要的角色

如要取得設定跨雲端存取權所需的權限，請要求管理員授予您專案的下列 IAM 角色：

管理 Lakehouse 目錄： BigLake 管理員 (roles/biglake.admin)
管理密鑰 (如果使用以密鑰為基礎的驗證)： Secret Manager 管理員 (roles/secretmanager.admin)
透過私有互連網路傳送流量 (使用者)： Compute 網路管理員 (roles/compute.networkAdmin)
透過私有互連網路 (目錄服務帳戶) 轉送流量：
- Service Directory 檢視者 (roles/servicedirectory.viewer)
- Service Directory PSC Authorized Service (roles/servicedirectory.pscAuthorizedService)

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

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

支援的目錄詳細資料

本指南提供操作說明，協助您在 Amazon Web Services (AWS) 或 Google Cloud上，使用 Snowflake Horizon Catalog 設定 Lakehouse。如要進一步瞭解外部位置規定和支援的設定，請參閱「支援的目錄」。

限制和注意事項

本節列出存取跨雲端資料的限制和注意事項。

支援 Cross-Cloud Interconnect 的雲端供應商： 無邊界湖倉支援透過私人互連與下列遠端雲端供應商連線：Amazon Web Services (AWS)。您可以選擇使用專屬 Cross-Cloud Interconnect 或合作夥伴 Cross-Cloud Interconnect。
支援的資料表：只有 Snowflake Iceberg 資料表會同步至 Lakehouse。中繼資料重新整理時，系統會忽略標準原生 Snowflake 資料表。
唯讀：Lakehouse 中的聯合目錄是遠端目錄的唯讀檢視畫面。系統不支援資源操作 (例如建立、更新或刪除資源)，您必須直接在遠端目錄中執行這些操作。
網路轉送：如果未設定私人互連網路 (例如專屬 CCI 或合作夥伴 CCI)，查詢會透過公用網際網路轉送。這可能會導致遠端雲端供應商收取較高的輸出費用，且效能較難預測。
資料更新間隔：聯邦目錄的 --refresh-interval 旗標會決定中繼資料的同步頻率。值必須為 0s (停用) 或至少 300s (5 分鐘)。如果命名空間和表格資源越多，目錄的背景中繼資料重新整理作業可能需要較長時間。如果先前的重新整理作業超出時間，系統會略過目前的重新整理作業，但會在下一個間隔排定下一次重新整理作業。

一般工作流程

如要存取跨雲端資料，請按照下列一般步驟操作：

設定跨雲端互連 (選用)：設定 Google Cloud VPC 與遠端雲端供應商之間的私人連線。
設定聯盟：設定驗證機制，並在 Lakehouse 中建立聯合目錄。
- 以密鑰為基礎的驗證 (PAT)：使用遠端目錄憑證在 Secret Manager 中建立密鑰。接著，在 Lakehouse 中建立聯合目錄，並授予目錄服務帳戶密鑰存取權。
- Workload Identity Federation (WIF)：在 Lakehouse 中建立聯盟型目錄，並指定必要的 Snowflake 角色。然後將目錄的服務帳戶 ID 連結至 Snowflake 中的服務使用者。Snowflake 服務使用者應具備遠端 Snowflake Horizon Catalog 的使用權限。
驗證連線：確認 Lakehouse 可以順利連線至遠端目錄。
查詢資料：使用 BigQuery 或 Managed Service for Apache Spark，對聯合資料執行查詢。詳情請參閱「查詢遠端資料」。
設定權限：使用 IAM 管理可查看及查詢同盟資料的使用者。

設定 Cross-Cloud Interconnect (選用)

根據預設，對遠端目錄的查詢會透過公開網際網路傳輸。為協助提升安全性及法規遵循能力、提供可預測的效能，以及降低資料傳輸費用，請使用私有互連。這會在您的 Google Cloud虛擬私有雲 (VPC) 與遠端雲端供應商的網路 (例如 AWS) 之間，建立專屬的私人網路連線。

您可以在 Google Cloud 虛擬私有雲和遠端雲端供應商的虛擬私有雲 (例如 AWS) 之間，佈建及設定下列任一私人互連選項：

專屬 Cross-Cloud Interconnect：專屬實體連線。
合作夥伴 Cross-Cloud Interconnect：透過支援的服務供應商建立連線。

在 Cloud Router Google Cloud 和遠端雲端供應商的 VPC 之間建立 BGP 工作階段，確保路徑交換。

如要啟用私下查詢，您必須透過私有互連，設定從 Lakehouse 到遠端儲存空間值區 (例如 AWS Amazon S3 值區) 的路徑。您可以按照兩種架構流程設定這項路徑：

內部區域 Proxy 網路負載平衡器轉送：這個流程會使用Google Cloud 內部區域 Proxy 網路負載平衡器，將要求分配至指向多個 AWS 彈性網路介面 (ENI) 的混合式連線網路端點群組 (NEG)。這個流程對於負載平衡、擴充性和高可用性至關重要。合作夥伴 CCI 必須使用此功能，建議專屬 CCI 也使用此功能，以利負載平衡、擴充及高可用性。
直接端點路由：這個流程會將 Service Directory 直接連線至單一 AWS 介面 VPC 端點 IP 位址。這個流程僅適用於專屬 CCI，不支援合作夥伴 CCI。

選取符合架構需求的設定流程：

內部區域 Proxy 網路負載平衡器

如要設定內部區域 Proxy 網路負載平衡器，將要求分配到多個 AWS ENI，以達到高可用性和負載平衡，請按照下列步驟操作：

設定 AWS 網路

首先，請建立 Amazon S3 虛擬私有雲介面端點 (AWS PrivateLink)：

在 AWS VPC 控制台中，為 Amazon S3 建立介面端點。
指定服務名稱為 com.amazonaws.AWS_REGION.s3。
選取透過 Direct Connect 連線至 Google Cloud VPC 的 VPC 和子網路。
將安全性群組附加至端點，控管連入存取權。
這會在每個選取的子網路中佈建彈性網路介面 (ENI)。記下這些 ENI 的私人 IP 位址。

接著，請設定安全群組：

確認附加至 Amazon S3 端點 ENI 的安全性群組允許來自 Google Cloud 虛擬私有雲的通訊埠 443傳入 TCP 流量。這必須包含Google Cloud 僅限 Proxy 子網路的 CIDR 範圍，才能允許健康狀態檢查和轉送的流量。

設定 Google Cloud 網路

為簡化設定，請執行下列指令來設定內部負載平衡器。如需進階設定或更多詳細資料，請參閱「為混合式端點設定內部區域 Proxy 網路負載平衡器」。

gcloud compute networks subnets create PROXY_SUBNET_NAME \
    --purpose=REGIONAL_MANAGED_PROXY \
    --role=ACTIVE \
    --region=REGION \
    --network=VPC_NETWORK \
    --range=PROXY_SUBNET_RANGE

更改下列內容：

PROXY_SUBNET_NAME：僅限 Proxy 的子網路名稱。
PROXY_SUBNET_RANGE：虛擬私有雲網路中未使用的 CIDR 範圍 (例如 10.129.0.0/23)。

建立地區健康狀態檢查：
```
gcloud compute health-checks create tcp HEALTH_CHECK_NAME \
    --region=REGION \
    --port=443
```
更改下列內容：
- HEALTH_CHECK_NAME：健康狀態檢查的名稱。
- REGION： Google Cloud 區域 (例如 us-east4)。
建立混合式連線網路端點群組 (NEG)，並新增端點：

為每個可用區建立混合式 NEG (NON_GCP_PRIVATE_IP_PORT)：
```
gcloud compute network-endpoint-groups create NEG_NAME \
    --network-endpoint-type=NON_GCP_PRIVATE_IP_PORT \
    --zone=ZONE \
    --network=VPC_NETWORK
```
將 AWS ENI 的私有 IP 位址新增至對應的混合 NEG：
```
gcloud compute network-endpoint-groups update NEG_NAME \
    --zone=ZONE \
    --add-endpoint="ip=AWS_S3_IP,port=443"
```
更改下列內容：
- NEG_NAME：混合式 NEG 的名稱。
- ZONE： Google Cloud 區域 (例如 us-east4-a)。這個區域必須位於 Cross-Cloud Interconnect VLAN 連結的區域內。
- VPC_NETWORK：虛擬私有雲網路的名稱。
- AWS_S3_IP：該區域中 AWS Amazon S3 虛擬私有雲端點 (ENI) 的私有 IP 位址。
如果 AWS ENI 分散在多個可用區，請重複執行這些指令，為其他可用區建立 NEG 並新增端點。

建立及設定後端服務：

使用內部代管負載平衡建立區域後端服務：

gcloud compute backend-services create BACKEND_SERVICE_NAME \
    --load-balancing-scheme=INTERNAL_MANAGED \
    --protocol=TCP \
    --region=REGION \
    --health-checks=HEALTH_CHECK_NAME \
    --health-checks-region=REGION

將混合 NEG 新增至後端服務：

gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
    --region=REGION \
    --network-endpoint-group=NEG_NAME \
    --network-endpoint-group-zone=ZONE \
    --balancing-mode=CONNECTION \
    --max-connections=MAX_CONNECTIONS

更改下列內容：

BACKEND_SERVICE_NAME：後端服務的名稱。
NEG_NAME：您在上一個步驟中建立的混合 NEG 名稱。
ZONE： Google Cloud 區域 (例如 us-east4-a)。
MAX_CONNECTIONS：後端應處理的並行連線數量上限 (例如 100)。

針對您建立的每個混合 NEG 重複執行 add-backend 指令。

設定負載平衡器前端：

建立目標 TCP Proxy：

gcloud compute target-tcp-proxies create TARGET_PROXY_NAME \
    --backend-service=BACKEND_SERVICE_NAME \
    --region=REGION

建立轉送規則，將流量轉送至目標 Proxy：

gcloud compute forwarding-rules create FORWARDING_RULE_NAME \
    --load-balancing-scheme=INTERNAL_MANAGED \
    --network=VPC_NETWORK \
    --subnet=VPC_SUBNET \
    --ports=443 \
    --region=REGION \
    --target-tcp-proxy=TARGET_PROXY_NAME \
    --target-tcp-proxy-region=REGION \
    --allow-global-access

更改下列內容：

TARGET_PROXY_NAME：目標 Proxy 的名稱。
FORWARDING_RULE_NAME：轉送規則的名稱。
VPC_SUBNET：虛擬私有雲子網路的名稱。

為負載平衡器建立轉送規則後，請記下指派給負載平衡器的內部 IP 位址。這是你的 ILB_IP_ADDRESS。

設定 Service Directory

在 Service Directory 中註冊 ILB 的 IP 位址，讓 Lakehouse 能夠探索該位址。

為遠端雲端建立命名空間：
```
gcloud service-directory namespaces create NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION
```
更改下列內容：
- NAMESPACE：命名空間的專屬 ID。
- PROJECT_ID：您的 Google Cloud 專案 ID。
- REGION： Google Cloud 區域。例如 us-east4。這必須與同盟目錄位於相同區域。

在 Service Directory 命名空間中建立服務：

gcloud service-directory services create SERVICE_NAME \
    --namespace=NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION

更改下列內容：

SERVICE_NAME：服務的專屬 ID。

在服務中建立 ILB 的端點：

gcloud service-directory endpoints create ENDPOINT_NAME \
    --project=PROJECT_ID \
    --namespace=NAMESPACE \
    --service=SERVICE_NAME \
    --location=REGION \
    --network=projects/PROJECT_NUMBER/global/networks/VPC_NETWORK \
    --address=ILB_IP_ADDRESS \
    --port=443

更改下列內容：

ENDPOINT_NAME：端點的專屬 ID。
PROJECT_NUMBER：您的 Google Cloud專案編號。在 --network 標記中使用專案編號。
ILB_IP_ADDRESS：ILB 轉送規則的內部 IP 位址。

直接端點

如要設定 Service Directory，將流量直接轉送至單一 AWS 介面虛擬私有雲端點 IP 位址，請按照下列步驟操作：

在 AWS 虛擬私有雲中，為 Amazon S3 建立介面 VPC 端點。記下這個端點的 IP 位址和通訊埠。
為遠端雲端建立命名空間：
```
gcloud service-directory namespaces create NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION
```
更改下列內容：
- NAMESPACE：命名空間的專屬 ID。
- PROJECT_ID：您的 Google Cloud 專案 ID。
- REGION： Google Cloud 區域。例如 us-east4。這必須與同盟目錄位於相同區域。

在 Service Directory 命名空間中建立服務：

gcloud service-directory services create SERVICE_NAME \
    --namespace=NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION

更改下列內容：

SERVICE_NAME：服務的專屬 ID。

在服務中建立端點，內含 Amazon S3 介面 VPC 端點的路徑資訊：
```
gcloud service-directory endpoints create ENDPOINT_NAME \
    --service=SERVICE_NAME \
    --namespace=NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION \
    --address=S3_VPCE_IP_ADDRESS \
    --port=S3_VPCE_PORT \
    --network=projects/PROJECT_NUMBER/global/networks/VPC_NETWORK
```
更改下列內容：
- ENDPOINT_NAME：端點的專屬 ID。
- S3_VPCE_IP_ADDRESS：Amazon S3 介面 VPC 端點的 IP 位址。例如：10.0.1.45。
- S3_VPCE_PORT：Amazon S3 介面 VPC 端點的通訊埠編號。例如：443。
- PROJECT_NUMBER：您的 Google Cloud專案編號。在 --network 標記中使用專案編號。
- VPC_NETWORK：與私有互連相關聯的虛擬私有雲網路名稱。 Google Cloud

設定聯盟

如要查詢資料，您必須設定 Lakehouse 聯邦目錄，並連線至遠端 Snowflake Horizon 目錄。

設定驗證機制

如要存取遠端 Snowflake Horizon Catalog，同盟需要憑證或角色設定。選擇下列其中一種做法。

以密鑰為準 (PAT)

這個選項會使用以程式輔助方式存取的存取權杖 (PAT)，並透過區域性 Secret Manager 密鑰安全地儲存。

產生程式輔助存取權杖 (PAT)，並取得目標目錄的讀取權限。
建立名為 credentials.json 的 JSON 檔案，其中包含您的酬載：
```
{
  "client_secret": "SNOWFLAKE_PAT_TOKEN",
  "scope": "session:role:SNOWFLAKE_ROLE"
}
```
更改下列內容：
- SNOWFLAKE_PAT_TOKEN：您的 Snowflake 程式輔助存取權杖 (PAT)。
- SNOWFLAKE_ROLE：工作階段所需的特定 Snowflake 角色。例如：ICEBERG_VIEW。
注意： 由於驗證完全由 PAT 權杖和範圍處理，因此 Snowflake Horizon 設定不需要 client_id 參數。
設定 Secret Manager 的區域端點：

根據預設，Secret Manager 會使用全域端點。不過，Lakehouse 要求密鑰必須與 Lakehouse 目錄儲存在相同區域。如要使用 gcloud CLI 與區域性密鑰互動，您必須為目前的工作階段或設定檔覆寫預設 API 端點。為避免連線問題，您必須在相同區域建立密鑰和目錄。
```
gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
```
更改下列內容：
- REGION：儲存 Secret Manager 密鑰的 Google Cloud 區域。例如：us-east4。為避免連線問題，您的密鑰和目錄必須建立在相同區域。
將酬載上傳至 Secret Manager：
```
gcloud secrets create SNOWFLAKE_SECRET_NAME \
  --location="REGION" \
  --project="PROJECT_ID" \
  --data-file=credentials.json
```
更改下列內容：
- SNOWFLAKE_SECRET_NAME：Snowflake 密鑰的名稱。
- PROJECT_ID：您的 Google Cloud 專案 ID。

Workload Identity Federation

Workload Identity Federation (WIF) 會將 Lakehouse 目錄服務帳戶直接連結至 Snowflake 服務使用者，避免使用長期有效的密碼。無須進行任何設定，繼續建立聯合目錄。

建立聯合目錄

使用 Google Cloud 控制台或 gcloudCLI 建立聯合目錄。

控制台

如要建立聯合目錄，請按照下列步驟操作：

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

前往 Lakehouse
按一下「建立目錄」。
按一下「聯合目錄」。

系統會顯示「目錄設定」詳細資料。
在「聯合目錄來源」部分，選取「Snowflake (Horizon)」。
針對「Data location」(資料位置)，選取要建立聯合目錄的 Lakehouse 區域。例如：us-east4。如要盡可能縮短延遲時間 (即使透過公開網際網路)，請在選取區域時採取下列做法：
- 如果 Snowflake Horizon Catalog 位於 AWS，請選取最接近 AWS 區域的Google Cloud 區域。
- 如果 Snowflake Horizon Catalog 處於開啟狀態 Google Cloud，請選取完全相同的區域。
按一下「繼續」。

系統會顯示「連線詳細資料」。
在「Remote catalog details」(遠端目錄詳細資料) 部分的「Snowflake account identifier」(Snowflake 帳戶 ID) 欄位中，輸入 Snowflake 帳戶 ID。例如：my_org-my_account。
在「Snowflake warehouse」(Snowflake 倉儲) 欄位中，輸入 Snowflake 倉儲名稱。這也稱為 Snowflake Horizon Catalog 中的資料庫名稱。
選取「驗證方式」選項：
- 在「Secret」(密鑰) 中，輸入「Secret-based (PAT)」(以密鑰為準 (PAT)) 的密鑰名稱。請使用下列格式： projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME。
- 如果是 OIDC，請輸入 Workload Identity Federation 的 Snowflake 角色。例如：ICEBERG_VIEW。
選用：在「Service directory name」(服務目錄名稱) 欄位中，輸入 Service Directory 服務的路徑。例如：projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME。如果您要設定私人互連 (Cross-Cloud Interconnect)，才需要執行這項操作。
點選「建立」。

gcloud CLI

以密鑰為準 (PAT)

公用網際網路 (無 CCI)

如未設定 CCI，連線會透過公開網際網路安全傳輸。

gcloud alpha biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="snowflake" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS"

更改下列內容：

PROJECT_ID：您的 Google Cloud 專案 ID。
REGION：建立聯合目錄的 Lakehouse 區域。例如，us-east4。如要盡可能縮短延遲時間，請選取最靠近 Snowflake 區域的 Google Cloud 區域。
SNOWFLAKE_SECRET_NAME：Snowflake 密鑰的名稱。
SNOWFLAKE_ACCOUNT_IDENTIFIER：您的 Snowflake 帳戶 ID (例如 my_org-my_account)。
SNOWFLAKE_WAREHOUSE：要與之聯合的 Snowflake 倉儲。這也稱為 Snowflake Horizon Catalog 中的資料庫名稱。
REFRESH_INTERVAL：(選填) 指定更新目錄資訊的頻率。將這個值設為時間長度，例如 330s 或 5m30s。值必須為 0s (已停用) 或至少 300s (5m)。如果時間長度短於 300s，系統會顯示錯誤。間隔越短，資料更新頻率越高，但 API 呼叫費用可能也會增加。時間間隔越長，費用可能越低，但查詢到的資料可能無法反映最新的資料集。如果省略或將值設為 0s，系統就不會啟動背景中繼資料重新整理。除非將重新整理間隔更新為有效的正值，否則這項功能會維持停用狀態。
NAMESPACE_FILTERS：(選用) 以半形逗號分隔的命名空間清單，用於同盟。例如，ns1,ns2。如省略，則會納入所有命名空間。

客戶擁有 (CCI)

如果您已設定私人互連網路 (例如專屬 CCI 或合作夥伴 CCI)，請提供 Service Directory 服務參照，讓 Lakehouse 私下轉送流量。

gcloud alpha biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="snowflake" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME"

更改下列內容：

PROJECT_ID：您的 Google Cloud 專案 ID。
REGION：建立聯合目錄的 Lakehouse 區域。注意：這個區域必須與服務目錄命名空間和區域性密鑰相同。
SNOWFLAKE_SECRET_NAME：Snowflake 密鑰的名稱。
SNOWFLAKE_ACCOUNT_IDENTIFIER：您的 Snowflake 帳戶 ID。
SNOWFLAKE_WAREHOUSE：要與之聯合的 Snowflake 倉儲。這也稱為 Snowflake Horizon Catalog 中的資料庫名稱。
REFRESH_INTERVAL：(選填) 指定更新目錄資訊的頻率。將這個值設為時間長度，例如 330s 或 5m30s。值必須為 0s (已停用) 或至少 300s (5m)。如果時間長度短於 300s，系統會顯示錯誤。間隔越短，資料更新頻率越高，但 API 呼叫費用可能也會增加。時間間隔越長，費用可能越低，但查詢到的資料可能無法反映最新的資料集。如果省略或將值設為 0s，系統就不會啟動背景中繼資料重新整理。除非將重新整理間隔更新為有效的正值，否則這項功能會維持停用狀態。
NAMESPACE_FILTERS：(選用) 以半形逗號分隔的命名空間清單，用於同盟。例如，ns1,ns2。如省略，則會納入所有命名空間。
NAMESPACE：您在設定私人互連時建立的 Service Directory 命名空間。
SERVICE_NAME：您在設定專屬互連時建立的 Service Directory 服務名稱。

Workload Identity Federation

公用網際網路 (無 CCI)

gcloud alpha biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="snowflake" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --snowflake-role="SNOWFLAKE_ROLE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS"

客戶擁有 (CCI)

如果您設定了私人互連網路 (例如專屬 CCI 或合作夥伴 CCI)，請提供 Service Directory 服務參照，讓 Lakehouse 私下路由流量。

gcloud alpha biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="snowflake" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --snowflake-role="SNOWFLAKE_ROLE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME"

更改下列內容：

PROJECT_ID：您的 Google Cloud 專案 ID。
SNOWFLAKE_ACCOUNT_IDENTIFIER：您的 Snowflake 帳戶 ID。
SNOWFLAKE_WAREHOUSE：要與之聯合的 Snowflake 倉儲。這也稱為 Snowflake Horizon Catalog 中的資料庫名稱。
SNOWFLAKE_ROLE：工作階段所需的特定 Snowflake 角色。例如：ICEBERG_VIEW。
FEDERATED_CATALOG_NAME：Lakehouse 聯合目錄的名稱。
REGION：建立聯合目錄的 Lakehouse 區域。
REFRESH_INTERVAL：(選填) 指定更新目錄資訊的頻率。將這個值設為時間長度，例如 330s 或 5m30s。值必須為 0s (已停用) 或至少 300s (5m)。如果時間長度短於 300s，系統會顯示錯誤。間隔越短，資料更新頻率越高，但 API 呼叫費用可能也會增加。時間間隔越長，費用可能越低，但查詢到的資料可能無法反映最新的資料集。如果省略或將值設為 0s，系統就不會啟動背景中繼資料重新整理。除非將重新整理間隔更新為有效的正值，否則這項功能會維持停用狀態。
NAMESPACE_FILTERS：(選用) 以半形逗號分隔的命名空間清單，用於同盟。例如，ns1,ns2。如省略，則會納入所有命名空間。
NAMESPACE：Service Directory 服務的命名空間。
SERVICE_NAME：Service Directory 服務的名稱。

完成驗證設定

使用所選驗證類型完成驗證程序。

以密鑰為準 (PAT)

建立目錄時，Lakehouse 會為目錄佈建專屬服務帳戶 (在資源說明中以 biglake-service-account 形式傳回)。

您必須授予這個服務帳戶存取先前建立的密鑰權限。請注意，傳播 IAM 政策可能需要幾分鐘。

授予目錄的服務帳戶密鑰存取權：

gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
gcloud secrets add-iam-policy-binding SNOWFLAKE_SECRET_NAME \
  --project="PROJECT_ID" \
  --location="REGION" \
  --member="serviceAccount:$(gcloud alpha biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
      --project="PROJECT_ID" \
      --format='value(biglake-service-account)')" \
  --role="roles/secretmanager.secretAccessor"

如要確認聯盟目錄服務帳戶是否可存取密鑰，請執行下列指令：

gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
gcloud secrets get-iam-policy SNOWFLAKE_SECRET_NAME \
    --project="PROJECT_ID" \
    --location="REGION"

在輸出內容中，確認 biglake-service-account 服務帳戶已獲派 roles/secretmanager.secretAccessor 角色。

Workload Identity Federation

建立目錄後，您必須將目錄的服務帳戶身分連結至 Snowflake 中的服務使用者。

從目錄詳細資料中擷取 Lakehouse 服務帳戶 ID (主體)。

您可以從建立指令的 JSON 回應 (欄位 biglake-service-account-id) 取得這項資訊。

或者，您也可以對目錄執行 describe 指令來取得值：
```
gcloud alpha biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
  --project="PROJECT_ID"
```
在輸出內容中尋找 biglake-service-account-id。

登入 Snowflake 管理執行個體，然後執行下列指令碼，與 Lakehouse 服務身分建立信任關係：

USE ROLE ACCOUNTADMIN;

CREATE USER SNOWFLAKE_SERVICE_USER
  TYPE = SERVICE
  WORKLOAD_IDENTITY = (
    TYPE = GCP
    SUBJECT = 'LAKEHOUSE_SERVICE_ACCOUNT_ID'
  )
  DEFAULT_ROLE = SNOWFLAKE_ROLE
  COMMENT = 'Service user for Lakehouse federation over WIF';

-- Also explicitly GRANT permissions to the role
GRANT ROLE SNOWFLAKE_ROLE TO USER SNOWFLAKE_SERVICE_USER;

更改下列內容：

SNOWFLAKE_SERVICE_USER：Snowflake 中新服務使用者的名稱。
LAKEHOUSE_SERVICE_ACCOUNT_ID：在上一個步驟中擷取的服務帳戶 ID。
SNOWFLAKE_ROLE：Snowflake 角色 (必須與建立目錄時指定的角色相符)。

完成私人互連設定 (僅限 Cross-Cloud Interconnect)

如果透過私人互連網路 (專屬或合作夥伴 CCI) 轉送流量，您必須授予 Lakehouse 目錄服務帳戶權限，才能透過 Service Directory 探索及授權連線。

控制台

前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

前往「IAM」頁面
按一下「授予存取權」 (或「新增」)。
在「新增主體」欄位中，輸入 Lakehouse 目錄服務帳戶電子郵件地址。您可以描述目錄來擷取這封電子郵件 (請參閱 gcloud 分頁)。
在「角色」下拉式選單中，選取「Service Directory Viewer」 (roles/servicedirectory.viewer)。
按一下「新增其他角色」，然後選取「Service Directory PSC Authorized Service」(Service Directory PSC 授權服務) (roles/servicedirectory.pscAuthorizedService)。
按一下 [儲存]。

gcloud CLI

將必要角色指派給目錄的服務帳戶：

# Grant Service Directory Viewer
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(gcloud alpha biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --format='value(biglake-service-account)')" \
--role="roles/servicedirectory.viewer"

# Grant Service Directory PSC Authorized Service
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(gcloud alpha biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --format='value(biglake-service-account)')" \
--role="roles/servicedirectory.pscAuthorizedService"

驗證連線

確認目錄背景中繼資料重新整理週期已順利完成，且命名空間和資料表已同步處理。

確認重新整理狀態顯示成功：

gcloud alpha biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
  --project="PROJECT_ID"

確認命名空間已同步：

gcloud alpha biglake iceberg namespaces list \
  --project="PROJECT_ID" \
  --catalog="FEDERATED_CATALOG_NAME"

確認命名空間中的資料表已同步：

gcloud alpha biglake iceberg tables list \
  --project="PROJECT_ID" \
  --catalog="FEDERATED_CATALOG_NAME" \
  --namespace="NAMESPACE_ID"

為 Snowflake Horizon Catalog 設定跨雲端連線 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

支援的目錄詳細資料

限制和注意事項

一般工作流程

設定 Cross-Cloud Interconnect (選用)

內部區域 Proxy 網路負載平衡器

直接端點

設定聯盟

設定驗證機制

以密鑰為準 (PAT)

Workload Identity Federation

建立聯合目錄

控制台

gcloud CLI

以密鑰為準 (PAT)

公用網際網路 (無 CCI)

客戶擁有 (CCI)

Workload Identity Federation

公用網際網路 (無 CCI)

客戶擁有 (CCI)

完成驗證設定

以密鑰為準 (PAT)

Workload Identity Federation

完成私人互連設定 (僅限 Cross-Cloud Interconnect)

控制台

gcloud CLI

驗證連線

後續步驟

為 Snowflake Horizon Catalog 設定跨雲端連線