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

Referencia del protocolo

Advertencia: Esta página trata sobre las API anteriores de Google, las API de datos de Google, y solo es relevante para las API que aparecen en el directorio de las API de datos de Google, muchas de las cuales se reemplazaron con API más nuevas. Para obtener información sobre una API nueva específica, consulta la documentación de la API nueva. Para obtener información sobre cómo autorizar solicitudes con una API más reciente, consulta Autenticación y autorización de cuentas de Google.

Este documento describe el protocolo de datos de Google que utilizan muchas API de Google, incluida la información sobre cómo se ve una consulta, cómo se ven los resultados, etc.

Para obtener más información sobre el Protocolo de datos de Google, consulte la página de descripción general de la Guía para programadores y el documento Conceptos básicos de protocolo.

Público

Este documento está dirigido a cualquier persona que desee comprender los detalles del protocolo y el formato XML que utilizan las API para implementar el protocolo de datos de Google.

Si solo deseas escribir un código que use una de estas API, no necesitas conocer estos detalles; en su lugar, puedes usar las bibliotecas cliente específicas del lenguaje.

Pero si deseas comprender el protocolo, lee este documento. Por ejemplo, es posible que desee leer este documento para realizar las siguientes tareas:

Evaluar la arquitectura del protocolo de datos de Google
codificar con el protocolo sin usar las bibliotecas cliente proporcionadas
escribir una biblioteca cliente en un nuevo idioma

En este documento, se asume que comprende los conceptos básicos de XML, los espacios de nombres, los feeds sindicados y las solicitudes GET, POST, PUT y DELETE en HTTP, así como el concepto de "recurso" de HTTP. Para obtener más información sobre estos temas, consulta la sección Recursos adicionales de este documento.

Este documento no depende de un lenguaje de programación en particular; puedes enviar y recibir mensajes del protocolo de datos de Google con cualquier lenguaje de programación que te permita emitir solicitudes HTTP y analizar respuestas basadas en XML.

Detalles del protocolo

En esta sección, se describe el formato del documento del protocolo de datos de Google y la sintaxis de la consulta.

Formato del documento

El protocolo de datos de Google y Atom comparten el mismo modelo básico de datos: un contenedor que contiene algunos datos globales y cualquier cantidad de entradas. Para cada protocolo, el formato se define mediante un esquema base, pero se puede extender con espacios de nombres externos.

Atom es el formato predeterminado para el protocolo de datos de Google. Para solicitar una respuesta en otro formato, usa el parámetro de consulta alt. Si deseas obtener más información, consulta Solicitudes de consulta.

Nota: La mayoría de los feeds del protocolo de datos de Google en formato Atom usan el espacio de nombres Atom como espacio de nombres predeterminado especificando un atributo xmlns en el elemento del feed, como se ve en los ejemplos proporcionados en Conceptos básicos del protocolo. Por lo tanto, los ejemplos que aparecen en este documento no especifican atom: de manera explícita para los elementos de un feed con formato Atom.

En las siguientes tablas, se muestra la representación de Atom de los elementos del esquema. Todos los datos que no se mencionan en estas tablas se tratan como archivos XML simples. A menos que se indique lo contrario, los elementos XML en una columna determinada están en el espacio de nombres Atom.

Nota: Este resumen utiliza notación XPath estándar: en particular, las barras diagonales muestran la jerarquía de los elementos, y el signo @ indica un atributo de un elemento.

En cada una de las siguientes tablas, se requieren los elementos destacados.

La siguiente tabla muestra los elementos de un feed de protocolo de datos de Google:

Elemento de esquema de feed	Representación de Atom
Título del feed	`/feed/title`
ID del feed	`/feed/id`
Vínculo HTML del feed	`/feed/link[@rel="alternate"]`\ `[@type="text/html"]/@href`
Descripción del feed	`/feed/subtitle`
Idioma del feed	`/feed/@xml:lang`
Derechos de autor del feed	`/feed/rights`
Autor del feed	`/feed/author/name` `/feed/author/email` (Es obligatorio en ciertos casos; consulta la especificación de Atom).
Fecha de la última actualización del feed	`/feed/updated` (Formato RFC 3339)
Categoría del feed	`/feed/category/@term`
Esquema de categoría de feed	`/feed/category/@scheme`
Generador de feeds	`/feed/generator` `/feed/generator/@uri`
Ícono de feed	`/feed/icon`
Logotipo del feed	`/feed/logo`

La siguiente tabla muestra los elementos de un feed de resultados de búsqueda del protocolo de datos de Google. Tenga en cuenta que el protocolo expone algunos de los elementos de respuesta de OpenSearch 1.1 en los feeds de resultados de la búsqueda.

Elemento de esquema de feed de resultados de búsqueda	Representación de Atom
Cantidad de resultados de la búsqueda	`/feed/openSearch:totalResults`
Índice de inicio de resultados de la búsqueda	`/feed/openSearch:startIndex`
Cantidad de resultados de búsqueda por página	`/feed/openSearch:itemsPerPage`

En la siguiente tabla, se muestran los elementos de una entrada del Protocolo de datos de Google:

Elemento de esquema de entrada	Representación de Atom
ID de entrada	`/feed/entry/id`
Título de la entrada	`/feed/entry/title`
Vínculo de entrada	`/feed/entry/link`
Resumen de entradas	`/feed/entry/summary` (Es obligatorio en ciertos casos; consulta la especificación de Atom).
Entrada	`/feed/entry/content` (Si no hay ningún elemento de contenido, la entrada debe contener al menos un elemento `<link rel="alternate">`).
Autor de la entrada	`/feed/entry/author/name` `/feed/entry/author/email` (Es obligatorio en ciertos casos; consulta la especificación de Atom).
Categoría de entrada	`/feed/entry/category/@term`
Esquema de categoría de entrada	`/feed/entry/category/@scheme`
Fecha de publicación de la entrada	`/feed/entry/published` (RFC 3339)
Fecha de actualización de la entrada	`/feed/entry/updated` (RFC 3339)

Consultas

En esta sección, se describe cómo usar el sistema de consultas.

Principios del diseño de modelos de consultas

El modelo de consulta es intencionalmente muy simple. Los principios básicos son:

Las consultas se expresan como URI HTTP en lugar de encabezados HTTP o como parte de la carga útil. Uno de los beneficios de este enfoque es que puede vincularlo a una consulta.
Los predicados tienen un solo elemento. Por lo tanto, no hay forma de enviar una consulta de correlación, como “buscar todos los correos electrónicos de las personas que me enviaron al menos 10 correos electrónicos hoy”.
El conjunto de propiedades para las que se pueden predicar las consultas es muy limitado; la mayoría de las consultas son simplemente búsquedas de texto completo.
El orden de los resultados depende de la implementación.
El protocolo es naturalmente extensible. Si deseas exponer predicados o realizar clasificaciones adicionales en tu servicio, puedes hacerlo fácilmente mediante la introducción de nuevos parámetros.

Solicitudes de consulta

