examlab .net 用最有效率的方法，考取最有價值的證照
支持
本篇導覽 約 27 分鐘

Cloud SDK 與客戶端函式庫

5,400 字 · 約 27 分鐘閱讀 ·

Professional Cloud Architect 使用 Google Cloud 客戶端函式庫、理解 API 類型差異及實施強健應用程式級別整合的指南。

立即做 20 題練習 → 免費 · 不用註冊 · PCA

雲端整合簡介

對於 Professional Cloud Architect 來說，設計應用程式如何與 Google Cloud 服務互動是一項關鍵的架構決策。您必須建議團隊在 Cloud Client Libraries、Google API Client Libraries 或直接呼叫 REST/gRPC 之間做出選擇。

目標是在應用程式程式碼與 GCP 後端之間提供可靠、高效能且安全的連接。

一套工具集，包含 gcloud、gsutil、bq、kubectl（透過 gke-gcloud-auth-plugin），以及可選元件如 alpha、beta、nomos，以及 terraform（透過外掛）。它是管理 GCP 資源並透過 Application Default Credentials 為客戶端驗證的標準本機與伺服器介面。

白話文解釋（Plain English Explanation）

比喻 1 — 流利的翻譯官（客戶端函式庫）

想像您在國外的餐廳。直接呼叫 REST API 就像使用字典查找每一個單字，速度慢且容易出錯。使用客戶端函式庫（例如 Python 的 google-cloud-storage）就像桌邊有一位流利的翻譯官。您只需說「我要牛排」，翻譯官就會為您處理文法、禮貌用語、不穩服務時的重試以及付款。

比喻 2 — 員工識別證（ADC）

Application Default Credentials (ADC) 就像一張公司識別證。當您走進辦公室（雲端環境）時，不必一直告訴別人您是誰。您的證件已經別在襯衫上了。「辦公室」(SDK) 會透過 metadata server 自動辨識您的證件，並讓您進入授權進入的房間（如 BigQuery、Spanner、Pub/Sub）— 不需要 JSON 金鑰檔。

比喻 3 — 渦輪增壓 vs. 標準引擎（gRPC vs REST）

REST 就像標準引擎。它可靠、每個人都知道如何修理，且適用於任何燃料 (HTTP/1.1)。gRPC（許多 Cloud Client Libraries 在底層使用 — 例如 Spanner、Pub/Sub、Bigtable）就像渦輪增壓引擎。它使用高壓燃料 (HTTP/2) 和特殊的緊湊燃料混合物 (Protocol Buffers)，能以更少的力氣跑得更快、承載更多負荷。

客戶端函式庫類型

Google 提供兩個主要的函式庫層級：

  1. Google Cloud Client Libraries (推薦):
    • 針對特定語言（Java、Python、Go、Node.js、.NET、Ruby、PHP、C++）手寫。
    • 提供慣用程式碼（例如：在 Node 中使用 Promises，在 Go 中使用 Goroutines）。
    • 自動處理底層細節，如重試、身分驗證和分頁。
  2. Google API Client Libraries (基於探索):
    • 根據 API 探索文件產出。
    • 涵蓋幾乎所有 Google API（包括較舊的 API，例如 Google Workspace Admin SDK）。
    • 與 Cloud Client Libraries 相比，較不具備語言慣用法。

對 PCA 情境，當 Cloud Client Libraries 存在時請永遠優先建議。它是唯一內建指數型退避自動重試、deadline 傳播，以及對高 RPS 服務（如 Cloud Spanner、Pub/Sub、Bigtable）使用 gRPC 長連線的層級。Discovery-based 函式庫並沒有這些屬性。

gcloud CLI 元件：alpha、beta 與 Component Install

gcloud 是模組化的。出廠的二進位檔只內含穩定範圍，其餘都活在按需安裝的元件 (components) 中。

Stable vs alpha vs beta

  • gcloud <command> — 穩定、GA。背後是 GA API，可安全用於自動化。
  • gcloud beta <command> — pre-GA，介面可能變動但不太會被移除。適合先試用 Cloud Run 或 Vertex AI 的新旋鈕。
  • gcloud alpha <command> — 實驗性，常有 breaking changes。永遠不要把 alpha 指令寫進正式 CI/CD。

