系统参数

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 方法。部分网络代理不接受其中一些 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 包含发出请求的原因，适合在审计日志中记录。支持案例票据编号就是一个示例原因。对于审核日志，原因中的字符决定了原因在附加到日志条目之前是否会进行 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-06 更新了 x-goog-request-params 的文档。
  • 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 系统参数。