Un cliente consulta un servicio de Google mediante una solicitud GET HTTP. El URI de consulta consiste en el URI del recurso (llamado FeedURI en Atom) seguido de los parámetros de consulta. La mayoría de los parámetros de búsqueda se representan como parámetros de URL ?name=value[&...] tradicionales. Los parámetros de categoría se controlan de manera diferente. Consulta a continuación.

Por ejemplo, si el FeedURI es http://www.example.com/feeds/jo, entonces puedes enviar una consulta con el siguiente URI:

http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z

El protocolo de datos de Google admite HTTP condicional GET. Las API que implementan el protocolo establecen el encabezado de respuesta Última modificación según el valor del elemento <atom:updated> en el feed o la entrada mostrados. Un cliente puede devolver este valor como el valor del encabezado de solicitud If-Modified-Since para evitar recuperar el contenido de nuevo si no cambió. Si el contenido no ha cambiado desde la hora If-Modified-Since, el servicio muestra una respuesta HTTP 304 (No modificada).

Las API que implementan el protocolo de datos de Google deben admitir consultas alt. La compatibilidad con otros parámetros es opcional. Pasar un parámetro estándar no comprendido por un servicio determinado da como resultado una respuesta 403 Forbidden. Pasar un parámetro no estándar no admitido da como resultado una respuesta 400 Bad Request. Para obtener información sobre otros códigos de estado, consulta la sección Códigos de estado HTTP de este documento.

Los parámetros estándar de consulta se resumen en la siguiente tabla. Todos los valores de los parámetros deben estar codificados en URL.

Parámetro	Significado	Notas
`alt`	Tipo de representación alternativa	Si no especificas un parámetro `alt`, el servicio muestra un feed Atom. Esto equivale a `alt=atom`. `alt=rss` muestra un feed de resultados RSS 2.0 (solo de lectura). Cuando solicitas datos de un servicio en formato RSS, el servicio proporciona un feed (u otra representación del recurso) en formato RSS. Si no hay una propiedad RSS equivalente para una propiedad de API de datos determinada, el servicio usa la propiedad Atom y la etiqueta con un espacio de nombres adecuado para indicar que es una extensión de RSS. `alt=json` muestra una representación JSON del feed. Más información `alt=json-in-script` Solicita una respuesta que une el JSON en una etiqueta de secuencia de comandos. Más información `alt=atom-in-script` Solicita una respuesta Atom que une una string XML en una etiqueta de secuencia de comandos. `alt=rss-in-script` Solicita una respuesta RSS que une una string XML en una etiqueta de secuencia de comandos. `alt=atom-service` Solicita un documento de servicio de Atom que describa el feed.
`author`	Autor de la entrada	El servicio muestra entradas en las que el nombre del autor o la dirección de correo electrónico coinciden con tu cadena de consulta.
`category`	Filtro de consulta de categoría	Una forma alternativa de realizar un filtro de categoría Los dos métodos son equivalentes. Para hacer una `OR` entre los términos, usa una barra vertical (\|), codificada en URL como `%7C`. Por ejemplo, `http://www.example.com/feeds?category=Fritz%7CLaurie` muestra entradas que coinciden con cualquiera de las categorías. Para usar una `AND` entre los términos, usa un carácter de coma (,). Por ejemplo, `http://www.example.com/feeds?category=Fritz,Laurie` muestra entradas que coinciden con ambas categorías.
`/-/category`	Filtro de consulta de categoría	Enumera cada categoría como si fuera parte del URI del recurso, en el formato `/categoryname/`. Esta es una excepción al formulario habitual de `name=value`. Enumera todas las categorías antes que cualquier otro parámetro de consulta. Preceda la primera categoría con `/-/` para dejar en claro que es una categoría. Por ejemplo, si el feed de Juan tiene una categoría para las entradas sobre Fritz, puedes solicitarlas como la siguiente: `http://www.example.com/feeds/jo/-/Fritz`. Esto permite que la implementación distinga los URI de consulta basados en categorías de los URI de recursos. Puedes realizar consultas en varias categorías; para ello, enumera varios parámetros de categorías, separados por barras diagonales. El servicio muestra todas las entradas que coinciden con todas las categorías (como usar `AND` entre los términos). Por ejemplo, `http://www.example.com/feeds/jo/-/Fritz/Laurie` muestra entradas que coinciden con ambas categorías. Para hacer una `OR` entre los términos, usa una barra vertical (`\|`) codificada como URL como `%7C`. Por ejemplo, `http://www.example.com/feeds/jo/-/Fritz%7CLaurie` muestra entradas que coinciden con cualquiera de las categorías. Una entrada coincide con una categoría especificada si pertenece a una categoría que tiene una etiqueta o término coincidente, como se define en la especificación de Atom. Aproximadamente, el "término" es la string interna que usa el software para identificar la categoría, mientras que la "etiqueta" es la string legible que se presenta a un usuario en una interfaz de usuario. Para excluir las entradas que coincidan con una categoría determinada, utiliza el formulario `/-categoryname/`. Para buscar una categoría que tenga un esquema, como `<category scheme="urn:google.com" term="public"/>`, debes colocar el esquema entre llaves antes del nombre de la categoría. Por ejemplo: `/{urn:google.com}public`. Si el esquema contiene un carácter de barra diagonal (`/`), debe codificarse como URL como `%2F`. Para hacer coincidir una categoría que no tiene esquema, usa un par de llaves. Si no especifica llaves, las categorías en cualquier esquema coincidirán. Las funciones anteriores se pueden combinar. Por ejemplo, `/A%7C-{urn:google.com}B/-C` significa `(A OR (NOT B)) AND (NOT C)`.
ID de entrada	ID de una entrada específica para recuperar	Si especificas un ID de entrada, no puedes especificar ningún otro parámetro. El servicio determina la forma del ID de entrada. A diferencia de la mayoría de los otros parámetros de consulta, el ID de entrada se especifica como parte del URI, no como un par nombre=valor. Ejemplo: `http://www.example.com/feeds/jo/entry1`.
`fields`	Filtro de respuesta	Muestra solo los campos solicitados, en lugar de la representación de recursos completa. Por ejemplo: http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit'])) Cuando recibe esta solicitud, el servidor muestra una respuesta que solo contiene los elementos de entrada y de vínculo del feed. Además, los elementos de entrada que se muestran son entradas parciales que contienen solo ETag, ID, actualizadas y editan relaciones de vínculo. El valor de los campos debe estar codificado como URL, como con todos los valores de los parámetros de consulta. Para obtener más información, consulta la sección Respuesta parcial. Actualmente, este parámetro es una función experimental.
`max-results`	Cantidad máxima de resultados que se recuperarán	Para cualquier servicio que tenga un valor `max-results` predeterminado (para limitar el tamaño predeterminado del feed), puedes especificar un número muy grande si deseas recibir todo el feed.
`prettyprint`	Muestra una respuesta XML con identificaciones y saltos de línea	Si es `prettyprint=true`, el archivo XML que muestra el servidor será legible (bastante impreso). Valor predeterminado: `prettyprint=false`
`published-min`, `published-max`	Límites en la fecha de publicación de la entrada	Usa el formato de marca de tiempo RFC 3339. Por ejemplo: `2005-08-09T10:57:00-08:00`. El límite inferior es inclusivo, mientras que el límite superior es exclusivo.
`q`	String de consulta de texto completo	Cuando creas una consulta, enumera los términos de búsqueda separados por espacios con el formato `q=term1 term2 term3`. (Al igual que con todos los valores de los parámetros de consulta, los espacios deben estar codificados en URL). El servicio muestra todas las entradas que coinciden con todos los términos de búsqueda (como usar `AND` entre los términos). Al igual que la búsqueda web de Google, un servicio busca palabras completas (y palabras relacionadas con la misma raíz), no substrings. Para buscar una frase exacta, escribe la frase entre comillas: `q="exact phrase".` Para excluir las entradas que coincidan con un término determinado, usa el formulario `q=-term`. La búsqueda no distingue entre mayúsculas y minúsculas. Ejemplo: Para buscar todas las entradas que contengan la frase exacta "Elizabeth Bennet" y la palabra "Darcy", pero que no contengan la palabra "Austen", usa la siguiente consulta: `?q="Elizabeth Bennet" Darcy -Austen`
`start-index`	Índice basado en 1 del primer resultado que se recuperará	Ten en cuenta que este no es un mecanismo general de cursor. Si primero envías una consulta con `?start-index=1&max-results=10` y, luego, envías otra consulta con `?start-index=11&max-results=10`, el servicio no puede garantizar que los resultados sean equivalentes a `?start-index=1&max-results=20`, ya que las inserciones y eliminaciones se pudieron haber realizado entre las dos consultas.
`strict`	Verificación estricta de parámetros de consulta	Configura `strict=true` para verificar que el servicio reconozca todos los parámetros de consulta. Se mostrará un error si no se reconoce un parámetro. Valor predeterminado: `strict=false`
`updated-min`, `updated-max`	Límites en la fecha de actualización de la entrada	Usa el formato de marca de tiempo RFC 3339. Por ejemplo: `2005-08-09T10:57:00-08:00`. El límite inferior es inclusivo, mientras que el límite superior es exclusivo. En algunos casos (como cuando se usa la versión 2.1 o posterior de la API de datos del calendario), si se especifica un `updated-min` que está demasiado lejos, se mostrará el estado HTTP 410 (Eliminado).

