本頁說明如何使用用戶端程式庫存取 Google API。
使用支援的語言,透過用戶端程式庫更輕鬆地存取 Google Cloud API。您可以直接向伺服器發出原始要求來使用 API,但用戶端程式庫提供的簡化功能可大幅減少您需要編寫的程式碼量。 Google Cloud 驗證作業尤其如此,因為用戶端程式庫支援應用程式預設憑證 (ADC)。
如果您接受來自外部來源 (例如客戶) 的憑證設定 (JSON、檔案或串流),請參閱使用外部來源憑證設定時的安全規定。
搭配用戶端程式庫使用應用程式預設憑證
如要使用應用程式預設憑證驗證應用程式,您必須先為應用程式執行的環境設定 ADC。使用用戶端程式庫建立用戶端時,用戶端程式庫會自動檢查您提供給 ADC 的憑證,並使用這些憑證向程式碼使用的 API 進行驗證。您的應用程式不需要明確驗證或管理權杖,驗證程式庫會自動管理這些需求。
在本地開發環境中,您可以使用 gcloud CLI 透過使用者憑證或透過服務帳戶模擬設定 ADC。如果是實際工作環境,請附加服務帳戶來設定 ADC。
建立用戶端範例
下列程式碼範例會建立 Cloud Storage 服務的用戶端。 您的程式碼可能需要不同的用戶端;這些範例僅用於說明如何建立及使用用戶端,不必使用任何程式碼明確驗證。
您必須先完成下列步驟,才能執行下列範例:
Go
Java
Node.js
PHP
Python
Ruby
搭配用戶端程式庫使用 API 金鑰
您只能搭配接受 API 金鑰的 API 用戶端程式庫使用 API 金鑰。此外,API 金鑰不得設有 API 限制,導致無法用於 API。
如要進一步瞭解在快捷模式中建立的 API 金鑰,請參閱 Google Cloud 快捷模式常見問題。
本範例使用接受 API 金鑰的 Cloud Natural Language API,示範如何向程式庫提供 API 金鑰。
C#
如要執行這個範例,您必須安裝 Natural Language 用戶端程式庫。
C++
如要執行這個範例,您必須安裝 Natural Language 用戶端程式庫。
Go
如要執行這個範例,您必須安裝 Natural Language 用戶端程式庫。
Node.js
如要執行這個範例,您必須安裝 Natural Language 用戶端程式庫。
Python
如要執行這個範例,您必須安裝 Natural Language 用戶端程式庫。
在應用程式中使用 API 金鑰時,請確保儲存和傳輸期間的金鑰安全無虞。公開 API 金鑰可能會導致帳戶產生非預期費用。詳情請參閱「管理 API 金鑰的最佳做法」。
使用外部來源的憑證設定時的安全需求
一般來說,您可以使用 gcloud CLI 指令或 Google Cloud 控制台產生憑證設定。舉例來說,您可以使用 gcloud CLI 產生本機 ADC 檔案或登入設定檔。同樣地,您可以使用 Google Cloud 控制台建立及下載服務帳戶金鑰。
不過,在某些情況下,憑證設定是由外部實體提供,這些憑證設定用於向 Google API 進行驗證。
部分類型的憑證設定包含端點和檔案路徑,驗證程式庫會使用這些資訊取得權杖。接受外部來源的憑證設定時,您必須先驗證設定,才能使用。如果未驗證設定,惡意行為人可能會使用憑證入侵您的系統和資料。
驗證外部來源的憑證設定
驗證外部憑證的方式取決於應用程式接受的憑證類型。
驗證服務帳戶金鑰
如果應用程式只接受服務帳戶金鑰,請使用服務帳戶金鑰專用的憑證載入器,如下列範例所示。特定類型的憑證載入器只會剖析服務帳戶金鑰的欄位,不會暴露任何安全漏洞。
C#
var saCredential = ServiceAccountCredential.FromServiceAccountData(stream);
C++
auto cred = google::cloud::MakeServiceAccountCredentials(json)
Java
ServiceAccountCredentials credentials =
ServiceAccountCredentials.fromStream(credentialsStream);
Node.js
const keys = JSON.parse(json_input)
const authClient = JWT.fromJSON(keys);
PHP
cred = new Google\Auth\Credentials\ServiceAccountCredentials($scope, $jsonKey);
Python
cred = service_account.Credentials.from_service_account_info(json_data)
Ruby
creds = Google::Auth::ServiceAccountCredentials.make_creds(json_key_io: json_stream)
如果無法使用特定類型的憑證載入器,請確認 type
欄位的值為 service_account
,藉此驗證憑證。如果 type
欄位的值為其他值,請勿使用服務帳戶金鑰。
驗證其他憑證設定
如果應用程式接受服務帳戶金鑰以外的任何類型憑證,則必須進行額外驗證。其他類型的憑證設定範例包括 ADC 憑證檔案、Workload Identity 聯盟憑證檔案,或 Workforce Identity 聯盟登入設定檔。
下表列出憑證中可能出現的欄位,您需要驗證這些欄位。並非所有憑證設定都會顯示這些欄位。
欄位 | 目的 | 預期值 |
---|---|---|
service_account_impersonation_url |
驗證程式庫會使用這個欄位存取端點,為要模擬的服務帳戶產生存取權杖。 | https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/service account email:generateAccessToken |
token_url |
驗證程式庫會將外部權杖傳送至這個端點,以交換同盟存取權杖。 | https://sts.googleapis.com/v1/token |
credential_source.file |
驗證程式庫會從這個欄位指定位置的檔案讀取外部權杖,並傳送至 token_url 端點。
|
含有外部權杖的檔案路徑。您應該會認出這個路徑。 |
credential_source.url |
傳回外部權杖的端點。驗證程式庫會將要求傳送至這個網址,並將回應傳送至 token_url 端點。 |
下列其中一項:
|
credential_source.executable.command |
如果 GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 環境變數設為 1 ,驗證程式庫會執行這項指令或可執行檔。 |
可執行檔或指令,會傳回外部權杖。 您應該會認得這項指令,並驗證其安全性。 |
credential_source.aws.url |
驗證程式庫會向這個網址發出要求,以擷取 AWS 安全權杖。 |
下列任一確切值:
|
credential_source.aws.region_url |
驗證程式庫會向這個網址發出要求,以擷取有效的 AWS 區域。 |
下列任一確切值:
|
credential_source.aws.imdsv2_session_token_url |
驗證程式庫會向這個網址發出要求,以擷取 AWS 工作階段權杖。 |
下列任一確切值:
|