Guía para desarrolladores: JavaScript

La API de datos de Blogger permite que las aplicaciones cliente vean y actualicen el contenido de Blogger en forma de feeds de la API de datos de Google.

Tu aplicación cliente puede usar la API de datos de Blogger para crear entradas de blog nuevas, editar o borrar entradas de blog existentes y buscar entradas de blog que coincidan con criterios específicos.

Además de proporcionar información general sobre las capacidades de la API de datos de Blogger, en este documento se proporcionan ejemplos de interacciones básicas de la API de datos con la biblioteca cliente de JavaScript. Si te interesa obtener más información sobre el protocolo subyacente que usa la biblioteca, consulta la sección Protocolo de esta guía para desarrolladores.

Contenido

Público

Este documento está dirigido a los programadores que desean escribir aplicaciones cliente de JavaScript que puedan interactuar con Blogger. Se proporciona una serie de ejemplos de interacciones básicas de la API de datos con la biblioteca cliente de JavaScript.

Para obtener información de referencia de la API de datos de Blogger, consulta la guía de referencia del protocolo. En este documento, se supone que comprendes las ideas generales detrás del protocolo de las APIs de datos de Google y el modelo de datos y el flujo de control que usa la biblioteca cliente de JavaScript. También se da por sentado que sabes programar en JavaScript.

Para obtener información de referencia sobre las clases y los métodos proporcionados por la biblioteca cliente, consulta la referencia de la API de la biblioteca cliente de JavaScript.

Este documento está diseñado para leerse en orden; cada ejemplo se basa en ejemplos anteriores.

Condiciones de Uso

Cuando uses esta biblioteca, aceptas cumplir con las Condiciones de Uso de la Biblioteca cliente de JavaScript de Google.

Acerca de los entornos compatibles

Actualmente, solo admitimos aplicaciones cliente de JavaScript que se ejecutan en una página web en un navegador. Por el momento, los navegadores compatibles son Firefox 1.5 y Internet Explorer 6.0 y versiones posteriores.

La biblioteca cliente de JavaScript controla toda la comunicación con el servidor del servicio. Si eres un desarrollador de JS con experiencia, es posible que te preguntes: “¿Y qué sucede con la política del mismo origen?”. La biblioteca cliente de JavaScript permite que tu cliente envíe solicitudes a la API de datos de Google desde cualquier dominio sin dejar de cumplir con el modelo de seguridad del navegador.

Primeros pasos

Antes de poder escribir una aplicación cliente de JavaScript, debes realizar algunas configuraciones para adquirir la biblioteca.

Cómo crear una cuenta de Blogger

Te recomendamos que te registres para obtener una cuenta de Blogger a fin de realizar pruebas. Blogger usa Cuentas de Google. Si ya tienes una, no necesitas hacer nada más.

Adquiere la biblioteca

Antes de que tu cliente pueda usar la biblioteca cliente, debe solicitar el código de la biblioteca cliente al servidor.

Comienza con una etiqueta <script> en la sección <head> de tu documento HTML para recuperar el cargador de la API de AJAX de Google:

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

Para adquirir la biblioteca cliente de la API de datos de Google después de recuperar el cargador, usa la siguiente línea en tu código de configuración de JavaScript, que se debe llamar desde la sección <head> de tu documento HTML (o desde un archivo JavaScript incluido con una etiqueta <script> en la sección <head> de tu documento HTML):

google.load("gdata", "1.x");

El segundo parámetro de google.load() es el número de versión solicitado de la biblioteca cliente de JavaScript.Nuestro esquema de numeración de versiones se basa en el que usa la API de Google Maps. Estos son los números de versión posibles y su significado:

"1"
La segunda y última revisión de la versión principal 1.
"1.x"
Es la revisión más reciente de la versión principal 1.
"1.s"
La revisión estable más reciente de la versión principal 1. Ocasionalmente, declararemos que una versión determinada de la biblioteca cliente es "estable" según los comentarios que recibamos de los desarrolladores. Sin embargo, es posible que esa versión no tenga las funciones más recientes.
"1.0", "1.1", etcétera
Es una versión específica de la biblioteca, con un número de revisión mayor y menor especificado.

Después de llamar a google.load(), debes indicarle al cargador que espere hasta que la página termine de cargarse y, luego, llame al código:

google.setOnLoadCallback(getMyBlogFeed);

En el ejemplo anterior, getMyBlogFeed() es una función que definiremos más adelante en este documento. Usa este enfoque en lugar de tener un controlador onload adjunto al elemento <body>.

Autenticación en el servicio de Blogger

Puedes acceder a los feeds públicos y privados con la API de datos de Blogger. Los feeds públicos no requieren autenticación, pero son de solo lectura. Si deseas modificar los blogs, tu cliente debe autenticarse antes de solicitar feeds privados.

La biblioteca cliente de JavaScript utiliza el sistema de autenticación AuthSub. Para obtener más información sobre la autenticación con las APIs de datos de Google en general, consulta la documentación de autenticación.

Autenticación del proxy de AuthSub