Acerca de las búsquedas por categoría

Decidimos proporcionar un formato levemente inusual para las consultas de categorías. En lugar de requerir una consulta como la siguiente:

http://example.com/jo?category=Fritz&category=2006

permitimos usar:

http://example.com/jo/-/Fritz/2006

Este enfoque identifica un recurso sin usar parámetros de consulta y produce URI más limpios. Elegimos este enfoque para las categorías porque creemos que las consultas de categorías estarán entre las consultas más comunes.

La desventaja de este enfoque es que necesitas usar /-/ en este tipo de consultas de categoría, de modo que los servicios puedan distinguir las consultas de categoría de otros URI de recursos, como http://example.com/jo/MyPost/comments.

Respuestas a la consulta

Las consultas muestran un feed Atom, una entrada Atom o un feed RSS, según los parámetros de la solicitud.

Los resultados de la consulta contienen los siguientes elementos de OpenSearch directamente en el elemento <feed> o <channel> (según si los resultados son Atom o RSS):

openSearch:totalResults: Es la cantidad total de resultados de la búsqueda (no necesariamente todos los presentes en el feed de resultados).
openSearch:startIndex: El índice basado en 1 del primer resultado.
openSearch:itemsPerPage: La cantidad máxima de elementos que aparecen en una página. Esto permite que los clientes generen vínculos directos a cualquier conjunto de páginas posteriores. Sin embargo, si existe alguna posibilidad de uso de este número, consulta la nota sobre start-index en la tabla de la sección Solicitudes de consulta.

El feed y las entradas de la respuesta de Atom también pueden incluir cualquiera de los siguientes elementos de Atom y API de datos (así como otros enumerados en la especificación de Atom):

<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>: Especifica el URI en el que se puede recuperar el feed de Atom completo.
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>: Especifica el PostURI del feed de Atom (se pueden publicar entradas nuevas).
<link rel="self" type="..." href="..."/>: Contiene el URI de este recurso. El valor del atributo type depende del formato solicitado. Si no hay cambios en los datos mientras tanto, envía otro GET a este URI y muestra la misma respuesta.
<link rel="previous" type="application/atom+xml" href="..."/>: Especifica el fragmento de la parte anterior de este conjunto de resultados de consulta, si está fragmentado.
<link rel="next" type="application/atom+xml" href="..."/>: Especifica el URI del siguiente fragmento del conjunto de resultados de consulta, si está fragmentado.
<link rel="edit" type="application/atom+xml" href="..."/>: Especifica el EditURI de la entrada Atom (a la que se envía una entrada actualizada).

A continuación, se muestra un cuerpo de respuesta de muestra en respuesta a una consulta de búsqueda:

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <id>http://www.example.com/feed/1234.1/posts/full</id>
  <updated>2005-09-16T00:42:06Z</updated>
  <title type="text">Books and Romance with Jo and Liz</title>
  <link rel="alternate" type="text/html" href="http://www.example.net/"/>
  <link rel="http://schemas.google.com/g/2005#feed"
    type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/>
  <link rel="http://schemas.google.com/g/2005#post"
    type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/>
  <link rel="self" type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <generator version="1.0"
    uri="http://www.example.com">Example Generator Engine</generator>
  <openSearch:totalResults>2</openSearch:totalResults>
  <openSearch:startIndex>0</openSearch:startIndex>
  <entry gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'>
    <id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id>
    <published>2005-01-09T08:00:00Z</published>
    <updated>2005-01-09T08:00:00Z</updated>
    <category scheme="http://www.example.com/type" term="blog.post"/>
    <title type="text">This is the title of entry 1009</title>
    <content type="xhtml">
      <div
        xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div>
    </content>
    <link rel="alternate" type="text/html"
      href="http://www.example.com/posturl"/>
    <link rel="edit" type="application/atom+xml"
      href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
  </entry>
  <entry gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'>
    <id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id>
    <published>2005-01-07T08:00:00Z</published>
    <updated>2005-01-07T08:02:00Z</updated>
    <category scheme="http://www.example.com/type" term="blog.post"/>
    <title type="text">This is the title of entry 1007</title>
    <content type="xhtml">
      <div
        xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div>
    </content>
    <link rel="alternate" type="text/html"
      href="http://www.example.com/posturl"/>
    <link rel="edit" type="application/atom+xml"
      href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
  </entry>
</feed>

Si el feed solicitado está en formato Atom, no se especifican parámetros de consulta y el resultado no contiene todas las entradas, el siguiente elemento se inserta en el feed de nivel superior: <link rel="next" type="application/atom+xml" href="..."/>. Apunta a un feed que contiene el siguiente conjunto de entradas. Los conjuntos posteriores contienen un elemento <link rel="previous" type="application/atom+xml" href="..."/> correspondiente. Si se siguen todos los vínculos next, un cliente puede recuperar todas las entradas de un feed.

