Guía para desarrolladores: PHP

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 las APIs de datos de Google de Zend. 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

  1. Público
  2. Cómo comenzar
    1. Cómo crear una cuenta de Blogger
    2. Cómo ejecutar el código de muestra
    3. Cómo usar métodos get y set mágicos
    4. Otros recursos
  3. Autentícate en el servicio de Blogger
    1. Autenticación de OAuth
    2. Autenticación del proxy de AuthSub
    3. Autenticación mediante nombre de usuario y contraseña de ClientLogin
  4. Cómo recuperar una lista de blogs
  5. Crear publicaciones
    1. Publicar una entrada de blog
    2. Cómo crear un borrador de la entrada de blog
  6. Cómo recuperar publicaciones
    1. Cómo recuperar todas las entradas de blog
    2. Cómo recuperar publicaciones con parámetros de consulta
  7. Cómo actualizar las publicaciones
  8. Cómo borrar publicaciones
  9. Comentarios
    1. Cómo crear comentarios
    2. Cómo recuperar comentarios
    3. Cómo borrar comentarios

Público

Este documento está dirigido a los programadores que desean escribir aplicaciones cliente de PHP que puedan interactuar con Blogger.

En este documento, se asume que comprendes las ideas generales detrás del protocolo de las APIs de datos de Google.

Para obtener información de referencia sobre las clases y los métodos proporcionados por la biblioteca cliente, consulta la referencia de API de la biblioteca cliente de PHP. Si deseas obtener información general de referencia de la API de datos de Blogger, consulta la guía de referencia del protocolo.

Primeros pasos

Para obtener ayuda con la configuración de la biblioteca cliente, consulta la guía de introducción.

La biblioteca cliente de Zend requiere PHP 5.1.4 o posterior. Está disponible como parte del marco de trabajo de Zend y también como descarga independiente. Para interactuar con Blogger, usa la versión 1.0.0 o posterior de la biblioteca cliente.

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.

Cómo ejecutar el código de muestra

En el repositorio de SVN de Zend Framework, se encuentra disponible un cliente de muestra completo en funcionamiento, que contiene todo el código de muestra que aparece en este documento. La muestra se encuentra en /framework/standard/trunk/demos/Zend/Gdata/Blogger.php. La muestra contiene todas las funciones que se explican en este documento. Solo se puede ejecutar desde la línea de comandos:

php Blogger.php -- --user=[email_address] --pass=[password]

Antes de ejecutar esta muestra o desarrollar tu propio código con el framework de Zend, es posible que debas configurar include_path y cargar las clases adecuadas. La ruta de inclusión se puede establecer con el parámetro de configuración php.ini o el método set_include_path. Este código solicita acceso a la clase principal Zend_Gdata, la clase Zend_Gdata_Query y la clase de autenticación Zend_Gdata_ClientLogin.

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata');
Zend_Loader::loadClass('Zend_Gdata_Query');
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');

Cómo usar métodos get y set

Se agregó compatibilidad en toda la biblioteca cliente de PHP con los métodos get y set mágicos para que los desarrolladores lo necesiten. Esto permite acceder de forma segura a las propiedades de una clase con métodos tradicionales de set y get, o bien mediante el acceso a las propiedades. Por ejemplo, si $gdataObject es una instancia de un objeto de esta biblioteca, las siguientes dos líneas de código tienen efectos idénticos:

$gdataObject->setFoo("bar");
$gdataObject->foo = "bar";

Del mismo modo, estas dos líneas de código también tienen efectos idénticos:

$baz = $gdataObject->getFoo();
$baz = $gdataObject->foo;

Del mismo modo, los métodos de fábrica mágico facilitan la declaración de objetos nuevos. En lugar de recordar los nombres de clases largos que exige la convención de nombres de Zend, puedes crear un object nuevo llamando a newObject(); en un cliente de servicio de Zend. Por ejemplo, los dos fragmentos siguientes declaran un nuevo objeto de extensión draft. Encontrarás más información sobre drafts en la sección Cómo crear una publicación.