Las aplicaciones web que necesitan autenticar a sus usuarios en las Cuentas de Google usan la autenticación del proxy de AuthSub. El operador del sitio web y el código del cliente no tienen acceso al nombre de usuario y la contraseña del usuario de Blogger. En su lugar, el cliente obtiene tokens AuthSub especiales que le permiten actuar en nombre de un usuario en particular.

Esta es una descripción general breve de lo que sucede durante el proceso de autenticación de un cliente de JavaScript basado en la Web:

  1. La aplicación cliente llama al método google.accounts.user.login() proporcionado por la biblioteca cliente y le pasa un valor de "alcance" que indica qué servicio de Google usar. En Blogger, el alcance es "http://www.blogger.com/feeds/".
  2. La biblioteca cliente envía al navegador a la página "Solicitud de acceso" de Google, en la que el usuario puede ingresar sus credenciales para acceder al servicio.
  3. Si el usuario accede correctamente, el sistema AuthSub envía el navegador de vuelta a la URL del cliente web y pasa el token de autenticación.
  4. La biblioteca cliente de JavaScript almacena el token en una cookie y devuelve el control a la función de la aplicación cliente que llamó a google.accounts.user.login().
  5. Luego, cuando la aplicación cliente llama a los métodos de la biblioteca cliente que interactúan con Blogger, la biblioteca cliente adjunta automáticamente el token a todas las solicitudes.

Nota: Para que la biblioteca cliente de JavaScript realice solicitudes autenticadas de Blogger en un navegador web, tu página debe contener una imagen alojada en el mismo dominio que tu página. Puede ser cualquier imagen, incluso una imagen transparente de un solo píxel, pero debe haber una en la página. Si quieres que la imagen no aparezca en tu página, puedes usar el atributo style de la etiqueta <img> para posicionarla fuera del área de renderización. Por ejemplo: style="position:absolute; top: -1000px;".

Este es el código cliente-aplicación que controla el acceso. Más adelante, llamaremos a la función setupMyService() desde otro código.

function logMeIn() {
  scope = "http://www.blogger.com/feeds/";
  var token = google.accounts.user.login(scope);
}

function setupMyService() {
  var myService =
    new google.gdata.blogger.BloggerService('exampleCo-exampleApp-1');
  logMeIn();
  return myService;
}

Sugerencia: Te recomendamos que proporciones un botón de acceso o algún otro mecanismo de entrada del usuario para solicitarle que inicie el proceso de acceso de forma manual. Si, en cambio, llamas a google.accounts.user.login() inmediatamente después de la carga, sin esperar la interacción del usuario, lo primero que verá cuando llegue a tu página es una página de acceso de Google. Si el usuario decide no acceder, Google no lo dirige de vuelta a tu página. Por lo tanto, desde el punto de vista del usuario, intentó visitar tu página, pero se lo retiró y nunca volvió. Esta situación puede ser confusa y frustrante para los usuarios. En el código de ejemplo de este documento, llamaremos a google.accounts.user.login() inmediatamente después de la carga para que el ejemplo sea simple, pero no recomendamos este enfoque para las aplicaciones cliente del mundo real.

Ten en cuenta que no tienes que hacer nada con la variable llamada token; la biblioteca cliente realiza un seguimiento del token, por lo que tú no tienes que hacerlo.

Nota: Cuando creas un objeto BloggerService nuevo, la biblioteca cliente llama a un método llamado google.gdata.client.init(), que verifica que el navegador en el que se ejecuta el cliente sea compatible. Si se produce un error, la biblioteca cliente muestra un mensaje de error al usuario. Si quieres controlar este tipo de error por tu cuenta, puedes llamar explícitamente a google.gdata.client.init(handleInitError) antes de crear el servicio, en el que handleInitError() es tu función. Si se produce un error de inicialización, entonces tu función recibe un objeto de error estándar, por lo que puedes hacer lo que quieras con ese objeto.

El token sigue siendo válido hasta que lo revoques llamando a google.accounts.user.logout():

function logMeOut() {
  google.accounts.user.logout();
}

Si no llamas a logout(), la cookie que almacena el token durará dos años, a menos que el usuario la borre. La cookie se retiene en todas las sesiones del navegador, por lo que el usuario puede cerrar el navegador, volver a abrirlo y volver a tu cliente; el usuario seguirá teniendo acceso.

Sin embargo, existen ciertas circunstancias inusuales en las que un token puede volverse no válido durante una sesión. Si Blogger rechaza un token, tu cliente debe manejar la condición de error llamando a logout() para quitar la cookie que contiene el token actual y, luego, llamando a login() nuevamente para adquirir un nuevo token válido.

Hay otros dos métodos de AuthSub que pueden resultarte útiles en diversos contextos:

  • google.accounts.user.checkLogin(scope) te indica si el navegador tiene o no un token de autenticación para el permiso determinado.
  • google.accounts.user.getInfo() proporciona información detallada sobre el token actual para su uso de depuración.

Si quieres obtener detalles sobre el uso de JavaScript para interactuar con AuthSub, incluida la información sobre la administración de tokens y en checkLogin() y getInfo(), consulta el documento Cómo usar la autenticación de “AuthSub” con la biblioteca cliente de JavaScript.

Volver al principio