Códigos de estado HTTP

En la siguiente tabla, se describe el significado de varios códigos de estado HTTP en el contexto de las API de datos.

Programa	Explicación
200 OK	No hay errores.
201 CREATED	Se creó correctamente un recurso.
304 NO MODIFICADO	El recurso no ha cambiado desde la hora especificada en el encabezado If-Modified-Since de la solicitud.
SOLICITUD DE MAYÚSCULAS 400	El URI o encabezado de la solicitud no es válido, o bien el parámetro no estándar no es compatible.
401 UNAUTHORIZED	Se requiere autorización.
403 FORBIDDEN	No se admite el parámetro estándar o se produjo un error de autenticación o autorización.
Error 404	No se encontró el recurso (como un feed o una entrada).
CONFLICTO 409	El número de versión especificado no coincide con el número de versión más reciente del recurso.
410 GONE	El historial de cambios solicitado ya no está disponible en el servidor. Consulta la documentación específica del servicio para obtener más detalles.
ERROR DE SERVIDOR INTERNO 500	Error interno. Este es el código predeterminado que se utiliza para todos los errores de servidor no reconocidos.

Control de versiones de recursos (ETag)

A veces, es necesario poder hacer referencia a una versión específica de una entrada en particular.

Esto es importante en dos casos en particular:

Hacer una “recuperación condicional” en la que tu cliente solicita una entrada y el servidor la envía solo si cambió desde la última vez que el cliente la solicitó.
Garantizar que varios clientes no reemplacen los cambios de los demás sin darse cuenta Para esto, las API de datos realizan actualizaciones y eliminaciones si el cliente especifica un identificador de versión anterior para la entrada.

Las API de datos de Google manejan ambos casos con ETags, una parte estándar de HTTP.

Un ETag es un identificador que especifica una versión particular de una entrada en particular. El servidor adjunta una ETag a los elementos de entrada y feed que envía a los clientes. Cuando cambia una entrada o un feed, también cambia su ETag.

Las API de datos de Google proporcionan ETags en dos lugares: en un encabezado HTTP ETag y en un atributo gd:etag de los elementos <feed> y <entry>.

En las API de datos de Google, una ETag suele ser una cadena de letras y números que, a veces, también incluye guiones y puntos. La string suele encerrarse entre comillas. (Las comillas forman parte de la ETag). Por ejemplo, esta es una ETag de una entrada de la API de datos: "S0wCTlpIIip7ImA0X0QI".

Hay dos tipos de ETag: fuerte y débil. Los ETag fuertes identifican una versión específica de una entrada específica y se pueden usar para evitar reemplazar los cambios de otros clientes. En el contexto de las API de datos de Google, las ETags débiles se utilizan únicamente para la recuperación condicional. Una ETag débil siempre comienza con W/. Por ejemplo: W/"D08FQn8-eil7ImA9WxZbFEw.".

No todas las API de datos de Google admiten ETags fuertes. Aquellos que lo hacen, las ETag fuertes solo se usan para entradas; las ETags de los feeds siempre son débiles.

A continuación se incluye un ejemplo de un feed (incluidos algunos encabezados de HTTP) recuperados de un servicio que admite ETags fuertes:

GData-Version: 2.0
ETag: W/"C0QBRXcycSp7ImA9WxRVFUk."
...
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  ...
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    ...
  </entry>
</feed>

Las bibliotecas cliente que admiten la versión 2 de las API de datos manejan las ETag de forma transparente. La siguiente información está dirigida a los clientes que no usan bibliotecas cliente y a los lectores interesados en cómo se administran las versiones en el nivel de protocolo.

Nota: Para obtener información sobre el sistema de control de versiones de recursos utilizado en la versión 1.0 de las API de datos, consulta la Guía de referencia de 1.0.

Recuperación condicional

Si deseas recuperar una entrada que recuperaste antes, puedes mejorar la eficiencia indicando al servidor que envíe la entrada solo si ha cambiado desde la última vez que la recuperaste.

Para realizar este tipo de recuperación condicional, envía una solicitud GET HTTP que incluya un encabezado HTTP If-None-Match. En el encabezado, especifica la ETag de la entrada.

A continuación, se muestra un ejemplo de un encabezado If-None-Match:

If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."

Cuando el servidor recibe esta solicitud, comprueba si la entrada que solicitaste tiene la misma ETag que la ETag que especificaste. Si las ETags coinciden, la entrada no ha cambiado, y el servidor muestra un código de estado HTTP 304 Not Modified.

Si las ETags no coinciden, la entrada se modificó desde la última vez que la solicitaste, y el servidor muestra la entrada.

Actualizando entradas

La manera más sencilla de evitar que se reemplacen los cambios de otro cliente es que el servidor se asegure de que cuando tu cliente envía una entrada actualizada, la versión de la entrada con la que tu cliente comenzó es la misma que la versión actual almacenada por el servidor. Si un segundo cliente realiza una actualización antes de que lo haga el cliente, se rechaza la actualización, ya que el cliente ya no basa sus modificaciones en la última versión.

Cuando tu cliente recupera datos de un servicio que admite ETags fuertes, cada entrada tiene un ETag que actúa como un identificador de versión único para esa versión de esa entrada.

Nota: La actualización mediante ETags solo funciona con ETags fuertes. En el caso de los servicios que proporcionan ETags débiles, todas las actualizaciones se realizan correctamente, independientemente de que otro usuario haya actualizado la entrada desde que la recuperaste. La actualización más reciente siempre reemplaza las otras actualizaciones anteriores. Por lo tanto, no envíes ETags débiles al actualizar o eliminar; recibirás un mensaje de error si lo haces.

Por lo tanto, cuando el cliente envía una actualización a un servicio e-Tags fuerte, debe especificar qué versión de la entrada se está actualizando. Existen dos maneras de hacerlo:

Usa un encabezado HTTP If-Match.
Usa el atributo gd:etag en el elemento <atom:entry>.

Recomendamos el enfoque If-Match siempre que sea posible.

Para actualizar una entrada mediante If-Match, primero obtén la entrada que deseas actualizar. Realiza los cambios deseados en la entrada y, luego, crea una solicitud PUT nueva que contenga la entrada modificada. (Para obtener detalles sobre las URL que deben usarse, consulta la documentación específica del servicio).

Antes de enviar el PUT, agrega un encabezado HTTP If-Match que contenga la ETag de la entrada original:

If-Match: "S0wCTlpIIip7ImA0X0QI"

Luego, envía la solicitud PUT.

Si la actualización se realiza correctamente, el servidor muestra un código de estado HTTP 200 OK y una copia de la entrada actualizada.

Si la actualización falla porque la ETag que especificaste no coincide con la ETag actual en la entrada (lo que implica que la entrada cambió en el servidor desde la última vez que la obtuviste), el servidor muestra un código de estado HTTP 412 Precondition Failed.

Si no puedes escribir encabezados HTTP con facilidad o tienes algún otro motivo para evitar el uso del encabezado If-Match, puedes usar el atributo gd:etag en su lugar.