// Traditional instantiation
$gdClient = new Zend_Gdata();
$draft = new Zend_Gdata_App_Extension_Draft();

// Magic factory instantiation
$gdClient = new Zend_Gdata();
$draft = $gdClient->newDraft();

Los métodos set y métodos get y las fábricas son opcionales, por lo que debes usar el enfoque que mejor se adapte a tus necesidades.

Otros recursos

Otros recursos para el componente de las APIs de datos de Google del framework Zend (Zend_Gdata):

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. Puede autenticarse con cualquiera de estos tres enfoques: autenticación OAuth, autenticación del proxy AuthSub o autenticación del nombre de usuario y contraseña ClientLogin.

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.

En la mayoría de las muestras de las secciones posteriores de este documento, se supone que tienes un objeto de cliente autenticado llamado $gdClient.

Autenticación de OAuth

Para obtener documentación sobre la autenticación de OAuth con la biblioteca de GData de PHP de Zend, consulta OAuth en las bibliotecas cliente del protocolo de datos de Google.

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. Para obtener información más detallada, consulta la documentación de AuthSub.

Cuando un usuario visita tu aplicación por primera vez, aún no se ha autenticado. En este caso, debes mostrar información y un vínculo que dirija al usuario a una página de Google para autenticar tu solicitud de acceso a sus blogs. La biblioteca cliente de Zend proporciona una función para generar la URL de la página de Google. El siguiente código recupera la URL de la página AuthSubRequest:

function getAuthSubUrl()
{
  $next = getCurrentUrl();
  $scope = 'http://www.google.com/blogger/feeds/';
  $secure = false;
  $session = true;
  return Zend_Gdata_AuthSub::getAuthSubTokenUri($next, $scope, $secure, $session);
}

$authSubUrl = getAuthSubUrl();
echo '<a href=\"$authSubUrl\">login to your Google account</a>';

El método getAuthSubTokenUri toma los siguientes parámetros (correspondientes a los parámetros de consulta que usa el controlador de AuthSubRequest):

siguiente
Es la URL de la página a la que Google debe redireccionar al usuario después de la autenticación.
permiso
Indica que la aplicación solicita un token para acceder a los feeds de Blogger. La cadena de alcance que se debe usar es http://www.blogger.com/feeds/ (codificada como URL, por supuesto).
seguro
Indica si el cliente solicita un token seguro.
sesión
Indica si el token que se muestra se puede intercambiar por un token de uso múltiple (sesión).

En el ejemplo anterior, se muestra una llamada que no solicita un token seguro (el valor de secure es false). La URL de solicitud resultante podría verse de la siguiente manera:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.blogger.com%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.php

El usuario sigue el vínculo al sitio de Google y se autentica en su Cuenta de Google.

Después de que el usuario se autentica, el sistema AuthSub lo redirecciona a la URL que especificaste en el parámetro de consulta next de la URL de AuthSubRequest. El sistema AuthSub agrega un token de autenticación a esa URL, como el valor del parámetro de consulta token. Por ejemplo:

http://www.example.com/welcome.php?token=yourAuthToken

Puedes recuperar el valor del token con $_GET['token'].

Este valor de token representa un token AuthSub de un solo uso. En este ejemplo, como se especificó $session = true, este token se puede intercambiar por un token de sesión de AuthSub mediante el método Zend_Gdata_AuthSub::getAuthSubSessionToken, que llama al servicio AuthSubSessionToken:

if(! isset($_SESSION['sessionToken']) && isset($_GET['token'])) {
  $_SESSION['sessionToken'] =
      Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
}

El fragmento de código primero verifica si ya hay un token de sesión de AuthSub presente. Si no es así, pero se especifica un token de un solo uso en la URL, el fragmento de código pasa el token de un solo uso al método getAuthSubSessionToken y la interfaz de AuthSub muestra un token de sesión. Luego, el código coloca el valor del token de sesión en la variable de sesión $_SESSION['sessionToken'].

