A API de dados do Blogger permite que aplicativos cliente vejam e atualizem o conteúdo do Blogger na forma de feeds da API Google Data.
Seu aplicativo cliente pode usar a API de dados do Blogger para criar novas postagens de blog, editar ou excluir postagens de blog existentes e consultar postagens de blog que correspondam a critérios específicos.
Além de fornecer informações sobre os recursos da API de dados do Blogger, este documento apresenta exemplos de interações básicas da API Data usando a biblioteca de cliente das APIs de dados do Google Zend. Se você quiser saber mais sobre o protocolo subjacente usado pela biblioteca, consulte a seção "Protocolo" deste guia do desenvolvedor.
Índice
Público-alvo
Este documento é para os programadores que querem criar aplicativos cliente PHP que podem interagir com o Blogger.
Neste documento, presumimos que você entenda as ideias gerais por trás do protocolo das APIs de dados 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 do PHP. Para informações gerais de referência da API Blogger Data, consulte o Guia de referência de protocolos.
Primeiros passos
Se você precisar de ajuda para configurar a biblioteca de cliente, consulte o Guia de primeiros passos.
A biblioteca de cliente do 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 posterior da biblioteca de cliente.
Criar uma conta do Blogger
Inscreva-se em uma conta do Blogger para fins de teste. O Blogger usa as Contas do Google. Portanto, se você já tem uma Conta do Google, está tudo pronto.
Como executar o código de amostra
Um cliente de exemplo totalmente funcional, contendo todo o código de amostra mostrado neste documento, está disponível no repositório SVN de framework do Zend. A amostra está localizada em /framework/standard/chain/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 esse 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,
à 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 agentes de mágica
Em toda a biblioteca de cliente PHP, foi adicionado suporte aos seters/getters mágicos como uma conveniência para os desenvolvedores. Elas permitem que as propriedades
de uma classe sejam acessadas com segurança usando os métodos setter/getter tradicionais ou
acessando as 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 mágicos de fábrica facilitam a declaração de novos objetos. Em vez
de lembrar os nomes de classes 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 de mágica são opcionais, portanto, use a abordagem que funcionar melhor para você.
Outros recursos
Outros recursos para o componente das APIs de dados do Google (Zend_Gdata):
- Documentação de referência
- Informações e arquivos da lista de e-mails
- Informações sobre a Subversão de framework do Zend
- Snapshots do Night Framework Night Framework
Como autenticar no serviço do Blogger
Você pode acessar feeds públicos e privados usando a API de dados do Blogger. Os feeds públicos não exigem autenticação, mas são somente leitura. Se você quiser modificar blogs, seu cliente precisará se autenticar antes de solicitar feeds privados. Ele pode ser autenticado usando qualquer uma das três abordagens: autenticação de OAuth, autenticação de proxy dSYM ou autenticação de nome de usuário/senha do ClientLogin.
Para mais informações sobre autenticação com as APIs de dados do Google em geral, consulte a documentação de autenticação.
A maioria das amostras nas seções seguintes deste documento pressupõe que você tenha um objeto de cliente autenticado chamado $gdClient.
Autenticação OAuth
Para ver a documentação sobre a autenticação OAuth com a biblioteca GData PHP do Zend, consulte OAuth nas bibliotecas de cliente do protocolo de dados do Google.
Autenticação via proxy do AuthSub
A autenticação de proxy dSYM é 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 dSYM especiais que permitem ao cliente agir em nome de um usuário específico. Para informações mais detalhadas, consulte a documentação do SWF.
Quando um usuário visita seu aplicativo pela primeira vez, ele ainda não foi autenticado. Nesse caso, é necessário exibir algumas informações e um link que direcione o usuário para uma página do Google para autenticar sua solicitação de acesso aos blogs. A biblioteca de cliente do Zend oferece uma função para gerar o URL da página do Google. O código abaixo recupera o URL da página dSYMRequest:
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 dSYMRequest):
- próxima
- O URL da página a que o Google deve redirecionar o usuário após a autenticação.
- escopo
- Indica que o aplicativo está solicitando um token para acessar feeds do Blogger. A string do escopo a ser usada é
http://www.blogger.com/feeds/(codificada para URL, é claro). - proteger
- Indica se o cliente está solicitando um token seguro.
- seção
- Indica se o token retornado pode ser trocado por um token multiuso (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 ter a seguinte aparência:
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 faz a autenticação, o sistema dSYM os redireciona para o URL especificado no parâmetro de consulta next do URL de dSYMRequest. O sistema dSYM 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 recuperar 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 dSYM 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 dSYM já está
presente. Se não for, mas um token de uso único for especificado no URL, o snippet de código transmitirá o token de uso único para o método getAuthSubSessionToken, e a interface dSYM retornará um token de sessão. Em seguida, o código coloca o valor do token de sessão na variável de sessão $_SESSION['sessionToken'].
O aplicativo pode usar o valor do token de sessão em interações
subsequentes com o Blogger. Você pode usar o método
Zend_Gdata_AuthSub::getHttpClient para receber um objeto Zend_Http_Client
que tenha a predefinição de cabeçalho Authorization para incluir credenciais
dSYM.
$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 independente"instalado"(como um aplicativo de desktop).
O código a seguir usa o método Zend_Gdata_ClientLogin::getHttpClient para executar uma solicitação ao serviço ClientLogin, recuperar 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 é explicitamente definido 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 amostra, consulte a documentação de Autenticação em 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 CAPTCHA. Se você quiser que o Google emita e processe o desafio CAPTCHA, envie o usuário para
https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger,
em vez do URL de gerenciamento do CAPTCHA fornecido na documentação do
ClientLogin.
Recuperar uma lista de blogs
A API de dados do Blogger fornece um feed que lista os blogs para um usuário específico. Esse feed é conhecido como "metafeed."
O exemplo de código a seguir usa um objeto $gdClient autenticado
para recuperar o metafeed e imprimir o título de cada blog.
A classe
Zend_Gdata_Query cuida da construção do URL da consulta. Nesse caso, não é necessário realizar nenhum trabalho
adicional, mas a utilidade da classe Query vai se tornar
visível 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++;
}
}
Observe o URL usado pelo método getFeed. Este é o URL do metafeed padrão. Ele retorna uma lista de blogs para o usuário autenticado no momento.
Para acessar um feed de um usuário diferente, coloque o ID do usuário em vez 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ê precisará dele para executar operações de criação, atualização e exclusão em postagens e comentários. A variável $index representa
o blog usado no feed do blog do usuário. O campo id assume o formato
tag:blogger.com,1999:user-userID.blog-blogID. Portanto, uma
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 de dados do Blogger permite criar e publicar novas entradas de blog, bem como criar rascunhos de entradas.
Observação: no momento, não é possível definir um autor personalizado para postagens. Todas as novas postagens aparecerão como se tivessem sido criadas pelo usuário autenticado no momento.
Publicar uma postagem do blog
Você pode usar a biblioteca de cliente PHP para publicar novas entradas de blog.
Primeiro, crie uma instância de entrada para representar a postagem do blog. Depois você pode definir o título, o conteúdo e outros atributos da postagem. Por fim, chame o método
insertEntry
para inserir a postagem. É possível ver as instanciações mágicas
de fábrica 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;
}
Criando um rascunho de postagem do blog
Os rascunhos de postagens são criados 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 um 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];
}
Da mesma forma que você define 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 os atribua ao atributo de controle de entrada.
É possível transformar um rascunho de postagem do blog em uma postagem publicada recuperando-a, definindo o atributo de rascunho como no e atualizando-a. Abordaremos a recuperação e a atualização das postagens nas próximas duas seções.
Recuperar postagens
As seções a seguir descrevem como recuperar uma lista de postagens de blog, com e sem parâmetros de consulta.
Você pode consultar um feed público do Blogger sem autenticação. Portanto, você não precisa definir credenciais ou fazer a autenticação dSYM antes de recuperar postagens de um blog público.
Recuperar 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, desta vez, envie o URL do feed da postagem 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
Com a API de dados do Blogger, você pode solicitar um conjunto de entradas que correspondam a critérios específicos, como a solicitação de postagens do blog publicadas ou atualizadas em um determinado período. Para fazer isso, crie um objeto de consulta e transmita-o para o
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 a seguir imprime o título e o conteúdo de cada postagem do blog publicada entre os horários de início e término informados:
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 mostrará 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 de dados do Blogger aceita os seguintes parâmetros de consulta:
- categories
- Especifica as categorias (também conhecidas como rótulos) para filtrar os resultados do feed. Por exemplo,
http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurieretorna entradas com os rótulosFritzeLaurie. - max-results
- O número máximo de entradas a serem retornadas.
- min-min, publicado-max
- Os limites nas datas de publicação das entradas.
- start-index
- O índice baseado em 1 do primeiro resultado a ser recuperado (para paginação).
Para mais informações sobre os parâmetros de consulta, consulte o Guia de referência da API de dados do Blogger e o Guia de referência das APIs de dados do Google.
Atualizando postagens
Para atualizar uma postagem do blog, primeiro recupere a entrada que quer atualizar, modifique-a e envie-a ao Blogger usando o método save. O snippet de código a seguir modifica o título e o
conteúdo de uma entrada do 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 a postagens.
Como excluir postagens
Para excluir uma postagem, transmita o URL de edição da postagem ao método delete
no objeto $gdClient, desta maneira:
public function deletePost($gdClient, $blogID, $postID)
{
$uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default/' . $postID;
$gdClient->delete($uri);
}
Comentários
A API de dados do Blogger permite criar, recuperar e excluir comentários. Não é possível atualizar comentários (nem disponível na interface da Web).
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 de propriedade do usuário autenticado.
Observação: no momento, não é possível definir um autor personalizado para comentários. Todos os novos comentários serão exibidos como se tivessem sido criados pelo usuário autenticado no momento.
Como recuperar comentários
Você pode recuperar os comentários de uma postagem específica no URL de feed de comentários da postagem:
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);
}
Também é possível receber os comentários de todas as postagens usando o URL do feed de comentários do blog:
http://www.blogger.com/feeds/blogID/comments/default
Como excluir comentários
Para excluir um comentário, transmita o URL de edição dele para o método delete no objeto $gdClient da seguinte maneira:
public function deleteComment($gdClient, $blogID, $postID, $commentID)
{
$uri = 'http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default/' . $commentID;
$gdClient->delete($uri);
}