Si no envías un encabezado If-Match, el servidor usa el valor del atributo gd:etag de la entrada actualizada como un valor implícito de If-Match.

Para anular el sistema de versiones y actualizar la entrada sin importar si alguien más la actualizó desde que la recuperaste, usa If-Match: * en lugar de especificar la ETag en el encabezado.

Para obtener información sobre qué servicios admiten ETags fuertes, consulta la Guía de migración.

Borra entradas

Borrar entradas que usan ETags fuertes funciona de manera muy similar a actualizarlas.

Para borrar una entrada que tenga una ETag fuerte, primero recupera la entrada que deseas borrar y luego envía una solicitud DELETE a la URL de edición de la entrada.

Si deseas asegurarte de no borrar una entrada que haya cambiado otro cliente desde que la obtuviste, incluye un encabezado HTTP If-Match que contenga el valor ETag de la entrada original.

Si deseas anular el sistema de control de versiones y borrar la entrada sin importar si alguien más la actualizó desde que la recuperaste, usa If-Match: * en lugar de especificar la ETag en el encabezado.

Si una entrada no tiene una ETag fuerte, una solicitud DELETE siempre se realiza de forma correcta.

Respuesta parcial (experimental)

De forma predeterminada, el servidor devuelve la representación completa del recurso de destino después de procesar las solicitudes. La respuesta parcial te permite solicitar solo los elementos o atributos de interés, en lugar de la representación de recursos completa. Esto permite que tu aplicación cliente evite la transferencia, el análisis y el almacenamiento de campos innecesarios, para que pueda usar los recursos de red, CPU y memoria de manera más eficiente.

Para saber si hay una respuesta parcial disponible para el producto que estás usando, consulta la documentación de la API.

Para solicitar una respuesta parcial, usa el parámetro de búsqueda fields a fin de especificar los elementos o atributos que deseas que se muestren. A continuación, le mostramos un ejemplo:

http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))

La respuesta del servidor solo contiene elementos de vínculo y de entrada para el feed; los elementos de entrada contienen solo información de ETag, ID, actualizada y edición de vínculo. La sintaxis del parámetro de búsqueda fields se trata en las siguientes secciones. Para obtener más detalles sobre la respuesta, consulta Administra respuestas parciales.

Nota: Puedes usar el parámetro de consulta fields con cualquier solicitud que muestre datos. Además de GET, incluye POST y PUT (así como PATCH, que se usa para realizar actualizaciones parciales). Sin embargo, el parámetro de consulta fields solo afecta a los datos de respuesta; no afecta a los datos que debes proporcionar ni a los campos que se actualizan o crean.

Resumen de la sintaxis de los parámetros de campos

El formato del valor del parámetro de búsqueda fields se basa en la sintaxis de XPath. Sin embargo, solo admite un subconjunto de expresiones XPath válidas. 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 elemento b que se anida en el elemento a; usa a/b/c para seleccionar un elemento c anidado en b.
Usa el prefijo '@' para identificar un atributo con el nombre determinado; omite el prefijo '@' para hacer referencia a un elemento.
Aplica condiciones de campo para seleccionar elementos que coincidan con determinados criterios. Para ello, coloca expresiones entre corchetes “[ ]” después del elemento que quieras restringir.
Por ejemplo, fields=entry[author/name='Elizabeth'] solo muestra entradas de feed para las que Elizabeth es la autora.
Especifica subselectores de campo para solicitar solo atributos o subelementos específicos. Para ello, coloca expresiones entre paréntesis “( )” después de cualquier elemento seleccionado.
Por ejemplo, fields=entry(id,author/email) solo muestra el ID y el correo electrónico del autor para cada entrada del feed.
Puedes delimitar strings con comillas dobles o simples.