管理元件

gcloud components list              # 顯示已安裝與可用元件
gcloud components install kubectl   # 安裝由 gcloud 發行的 kubectl
gcloud components install beta      # 啟用 beta 介面
gcloud components update            # 更新所有已安裝元件
gcloud components remove app-engine-python

元件涵蓋 kubectl、gke-gcloud-auth-plugin、bq、gsutil、cloud_sql_proxy、cbt（Bigtable CLI）、app-engine-python、app-engine-java、pubsub-emulator、bigtable-emulator、datastore-emulator、nomos（Config Sync）、以及 skaffold。

在透過 apt 套件庫 (google-cloud-cli 套件) 安裝的 Debian/Ubuntu 系統上，gcloud components install 會被停用 — 套件管理器擁有元件生命週期，您必須改用 apt install google-cloud-cli-kubectl。架構師如果把 gcloud components install 寫進 Debian image 的 cloud-init，會看到無聲失敗。需要在 Linux 伺服器上自管元件，請改用壓縮檔 (tarball) 安裝器。

Google Cloud SDK 安裝模式

支援四種安裝模式，正確選擇取決於工作負載的邊界。

1. 互動工作站（開發者筆電）

從 dl.google.com/dl/cloudsdk/channels/rapid/downloads/ 下載版本化壓縮檔，執行 ./install.sh，讓它修改您的 shell rc。可獲得自管的 gcloud components 與最簡單的更新流程。

2. 伺服器 / CI runner

使用 Linux 套件管理器套件庫 (apt/yum/dnf) 取得符合 SOC-2 的簽章套件。鎖定大版本 (google-cloud-cli=445.*)，避免一夜之間 reproducible build 默默壞掉。

3. 容器化 CI/CD

從 gcr.io/google.com/cloudsdktool/cloud-sdk:<version>-slim 拉取鎖定 tag。-slim 變體不含可選元件，可在 multi-stage 中以 RUN gcloud components install 加入需要的元件。

4. Cloud Shell

gcloud、gsutil、bq、kubectl、terraform、nomos、skaffold 及語言執行環境（Python/Go/Node/Java）皆預先安裝且預先驗證。最適合做 ad-hoc 管理任務，無需 bootstrapping 認證。

在 GCP 上用 Terraform 時，不要透過 gcloud components 安裝 Terraform（其實也不會配發到那裡）。請使用 HashiCorp 官方二進位檔或 tenv/tfenv。Terraform 讀取 ADC 的方式與 Cloud Client Libraries 完全相同 — 設定 GOOGLE_APPLICATION_CREDENTIALS、執行 gcloud auth application-default login、或仰賴掛在 runner 上的 workload identity。這樣 Terraform google provider 的身分驗證就和您的應用程式碼一致。

跨語言的客戶端函式庫

支援的語言矩陣一致，但每個語言都有值得注意的慣用差異。

Python (google-cloud-*)

from google.cloud import storage
client = storage.Client()          # 自動讀取 ADC
bucket = client.bucket("my-data")

使用 google-auth + grpcio。執行緒沒問題；asyncio 請改用 *-async 變體（例如 google-cloud-storage async 透過 gcloud-aio-storage）。

