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 Python. Se você quiser saber mais sobre o protocolo subjacente que a biblioteca usa, consulte a seção de protocolo deste guia do desenvolvedor.
Índice
Público-alvo
Este documento é destinado a programadores que querem criar aplicativos cliente Python que possam 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 gerais de referência da API de dados do Blogger, 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 Python requer o Python 2.2 ou mais recente. Depois de fazer o download da biblioteca de cliente, você também precisará fazer o download e instalar o pacote ElementTree.
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 completo de trabalho, contendo todo o exemplo de código mostrado neste
documento, está disponível no arquivo BloggerExample.py, no diretório
gdata-python-client/samples/blogger/.
O cliente de amostra executa várias operações no blog fornecido para demonstrar o uso da API de dados do Blogger.
É possível executar o exemplo com os seguintes argumentos:
python BloggerExample.py --email [email_address] --password [password]
Para usar os exemplos neste documento no seu próprio código, você precisará das seguintes instruções import:
from gdata import service import gdata import atom
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 OAuth, autenticação de proxy SMTP 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 uma instância GDataService autenticada.
Autenticação OAuth
Para ver a documentação sobre a autenticação do OAuth usando a biblioteca GData do Python, 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 Python fornece uma função para gerar o URL da página do Google. O código abaixo recupera o URL da página Ao definir uma solicitação na Web:
def GetAuthSubUrl(): next = 'http://www.example.com/welcome.pyc' scope = 'http://www.blogger.com/feeds/' secure = False session = True blogger_service = service.GDataService() return blogger_service.GenerateAuthSubURL(next, scope, secure, session); authSubUrl = GetAuthSubUrl(); print '<a href="%s">Login to your Google account</a>' % authSubUrl
O método GenerateAuthSubURL 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 poderá 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.pyc
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.pyc?token=yourAuthToken
Há várias maneiras de recuperar o valor do token do URL. Por exemplo:
import cgi parameters = cgi.FieldStorage() authsub_token = parameters['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 UpgradeToSessionToken,
que chama o serviço AuthSubSessionToken:
blogger_service = service.GDataService() blogger_service.auth_token = authsub_token blogger_service.UpgradeToSessionToken()
Ou seja, você transmite o token de uso único para o método UpgradeToSessionToken, e a interface do dSYM retorna um token de sessão.
O aplicativo pode usar o valor do token de sessão em interações subsequentes com o Blogger. A biblioteca de cliente envia automaticamente o token junto com as solicitações.
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). Basta chamar o método ProgrammaticLogin() na instância GDataService e todas as interações subsequentes com o Blogger serão autenticadas:
blogger_service = service.GDataService('user@example.com', 'secretPassword')
blogger_service.source = 'exampleCo-exampleApp-1.0'
blogger_service.service = 'blogger'
blogger_service.account_type = 'GOOGLE'
blogger_service.server = 'www.blogger.com'
blogger_service.ProgrammaticLogin()
No snippet acima, definimos três propriedades na instância GDataService. O primeiro é o nome do aplicativo no
formato companyName-applicationName-versionID.
O segundo é o nome do serviço com que queremos interagir. O terceiro é o
endereço do servidor.
Observe que account_type é 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.
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."
A amostra de código a seguir usa uma instância autenticada do GDataService para recuperar o metafeed e imprimir o título de cada blog.
def PrintUserBlogTitles(blogger_service):
query = service.Query()
query.feed = '/feeds/default/blogs'
feed = blogger_service.Get(query.ToUri())
print feed.title.text
for entry in feed.entry:
print "\t" + entry.title.text
Observe o URL usado pelo método Get. 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. O snippet abaixo escolhe o primeiro blog recuperado de um usuário.
blog_id = feed.entry[0].GetSelfLink().href.split("/")[-1]
No exemplo BloggerExample.py, uma classe BloggerExample é criada, e o ID do blog é definido no construtor para facilitar o acesso posteriormente. Para a maioria dos exemplos a seguir neste documento,
blog_id é transmitido como uma variável.
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
É possível usar a biblioteca de cliente Python para publicar novas entradas de blog.
Primeiro, crie uma instância GDataEntry para representar a postagem do blog.
Depois você pode definir o título, o conteúdo e outros atributos da postagem.
Por fim, use a instância GDataService para inserir a postagem. Veja um exemplo de como publicar uma nova postagem no blog:
def CreatePublicPost(blogger_service, blog_id, title, content):
entry = gdata.GDataEntry()
entry.title = atom.Title('xhtml', title)
entry.content = atom.Content(content_type='html', text=content)
return blogger_service.Post(entry, '/feeds/%s/posts/default' % blog_id)
blogEntry = CreatePublicPost(blogger_service, blog_id,
title='I have the answer', content='Eureka! It is 42!')
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 elemento de extensão draft na instância
GDataEntry. A postagem do blog acima pode ser criada como rascunho adicionando as
linhas destacadas:
def CreateDraftPost(blogger_service, blog_id, title, content):
entry = gdata.GDataEntry()
entry.title = atom.Title('xhtml', title)
entry.content = atom.Content(content_type='html', text=content)
control = atom.Control()
control.draft = atom.Draft(text='yes')
entry.control = control
return blogger_service.Post(entry, '/feeds/%s/posts/default' % blog_id)
draftEntry = CreateDraftPost(blogger_service, blog_id,
title='I have the question',
content='What do you get if you multiply six by nine?')
É 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 método GetFeed com o URL do feed da postagem do blog:
def PrintAllPosts(blogger_service, blog_id):
feed = blogger_service.GetFeed('/feeds/' + blog_id + '/posts/default')
print feed.title.text
for entry in feed.entry:
print "\t" + entry.title.text
print "\t" + entry.content.text
print "\t" + entry.updated.text
print
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 uma instância Query e chame o
método Get().
Por exemplo, para enviar uma consulta de período, defina as propriedades published_min e published_min da instância Query.
O snippet de código a seguir exibe o título e o conteúdo de cada postagem do blog
publicada entre os horários de início e término informados:
def PrintPostsInDateRange(blogger_service, blog_id, start_time='2007-04-01', end_time='2007-04-25'):
query = service.Query()
query.feed = '/feeds/' + blog_id + '/posts/default'
query.published_min = start_time
query.published_max = end_time
feed = blogger_service.Get(query.ToUri())
print feed.title.text + " posts between " + start_time + " and " + end_time
for entry in feed.entry:
print "\t" + entry.title.text
print "\t" + entry.content.text
print "\t" + entry.updated.text
print
O objeto Query é criado usando o mesmo URL do feed de postagens usado para recuperar postagens.
A API Data do Blogger é compatível com as seguintes propriedades Query:
- 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. Para especificar essa consulta de categoria na biblioteca de cliente do Python, é possível usarquery.categories = ['Fritz','Laurie',] - max_results
- O número máximo de entradas a serem retornadas.
- publicados_min, publicados_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).
- updated_min, updated_max
- Os limites nas datas de atualização de entrada. Esses parâmetros de consulta são ignorados a menos que o parâmetro
orderbyesteja definido comoupdated.
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 Put. O snippet de código a seguir modifica o título de uma entrada de
blog, supondo que você já tenha recuperado a entrada do servidor.
def UpdatePostTitle(blogger_service, entry_to_update, new_title='The REAL answer'):
entry_to_update.title = atom.Title('xhtml', new_title)
return blogger_service.Put(entry_to_update, entry_to_update.GetEditLink().href)
O código acima retorna um GDataEntry contendo a postagem
completamente atualizada. Para atualizar outras propriedades, basta defini-las na instância GDataEntry antes de chamar Put.
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 GDataService, desta maneira:
def DeletePost(blogger_service, edit_link_href): blogger_service.Delete(edit_link_href)
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 GDataEntry e insira-o da seguinte maneira:
def CreateComment(blogger_service, blog_id, post_id, comment_text='Mostly harmless'): feed_uri = '/feeds/' + blog_id + '/' + post_id + '/comments/default' entry = gdata.GDataEntry() entry.content = atom.Content(content_type='xhtml', text=comment_text) return blogger_service.Post(entry, feed_uri)
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:
def PrintAllComments(blogger_service, blog_id, post_id):
feed_url = '/feeds/' + blog_id + '/' + post_id + '/comments/default'
feed = blogger_service.Get(feed_url)
print feed.title.text
for entry in feed.entry:
print "\t" + entry.title.text
print "\t" + entry.updated.text
print
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 GDataService da seguinte maneira:
def DeleteComment(blogger_service, post_id, comment_id): feed_url = '/feeds/' + post_id + '/comments/default/' + comment_id blogger_service.Delete(feed_url)