Luego, tu aplicación puede usar el valor del token de sesión en interacciones posteriores con Blogger. Puedes usar el método Zend_Gdata_AuthSub::getHttpClient para obtener un objeto Zend_Http_Client que tenga el ajuste predeterminado de encabezado Authorization para incluir las credenciales de AuthSub:

$client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['sessionToken']);

Autenticación de nombre de usuario y contraseña de ClientLogin

Usa la autenticación ClientLogin si tu cliente es un cliente “instalado” independiente de un solo usuario (como una aplicación de escritorio).

El siguiente código usa el método Zend_Gdata_ClientLogin::getHttpClient para realizar una solicitud al servicio ClientLogin, recuperar un token de autenticación y crear un objeto Zend_Http_Client con el encabezado de autenticación adecuado. Luego, el HttpClient que muestra este método se usa para construir un objeto de servicio Zend_Gdata.

Ten en cuenta que $accountType está configurado explícitamente como GOOGLE. Si no estableces este parámetro, los usuarios de G Suite no podrán usar correctamente la API de Blogger. 

$user = 'user@example.com';
$pass = 'secretPasswd';
$service = 'blogger';

$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service, null,
        Zend_Gdata_ClientLogin::DEFAULT_SOURCE, null, null,
        Zend_Gdata_ClientLogin::CLIENTLOGIN_URI, 'GOOGLE');
$gdClient = new Zend_Gdata($client);

Para obtener más información sobre la autenticación de ClientLogin, incluidas las solicitudes y respuestas de muestra, consulta la documentación de Autenticación para aplicaciones instaladas.

Nota: Usa el mismo token para todas las solicitudes de una sesión determinada; no adquieras un token nuevo para cada solicitud de Blogger.

Nota: Como se describe en la documentación de ClientLogin, la solicitud de autenticación puede fallar y solicitar un desafío de CAPTCHA. Si deseas que Google emita y controle el desafío de CAPTCHA, envía al usuario a https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (en lugar de a la URL de control de CAPTCHA que se indica en la documentación de ClientLogin).

Cómo recuperar una lista de blogs

La API de datos de Blogger proporciona un feed en el que se enumeran los blogs de un usuario en particular; ese feed se conoce como "metafeed".

En el siguiente código de muestra, se usa un objeto $gdClient autenticado para recuperar el metafeed y, luego, imprimir el título de cada blog.

La clase Zend_Gdata_Query se encarga de construir la URL de consulta. En este caso, no es necesario realizar ningún trabajo adicional, pero la utilidad de la clase Query se volverá evidente en la sección Cómo recuperar publicaciones mediante los parámetros de consulta de este documento.

function printAllBlogs()
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/default/blogs');
  $feed = $gdClient->getFeed($query);
  printFeed($feed);
}

function printFeed($feed)
{
  $i = 0;
  foreach($feed->entries as $entry) {
    print $i ." ". $entry->title->text . "\n";
    $i++;
  }
}

Ten en cuenta la URL que usa el método getFeed. Esta es la URL del metafeed predeterminada; muestra una lista de blogs para el usuario autenticado actualmente. Para acceder al feed de un usuario diferente, puedes colocar el ID del usuario en lugar de default en la URL del metafeed. El ID del usuario es la cadena de dígitos que aparece al final de la URL del perfil del usuario.

El fragmento de código que aparece a continuación demuestra cómo extraer un ID de blog del feed. Necesitarás el ID del blog para realizar operaciones de creación, actualización y eliminación en entradas y comentarios. La variable $index representa qué blog del feed del usuario se está usando. El campo id toma el formato tag:blogger.com,1999:user-userID.blog-blogID, por lo que un split en el carácter "-" coloca el ID de blog en el último elemento del array resultante.

$idText = split('-', $feed->entries[$index]->id->text);
$blogID = $idText[2];

Creando publicaciones

La API de datos de Blogger te permite crear y publicar entradas de blog nuevas, así como borradores de entradas.

Nota: Por el momento, no se admite la configuración de un autor personalizado para las publicaciones. Todas las publicaciones nuevas aparecerán como si las hubiera creado el usuario autenticado actualmente.

