Se usó la API de Cloud Translation para traducir esta página.

Sugerencias sobre rendimiento

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 aplican a la API de Civic Information de Google.

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 campo b que se anida en el campo a; usa a/b/c para seleccionar un campo c anidado en b.

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 como data: { ... }, no incluyas “data” en la especificación fields. Incluir el objeto de datos con una especificación de campos como data/a/b provoca un error. En su lugar, solo usa una especificación de fields como a/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 que fields=items(id) es equivalente a fields=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 arreglo `facets`, que se anida en el objeto `context`.
`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 de `pagemap`.

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 objeto `author` en el recurso solicitado.
`links/*/href`	Muestra el campo `href` de todos los objetos que son secundarios de `links`.

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 el `uri` 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.