如要瞭解 ADC 的運作方式 (包括憑證的位置),請參閱「應用程式預設憑證的運作方式」。
使用者憑證無效
如果 API 要求傳回錯誤訊息,指出這個 API 不支援使用者憑證、API 未在專案中啟用,或未設定配額專案,請參閱下列資訊。
Google Cloud API 有兩種:
資源導向 API:使用與所存取資源相關聯的專案,進行計費和配額。
用戶端 API:使用與用戶端相關聯的專案,存取帳單和配額資源。
提供使用者憑證,向用戶端 API 進行驗證時,必須指定要用於計費和配額的專案。這項專案稱為「配額專案」。
指定配額專案的方法有很多種,包括下列選項:
更新 ADC 檔案,使用其他專案做為配額專案:
gcloud auth application-default set-quota-project YOUR_PROJECT
如果您使用 gcloud CLI 呼叫 API,可以在 gcloud CLI 設定中設定配額專案:
gcloud config set billing/quota_project YOUR_PROJECT
如果您直接呼叫 REST 或 RPC API,請使用
x-goog-user-projectHTTP 標頭,在每項要求中指定配額專案。詳情請參閱「使用 REST 要求設定配額專案」。
您必須具備專案的 serviceusage.services.use IAM 權限,才能將其指定為計費專案。serviceusage.services.use 權限包含在 Service Usage Consumer IAM 角色中。如果您沒有任何專案的 serviceusage.services.use 權限,請與安全性管理員或專案擁有者聯絡,請對方在專案中授予您「服務使用情形消費者」角色。
如要進一步瞭解配額專案,請參閱「配額專案總覽」。如要瞭解設定配額專案的其他方式,請參閱「設定配額專案」。
憑證不正確
如果憑證似乎未提供預期的存取權,或找不到憑證,請檢查下列事項:
如果您使用 gcloud CLI 在本機環境中存取 Google Cloud ,請務必瞭解您使用的憑證。使用 gcloud CLI 時,您會使用透過
gcloud auth login指令提供給 gcloud CLI 的憑證。您並未使用提供給 ADC 的憑證。如要進一步瞭解這兩組憑證,請參閱「gcloud CLI 驗證設定和 ADC 設定」。請務必「僅」在使用服務帳戶金鑰或其他 JSON 檔案進行 ADC 時,設定
GOOGLE_APPLICATION_CREDENTIALS環境變數。環境變數指向的憑證優先於其他憑證,包括 Workload Identity Federation for GKE 的憑證。確認提出要求的主體具備必要的 IAM 角色。如果您使用的是使用者憑證,則必須將角色授予與使用者帳戶相關聯的電子郵件地址。如果您使用的是服務帳戶,該服務帳戶必須具備必要角色。
如果您在 API 要求中提供 API 金鑰,則無論在任何位置,API 金鑰的優先順序都高於 ADC。如果您已設定
GOOGLE_APPLICATION_CREDENTIALS環境變數,且使用 API 金鑰,API 可能會傳回警告,指出您提供給 ADC 的憑證遭到忽略。如要停止顯示警告,請取消設定GOOGLE_APPLICATION_CREDENTIALS環境變數。
驗證範圍不足
如果 API 要求傳回 Request had insufficient authentication scopes,且原因為 ACCESS_TOKEN_SCOPE_INSUFFICIENT,表示存取權杖不含 API 所需的範圍。授予 IAM 角色無法修正這項錯誤。
如要解決錯誤,請執行下列任一操作:
從錯誤詳細資料的
service和method欄位中找出 API。在方法的 API 參考資料或 Google API 的 OAuth 2.0 範圍中,找出 API 所需的範圍。大多數 Google Cloud API 都接受
https://www.googleapis.com/auth/cloud-platform範圍。Google Workspace API 需要專屬範圍。查看權杖具有哪些範圍。在發生錯誤的環境中執行下列指令,並查看
scope欄位:curl "https://oauth2.googleapis.com/tokeninfo?access_token=$(gcloud auth application-default print-access-token)"
在憑證取得範圍的位置,新增缺少的範圍:
Compute Engine:更新 VM 的存取權範圍。詳情請參閱「存取權範圍」和「附加服務帳戶並更新存取權範圍」。
GKE:建立具有必要存取權範圍的節點集區,或使用 Workload Identity Federation for GKE 處理工作負載。詳情請參閱「預設存取權範圍」和「從 GKE 工作負載向 Google Cloud API 進行驗證」。
程式碼:建立憑證時,將範圍新增至要求的範圍。如要瞭解各 API 所需的範圍,請參閱「Google API 適用的 OAuth 2.0 範圍」。
全網域委派:在 Google Workspace 管理控制台中,為服務帳戶的用戶端 ID 授權必要範圍,然後在建立憑證時,在程式碼中要求這些範圍。詳情請參閱「將網域層級的權限委派給服務帳戶」和「使用全網域委派功能控管 API 存取權」。
無法辨識的憑證類型
如果 API 要求傳回的錯誤包含 Error creating credential
from JSON. Unrecognized credential type,請確認您使用的是有效憑證。用戶端 ID 檔案不支援為 ADC 提供憑證。