En este documento, se describe el protocolo que utilizan las API de datos de Google y se incluye información acerca del aspecto de una consulta, el aspecto de los resultados, etc.
Si deseas obtener más información sobre las API de datos de Google, consulta el documento de la Guía para programadores de datos de Google y la Guía 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 de datos de Google.
Si solo quieres escribir un código que use las API del cliente de datos de Google, 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 de datos de Google
- codificar con el protocolo sin usar las bibliotecas cliente de Google Data 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 de datos de Google usando 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 de los documentos de datos de Google y la sintaxis de las consultas.
Formato del documento
Google Data, Atom y RSS 2.0 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.
Las API de datos de Google pueden usar el formato de distribución de Atom (para operaciones de lectura y escritura) o el formato RSS (para lecturas únicamente).
Atom es el formato predeterminado de los datos de Google. Para solicitar una respuesta en formato RSS, usa el parámetro /alt=rss/. Para obtener más información, consulta Solicitudes de consulta.
Cuando solicitas datos en formato RSS, los datos de Google proporcionan un feed (u otra representación del recurso) en formato RSS. Si no hay una propiedad RSS equivalente para una propiedad de datos de Google determinada, se usará la propiedad Atom y se etiquetará con un espacio de nombres adecuado para indicar que es una extensión de RSS.
Nota: La mayoría de los feeds de datos de Google en formato Atom usan el espacio de nombres Atom como espacio de nombres predeterminado. Para hacerlo, deben especificar un atributo xmlns en el elemento del feed. Consulte la sección de ejemplos para ver ejemplos sobre cómo hacerlo. 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 muestran las representaciones Atom y RSS de los elementos del esquema. Todos los datos que no se mencionan en estas tablas se tratan como XML sin formato y se muestran de la misma manera en ambas representaciones. A menos que se indique lo contrario, los elementos XML en una columna determinada se encuentran en el espacio de nombres correspondiente a esa columna. 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 datos de Google:
| Elemento de esquema de feed | Representación de Atom | Representación RSS |
|---|---|---|
| Título del feed | /feed/title |
/rss/channel/title |
| ID del feed | /feed/id |
/rss/channel/atom:id |
| Vínculo HTML del feed | /feed/link[@rel="alternate"]\[@type="text/html"]/@href |
/rss/channel/link |
| Descripción del feed | /feed/subtitle |
/rss/channel/description |
| Idioma del feed | /feed/@xml:lang |
/rss/channel/language |
| Derechos de autor del feed | /feed/rights |
/rss/channel/copyright |
| Autor del feed |
(Es obligatorio en ciertos casos; consulta la especificación de Atom). |
/rss/channel/managingEditor |
| Fecha de la última actualización del feed | /feed/updated(Formato RFC 3339) |
/rss/channel/lastBuildDate(Formato RFC 822) |
| Categoría del feed | /feed/category/@term |
/rss/channel/category |
| Esquema de categoría de feed | /feed/category/@scheme |
/rss/channel/category/@domain |
| Generador de feeds | /feed/generator/feed/generator/@uri |
/rss/channel/generator |
| Ícono de feed | /feed/icon |
/rss/channel/image/url (a menos que también haya un logotipo, en cuyo caso el ícono no se incluye en el feed) |
| Logotipo del feed | /feed/logo |
/rss/channel/image/url |
La siguiente tabla muestra los elementos de un feed de resultados de la búsqueda de datos de Google. Tenga en cuenta que algunos datos de Google exponen 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 | Representación en RSS/OpenSearch |
|---|---|---|
| Cantidad de resultados de la búsqueda | /feed/openSearch:totalResults |
/rss/channel/openSearch:totalResults |
| Índice de inicio de resultados de la búsqueda | /feed/openSearch:startIndex |
/rss/channel/openSearch:startIndex |
| Cantidad de resultados de búsqueda por página | /feed/openSearch:itemsPerPage |
/rss/channel/openSearch:itemsPerPage |
En la siguiente tabla, se muestran los elementos de una entrada de datos de Google:
| Elemento de esquema de entrada | Representación de Atom | Representación RSS |
|---|---|---|
| ID de entrada | /feed/entry/id |
/rss/channel/item/guid |
| ID de versión de entrada | Si lo deseas, puedes incorporarlo en EditURI (consulta la sección Simultaneidad optimista de este documento). | — |
| Título de la entrada | /feed/entry/title |
/rss/channel/item/title |
| Vínculo de entrada | /feed/entry/link |
/rss/channel/item/link/rss/channel/item/enclosure/rss/channel/item/comments |
| Resumen de entradas |
(Es obligatorio en ciertos casos; consulta la especificación de Atom). |
/rss/channel/item/atom:summary |
| Entrada |
(Si no hay ningún elemento de contenido, la entrada debe contener al menos un elemento |
/rss/channel/item/description |
| Autor de la entrada |
(Es obligatorio en ciertos casos; consulta la especificación de Atom). |
/rss/channel/item/author |
| Categoría de entrada | /feed/entry/category/@term |
/rss/channel/item/category |
| Esquema de categoría de entrada | /feed/entry/category/@scheme |
/rss/channel/item/category/@domain |
| Fecha de publicación de la entrada | /feed/entry/published(RFC 3,339) |
/rss/channel/item/pubDate(RFC 822) |
| Fecha de actualización de la entrada | /feed/entry/updated(RFC 3,339) |
/rss/channel/item/atom:updated(RFC 3,339) |
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 datos 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
Los servicios de datos de Google admiten HTTP condicional GET. Configuran el encabezado de la última modificación según el valor del elemento <atom:updated> en la entrada o el feed que se muestra. 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 el momento If-Modified-Since, el servicio de datos de Google mostrará una respuesta HTTP 304 (No modificada).
Un servicio de datos de Google debe admitir consultas de categoría y 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 |
|---|---|---|
q |
String de consulta de texto completo |
|
/-/category |
Filtro de categoría |
|
category |
Filtro de categoría |
|
author |
Autor de la entrada |
|
alt |
Tipo de representación alternativa |
|
updated-min, updated-max |
Límites en la fecha de actualización de la entrada |
|
published-min, published-max |
Límites en la fecha de publicación de la entrada |
|
start-index |
Índice basado en 1 del primer resultado que se recuperará |
|
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. |
| ID de entrada | ID de una entrada específica para recuperar |
|
Acerca de las búsquedas por categoría
Decidimos especificar un formato levemente inusual para las consultas por categoría. En lugar de una consulta como la siguiente:
http://example.com/jo?category=Fritz&category=2006
usamos:
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 serán las más comunes.
La desventaja de este enfoque es que debes usar /-/ en las consultas de categorías, de modo que los servicios de datos de Google puedan distinguir las consultas de categorías 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-indexen la tabla de la sección Solicitudes de consulta.
El feed de respuesta y las entradas de Atom también pueden incluir cualquiera de los siguientes elementos de Atom y datos de Google (así como otros que se indican 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
typedepende 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:atom="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
<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>
<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>
<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 lo que significan los distintos códigos de estado HTTP en el contexto de los servicios de datos de Google.
| 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. |
| ERROR DE SERVIDOR INTERNO 500 | Error interno. Este es el código predeterminado que se utiliza para todos los errores no reconocidos. |
Simultaneidad optimista (control de versiones)
A veces, es importante asegurarse de que varios clientes no sobrescriban accidentalmente los cambios del otro. Esto es más fácil de lograr si se asegura de que la versión actual de una entrada que está modificando un cliente sea la misma que la versión en la que el cliente basa las modificaciones. Si un segundo cliente realiza una actualización antes que el primer cliente, se rechaza la primera actualización porque el primer cliente ya no basa sus modificaciones en la última versión.
En los feeds de datos de Google que admiten el control de versiones, se obtiene esta semántica agregando un ID de versión al EditURI de cada entrada. Ten en cuenta que solo el EditURI se ve afectado, no el ID de entrada. En este esquema, cada actualización cambia el EditURI de la entrada, lo que garantiza que las actualizaciones posteriores basadas en la versión original fallen. Las eliminaciones, por supuesto, son idénticas a las actualizaciones con respecto a esta función. Si envías una eliminación con un número de versión anterior, la eliminación falla.
No todos los feeds de datos de Google admiten la simultaneidad optimista. En un feed que sí lo admite, si el servidor detecta un conflicto de versiones en PUT o DELETE, el servidor responde con 409 Conflict. El cuerpo de la respuesta contiene el estado actual de la entrada (un documento Atom de entrada). Se le recomienda al cliente que resuelva el conflicto y que vuelva a enviar la solicitud mediante el EditURI de la respuesta 409.
Motivación y notas de diseño
Este enfoque de simultaneidad optimista nos permite implementar la semántica que deseamos sin necesidad de un nuevo lenguaje de marcado para los ID de versión, lo que hace que las respuestas de los datos de Google sean compatibles con los extremos que no son de Google Data Atom.
En lugar de especificar los ID de versión, podríamos haber elegido mirar la marca de tiempo de actualización en cada entrada (/atom:entry/atom:updated). Sin embargo, hay dos problemas con el uso de la marca de tiempo de actualización:
- Solo funciona para actualizaciones y no para eliminaciones.
- Obliga a las aplicaciones a usar valores de fecha y hora como ID de versión, lo que dificultaría readaptar los datos de Google a los almacenes de datos existentes.
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 para un servicio de datos 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 las solicitudes de datos de Google.
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 datos de Google o la documentación de autenticación de cuentas 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á funcionando con los servicios de datos de Google, pero el rendimiento puede verse afectado en comparación con los clientes que sí admiten esos 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,PUTyDELETE - 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