Go (cloud.google.com/go/*)

ctx := context.Background()
client, _ := storage.NewClient(ctx)

context-aware、慣用 deadlines、streaming gRPC 效率很高。是高 RPS 服務的首選。

Java (com.google.cloud:google-cloud-*)

使用 Gax（Google API extensions）做重試。請選用 BOM (libraries-bom) 讓所有 google-cloud-* artifact 版本對齊，避免 transitive dependency 間的 NoSuchMethodError。

Node.js (@google-cloud/*)

Promise-based，Pub/Sub 與 Storage 都暴露 streams。請尊重 keepAlive 並讓整個 process 共用一個 client — 每個 request 都建一個會造成 TCP/HTTP2 抖動。

對於高 QPS 的服務（Pub/Sub、Bigtable、Spanner），請在 process 生命週期中重複使用單一長壽 client instance。Client 擁有 gRPC channel pool；每個 request 建立新 client 會打壞連線池，造成 p99 延遲爆衝。這是團隊導入 Cloud Client Libraries 時最常見的架構檢視議題。

Application Default Credentials (ADC) 流程

這是 PCA 考試的核心概念。ADC 是 Cloud Client Libraries（以及 gcloud）自動尋找認證的策略。

搜尋順序：

  1. GOOGLE_APPLICATION_CREDENTIALS 環境變數（指向 JSON 金鑰檔或 external account 設定檔）。
  2. 由 Google Cloud CLI 提供的認證 (gcloud auth application-default login → 快取於 ~/.config/gcloud/application_default_credentials.json)。
  3. 附加服務帳戶的 Metadata Server，位於 http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token（適用於 GCE、開啟 Workload Identity 的 GKE、Cloud Run、Cloud Functions、App Engine）。

ADC 順序：(1) ENV 變數 → (2) gcloud 使用者認證 → (3) Metadata Server。PCA 考試就是考這個順序。若題目描述「程式在本機可跑，部署到 Cloud Run 就失敗」，請找有沒有殘留的 GOOGLE_APPLICATION_CREDENTIALS 環境變數指向不存在的金鑰檔 — 它會在 metadata server 被查詢之前就 short-circuit 步驟 3。

架構師規則： 在生產環境中，切勿使用 JSON 金鑰檔。請依賴中繼資料伺服器（步驟 3）。這可以避免金鑰洩漏或被硬編碼在原始碼控制系統中的風險。對於 on-prem 或 AWS 工作負載，請使用 Workload Identity Federation 搭配 external account 認證檔案 — 同樣不需要為 Google 服務帳戶匯出 JSON 金鑰。

gcloud 設定組合：多專案、多帳戶

gcloud config configurations 可維護命名的設定檔 — 當架構師在不同客戶專案間切換時非常關鍵。

gcloud config configurations create prod-eu
gcloud config set project my-prod-eu
gcloud config set account [email protected]
gcloud config set compute/region europe-west1

gcloud config configurations list
gcloud config configurations activate prod-eu

每個 configuration 儲存自己的專案、帳戶、region、zone，與元件特定屬性（如 core/log_http、auth/disable_credentials）。狀態存在 ~/.config/gcloud/configurations/。

模式：依環境分 configuration

  • dev → 沙盒專案、個人帳戶、us-central1
  • staging → staging 專案、透過金鑰冒充 deploy SA
  • prod-eu、prod-us → 生產專案、僅冒充 ([email protected])

模式：依客戶分 configuration

單兵顧問與 MSP 會為每個租戶建一個 configuration，避免指令跨客戶專案外洩。可搭配 CLOUDSDK_ACTIVE_CONFIG_NAME 將一個 config 鎖定於某 shell session 期間。

Cloud Shell vs 本機 SDK

PCA 上常見的決策是：要不要讓開發者使用 Cloud Shell，還是讓他們本機安裝 SDK。

面向 Cloud Shell 本機 SDK
身分驗證 以登入使用者預先驗證 需要 gcloud auth login + ADC 設定
持久性 5 GB $HOME（Persistent Disk），其他目錄為臨時 完整本機控制
網路外送 來自 Google 管理的 VPC，可經 proxy 連到內部服務 來自開發者網路
閒置 timeout 約 20 分閒置斷線，約 1 小時回收 VM 無
客製化 .customize_environment 腳本 + cloudshell_open 完全自由
費用 Google 帳戶持有者免費 SDK 免費；工作站自付
使用情境 Ad-hoc 管理、IAM break-glass、Demo CI/CD agent、日常開發

Cloud Shell 不適合長時間運行的 CI/CD runner：session 會終止、臨時檔案系統會遺失 build cache、且沒有 SLA。CI 請用自管 runner 或鎖定 cloud-sdk image 的 Cloud Build。若要透過強化的入口操作生產專案的互動管理工作，使用 Cloud Shell + 停用 gcloud auth login --update-adc + operator 帳戶強制 2SV 是站得住腳的模式。

gRPC vs REST 客戶端差異

許多 Google Cloud Client Libraries 底層預設使用 gRPC，但少數（Storage JSON API、BigQuery）預設使用 REST。

gRPC transport

  • HTTP/2 多工 — 多個並行呼叫共用一條 TCP 連線。
  • Protocol Buffers 二進位編碼 — 比 JSON 更小、解析更快。
  • 雙向 streaming — Pub/Sub StreamingPull 與 Speech-to-Text streaming 必備。
  • Deadlines 從 client 一路傳播到巢狀的 service 呼叫。

REST/JSON transport

  • 用 curl、httpie、瀏覽器 DevTools 更易調試。
  • 對於 HTTP/2 支援不一致的 proxy/CDN 場景更友善。
  • Cloud Storage 下載預設走 JSON API；只有 gRPC API 支援透過新的 media downloader 對 Compute Engine 做 zero-copy 下載。

在函式庫中選擇

部分函式庫可讓您選擇。例如 Cloud Spanner Java 提供 SessionPoolOptions 與 gRPC-only transport；Storage Python 可透過 google-cloud-storage[grpc] extras 選用 gRPC Storage API。99% 情境下預設值就是正確答案 — 只有在量測到吞吐量問題時才改。

在 Google Cloud Load Balancer 後方，gRPC 需要後端服務全程 HTTP/2 與 gRPC health check。如果把 Cloud Client Library 用戶端放在以 HTTP/1.1 設定的 Internal HTTP(S) Load Balancer 後方，gRPC 會以 UNAVAILABLE 連線失敗。從 sidecar proxy 遷移到 L7 GCLB 時，這是最常見的生產事故之一。

重試、Timeout 與 Deadline 設定

Cloud Client Libraries 出廠就有合理預設值，但架構師必須知道如何為 SLO 敏感工作負載調校。

預設重試 profile

  • 冪等讀取 (get*、list*、read*)：遇到 UNAVAILABLE、DEADLINE_EXCEEDED、RESOURCE_EXHAUSTED、ABORTED 自動重試。
  • 非冪等寫入 (create*、insert*)：只有呼叫攜帶 client 提供的冪等 token（如 Pub/Sub ordering_key、Spanner transaction ID）時才會重試。
  • 退避：帶 jitter 的指數型，從 100 ms 起跳、上限 60 秒、預設 5 分鐘總 deadline。

調校

Python：

from google.api_core import retry
custom_retry = retry.Retry(initial=0.5, maximum=10.0, multiplier=2.0, deadline=30.0)
client.list_buckets(retry=custom_retry, timeout=20.0)

Go：

client, _ := storage.NewClient(ctx,
    option.WithGRPCDialOption(grpc.WithDefaultCallOptions(grpc.WaitForReady(true))))
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()

Java： 在建立 client 的 *Settings builder 上覆寫 RetrySettings。

實施強健的客戶端

向團隊建議時，請強調這些模式：

  1. 帶 jitter 的指數退避 — 防止同步化的重試風暴。
  2. 單次呼叫 Timeout 要與重試 deadline 區分 — 互動式 request 的單次嘗試必須在 2-5 秒內完成。
  3. 斷路器 (Circuit Breaker) 在應用程式層（如 resilience4j、gobreaker）做跨 region 的容錯切換。

Cloud Code IDE 外掛與開發者工具

Cloud Code 是 Google 維護的 VS Code 與 JetBrains IDE 外掛。它屬於更廣的 SDK 故事，PCA 考試也值得一提。

功能

  • YAML schema 驗證 — GKE、Cloud Run、Skaffold、Kustomize manifests。
  • 內建 gcloud 命令面板 — 不必切換到終端機。
  • 即時除錯 — Cloud Run 服務（透過 gcloud beta code dev）與 GKE pod（透過 skaffold debug）。
  • Secret Manager autocomplete — 用於 Cloud Functions 環境變數。
  • Gemini Code Assist 整合 — 在 IDE 中直接呈現 GCP 特定的程式碼片段。

架構面意義

對於導入 Cloud Run 或 GKE 的開發團隊，Cloud Code 把內迴圈回饋週期從「git push、等 Cloud Build」縮短到「存檔、在叢集內 hot reload」。當客戶詢問如何讓團隊在 Kubernetes 上有產出，又不想強迫每位開發者深入學 kubectl，請推薦 Cloud Code。

gcloud auth login vs gcloud auth application-default login

這兩個指令在 PCA 考試常被搞混。

gcloud auth login

  • 為 gcloud CLI 本身做驗證，讓 gcloud compute instances list 之類的指令可運作。
  • 將使用者認證存於 ~/.config/gcloud/credentials.db。
  • 不會填入 ADC — 從同一個 shell 呼叫 Spanner/BigQuery 的 Cloud Client Library 程式碼仍會失敗。

gcloud auth application-default login

  • 為應用程式碼（Cloud Client Libraries、Terraform、Python SDK 腳本）做驗證。
  • 將認證存於 ~/.config/gcloud/application_default_credentials.json。
  • 使用不同的 OAuth client ID，搭配廣域的 cloud-platform scope。
  • 不會影響 gcloud CLI 指令。

服務帳戶 impersonation（建議）

請避免在生產專案上為人類使用者保留長壽 ADC。改用：

gcloud config set auth/impersonate_service_account [email protected]
# 之後每次 gcloud 與 ADC 呼叫都會透過 IAM Credentials API 鑄造短壽 (1h) token。

這要求人類使用者在目標 SA 上持有 roles/iam.serviceAccountTokenCreator，並在 Cloud Audit Logs 留下完整稽核軌跡。

gcloud auth login ≠ gcloud auth application-default login。前者解鎖 gcloud 二進位檔；後者解鎖您的 Python/Go/Java 程式碼。考試上「我的 Terraform 一直噴 'could not find default credentials'，但 gcloud projects list 卻能跑」→ 答案是執行 gcloud auth application-default login，不是 gcloud auth login。

常見問題 — Cloud SDK 與客戶端函式庫

Q1. 我可以在本地機器上使用客戶端函式庫嗎？

可以。使用 gcloud auth application-default login 設定您的本地環境。函式庫會找到您的使用者認證，並像使用服務帳戶一樣使用它們。

Q2. 如果我的語言沒有 Google Cloud 客戶端函式庫怎麼辦？

您可以使用 Google API Client Library（如果有），或使用標準 HTTP 函式庫（如 Python 中的 requests 或 JS 中的 axios）直接呼叫 REST API。

Q3. 我該如何在程式碼中處理「速率限制」？

大多數客戶端函式庫會拋出特定的錯誤代碼（例如 429 Too Many Requests 或 gRPC RESOURCE_EXHAUSTED）。您應該擷取此異常並實施指數型退避的重試 — 不過函式庫對冪等呼叫已替您處理。

Q4. 使用客戶端函式庫需要付費嗎？

不需要。這些函式庫是開源且免費使用的。您只需為實際產生的 GCP 資源和 API 呼叫付費。

Q5. 為什麼我的「gRPC」連線在通過負載平衡器時失敗？

請確保您的負載平衡器端到端支援 HTTP/2。在 GCP 中，全球外部 HTTPS 負載平衡器支援 gRPC，但您必須在後端服務 (Backend Service) 上啟用 HTTP/2 並使用 gRPC health check。

Q6. 我要怎麼在 CI 中鎖定 gcloud 版本？

使用容器 image tag gcr.io/google.com/cloudsdktool/cloud-sdk:<version>-slim；或 apt 方式請鎖定 google-cloud-cli=<version>-0。永遠不要在 build 內執行 gcloud components update — 會讓 build 不可重現。

Q7. gsutil 與新的 gcloud storage 指令有什麼關係？

gcloud storage 是 gsutil 的下一代替代品。它預設使用 parallel composite uploads，大型轉檔可快上 94%，且與其他所有 gcloud 指令共用 ADC。gsutil 為了相容性會繼續存在，但新自動化請以 gcloud storage 為標準。

最後的架構師提示

在 PCA 考試中，尋找關於**「程式碼中身分驗證的最佳實務」的問題。答案幾乎總是「使用服務帳戶和 ADC」。如果問題是關於「服務間通訊的效能」**，請聯想到 「gRPC 和 Protocol Buffers」。永遠建議使用 Cloud Client Libraries 而非原始 REST 呼叫，因為它們內建了可靠性功能。並記住順序：GOOGLE_APPLICATION_CREDENTIALS → gcloud 使用者認證 → metadata server。

官方資料來源

更多 PCA 主題