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 consultar entradas de blogs que coincidan con criterios específicos.
Además de proporcionar información sobre las capacidades de la API de datos de Blogger, en este documento, se proporcionan ejemplos de interacciones básicas para la API de datos mediante la biblioteca cliente de las API de datos 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
Público
Este documento está dirigido a programadores que desean escribir aplicaciones cliente PHP que pueden interactuar con Blogger.
En este documento, se supone que comprendes las ideas generales detrás del protocolo de las API de datos de Google.
Para obtener información de referencia sobre las clases y los métodos que proporciona la biblioteca cliente, consulta la referencia de la API de la biblioteca cliente de PHP. Para obtener información general sobre la API de datos de Blogger, consulta la guía de referencia del protocolo.
Cómo comenzar
Si deseas obtener ayuda para configurar 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 de Zend Framework y también como una descarga independiente. Para interactuar con Blogger, usa la versión 1.0.0 o una posterior de la biblioteca cliente.
Creación de una cuenta de Blogger
Te recomendamos que te registres en una cuenta de Blogger para realizar pruebas. Blogger usa Cuentas de Google, así que si ya tienes una, ya estás listo.
Cómo ejecutar el código de muestra
Un cliente de muestra funcional completo, que contiene todo el código de muestra que se muestra en este documento, está disponible en el repositorio de SVN del marco de trabajo de Zend. 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 marco de trabajo de Zend, es posible que debas configurar include_path y cargar las clases adecuadas. La ruta de inclusión se puede establecer con una configuración de php.ini o con el método set_include_path. Este código solicita acceso a las clases principales Zend_Gdata, Zend_Gdata_Query y 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');
Usar métodos get y métodos set mágicos
En toda la biblioteca cliente de PHP, se agregó compatibilidad con métodos get set para la conveniencia para los desarrolladores. De esta manera, se puede acceder a las propiedades de una clase de forma segura mediante métodos set o método get tradicionales o al acceder 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 mágicos de la fábrica facilitan la declaración de objetos nuevos. En lugar de recordar los nombres de clase largos exigidos por 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. Verá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, métodos get y fábricas son opcionales, así que usa el enfoque que más te convenga.
Otros recursos
Otros recursos para el componente de las API de datos de Google de Zend Framework (Zend_Gdata):
- Documentación de referencia
- Información y archivos de la lista de distribución
- Información de Zend Framework Subversion
- Instantáneas nocturnas de Zend Framework
Autenticación en el servicio de Blogger
Puedes acceder a los feeds públicos y privados mediante 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 los feeds privados. Se puede autenticar mediante cualquiera de estos tres métodos: autenticación OAuth, autenticación del proxy AuthSub o autenticación del nombre de usuario y contraseña de ClientLogin.
Para obtener más información sobre la autenticación con las API de datos de Google en general, consulta la documentación de autenticación.
En la mayoría de los ejemplos de las secciones posteriores de este documento, se supone que tienes un objeto de cliente autenticado llamado $gdClient.
Autenticación de OAuth
Para ver la documentación sobre la autenticación de OAuth con la biblioteca de GData 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 Cuentas de Google usan la autenticación del proxy de AuthSub. El operador del sitio web y el código de cliente no tienen acceso al nombre de usuario y la contraseña del usuario de Blogger; en cambio, el cliente obtiene tokens especiales de AuthSub que le permiten al cliente 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 autenticó. 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 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 string del alcance que se usará es
http://www.blogger.com/feeds/(codificada en la URL, por supuesto). - seguras
- Indica si el cliente solicita un token seguro.
- sesión
- Indica si el token que se muestra se puede intercambiar por un token multiuso (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 de AuthSub lo redirecciona a la URL que especificaste en el parámetro de búsqueda 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 búsqueda 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 de AuthSub de uso único. En este ejemplo, dado que 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 comprueba si ya existe un token de sesión de AuthSub. Si no es así, pero se especifica un token de uso único en la URL, el fragmento de código pasa el token de un solo uso al método getAuthSubSessionToken, y la interfaz 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'].
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 encabezado predeterminado Authorization a fin de incluir credenciales de AuthSub:
$client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['sessionToken']);
Autenticación de nombre de usuario/contraseña de ClientLogin
Usa la autenticación ClientLogin si tu cliente es un cliente independiente instalado 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, se usa el HttpClient que muestra este método para construir un objeto de servicio Zend_Gdata.
Ten en cuenta que $accountType se establece explícitamente en GOOGLE. Si no se configura este parámetro, los usuarios de G Suite no podrán usar la API de Blogger correctamente.
$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 CAPTCHA. Si deseas que Google emita y maneje la verificación 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 proporcionada en la documentación de ClientLogin).
Cómo recuperar una lista de blogs
La API de datos de Blogger proporciona un feed que enumera los blogs de un usuario en particular. Ese feed se conoce como &meta; metafeed.
El siguiente código de muestra 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 la consulta. En este caso, no es necesario realizar ningún trabajo adicional, pero la utilidad de la clase Query se hará evidente en la sección Cómo recuperar publicaciones por 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 de metafeed predeterminada; se muestra una lista de blogs para el usuario autenticado actualmente.
Para acceder a un feed de un usuario diferente, puedes colocar el ID del usuario en lugar de default en la URL del feed de metadatos. El ID del usuario es la string de dígitos que aparece al final de la URL del perfil del usuario.
En el siguiente fragmento de código, se muestra 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
el blog del feed del blog del usuario que se usa. El campo id toma la forma tag:blogger.com,1999:user-userID.blog-blogID, por lo que un split en el carácter '' coloca el ID del blog en el último elemento del arreglo resultante.
$idText = split('-', $feed->entries[$index]->id->text);
$blogID = $idText[2];
Crear publicaciones
La API de datos de Blogger te permite crear y publicar entradas de blog nuevas, además de crear 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 fueran creadas por el usuario autenticado actual.
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. Puedes ver las instancias de fábrica mágicas en funcionamiento aquí 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 una entrada de blog en borrador
Los borradores de entradas se crean de la misma manera que las entradas públicas, pero debes configurar el atributo de borrador del objeto de entrada. Puedes crear una entrada de blog como la anterior como borrador si agregas 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];
}
Prácticamente de la misma forma que cuando configuras el título o el contenido de una publicación, debes crear nuevos objetos Zend_Gdata_App_Extension_Control y Zend_Gdata_App_Extension_Draft, y asignarlos al atributo de control de la entrada.
Puedes convertir un borrador de una entrada de blog en una entrada publicada si recuperas la entrada del borrador, estableces 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.
Recuperando 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 entradas de un blog público.
Recuperando todas las entradas de blog
Para recuperar las entradas del usuario, llama al mismo método getFeed que se usó para recuperar el metafeed de blogs, pero esta vez envía la URL del feed de 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 con parámetros de búsqueda
La API de datos de Blogger te permite solicitar un conjunto de entradas que coincidan con los criterios especificados, 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 proporcionadas:
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 las categorías (también conocidas como etiquetas) para filtrar los resultados del feed. Por ejemplo,
http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Lauriemuestra entradas con las etiquetasFritzyLaurie. - resultados máximos
- La cantidad máxima de entradas que se mostrarán.
- mín. publicados, máx. publicados
- Los límites en las fechas de publicación de las entradas
- índice de inicio
- El índice basado en 1 del primer resultado que se recuperará (para la paginación).
Para obtener más información sobre los parámetros de búsqueda, revisa la Guía de referencia de la API de datos de Blogger y la Guía de referencia de las API de datos de Google.
Actualizando entradas
Para actualizar una entrada de blog existente, primero recuperas la entrada que deseas actualizar, la modificas y, luego, la envías a Blogger con 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 admite modificar los datos del autor asociados con las publicaciones.
Eliminando publicaciones
Para borrar una publicación, pasa la URL de edición de la publicació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 eliminar comentarios. La actualización de comentarios no es compatible (ni está disponible en la interfaz web).
Creación de comentarios
Para publicar un comentario, crea un objeto de entrada e 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 un blog que pertenezca 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 actual.
Recuperando comentarios
Puedes recuperar los comentarios de una entrada en particular 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);
}
También puedes obtener los comentarios de todas las entradas en la URL del feed de comentarios del blog:
http://www.blogger.com/feeds/blogID/comments/default
Borrando comentarios
Para borrar un comentario, pasa la URL de edición del comentario 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);
}