Guia do desenvolvedor: PHP

A API Data do Blogger permite que os aplicativos clientes acessem e atualizem o conteúdo do Blogger na forma de feeds da API Data do Google.

O aplicativo cliente pode usar a API Blogger Data para criar novas postagens do blog, editar ou excluir postagens existentes e consultar postagens que correspondem a critérios específicos.

Além de fornecer alguns antecedentes sobre os recursos da API Data do Blogger, este documento apresenta exemplos de interações básicas usando a biblioteca de cliente das APIs Data do Google Zend. Se você quiser saber mais sobre o protocolo usado pela biblioteca, consulte a seção de protocolo deste guia para desenvolvedores.

Conteúdo

Público-alvo

Este documento é destinado a programadores que querem criar aplicativos cliente PHP que possam interagir com o Blogger.

Este documento pressupõe que você entenda as ideias gerais por trás do protocolo das APIs Data do Google.

Para informações de referência sobre as classes e os métodos fornecidos pela biblioteca de cliente, consulte a referência da API da biblioteca de cliente PHP. Para informações gerais de referência da API Data do Blogger, consulte o guia de referência do protocolo.

Primeiros passos

Para receber ajuda com a configuração da biblioteca de cliente, consulte o Guia de início.

A biblioteca de cliente Zend requer o PHP 5.1.4 ou mais recente. Ele está disponível como parte do Zend Framework e também como um download separado. Para interagir com o Blogger, use a versão 1.0.0 ou mais recente da biblioteca de cliente.

Como criar uma conta do Blogger

Talvez seja melhor criar uma conta do Blogger para fins de teste. O Blogger usa Contas do Google. Se você já tem uma, está tudo pronto.

Como executar o código de amostra

Um cliente de exemplo completo, que contém todo o código de exemplo mostrado neste documento, está disponível no repositório SVN do Zend Framework. O exemplo está localizado em /framework/standard/trunk/demos/Zend/Gdata/Blogger.php. O exemplo contém todas as funções explicadas neste documento. Ele só pode ser executado na linha de comando:

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

Antes de executar este exemplo ou desenvolver seu próprio código usando o Zend Framework, talvez seja necessário definir o include_path e carregar as classes apropriadas. O caminho de inclusão pode ser definido usando uma configuração php.ini ou o método set_include_path. Esse código solicita acesso à classe principal Zend_Gdata, à classe Zend_Gdata_Query e à classe de autenticação 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');

Como usar getters e setters mágicos

Na biblioteca de cliente PHP, o suporte a setters/getters mágicos foi adicionado para facilitar a vida dos desenvolvedores. Elas permitem que as propriedades de uma classe sejam acessadas com segurança usando métodos setters/getters tradicionais ou através do acesso às propriedades. Por exemplo, se $gdataObject for uma instância de um objeto nesta biblioteca, as duas linhas de código a seguir terão efeitos idênticos:

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

Da mesma forma, essas duas linhas de código também têm efeitos idênticos:

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

Da mesma forma, os métodos de fábrica mágicos facilitam a declaração de novos objetos. Em vez de lembrar os nomes de classe longos exigidos pela convenção de nomenclatura do Zend, você pode criar um novo object chamando newObject(); em um cliente de serviço do Zend. Por exemplo, os dois snippets a seguir declaram um novo objeto de extensão draft. Saiba mais sobre drafts na seção Como criar uma postagem.

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

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

Os setters/getters e fábricas mágicos são opcionais. Use a abordagem que funcionar melhor para você.

Outros recursos

Outros recursos para o componente das APIs Google Data do Zend Framework (Zend_Gdata):

• Documentação de referência
• Informações e arquivos da lista de e-mails
• Informações da Subversion do Zend Framework
• Snapshots diários do Zend Framework

Como fazer a autenticação no serviço do Blogger

É possível acessar feeds públicos e privados usando a API Data do Blogger. Os feeds públicos não exigem autenticação, mas são somente leitura. Se você quer modificar blogs, seu cliente precisa se autenticar antes de solicitar feeds privados. Ela pode ser autenticada usando uma destas três abordagens: autenticação OAuth, autenticação de proxy AuthSub ou autenticação de nome de usuário/senha ClientLogin.

Para mais informações sobre a autenticação com as APIs de dados do Google em geral, consulte a documentação de autenticação.

A maioria dos exemplos nas seções seguintes deste documento pressupõe que você tenha um objeto cliente autenticado chamado $gdClient.

Autenticação OAuth

Para conferir a documentação sobre a autenticação OAuth usando a biblioteca Zend PHP GData, consulte OAuth nas bibliotecas de cliente do protocolo de dados do Google.

Autenticação via proxy do AuthSub

A autenticação de proxy AuthSub é usada por aplicativos da Web que precisam autenticar os usuários nas Contas do Google. O operador do site e o código do cliente não têm acesso ao nome de usuário e à senha do usuário do Blogger. Em vez disso, o cliente recebe tokens AuthSub especiais que permitem que ele aja em nome de um usuário específico. Para mais informações, consulte a documentação do AuthSub.

