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 方法。某些网络代理不接受所有 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 |
用于按用户配额收费的伪用户标识符。如果未指定，则使用经过身份验证的主账号。如果没有经过身份验证的主账号，系统将使用客户端 IP 地址。指定此标志时，必须使用具有服务限制的有效 API 密钥来标识配额项目。否则，此参数会被忽略。 |
$outputDefaults |
强制输出 JSON 响应的原始默认值。 | |
$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 |
包含发出请求的原因，适合在审计日志中记录。支持案例票据编号就是一个示例原因。 | |
$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-02 发布的
quotaUser文档。 - 2020-07 年弃用的 OAuth 2.0 查询参数。
- 2019-10 引入了
X-Server-Timeout系统参数。 - 2017-10 引入了
X-Goog-User-Project系统参数。