Para escapar una comilla doble o simple, repite la comilla. Por ejemplo, """Hello,"" he said" produce la string "Hello," he said, y '''Hello,'' he said' produce la string 'Hello,' he said.
Puedes usar comodines en las selecciones de campo.
Por ejemplo, entry/gd:* selecciona todos los elementos secundarios de la entrada en el espacio de nombres gd, y entry/@gd:* selecciona los atributos del elemento secundario en el mismo espacio de nombres.

El parámetro de consulta fields actúa como un filtro de salida. Esto significa que la respuesta parcial se calcula solo después de procesar el resto de la consulta. Por ejemplo, si también especificas un parámetro de búsqueda max-results para indicar que quieres 20 resultados por página, se generan los primeros 20 resultados y se calcula la respuesta parcial a partir de ellos. Si la especificación de fields no coincide con ninguna de las primeras 20 entradas que seleccionó la consulta, entonces obtiene un feed vacío; no recupera las primeras 20 entradas que coinciden.

Nota: No intentes usar condiciones de campo como selectores de consultas. Es decir, no intente recuperar un feed completo y aplicar condiciones de campo para filtrar elementos de interés de un conjunto muy grande de datos. Siempre que sea posible, usa otros parámetros de consulta, como start-index y max-results, para reducir los resultados de cada consulta a un tamaño administrable. De lo contrario, el rendimiento que se puede obtener con una respuesta parcial podría superarse con la degradación grave del rendimiento causada por un uso inadecuado.

Da formato al valor del parámetro de campos

En los siguientes lineamientos, se explica cómo construir el valor del parámetro de búsqueda fields. Cada lineamiento incluye ejemplos y proporciona descripciones de cómo el valor del parámetro 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 siguientes ejemplos se omite la codificación.

Identifica los campos que deseas que se muestren o realiza selecciones de campo.

El valor del parámetro de búsqueda fields es una lista separada por comas de elementos o atributos (denominados de forma colectiva campos), y cada campo se especifica en relación con el elemento raíz de la representación del recurso. Por lo tanto, si recuperas un feed, los campos se especifican en relación con el elemento <feed>, y si vas a recuperar una sola entrada, los campos se especifican en relación con el elemento <entry>. Si el elemento seleccionado es (o forma parte de) un elemento repetido en el feed, el servicio muestra todas las instancias de ese elemento.

Estos son algunos ejemplos a nivel de feed:

Ejemplos	Efecto
`entry`	Muestra todos los elementos `<entry>` y todos los subelementos de esas entradas, pero no cualquier otro elemento secundario de `<feed>`.
`id,entry`	Muestra el feed `<id>` y todos los elementos `<entry>`.
`entry/title`	Muestra el elemento `<title>` para todas las entradas del feed. Cada vez que se muestra un elemento anidado, la respuesta incluye etiquetas de cierre para cualquier elemento superior . Las etiquetas superiores no incluyen ningún otro elemento o atributo secundario, a menos que también se seleccionen de manera explícita.
`entry/author/uri`	Muestra solo el subelemento `<uri>` del elemento `<author>` para todas las entradas del feed.
`entry/*:rating`	Muestra solo subelementos con nombre local `rating` en cualquier espacio de nombres para todas las entradas de feed.

Los siguientes son algunos ejemplos básicos:

Ejemplos	Efecto
`author`	Muestra el elemento secundario `<author>` de la entrada objetivo.
`@gd:etag`	Muestra el atributo `etag` de la entrada objetivo.
`author/uri`	Muestra el subelemento `<uri>` del elemento `<author>` para la entrada objetivo.
`media:group/media:*`	Muestra todos los subcampos de `<media:group>` en el espacio de nombres `media` para la entrada de destino.

Restringe la respuesta a los campos seleccionados que coincidan con ciertos criterios o usa las condiciones de campo.

De forma predeterminada, si tu solicitud especifica un elemento que ocurre más de una vez, la respuesta parcial incluirá todas las instancias de ese elemento. Sin embargo, también puedes especificar que la respuesta solo incluya elementos con un valor de atributo en particular o elementos que cumplan alguna otra condición con la sintaxis "[ ]", como se muestra en los siguientes ejemplos. Consulta la sección Sintaxis de condición de campo para obtener más detalles.

Ejemplos	Efecto
`entry[link/@rel='edit']`	Muestra las entradas del feed que contienen un elemento `<link>` con un valor de atributo `rel` de `'edit'`.
`entry/title[text()='Today']`	Muestra los elementos `<title>` que se producen en las entradas del feed si su contenido es `'Today'`.
`entry/author[name='Jo']`	Muestra los elementos `<author>` que se producen en las entradas del feed si tienen un subelemento `<name>` con contenido `'Jo'`.
`author[name='Jo']`	Muestra el elemento `<author>` en la entrada de destino si tiene un subelemento `<name>` con contenido `'Jo'`.

Solicita solo partes de los elementos seleccionados o usa subselecciones de campo.

De forma predeterminada, si tu solicitud especifica elementos específicos, el servicio muestra los elementos en su totalidad. Puedes especificar que la respuesta solo incluya ciertos subelementos dentro de los elementos seleccionados. Para hacerlo, usa la sintaxis de la subselección de “( )”, como se muestra en los siguientes ejemplos.

Ejemplos	Efecto
`entry/author(uri)`	Muestra solo el subelemento `<uri>` para los autores de las entradas del feed.
`entry/author[name='Jo'](uri)`	Muestra solo el subelemento `<uri>` de `<author>` para las entradas que tengan un nombre de autor de `'Jo'`.
`entry(link(@rel,@href))`	Muestra solo los valores de los atributos `rel` y `href` para cada elemento `<link>` de las entradas de feed.
`entry(title,link[@rel='edit'])`	Muestra solo los elementos `<title>` y `<link>` con los atributos `rel` de edición para cada entrada de feed.
`entry(title,author(uri)`	Muestra los elementos `<title>` y los elementos `<uri>` de autor para cada entrada de feed.

Más información sobre la sintaxis de las condiciones de los campos

Puedes usar condiciones de campo con campos o subcampos. La condición debe evaluarse como verdadera para que el campo seleccionado se incluya en los resultados.Si no hay una condición de campo, se incluyen todos los campos del tipo seleccionado.

El valor de texto del campo seleccionado se usa para las comparaciones. En este contexto, si el campo es un elemento, el valor de texto es su contenido; si el campo es un atributo, el valor de texto es el valor del atributo. Si el campo no tiene valor de texto, la comparación falla y el campo no se incluye en los resultados.

En la siguiente tabla, se muestran los operadores XPath que se admiten para las condiciones de campo y se proporcionan algunos ejemplos.

Operador	Sintaxis	Ejemplos
Comparación de strings	`=` o `eq` `!=` o `ne`	Muestra una entrada completa si contiene un elemento `<link>` con un atributo `rel` configurado como "`self'`: `entry[link/@rel='self']` Muestra una entrada completa si contiene un elemento `<title>` con contenido igual a la string `'unknown'`: `entry[title eq 'unknown']` Muestra el elemento `<title>` completo si el contenido no es `'unknown'`: `title[text() != 'unknown']`
Comparación lógica	`and or not`	Muestra cualquier vínculo que tenga un atributo `rel` establecido en `'self'` o `'edit'`: `link[@rel='self' or @rel='edit']` Muestra cualquier vínculo que tenga un atributo `rel` establecido en `'self'` y un atributo `type` establecido en `'application/atom+xml'`: `link[@rel='self' and @type='application/atom+xml']` Muestra cualquier vínculo que no tenga un atributo `rel` con el valor `'self'`: `link[not(@rel='self')]` Ten en cuenta que, como en XPath, `not` se ve como una llamada a función.
Comparación numérica	`=` o `eq` `!=` o `ne` `>` o `gt` `>`= o `ge` `<` o `lt` `<=` o `le`	Muestra cualquier elemento `<gd:rating>` con un atributo `value` que se pueda transformar en un número entero 5: `gd:rating[@value=5]` Muestra cualquier elemento `<gd:rating>` con un atributo `average` que se pueda transformar en un número de punto flotante mayor que 4.3: `gd:rating[@average gt 4.3]`
Comparación de fechas	Usa operadores de comparación numérica, como se muestra en los ejemplos.	Para realizar comparaciones de fecha y hora, puedes convertir elementos, atributos o literales de string en `xs:date` o `xs:dateTime`. Para `xs:dateTime`, la zona horaria predeterminada es UTC, pero es mejor especificar una de forma explícita. Muestra cualquier elemento `<yt:recorded>` que contenga una fecha desde el 1 de enero de 2005: `yt:recorded[xs:date(text())>=xs:date('2005-01-01')]` Muestra las entradas que se actualizaron después de la hora especificada, en la zona horaria UTC: `entry[xs:dateTime(updated)>xs:dateTime('2008-07-25T08:19:37.549Z')]`
Existencia	Use el nombre del elemento o atributo como se muestra en los ejemplos.	Muestra las entradas que contienen un vínculo con un atributo `rel`: `entry[link/@rel]` Muestra cualquier elemento `<gd:rating>` que tenga un atributo llamado `value`: `entry/gd:rating[@value]`
Booleano	`true()false()`	Los booleanos pueden ser útiles durante la prueba para forzar las condiciones del campo a un estado verdadero o falso. Muestra cualquier elemento `<link>`: `link[true()]`

Controla las respuestas parciales

Después de que un servidor que admite una respuesta parcial procesa una solicitud válida que incluye el parámetro de búsqueda fields, envía un código de estado HTTP 200 OK junto con los atributos o elementos solicitados. Si el parámetro de búsqueda fields tiene un error o no es válido, el servidor muestra un código de estado HTTP 400 Bad Request.

El elemento raíz de la respuesta es <feed> o <entry>, según el URI de destino. El contenido del elemento raíz incluye solo los campos seleccionados para ese feed o entrada, junto con las etiquetas de cierre de los elementos superiores.

Se puede repetir el valor del parámetro de búsqueda fields de la solicitud de dos maneras:

El elemento raíz tiene un atributo gd:fields que muestra el valor del parámetro de búsqueda fields especificado en la solicitud.
Si el URI de destino es un feed, cada entrada editable tiene un atributo gd:fields que muestra la parte de la selección fields que se aplica a él.

Nota: Para ver estos valores del atributo gd:fields en tu respuesta parcial, debes incluirlos en tu especificación del parámetro de búsqueda fields. Puedes hacerlo de forma explícita mediante @gd:fields o el @gd:* más general, que también incluye información de ETag.

En la siguiente consulta de ejemplo, se solicita al servidor que muestre un documento que solo contenga atributos en el espacio de nombres gd (tanto a nivel del feed como de entrada), así como el ID, el título y el vínculo de edición para cada entrada del feed:

http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])

El servidor muestra la siguiente respuesta parcial, junto con un código de estado HTTP 200 Successful:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
    gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
  <id>http://example.com/myFeed</id>
  <entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <title>This year</title>
  </entry>
  <entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/2/'/>
    <title>Last year</title>
  </entry>
  <entry d:etag='"EksPQAxHeCp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/3/'/>
    <title>Today</title>
  </entry>
</feed>

Si los campos seleccionados no coinciden con ninguna opción, el servicio seguirá mostrando un código de estado HTTP 200 Successful, pero la respuesta parcial es un feed vacío:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
  gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
</feed>

Actualización parcial (experimental)

Los productos de Google que admiten una respuesta parcial y recursos editables también te permiten usar la actualización parcial. Con la actualización parcial, envías solo los campos que deseas actualizar, en lugar de enviar una versión modificada de la representación de recursos completa. Esto permite que la aplicación cliente sea más eficiente cuando se realizan actualizaciones, así como cuando se usa la respuesta parcial para recuperar datos.

Sin embargo, en lugar de usar PUT, debes usar una solicitud PATCH cuando realices una actualización parcial. La semántica de PATCH es lo suficientemente potente a fin de que puedas agregar, reemplazar y borrar campos específicos para una entrada en particular, todo con una sola solicitud.

Para saber si hay una actualización parcial disponible del producto que estás usando, consulta la documentación específica del producto.

Envía una solicitud de actualización parcial

Para enviar una solicitud de actualización parcial, envía una solicitud HTTP PATCH a la misma URL que usarías normalmente con PUT a fin de actualizar el recurso. El cuerpo de la solicitud PATCH es un elemento <entry> parcial que especifica los campos que deseas agregar o modificar. El atributo gd:fields de la entrada indica los campos que deseas borrar.

El servidor procesa las solicitudes PATCH en un orden específico:

Primero, quita de la representación de recursos los campos especificados por el atributo gd:fields.
La sintaxis del atributo gd:fields es la misma que para el parámetro de búsqueda fields que se usa cuando se solicita una respuesta parcial. Consulta Sintaxis compatible para obtener más detalles.
Luego, se fusionan en la representación del recurso existente y los datos proporcionados en el cuerpo de la solicitud.
Para obtener más información sobre cómo se combinan los datos, consulta Agregar o actualizar campos.

Nota: Dado que el cuerpo de una solicitud PATCH no suele cumplir con el formato de distribución de Atom, el Content-Type que uses con una solicitud PATCH será application/xml.

A continuación, se muestra un ejemplo de una solicitud de actualización parcial:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='description'>
  <title>New title</title>
</entry>

Esta solicitud PATCH realiza los siguientes cambios en la representación del recurso almacenada en el servidor para la entrada del URI de destino:

Quita el elemento <description>.
Actualiza el elemento <title>.

Semántica de una solicitud de actualización parcial

Las siguientes instrucciones explican cómo configurar tu solicitud PATCH para borrar, agregar o actualizar campos específicos dentro de una entrada. Una sola solicitud PATCH puede realizar cualquier combinación de estas operaciones.

Borrar campos Usa el atributo gd:fields del elemento <entry> para identificar los campos que desees borrar del recurso. La siguiente solicitud de ejemplo borra el título y el resumen asociados con una entrada. Sin embargo, la solicitud no agrega ni actualiza ningún otro dato para la entrada.
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='title,summary'/>
```
Agregar o actualizar campos Usa el cuerpo del elemento <entry> para especificar los datos que deseas agregar o actualizar para un recurso. Estos campos se combinan en los datos existentes para el recurso, después de que se realiza alguna eliminación, de acuerdo con las siguientes reglas:
- Se agregan los campos que aún no están presentes. Si los datos de recursos aún no especifican un valor para un campo, el campo se agrega a los datos existentes. Por ejemplo, si una entrada no tiene título y tu solicitud PATCH contiene un elemento <title>, se agregará el título nuevo a la entrada.
- Los campos que ya están presentes se reemplazan o agregan. El comportamiento específico para la combinación de campos que ya se especifican en los datos de recursos depende de las características del campo:
  - Se reemplazan los campos que no se repiten. Si los datos de recursos ya especifican un valor para un elemento que no se repite, el valor que especifiques en la solicitud PATCH reemplazará el valor existente de ese elemento. Por ejemplo, en el siguiente ejemplo, el título nuevo reemplaza al título existente.
```
PATCH /myFeed/1/1/
Content-Type: application/xml

  <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <title>New Title</title>
</entry>
```
    A continuación, se proporciona un ejemplo más complejo. Para este ejemplo, supongamos que la entrada solo puede tener un autor y que el recurso de destino ya tiene valores para el nombre y la dirección de correo electrónico del autor. Aunque el elemento <author> tiene dos campos secundarios, solo el elemento <name> está presente en los datos proporcionados. Como resultado, solo se reemplaza el valor de ese campo. El valor del elemento <email>, que falta en los datos proporcionados, no se modifica.
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <author>
    <name>New Name</name>
  </author>
</entry>
```
  - Se agregan campos repetidos. Si los datos del recurso ya especifican un valor para un elemento recurrente, el elemento nuevo que proporciones se agregará al conjunto existente de valores.
    
    Ten en cuenta que puede haber ocasiones en las que quieras hacer algo diferente de agregar una instancia nueva de un elemento repetido. Por ejemplo, puedes realizar una de las siguientes acciones:
    - Reemplace una lista completa de elementos repetidos. Puedes borrar todos los campos repetidos con el atributo gd:fields (por ejemplo, gd:fields='ns:accessControl') y proporcionar un conjunto completo de los campos de reemplazo. Dado que todos los elementos existentes se borran primero, el conjunto de campos que proporciones no entrará en conflicto con ningún valor existente cuando se agreguen.
    - Reemplaza un valor de un conjunto de valores existentes para un elemento recurrente. En este caso, simplemente quita el único elemento. Para ello, define el valor gd:fields de forma lo suficientemente específica a fin de evitar borrar otros valores que desees conservar. Por ejemplo, para quitar solo un control de acceso con un action de embed, puedes usar gd:fields='ns:accessControl[@action="embed"]'. Luego, debes proporcionar el campo único con el que deseas reemplazarlo en el cuerpo del elemento <entry>:
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='ns:accessControl[@action="embed"]>
  <ns:accessControl action="embed" permission="allowed" />
</entry>
```

Controla la respuesta a una actualización parcial

Después de procesar una solicitud de actualización parcial válida, la API muestra un código de respuesta HTTP 200 OK. De forma predeterminada, el cuerpo de la respuesta es la entrada completa que actualizaste. El servidor actualiza los valores de ETag cuando procesa correctamente una solicitud PATCH, como lo hace con PUT.

Si una solicitud PATCH da como resultado un nuevo estado del recurso que no es válido de manera sintáctica o semántica, el servidor muestra un código de estado HTTP HTTP 400 Bad Request o 422 Unprocessable Entity, y el estado del recurso permanece sin cambios. Por ejemplo, si intentas borrar un campo obligatorio y no proporcionas un reemplazo, el servidor mostrará un error.

Nota: Es importante comprender cómo se relacionan los diferentes campos. Quizás sea posible poner un recurso en un estado incoherente actualizando solo una parte de los valores mutuamente interdependientes. Por ejemplo, es posible actualizar una hora de inicio a un valor posterior que una hora de finalización. Si bien la API debe mostrar un código de error, te recomendamos que pruebes completamente estos tipos de condiciones para garantizar la coherencia.

Notación alternativa cuando no se admite PATCH

Si tu firewall no permite PATCH, realiza una solicitud HTTP POST y establece el encabezado de anulación en PATCH, como se muestra a continuación:

POST /myfeed/1/1/ X-HTTP-Method-Override: PATCH Content-Type: application/xml ...

Usa una respuesta parcial con actualización parcial

Puedes usar una respuesta parcial como base de una solicitud de actualización parcial posterior. Si haces esto, especifica un parámetro de búsqueda fields que incluya vínculos de edición, además de @gd:*. Esto garantiza que la respuesta parcial incluya información como los valores de los atributos ETag y gd:fields, que son importantes para las solicitudes posteriores.

A continuación, se muestra un ejemplo que muestra una respuesta parcial que podrías usar como base para una actualización parcial futura:

http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who

El servidor responde:

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"E0UKRAREeCp7IWA6WhJT"'
    gd:fields="@gd;*,link[@rel='edit'](@href),gd:who">
  <link href='http://example.com/myFeed/1/1/'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='jo@gmail.com'/>
  <gd:who email='jane@gmail.com'/>
</entry>

Supongamos que deseas quitar el usuario con el correo electrónico 'jane@gmail.com', agregar un usuario con el correo electrónico 'will@gmail.com' y cambiar el correo electrónico del usuario que actualmente se muestra como 'jo@gmail.com' a 'josy@gmail.com'.

Puedes realizar estos cambios con solo comenzar con los resultados de la respuesta anterior, modificar solo los campos que son diferentes y enviar la entrada parcial modificada como el cuerpo de la solicitud PATCH. En este ejemplo, las modificaciones necesarias son las siguientes:

Borra <gd:who email='jane'/> de la lista de elementos proporcionados.
Agrega <gd:who email='will@gmail.com'/> a la lista de elementos proporcionados.
Reemplaza <gd:who email='jo@gmail.com'/> por <gd:who email='josy@gmail.com'/>.

A continuación, se muestra la solicitud PATCH basada en la respuesta parcial pavimentada:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who"
    gd:etag="FE8LQQJJeSp7IWA6WhVa">
  <link href='http://example.com/myFeed/1/1'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='josy@gmail.com'/>
  <gd:who email='will@gmail.com'/>
</entry>

Nota: Este enfoque se basa en que los atributos gd:fields y gd:etag (si son compatibles) se incluyan en la respuesta parcial para la entrada. El cuerpo de la entrada parcial debe conservar todos los campos y atributos que estaban presentes en la respuesta parcial, excepto aquellos que deseas quitar de forma explícita. Puedes actualizar cualquiera de los campos existentes del cuerpo con valores nuevos y agregar cualquier campo nuevo que desees agregar.

Autenticación

Cuando un cliente intenta acceder a un servicio, es posible que deba proporcionar las credenciales del usuario al servicio, para demostrar que este tiene la autoridad para realizar la acción en cuestión.

El enfoque que se debe utilizar para la autenticación depende del tipo de cliente:

Una aplicación de escritorio debe usar un sistema de autenticación específico de Google llamado Autenticación de la cuenta para aplicaciones instaladas (también conocida como "ClientLogin"). (Los clientes basados en la Web no deben usar este sistema).
Un cliente basado en la Web, como un frontend de terceros de un servicio de Google, debe usar un sistema de autenticación específico de Google llamado Proxy de autenticación de cuenta para aplicaciones basadas en la Web (también conocido como "AuthSub").

En el sistema ClientLogin, el cliente de escritorio solicita sus credenciales y luego las envía al sistema de autenticación de Google.

Si la autenticación se realiza correctamente, el sistema de autenticación muestra un token que el cliente usa posteriormente (en un encabezado de autorización HTTP) cuando envía solicitudes a la API de datos.

Si la autenticación falla, el servidor muestra un código de estado 403 Forbidden y un encabezado WWW-Authenticate que contiene un desafío aplicable a la autenticación.

El sistema de AuthSub funciona de manera similar, excepto que, en lugar de pedir las credenciales al usuario, lo conecta a un servicio de Google que solicita credenciales. Luego, el servicio muestra un token que la aplicación web puede usar. La ventaja de este enfoque es que Google (en lugar del front-end web) administra y almacena de manera segura las credenciales del usuario.

Para obtener más detalles sobre estos sistemas de autenticación, consulta la descripción general de la autenticación de las API de datos de Google o la documentación de la autenticación de la cuenta de Google.

Estado de sesión

Muchas implementaciones de lógica empresarial requieren interés por la sesión, es decir, realizar un seguimiento del estado de la sesión de un usuario.

Google realiza un seguimiento del estado de la sesión de dos maneras: con cookies y con un token que se puede enviar como un parámetro de consulta. Ambos métodos logran el mismo efecto. Recomendamos a los clientes que admitan uno de estos métodos de seguimiento del estado de sesión (cualquiera es suficiente). Si un cliente no admite ninguno de estos métodos, seguirá usando las API de datos, pero el rendimiento puede verse afectado en comparación con los clientes que sí admiten estos métodos. Específicamente, si un cliente no admite estos métodos, todas las solicitudes generan redireccionamientos y, por lo tanto, todas las solicitudes (y los datos asociados) se envían al servidor dos veces, lo que afecta el rendimiento del cliente y del servidor.

Las bibliotecas cliente de Google manejan el estado de la sesión por ti. Por lo tanto, si usas nuestras bibliotecas, no necesitas hacer nada para obtener asistencia sobre el estado de la sesión.

Recursos adicionales

Los siguientes documentos de terceros pueden resultarte útiles:

Comparación entre Atom y RSS de elementos entrelazados
Descripción general de Atom en IBM
Extensiones de Dublin Core a RSS
Definiciones de métodos de HTTP 1.1; especificación para GET, POST, PUT y DELETE
Definiciones de códigos de estado de HTTP 1.1
Cómo crear un protocolo REST
Cómo compilar servicios web de la manera REST
Introducción técnica al archivo XML
Espacios de nombres XML por ejemplo
Sección ETag de la especificación HTTP

Volver al principio