En este documento, se presentan técnicas que puedes usar para mejorar el rendimiento de tu aplicación. En algunos casos, se usan ejemplos de otras API o de API genéricas para ilustrar las ideas presentadas. Sin embargo, los mismos conceptos se pueden aplicar a la API de Resource Manager.
Compresión con gzip
Una forma fácil y conveniente de reducir el ancho de banda necesario para cada solicitud es habilitar la compresión gzip. Aunque esto requiere un tiempo de CPU adicional para descomprimir los resultados, la compensación con los costos de la red suele hacer que valga la pena.
Si quieres recibir una respuesta codificada en gzip, debes establecer un encabezado de Accept-Encoding
y modificar tu usuario-agente para que contenga la string gzip
. A continuación, se presenta un ejemplo de encabezados HTTP formados de manera correcta para habilitar la compresión gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)
Trabaja con recursos parciales
Otra forma de mejorar el rendimiento de tus llamadas a la API es solicitar solo la parte de los datos que te interesa. Esto permite que tu aplicación evite la transferencia, el análisis y el almacenamiento de campos innecesarios, por lo que puede usar recursos como la red, la CPU y la memoria con más eficiencia.
Respuesta parcial
De forma predeterminada, el servidor muestra la representación completa de un recurso después de procesar las solicitudes. Para lograr un mejor rendimiento, puedes pedirle al servidor que envíe solo los campos que realmente necesitas y obtener una respuesta parcial en su lugar.
Si quieres solicitar una respuesta parcial, usa el parámetro de solicitud de fields
para especificar los campos que deseas que se muestren. Puedes usar este parámetro con cualquier solicitud que muestre datos de respuesta.
Ejemplo
En el siguiente ejemplo, se muestra el uso del parámetro de fields
con una API “de demostración” genérica (ficticia).
Solicitud simple: esta solicitud HTTP GET
omite el parámetro de fields
y muestra el recurso completo.
https://www.googleapis.com/demo/v1
Respuesta de recursos completos: los datos de recursos completos incluyen los siguientes campos, junto con muchos otros que se omitieron para abreviar.
{ "kind": "demo", ... "items": [ { "title": "First title", "comment": "First comment.", "characteristics": { "length": "short", "accuracy": "high", "followers": ["Jo", "Will"], }, "status": "active", ... }, { "title": "Second title", "comment": "Second comment.", "characteristics": { "length": "long", "accuracy": "medium" "followers": [ ], }, "status": "pending", ... }, ... ] }
Solicitud de una respuesta parcial: la siguiente solicitud de este mismo recurso usa el parámetro de fields
para reducir la cantidad de datos que se muestran de manera significativa.
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
Respuesta parcial: en respuesta a la solicitud anterior, el servidor envía una respuesta que contiene solo información similar junto con un arreglo de elementos reducido que incluye solo el título HTML y la información de característica de longitud en cada elemento.
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
Ten en cuenta que la respuesta es un objeto JSON que incluye solo los campos seleccionados y sus objetos superiores adjuntos.
A continuación, se presentan los detalles sobre cómo dar formato al parámetro de fields
. Luego, se presentan más detalles sobre qué es lo que se muestra en la respuesta.
Resumen de la sintaxis de los parámetros de campos
El formato del valor del parámetro de solicitud de fields
se basa de manera general en la sintaxis de XPath. La sintaxis compatible se resume a continuación y se proporcionan ejemplos adicionales en la siguiente sección.
- Usa una lista separada por comas para seleccionar varios campos.
- Usa
a/b
si quieres seleccionar un campob
que se anida en el campoa
; usaa/b/c
para seleccionar un campoc
anidado enb
.
Excepción: En cuanto a las respuestas a la API que usan wrappers de “datos”, en los que la respuesta se anida en un objeto
data
que luce comodata: { ... }
, no incluyas “data
” en la especificaciónfields
. Incluir el objeto de datos con una especificación de campos comodata/a/b
provoca un error. En su lugar, solo usa una especificación defields
comoa/b
. - Puedes usar un subselector para solicitar un conjunto de subcampos específicos de objetos o arreglos, si colocas las expresiones entre paréntesis “
( )
”.Por ejemplo:
fields=items(id,author/email)
solo muestra el ID del elemento y el correo electrónico del autor para cada elemento del arreglo de elementos. También puedes especificar un subcampo único, en el quefields=items(id)
es equivalente afields=items/id
. - Usa comodines en las selecciones de campo, si es necesario.
Por ejemplo:
fields=items/pagemap/*
selecciona todos los objetos en un pagemap.
Más ejemplos del uso del parámetro de campos
En los siguientes ejemplos, se incluyen descripciones de cómo el valor del parámetro de fields
afecta la respuesta.
Nota: Al igual que con todos los valores de los parámetros de búsqueda, el valor del parámetro de fields
debe estar codificado como URL. Para facilitar la lectura, en los ejemplos de este documento se omite la codificación.
- Identifica los campos que deseas que se muestren o realiza selecciones de campo.
- El valor del parámetro de solicitud de
fields
es una lista de campos separada por comas y cada campo se especifica en relación con la raíz de la respuesta. Por lo tanto, si realizas una operación de lista, la respuesta es una colección y suele incluir un arreglo de recursos. Si realizas una operación que muestra un recurso único, los campos se especifican en relación con ese recurso. Si el campo que seleccionas es un arreglo, o es parte de uno, el servidor muestra la parte seleccionada de todos los elementos del arreglo.
A continuación, se presentan algunos ejemplos a nivel de colección:
Ejemplos Efecto items
Muestra todos los elementos del arreglo de elementos, incluidos todos los campos de cada elemento, pero ningún otro campo. etag,items
Muestra el campo etag
y todos los elementos del arreglo de elementos.items/title
Muestra solo el campo title
para todos los elementos del arreglo de elementos.
Cada vez que se muestra un campo anidado, la respuesta incluye los objetos superiores adjuntos. Los campos superiores no incluyen ningún otro campo secundario, a menos que también se seleccionen de manera explícita.context/facets/label
Muestra solo el campo label
para todos los miembros del arreglofacets
, que se anida en el objetocontext
.items/pagemap/*/title
Para cada elemento del arreglo de elementos, muestra solo el campo title
(si está presente) de todos los objetos que son secundarios depagemap
.
A continuación, se presentan algunos ejemplos a nivel de recursos:Ejemplos Efecto title
Muestra el campo title
del recurso solicitado.author/uri
Muestra el subcampo uri
del objetoauthor
en el recurso solicitado.links/*/href
Muestra el campo href
de todos los objetos que son secundarios delinks
. - Solicita solo las partes de los campos específicos mediante subselecciones.
- De forma predeterminada, si tu solicitud especifica campos particulares, el servidor muestra los objetos o los elementos del arreglo en su totalidad. Puedes especificar una respuesta que incluya solo ciertos subcampos. Para hacerlo, usa la sintaxis de la subselección de “
( )
”, como se muestra en el siguiente ejemplo.Ejemplo Efecto items(title,author/uri)
Muestra solo los valores del title
y eluri
del autor para cada elemento del arreglo de elementos.
Controla las respuestas parciales
Después de que un servidor procesa una solicitud válida que incluye el parámetro de búsqueda de fields
, devuelve un código de estado HTTP 200 OK
, junto con los datos solicitados. Si el parámetro de búsqueda de fields
tiene un error o no es válido, el servidor muestra un código de estado HTTP 400 Bad Request
, junto con un mensaje de error en el que se comunica al usuario qué fue lo que falló con su selección de campos (por ejemplo, "Invalid field selection a/b"
).
A continuación, se presenta el ejemplo de una respuesta parcial que se muestra en la sección de introducción anterior. La solicitud usa el parámetro de fields
para especificar qué campos mostrar.
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
La respuesta parcial se ve de la siguiente manera:
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
Nota: En cuanto a las API que admiten parámetros de búsqueda para la paginación de datos (maxResults
y nextPageToken
, por ejemplo), usa esos parámetros a fin de reducir los resultados de cada búsqueda a un tamaño administrable. De lo contrario, los aumentos del rendimiento posibles con una respuesta parcial podrían no realizarse.