本頁說明如何使用用戶端程式庫存取 Google API。
用戶端程式庫可讓您更輕鬆地使用支援的語言存取 Google Cloud API。您可以直接向伺服器發出原始要求,以便使用 Google Cloud API,但用戶端程式庫提供簡化功能,可大幅減少需要編寫的程式碼數量。這一點在驗證方面尤其重要,因為用戶端程式庫支援應用程式預設憑證 (ADC)。
如果您接受來自外部來源 (例如客戶) 的憑證設定 (JSON、檔案或串流),請詳閱使用外部來源的憑證設定時的安全性規定。
搭配用戶端程式庫使用應用程式預設憑證
如要使用應用程式預設憑證驗證應用程式,您必須先為應用程式執行環境設定 ADC。使用用戶端程式庫建立用戶端時,用戶端程式庫會自動檢查您提供給 ADC 的憑證,並使用這些憑證驗證程式碼使用的 API。您的應用程式不需要明確驗證或管理權杖;這些需求會由驗證程式庫自動管理。
如果是本地開發環境,您可以使用使用者憑證設定 ADC,也可以使用 gcloud CLI 以服務帳戶冒用身分設定 ADC。對於實際工作環境,您可以附加服務帳戶來設定 ADC。
建立用戶端範例
下列程式碼範例會為 Cloud Storage 服務建立用戶端。您的程式碼可能需要不同的用戶端;這些範例僅旨在說明如何建立用戶端,並在不使用任何程式碼明確驗證的情況下使用。
您必須先完成下列步驟,才能執行下列範例:
Go
Java
Node.js
PHP
Python
Ruby
搭配用戶端程式庫使用 API 金鑰
您只能在接受 API 金鑰的 API 中,搭配用戶端程式庫使用 API 金鑰。此外,API 金鑰不得設有 API 限制,以免無法用於 API。
如要進一步瞭解在快捷模式中建立的 API 金鑰,請參閱 Google Cloud 快捷模式常見問題。
本範例使用 Cloud Natural Language API (可接受 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 工作階段權杖。 |
下列任一值:
|