Quando um usuário visita seu aplicativo pela primeira vez, ele ainda não foi autenticado. Nesse caso, você precisa mostrar algumas informações e um link direcionando o usuário a uma página do Google para autenticar sua solicitação de acesso aos blogs. A biblioteca de cliente Zend fornece uma função para gerar o URL da página do Google. O código abaixo recupera o URL da 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>';

O método getAuthSubTokenUri usa os seguintes parâmetros, correspondentes aos parâmetros de consulta usados pelo gerenciador de AuthSubRequest:

próxima

O URL da página para a qual o Google vai redirecionar o usuário após a autenticação.

escopo

Indica que o aplicativo está solicitando um token para acessar os feeds do Blogger. A string de escopo a ser usada é http://www.blogger.com/feeds/ (codificada por URL, é claro).

seguro

Indica se o cliente está solicitando um token seguro.

sessão

Indica se o token retornado pode ser trocado por um token de uso múltiplo (sessão).

O exemplo acima mostra uma chamada que não solicita um token seguro (o valor de secure é false). O URL de solicitação resultante pode ser parecido com este:

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

O usuário segue o link para o site do Google e faz a autenticação na Conta do Google.

Depois que o usuário é autenticado, o sistema AuthSub redireciona ele para o URL especificado no parâmetro de consulta next do URL AuthSubRequest. O sistema AuthSub anexa um token de autenticação a esse URL como o valor do parâmetro de consulta token. Exemplo:

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

É possível extrair o valor do token usando $_GET['token'].

Esse valor de token representa um token AuthSub de um único uso. Neste exemplo, como $session = true foi especificado, esse token pode ser trocado por um token de sessão do AuthSub usando o método Zend_Gdata_AuthSub::getAuthSubSessionToken, que chama o serviço AuthSubSessionToken:

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

O snippet de código primeiro verifica se um token de sessão do AuthSub já está presente. Se não estiver, mas um token de uso único for especificado no URL, o snippet de código vai transmitir o token de uso único para o método getAuthSubSessionToken, e a interface do AuthSub vai retornar um token de sessão. Em seguida, o código coloca o valor do token de sessão na variável $_SESSION['sessionToken'] da sessão.

O aplicativo pode usar o valor do token de sessão em interações posteriores com o Blogger. Use o método Zend_Gdata_AuthSub::getHttpClient para receber um objeto Zend_Http_Client com o cabeçalho Authorization predefinido para incluir as credenciais AuthSub:

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

Autenticação por nome de usuário/senha do ClientLogin

Use a autenticação ClientLogin se o cliente for um cliente "instalado" independente para um único usuário, como um aplicativo de computador.

O código a seguir usa o método Zend_Gdata_ClientLogin::getHttpClient para realizar uma solicitação ao serviço ClientLogin, extrair um token de autenticação e criar um objeto Zend_Http_Client com o cabeçalho de autenticação apropriado. Em seguida, o HttpClient retornado por esse método é usado para construir um objeto de serviço Zend_Gdata.

Observe que $accountType é definido explicitamente como GOOGLE. Se esse parâmetro não for definido, os usuários do G Suite não poderão usar a API 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 mais informações sobre a autenticação do ClientLogin, incluindo solicitações e respostas de exemplo, consulte a documentação Autenticação para aplicativos instalados.

Observação: use o mesmo token para todas as solicitações em uma determinada sessão. Não adquira um novo token para cada solicitação do Blogger.

Observação: conforme descrito na documentação do ClientLogin, a solicitação de autenticação pode falhar e solicitar um desafio do CAPTCHA. Se você quiser que o Google emita e processe o desafio do CAPTCHA, envie o usuário para https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (em vez do URL de processamento do CAPTCHA fornecido na documentação do ClientLogin).

Como extrair uma lista de blogs

A API Data do Blogger fornece um feed que lista os blogs de um usuário específico. Esse feed é conhecido como "metafeed".

O código de exemplo a seguir usa um objeto $gdClient autenticado para extrair o metafeed e imprimir o título de cada blog.

A classe Zend_Gdata_Query cria o URL da consulta. Nesse caso, não é necessário fazer mais nada, mas a utilidade da classe Query vai ficar evidente na seção Como recuperar postagens por parâmetros de consulta deste 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++;
  }
}

Anote o URL usado pelo método getFeed. Esse é o URL de metafeed padrão. Ele retorna uma lista de blogs do usuário autenticado. Para acessar um feed de outro usuário, coloque o ID dele no lugar de default no URL do metafeed. O ID do usuário é a string de dígitos no final do URL do perfil do usuário.

O snippet de código abaixo demonstra como extrair um ID de blog do feed. Você vai precisar do ID do blog para realizar operações de criação, atualização e exclusão em postagens e comentários. A variável $index representa qual blog no feed do usuário está sendo usado. O campo id assume a forma tag:blogger.com,1999:user-userID.blog-blogID. Portanto, um split no caractere "-" coloca o ID do blog no último elemento da matriz resultante.

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