Publicar una entrada de blog

Puedes usar la biblioteca cliente de PHP para publicar entradas de blog nuevas.

Primero, crea una instancia de entrada para representar la entrada de blog. Luego, puedes configurar el título, el contenido y otros atributos de la entrada de blog. Por último, llama al método insertEntry para insertar la publicación. Aquí, puedes ver las instancias de fábrica mágica en funcionamiento con los nuevos objetos Zend_Gdata_Entry, Zend_Gdata_App_Extension_Title y Zend_Gdata_App_Extension_Content.

function createPublishedPost($title='Hello, world!', $content='I am blogging on the internet.')
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default';
  $entry = $gdClient->newEntry();
  $entry->title = $gdClient->newTitle($title);
  $entry->content = $gdClient->newContent($content);
  $entry->content->setType('text');

  $createdPost = $gdClient->insertEntry($entry, $uri);
  $idText = split('-', $createdPost->id->text);
  $newPostID = $idText[2];

  return $newPostID;
}

Creando el borrador de la entrada de blog

Las entradas en borrador se crean de la misma manera que las entradas públicas, pero debes establecer el atributo borrador del objeto de entrada. Puedes crear una entrada de blog como la anterior como borrador agregando las líneas destacadas:

function createDraftPost($title='Salutations, world!', $content='Hmm ... not quite right, must rework the title later.')
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default';
  $entry = $gdClient->newEntry();

  $entry->title = $gdClient->newTitle(trim($title));
  $entry->content = $gdClient->newContent($content);
  $entry->content->setType('text');

  $control = $gdClient->newControl();
  $draft = $gdClient->newDraft('yes');
  $control->setDraft($draft);
  $entry->control = $control;

  $createdPost = $gdClient->insertEntry($entry, $uri);
  $idText = split('-', $createdPost->id->text);
  return $idText[2];
}

De la misma manera que cuando configuras el título o el contenido de una entrada, creas objetos Zend_Gdata_App_Extension_Control y Zend_Gdata_App_Extension_Draft nuevos, y los asignas al atributo de control de la entrada.

Puedes convertir un borrador de una entrada de blog existente en una entrada publicada si recuperas la entrada en borrador, configuras el atributo borrador como no y, luego, actualizas la entrada. Abordaremos la recuperación y la actualización de publicaciones en las siguientes dos secciones.

Cómo recuperar publicaciones

En las siguientes secciones, se describe cómo recuperar una lista de entradas de blog, con y sin parámetros de consulta.

Puedes consultar un feed público de Blogger sin autenticación. Por lo tanto, no necesitas configurar credenciales ni realizar la autenticación de AuthSub antes de recuperar las entradas de un blog público.

Recuperando todas las entradas del blog

Para recuperar las entradas del usuario, llama al mismo método getFeed que se usa para recuperar el metafeed de los blogs, pero esta vez envía la URL del feed de las entradas de blog:

function printAllPosts($gdClient, $blogID)
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/posts/default');
  $feed = $gdClient->getFeed($query);
  printFeed($feed);
}

Cómo recuperar publicaciones mediante parámetros de consulta

La API de datos de Blogger te permite solicitar un conjunto de entradas que coincidan con criterios específicos, como solicitar entradas de blog publicadas o actualizadas en un período determinado. Para ello, crea un objeto de consulta y pásalo al método getFeed.

Por ejemplo, para enviar una consulta de período, configura los parámetros published-min y published-max del objeto de consulta. El siguiente fragmento de código imprime el título y el contenido de cada entrada de blog publicada entre la hora de inicio y la hora de finalización determinadas:

function printPostsInDateRange($gdClient, $blogID, $startDate='2007-04-01', $endDate='2007-04-25')
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/posts/default');
  $query->setParam('published-min', $startDate);
  $query->setParam('published-max', $endDate);

  $feed = $gdClient->getFeed($query);
  printFeed($feed);
}

