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

Sugerencias para un mejor 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 Directory.

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 enviar y recibir 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 pueda usar recursos como la red, la CPU y la memoria con más eficiencia.

Existen los siguientes dos tipos de solicitudes parciales:

Respuesta parcial: una solicitud en la que especificas qué campos incluir en la respuesta (usa el parámetro de la solicitud de fields).
Parche: una solicitud de actualización en la que envías solo los campos que deseas cambiar (usa el verbo HTTP PATCH).

En las siguientes secciones, se proporcionan más detalles sobre cómo realizar solicitudes parciales.

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.

Ten en cuenta que el parámetro de fields solo afecta a los datos de respuesta; no afecta a los datos que necesitas enviar, si los hay. Para reducir la cantidad de datos que envías cuando modificas recursos, usa una solicitud de parche.

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.

Parche (actualización parcial)

También puedes evitar el envío de datos innecesarios cuando modificas recursos. Si quieres enviar datos actualizados solo para los campos específicos que modificas, usa el verbo HTTP PATCH. La semántica de parches descrita en este documento es diferente (y más simple) de lo que era para la implementación anterior de GData de actualización parcial.

En el siguiente ejemplo, se muestra cómo el uso de un parche minimiza los datos que necesitas enviar para realizar una actualización pequeña.

Ejemplo

En este ejemplo, se muestra una solicitud de parche simple para actualizar solo el título de un recurso de API “de demostración” genérica (ficticia). El recurso también tiene un comentario, un conjunto de características, un estado y muchos otros campos, pero esta solicitud solo envía el campo title, ya que ese es el único campo que se modifica:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

Respuesta:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

El servidor muestra un código de estado 200 OK junto con la representación completa del recurso actualizado. Debido a que solo se incluyó el campo title en la solicitud de parche, ese es el único valor diferente al anterior.

Nota: Si usas el parámetro de fields de la respuesta parcial en combinación con el parche, puedes aumentar aún más la eficiencia de tu solicitud de actualización. Una solicitud de parche solo reduce el tamaño de la solicitud. Una respuesta parcial reduce el tamaño de la respuesta. Entonces, para reducir la cantidad de datos enviados en ambas direcciones, usa una solicitud de parche con el parámetro de fields.

Semántica de una solicitud de parche

El cuerpo de la solicitud de parche incluye solo los campos de recursos que deseas modificar. Cuando especificas un campo, debes incluir cualquier objeto superior adjunto, como los superiores adjuntos se muestran con una respuesta parcial. Los datos modificados que envíes se combinan con los datos para el objeto superior, si es que hay uno.

Agrega: para agregar un campo que aún no existe, especifica el campo nuevo y su valor.
Modifica: para modificar el valor de un campo existente, especifica el campo y configúralo en el valor nuevo.
Borra: para borrar un campo, especifícalo y configúralo como null. Por ejemplo, "comment": null. También puedes borrar un objeto completo (si es mutable), si lo configuras como null. Si usas la biblioteca cliente de la API de Java, usa Data.NULL_STRING. Para obtener más información, consulta la página sobre JSON null.

Nota sobre los arreglos: Las solicitudes de parche que contienen arreglos reemplazan el arreglo existente por el que proporcionaste. No puedes modificar, agregar o borrar elementos de un arreglo por etapas.

Usa parches en un ciclo de lectura, modificación, escritura

Comenzar por recuperar una respuesta parcial con los datos que deseas modificar puede ser una práctica útil. En particular, esto es importante para los recursos que usan ETags, ya que debes proporcionar el valor de ETag actual en el encabezado HTTP If-Match para actualizar el recurso con éxito. Después de obtener los datos, puedes modificar los valores que deseas cambiar y enviar la representación parcial modificada con una solicitud de parche. A continuación, se presenta un ejemplo en el que se supone que el recurso de demostración usa ETags:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

La respuesta parcial es la siguiente información:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

La siguiente solicitud de parche se basa en esa respuesta. Como se muestra a continuación, también usa el parámetro de fields para limitar los datos que se muestran en la respuesta del parche:

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

El servidor responde con un código de estado HTTP 200 OK y la representación parcial del recurso actualizado:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

Crea una solicitud de parche directamente

En cuanto a algunas solicitudes de parches, debes realizarlas en función de los datos que recuperaste antes. Por ejemplo, si deseas agregar un elemento a un arreglo y no quieres perder ninguno de los elementos del arreglo existentes, primero debes obtener los datos existentes. De manera similar, si una API usa ETags, debes enviar el valor de ETag anterior con tu solicitud para actualizar el recurso de manera correcta.

Nota: Puedes usar un encabezado HTTP "If-Match: *" para forzar la aplicación de un parche cuando las ETags están en uso. Si haces esto, no necesitas realizar operaciones de lectura antes de realizar las de escritura.

Para otras situaciones, sin embargo, puedes crear la solicitud de parche directamente, sin recuperar primero los datos existentes. Por ejemplo, puedes configurar con facilidad una solicitud de parche que actualiza un campo a un valor nuevo o agrega un campo nuevo. A continuación, se muestra un ejemplo:

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

Con esta solicitud, si el campo de comentario tiene un valor existente, el valor nuevo lo reemplaza; de lo contrario, se establece en el valor nuevo. De manera similar, si hubiera una característica de volumen, su valor se reemplaza; si no, se crea. Si está establecido, el campo de precisión se quita.

Controla la respuesta a un parche

Después de procesar una solicitud de parche válida, la API muestra un código de respuesta HTTP 200 OK junto con la representación completa del recurso modificado. Si la API usa ETags, el servidor actualiza los valores de ETag cuando procesa con éxito una solicitud de parche, al igual que lo hace con PUT.

La solicitud de parche muestra la representación de recursos completa, a menos que uses el parámetro de fields para reducir la cantidad de datos que se muestran.

Si una solicitud de parche genera un estado de recursos nuevo que no es válido de manera sintáctica o semántica, el servidor muestra un código de estado HTTP 400 Bad Requesto 422 Unprocessable Entity y el estado de recursos permanece igual. Por ejemplo, si intentas borrar el valor de un campo obligatorio, el servidor muestra un error.

Notación alternativa cuando no se admite el verbo HTTP PATCH

Si tu firewall no permite solicitudes HTTP PATCH, entonces haz una solicitud HTTP POST y configura el encabezado de anulación como PATCH, como se muestra a continuación:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

Diferencia entre parche y actualización

En la práctica, cuando envías datos para una solicitud de actualización que usa el verbo HTTP PUT, solo necesitas enviar los campos obligatorios o los opcionales; si envías valores para los campos que establece el servidor, se ignoran. Aunque esto puede parecer otra forma de hacer una actualización parcial, este enfoque tiene algunas limitaciones. Con las actualizaciones que usan el verbo HTTP PUT, la solicitud falla si no proporcionas los parámetros obligatorios y borra los datos establecidos antes si no proporcionas los parámetros opcionales.

Por esta razón, es mucho más seguro usar un parche. Solo debes proporcionar datos para los campos que deseas cambiar; los campos que omites no se borran. La única excepción a esta regla se produce con la repetición de elementos o arreglos: si omites todos, se mantienen tal como están; si proporcionas alguno de ellos, todo el conjunto se reemplaza por el conjunto que proporciones.