Parámetros del sistema

La plataforma de la API de Google proporciona un conjunto de funcionalidades comunes a todas las API de Google creadas con la plataforma. Para usarlas y controlarlas, la plataforma cuenta con un conjunto predefinido y especial de parámetros de solicitudes, que se conocen como parámetros del sistema. Estos parámetros están disponibles en todas las API de REST y de gRPC de Google. Además, se pueden especificar mediante un parámetro de búsqueda HTTP o un encabezado HTTP. Para las API de gRPC de Google, solo se admiten los encabezados HTTP.

La mayoría de los usuarios no necesitarán usar estos parámetros directamente. Sin embargo, las bibliotecas cliente que proporciona Google los suelen usar. Si necesitas escribir un código personalizado a fin de acceder de forma directa a las API de Google, los parámetros del sistema pueden ser útiles para realizar tareas como el control de impresión con sangría de JSON o la especificación de claves de API.

Asignación HTTP

Para las solicitudes HTTP, los parámetros del sistema se envían como parámetros de búsqueda de URL o encabezados de solicitudes HTTP. Por ejemplo, si tienes el parámetro del sistema $foo, se envía como ?$foo=xxx en la URL o ?%24foo=xxx si está codificado como URL. Consulta la siguiente tabla para obtener más detalles.

Nota: se agrega el prefijo del nombre $ para evitar conflictos con los parámetros de solicitud normales.

Asignación gRPC

Para las solicitudes gRPC, los parámetros del sistema se envían como encabezados de solicitudes HTTP con claves en minúsculas. Consulta la siguiente tabla para obtener más detalles.

Definiciones

Nota: Si deseas solicitar un rango de bytes específico de un recurso (por ejemplo, durante una descarga de contenido multimedia), usa el encabezado Range HTTP estándar (como Range: bytes=0-1023). No es un parámetro del sistema de Google y no tiene un parámetro de consulta estándar equivalente.

En la siguiente tabla, se enumeran todos los parámetros del sistema y sus definiciones.

Parámetro de consulta de URL	Encabezado HTTP/gRPC	Descripción
	Authorization	Credenciales de autenticación. Consulta Descripción general de la autenticación para obtener más información.
$alt, alt		Formato de respuesta alternativa. Los valores admitidos son json (predeterminado), media, proto y sse (transmisiones JSON).
$apiVersion	X-Goog-Api-Version	Es la versión de la API que se usará. No todas las APIs admiten este parámetro. Consulta la documentación de la API antes de usarlo.
$.xgafv		Es el formato de error JSON. Los valores admitidos son 1 y 2 (predeterminado). El formato de error 1 solo debe usarse en las bibliotecas cliente de las APIs de Google.
$callback, callback		Parámetro de devolución de llamada de JSONP.
$ct	Content-Type	Es la anulación del encabezado de la solicitud del tipo de contenido HTTP.
$fields, fields	X-Goog-FieldMask	FieldMask se usa para filtrar las respuestas. Si está vacío, se deben devolver todos los campos, a menos que se indique lo contrario en la documentación.
	X-HTTP-Method-Override	El método HTTP previsto para la solicitud. Algunos proxies de red no aceptan todos los métodos HTTP.
$key, key	X-Goog-Api-Key	Clave de API de Google. Consulta https://cloud.google.com/docs/authentication/api-keys para obtener más detalles.
passwd, password		Es un parámetro reservado para evitar poner contraseñas en URL.
$prettyPrint, prettyPrint		Es la respuesta de JSON en un formato legible. Los valores admitidos son true y false (predeterminado).
quotaUser	X-Goog-Quota-User	Es un identificador de seudo usuario para cobrar cuotas por usuario. Si no se especifica, se usa la principal autenticada. Si no hay una principal autenticada, se usará la dirección IP del cliente. Cuando se especifica, se debe usar una clave de API válida con restricciones del servicio para identificar el proyecto de cuota. De lo contrario, se ignorará este parámetro.
$outputDefaults		Se generan valores predeterminados proto para las respuestas de JSON.
$unique		Parámetro de consulta único para inhabilitar el almacenamiento en caché de solicitudes.
	X-Goog-Api-Client	Es la identificación del cliente de API. El valor es una lista separada por espacios de strings NAME "/" SEMVER, en la que NAME solo debe contener letras minúsculas, dígitos y guiones, y SEMVER debe ser una string de versión semántica. Por ejemplo: X-Goog-Api-Client: python/3.5.0 grpc-google-pubsub-v1/0.1.0-beta2 linux/2.7.0.
	X-Goog-Request-Reason	Contiene un motivo para realizar la solicitud, que se debe registrar en el registro de auditoría. Un motivo de ejemplo sería un número de ticket de casos de ayuda. En el caso de los registros de auditoría, los caracteres del motivo determinan si este se codifica en base64 antes de adjuntarse a la entrada de registro. Los motivos que incluyen solo letras, dígitos y espacios se conservan como texto sin formato. Los motivos que incluyen otros caracteres se codifican en base64.
$userProject	X-Goog-User-Project	Un proyecto especificado por el emisor para fines de cuota y facturación. El llamador debe tener el permiso serviceusage.services.use en el proyecto.
	X-Server-Timeout	Es el tiempo de espera (expresado en segundos con un número de punto flotante) para que el servidor termine de procesar la solicitud. Este parámetro del sistema solo se aplica a las APIs de REST para las que no se aplica el tiempo de espera del cliente.
	x-goog-request-params	Pasa parámetros adicionales para las solicitudes de gRPC. El valor debe estar codificado como una cadena de consulta de URL (p.ej., key1=value1&key2=value2). Las claves y los valores específicos admitidos en este encabezado dependen del servicio y el método de la API de Google individuales que se llamen. No hay un conjunto único y universal de parámetros para este encabezado. Siempre consulta la documentación de la API específica con la que interactúas para determinar qué parámetros son compatibles o necesarios. Entre los usos comunes, se incluyen los siguientes: Información de enrutamiento: En el caso de los servicios regionalizados, este encabezado suele incluir parámetros para ayudar a los GFE a enrutar la solicitud al backend regional correcto. Esto suele implicar claves que coinciden con partes del nombre del recurso (p.ej., name=projects/my-proj/locations/us-central1, parent=projects/my-proj/locations/us-central1) o parámetros de ubicación explícitos (p.ej., grpc-location=locations/us-central1). Funcionalidad específica de la API: Por ejemplo, la API de BigQuery Storage Write usa el parámetro write_stream dentro de este encabezado para las llamadas de gRPC multirregionales que no son de EE.UU. (p. ej., x-goog-request-params: write_stream=projects/myproject/datasets/myds/tables/mytable/streams/mystream). Ejemplo: x-goog-request-params: name=projects/my-project/locations/us-central1&foo=bar

Registro de cambios

• 2026-10 Se publicó la documentación de X-Goog-Api-Version.
• 2026-06: Se actualizó la documentación de x-goog-request-params.
• 2021-11 Se publicó la documentación de x-goog-request-params.
• 2021-02: Se publicó la documentación de quotaUser.
• Parámetros de consulta obsoletos de OAuth 2.0 de 2020-07.
• 2019-10 Se incorporó el parámetro del sistema X-Server-Timeout.
• 2017-10 Se incorporó el parámetro del sistema X-Goog-User-Project.