Un método de depuración útil para la clase Zend_Gdata_Query es getQueryUrl(), que te mostrará la URL codificada que se construyó.

Nota: Por el momento, no hay métodos set mágicos para los parámetros de consulta published-min y published-max. Sin embargo, puedes usar setStartIndex y setMaxResults.

La API de datos de Blogger admite los siguientes parámetros de consulta:

categorías
Especifica categorías (también conocidas como etiquetas) para filtrar los resultados del feed. Por ejemplo, http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie muestra entradas con las etiquetas Fritz y Laurie.
max-results
La cantidad máxima de entradas que se mostrarán.
mínimo-publicado, máximo-publicado
Los límites en las fechas de publicación de la entrada.
start-index
El índice basado en 1 del primer resultado que se recuperará (para paginación).

Para obtener más información sobre los parámetros de consulta, consulta la Guía de referencia de la API de datos de Blogger y la Guía de referencia de las APIs de datos de Google.

Actualizando publicaciones

Para actualizar una entrada de blog existente, primero recupera la entrada que deseas actualizar, luego, modifícala y, luego, envíala a Blogger mediante el método save. El siguiente fragmento de código modifica el título y el contenido de una entrada de blog, suponiendo que ya recuperaste la entrada del servidor.

public function updatePost($postID, $updatedTitle='Hello, World?',
                           $updatedContent='UPDATE: Still blogging',
                           $isDraft=False)
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/posts/default/' . $postID);
  $postToUpdate = $dClient->getEntry($query);
  $postToUpdate->title->text = $this->gdClient->newTitle($updatedTitle);
  $postToUpdate->content->text = $this->gdClient->newContent($updatedContent);

  if ($isDraft) {
    $draft = $gdClient->newDraft('yes');
  } else {
    $draft = $gdClient->newDraft('no');
  }

  $control = $gdClient->newControl();
  $control->setDraft($draft);
  $postToUpdate->control = $control;

  $updatedPost = $postToUpdate->save();
  return $updatedPost;
}

Nota: Por el momento, no se pueden modificar los datos del autor asociados con las publicaciones.

Borrando publicaciones

Para borrar una publicación, pasa su URL de edición al método delete en tu objeto $gdClient, de la siguiente manera:

public function deletePost($gdClient, $blogID, $postID)
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default/' . $postID;
  $gdClient->delete($uri);
}

Comentarios

La API de datos de Blogger permite crear, recuperar y borrar comentarios. No se admite la actualización de comentarios (tampoco está disponible en la interfaz web).

Creación de comentarios

Para publicar un comentario, crea un objeto de entrada y, luego, insértalo de la siguiente manera:

function createComment($gdClient, $blogID, $postID, $commentText)
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default';

  $newComment = $gdClient->newEntry();
  $newComment->content = $gdClient->newContent($commentText);
  $newComment->content->setType('text');
  $createdComment = $gdClient->insertEntry($newComment, $uri);

  $editLink = split('/', $createdComment->getEditLink()->href);
  $newCommentID = $editLink[8];

  return $newCommentID; 
}

Nota: Por el momento, solo puedes publicar comentarios en blogs que pertenecen al usuario autenticado.

Nota: Por el momento, no se admite la configuración de un autor personalizado para los comentarios. Todos los comentarios nuevos aparecerán como si los hubiera creado el usuario autenticado actualmente.

Cómo recuperar comentarios

Puedes recuperar los comentarios de una publicación específica desde la URL del feed de comentarios de la entrada:

public function printPostComments($gdClient, $blogID, $postID)
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default');
  $feed = $gdClient->getFeed($query);
  $printFeed($feed);
}

O puedes ver los comentarios de todas las entradas a través de la URL del feed de comentarios del blog:

http://www.blogger.com/feeds/blogID/comments/default

Borrando comentarios

Para borrar un comentario, pasa su URL de edición al método delete en tu objeto $gdClient de la siguiente manera:

public function deleteComment($gdClient, $blogID, $postID, $commentID)
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default/' . $commentID;
  $gdClient->delete($uri);
}

Volver al principio