Como criar postagens

A API Data do Blogger permite criar e publicar novas entradas de blog, além de criar rascunhos de entradas.

Observação: no momento, não é possível definir um autor personalizado para as postagens. Todas as novas postagens vão aparecer como se tivessem sido criadas pelo usuário autenticado no momento.

Publicar uma postagem do blog

Você pode usar a biblioteca de cliente do PHP para publicar novas entradas de blog.

Primeiro, crie uma instância de entrada para representar a postagem do blog. Em seguida, você pode definir o título, o conteúdo e outros atributos da postagem do blog. Por fim, chame o método insertEntry para inserir a postagem. É possível ver as instâncias de fábrica mágicas em ação aqui com os novos objetos Zend_Gdata_Entry, Zend_Gdata_App_Extension_Title e 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;
}

Criar um rascunho de postagem do blog

As postagens de rascunho são criadas da mesma forma que as postagens públicas, mas você precisa definir o atributo de rascunho do objeto de entrada. Você pode criar uma postagem de blog como a acima como rascunho adicionando as linhas 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];
}

Assim como ao definir o título ou o conteúdo de uma postagem, crie novos objetos Zend_Gdata_App_Extension_Control e Zend_Gdata_App_Extension_Draft e atribua-os ao atributo de controle da entrada.

Para transformar um rascunho de postagem do blog em uma postagem publicada, recupere o rascunho, defina o atributo de rascunho como no e atualize a postagem. Vamos abordar a recuperação e a atualização de posts nas próximas duas seções.

Como recuperar postagens

As seções a seguir descrevem como recuperar uma lista de postagens do blog, com e sem parâmetros de consulta.

É possível consultar um feed público do Blogger sem autenticação. Portanto, não é necessário definir credenciais ou fazer a autenticação do AuthSub antes de extrair postagens de um blog público.

Recuperação de todas as postagens do blog

Para recuperar as postagens do usuário, chame o mesmo método getFeed usado para recuperar o metafeed dos blogs, mas envie o URL do feed de postagens do blog:

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

Como recuperar postagens usando parâmetros de consulta

A API Blogger Data permite solicitar um conjunto de entradas que correspondem a critérios especificados, como solicitar postagens do blog publicadas ou atualizadas em um determinado período. Para fazer isso, crie um objeto de consulta e transmita-o ao método getFeed.

Por exemplo, para enviar uma consulta de período, defina os parâmetros published-min e published-max do objeto de consulta. O snippet de código abaixo mostra o título e o conteúdo de cada postagem do blog publicada entre o horário de início e de término especificados:

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);
}

Um método de depuração útil para a classe Zend_Gdata_Query é getQueryUrl(), que mostra o URL codificado que foi criado.

Observação: no momento, não há setters mágicos para os parâmetros de consulta published-min e published-max. No entanto, é possível usar setStartIndex e setMaxResults.

A API Data do Blogger é compatível com os seguintes parâmetros de consulta:

categorias

Especifica categorias (também conhecidas como rótulos) para filtrar os resultados do feed. Por exemplo, http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie retorna entradas com os rótulos Fritz e Laurie.

max-results

O número máximo de entradas a serem retornadas.

published-min, published-max

Os limites das datas de publicação da entrada.

start-index

O índice com base em 1 do primeiro resultado a ser recuperado (para paginação).

Para mais informações sobre parâmetros de consulta, consulte o Guia de referência da API Data do Blogger e o Guia de referência das APIs Data do Google.

Como atualizar postagens

Para atualizar uma postagem do blog, primeiro recupere a entrada que você quer atualizar, modifique-a e envie para o Blogger usando o método save. O snippet de código a seguir modifica o título e o conteúdo de uma entrada de blog, supondo que você já tenha recuperado a entrada do 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;
}

Observação: no momento, não é possível modificar os dados do autor associados às postagens.

Como excluir postagens

Para excluir uma postagem, transmita o URL de edição da postagem para o método delete no objeto $gdClient, desta forma:

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

Comentários

A API Data do Blogger permite criar, recuperar e excluir comentários. Não é possível atualizar comentários nem usar esse recurso na interface da Web.

Como criar comentários

Para postar um comentário, crie um objeto de entrada e insira-o da seguinte maneira:

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; 
}

Observação: no momento, só é possível postar comentários em um blog que pertence ao usuário autenticado.

Observação: no momento, não é possível definir um autor personalizado para comentários. Todos os novos comentários vão aparecer como se tivessem sido criados pelo usuário autenticado no momento.

Como recuperar comentários

É possível recuperar os comentários de uma postagem específica no URL do feed de comentários:

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);
}

Ou você pode usar o URL do feed de comentários do blog para receber os comentários de todas as postagens:

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

Excluir comentários

Para excluir um comentário, transmita o URL de edição do comentário para o método delete do objeto $gdClient, como este:

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

Voltar ao início