系統參數

Google 的 API 平台定義了系統參數，用於控制 REST 和 gRPC API 的常見功能，例如 API 金鑰、回應欄位遮罩、配額歸因和 JSON 格式。視通訊協定而定，您會以網址查詢參數或 HTTP 標頭的形式，將系統參數傳遞至服務。您可以在編寫自訂程式碼時直接指定這些參數，但 Google 提供的用戶端程式庫等工具會自動處理許多參數。

HTTP 對應

如果是 HTTP 要求，系統參數會以網址查詢參數或 HTTP 要求標頭的形式傳送。舉例來說，如果您有系統參數 $foo，系統會將其以 ?$foo=xxx 形式傳送至網址，或以 ?%24foo=xxx 形式傳送至網址 (如果網址已編碼)。詳情請參閱下表。

gRPC 對應

如果是 gRPC 要求，系統參數會以 HTTP 要求標頭的形式傳送，且鍵值為小寫。詳情請參閱下方表格。

定義

下表列出所有系統參數及其定義。

網址查詢參數 HTTP/gRPC 標頭 說明
Authorization 驗證憑證。詳情請參閱「驗證總覽」。
$alt、
alt		 替代回應格式。支援的值為 json (預設)、media、proto、sse (JSON 串流)。
$apiVersion X-Goog-Api-Version 要使用的 API 端點，並非所有 API 都支援這個參數，使用前請先查看 API 說明文件。
$.xgafv JSON 錯誤格式。支援的值為 1、2 (預設值)。錯誤格式 1 僅適用於 Google API 用戶端程式庫。
$callback、
callback		 JSONP 回呼參數。
$ct Content-Type 覆寫 HTTP Content-Type 要求標頭。
$fields、
fields		 X-Goog-FieldMask 用於篩選回應的 FieldMask。如果留空，除非另有說明，否則應傳回所有欄位。
X-HTTP-Method-Override 要求要使用的 HTTP 方法。某些網路 Proxy 只接受部分 HTTP 方法。
$key、
key		 X-Goog-Api-Key Google API 金鑰。詳情請參閱 https://cloud.google.com/docs/authentication/api-keys。
passwd、
password		 保留，避免在網址中加入密碼。
$prettyPrint、
prettyPrint		 美化 JSON 回應。支援的值為 true (預設) 和 false。
quotaUser X-Goog-Quota-User 虛擬使用者 ID，用於計算每位使用者的配額。如未指定，系統會使用已驗證的主體。如果沒有經過驗證的主體，系統會使用用戶端 IP 位址。如要指定配額專案，必須使用設有服務限制的有效 API 金鑰。否則系統會忽略這個參數。
$outputDefaults JSON 回應的強制輸出 proto 預設值。
$unique 用於停用要求快取的不重複查詢參數。
X-Goog-Api-Client API 用戶端身分識別資訊。值是以空格分隔的 NAME "/" SEMVER 字串清單，其中 NAME 只能包含小寫字母、數字和「-」，SEMVER 則應為語意版本字串。例如：X-Goog-Api-Client: python/3.5.0 grpc-google-pubsub-v1/0.1.0-beta2 linux/2.7.0。
X-Goog-Request-Reason 包含發出要求的理由，會記錄在稽核記錄中。例如客服案件編號。如果是稽核記錄，原因中的字元會決定原因是否要先經過 base64 編碼，再附加至記錄項目。如果原因只包含英文字母、數字和空格，系統會以純文字形式保留。包含其他字元的原因會以 base64 編碼。
$userProject X-Goog-User-Project 用於配額與帳單的呼叫者指定專案。呼叫端必須具備專案的「serviceusage.services.use」權限。
X-Server-Timeout 伺服器完成處理要求的逾時時間 (以秒為單位，浮點值)。這個系統參數僅適用於不適用用戶端逾時的 REST API。
x-goog-request-params 傳遞 gRPC 要求的其他參數。值必須經過網址查詢字串編碼 (例如 key1=value1&key2=value2)。

這個標頭支援的特定鍵和值，取決於所呼叫的個別 Google API 服務和方法。這個標頭沒有單一通用的參數組合。請務必參閱您要互動的特定 API 說明文件，判斷支援或必要的參數。

常見用途包括：
  • 轉送資訊：如果是區域化服務，這個標頭通常會包含參數，協助 GFE 將要求轉送至正確的區域後端。這通常涉及與資源名稱部分相符的鍵 (例如 name=projects/my-proj/locations/us-central1、parent=projects/my-proj/locations/us-central1) 或明確的位置參數 (例如 grpc-location=locations/us-central1)。
  • API 專屬功能：舉例來說，BigQuery Storage Write API 會在標頭中使用 write_stream 參數，進行非美國多區域 gRPC 呼叫 (例如 x-goog-request-params: write_stream=projects/myproject/datasets/myds/tables/mytable/streams/mystream)。
範例：
x-goog-request-params: name=projects/my-project/locations/us-central1&foo=bar

變更記錄

  • 2026 年 10 月：發布 X-Goog-Api-Version 說明文件。
  • 2026 年 6 月：更新「x-goog-request-params」的說明文件。
  • 2021 年 11 月：發布 x-goog-request-params 的說明文件。
  • 2021 年 2 月：發布 quotaUser 的說明文件。
  • 2020 年 7 月：淘汰 OAuth 2.0 查詢參數。
  • 2019 年 10 月：推出 X-Server-Timeout 系統參數。
  • 2017 年 10 月：推出 X-Goog-User-Project 系統參數。