系統參數

Google 的 API 平台為使用該平台建立的所有 Google API 提供一組通用功能。為了使用及控制這類功能，該平台預先訂立了一組稱為「系統參數」的要求參數。這些參數可在所有 Google REST API 和 gRPC API 中使用。系統參數可透過 HTTP 查詢參數或 HTTP 標頭指定。如果是 Google gRPC API，則只能透過 HTTP 標頭指定。

大部分使用者不需要直接使用這些參數。但 Google 提供的用戶端程式庫常常會用到。如果您需要編寫自訂程式碼來直接存取 Google API，系統參數可發揮不少功用，例如協助控制 JSON 美化作業或用來指定 API 金鑰。

HTTP 對應

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

gRPC 對應

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

定義

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

網址查詢參數	HTTP/gRPC 標頭	說明
	Authorization	驗證憑證。詳情請參閱「驗證總覽」。
$alt、 alt		替代回應格式。支援的值為 json (預設值)、media、proto、sse (JSON 串流)。
$.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 要求的其他參數。例如：x-goog-request-params: service=pubsub.googleapis.com&release=2021-11-01r0。

變更記錄

• 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 系統參數。