Guia do desenvolvedor: Python

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 da API Data usando a biblioteca de cliente do Python. Se você quiser saber mais sobre o protocolo subjacente usado pela biblioteca, consulte a seção Protocolo deste guia para desenvolvedores.

Conteúdo

Público-alvo

Este documento é destinado a programadores que querem criar aplicativos cliente Python 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 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 Python requer o Python 2.2 ou mais recente. Depois de fazer o download da biblioteca de cliente, também será necessário fazer o download e instalar o pacote ElementTree.

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 arquivo BloggerExample.py, no diretório gdata-python-client/samples/blogger/.

O cliente de exemplo realiza várias operações no blog fornecido para demonstrar o uso da API Data do Blogger.

É possível executar o exemplo com os seguintes argumentos:

python BloggerExample.py --email [email_address] --password [password]

Para usar os exemplos deste documento no seu próprio código, você vai precisar das seguintes instruções import:

from gdata import service
import gdata
import atom

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 das 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 uma instância GDataService autenticada.

Autenticação OAuth

Para conferir a documentação sobre a autenticação OAuth usando a biblioteca Python 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 do Python fornece uma função para gerar o URL da página do Google. O código abaixo recupera o URL da página AuthSubRequest:

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 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.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 é 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.pyc?token=yourAuthToken

Há várias maneiras de extrair 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 do AuthSub 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 seu token de uso único para o método UpgradeToSessionToken, e a interface do AuthSub retorna um token de sessão.

O aplicativo pode usar o valor do token de sessão em interações posteriores com o Blogger. A biblioteca de cliente envia automaticamente o token 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 "instalado" independente para um único usuário, como um aplicativo de computador. 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 nosso aplicativo no formulário 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 é 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.

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 exemplo de código a seguir usa uma instância GDataService autenticada para extrair 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

Anote o URL usado pelo método Get. 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. O snippet abaixo escolhe o primeiro blog recuperado para 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 mais tarde. Na maioria dos exemplos a seguir neste documento, blog_id é transmitido como uma variável.

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 Python para publicar novas entradas de blog.

Primeiro, crie uma instância GDataEntry 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, use a instância GDataService para inserir a postagem. Confira um exemplo de como publicar uma nova postagem do 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!')

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 elemento de extensão draft na instância GDataEntry. A postagem do blog acima pode ser criada como um 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?')

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 postagens 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 método GetFeed com o URL do feed de postagens 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

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 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 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 fornecidos:

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 oferece suporte às seguintes propriedades Query:

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. Para especificar essa consulta de categoria na biblioteca de cliente Python, use query.categories = ['Fritz','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).
updated_min, updated_max
Os limites nas datas de atualização da entrada. Esses parâmetros de consulta são ignorados, a menos que o parâmetro orderby seja definido como updated.

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 Put. O snippet de código a seguir modifica o título de uma entrada de blog, assumindo que você já recuperou 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 toda a postagem recém-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 às postagens.

Como excluir postagens

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

def DeletePost(blogger_service, edit_link_href):
  blogger_service.Delete(edit_link_href)

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 GDataEntry e insira 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 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 pelo URL do feed de comentários:

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 

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 GDataService, como este:

def DeleteComment(blogger_service, post_id, comment_id):
  feed_url = '/feeds/' + post_id + '/comments/default/' + comment_id
  blogger_service.Delete(feed_url)

Voltar ao início