Guia do desenvolvedor: PHP

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

Seu aplicativo cliente pode usar a API de dados do Blogger para criar novas postagens, editar ou excluir postagens existentes e consultar as postagens que correspondam a critérios específicos.

Além de fornecer algumas informações sobre os recursos da API de dados do Blogger, este documento traz exemplos de interações básicas dessa API usando a biblioteca de cliente das APIs de dados do Google do Zend. Se você quiser entender mais sobre o protocolo subjacente que a biblioteca usa, consulte a seção "Protocolo" deste Guia para desenvolvedores.

Conteúdo

  1. Público
  2. Como começar
    1. Como criar uma conta do Blogger
    2. Como executar o exemplo de código
    3. Como usar getters e setters mágicos
    4. Outros recursos
  3. Como autenticar no serviço do Blogger
    1. Autenticação OAuth
    2. Autenticação por proxy do AOSP
    3. Autenticação por nome de usuário/senha do PuTTY
  4. Como recuperar uma lista de blogs
  5. Criar postagens
    1. Publicar uma postagem do blog
    2. Como criar o rascunho de uma postagem do blog
  6. Recuperar postagens
    1. Recuperar todas as postagens do blog
    2. Como recuperar postagens usando parâmetros de consulta
  7. Como atualizar postagens
  8. Como excluir postagens
  9. Comentários
    1. Como criar comentários
    2. Recuperar comentários
    3. Como excluir comentários

Público

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

Este documento pressupõe que você compreende 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 PHP. Para informações gerais de referência da API Blogger Data, consulte o Guia de referência de protocolo.

Como começar

Para receber ajuda na configuração da biblioteca de cliente, consulte o Guia explicativo.

A biblioteca de cliente do Zend requer PHP 5.1.4 ou posterior. 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.

Como criar uma conta do Blogger

Recomendamos que você se inscreva em uma conta do Blogger para fins de teste. O Blogger usa Contas do Google. Portanto, se você já tem uma, não precisa fazer mais nada.

Como executar o código de amostra

Um cliente de amostra completo e funcional, contendo todo o código de amostra mostrado neste documento, está disponível no repositório SVN do Zend Framework. A amostra está localizada em /framework/standard/trunk/demos/Zend/Gdata/Blogger.php. A amostra 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, pode ser necessário definir o include_path e carregar as classes adequadas. O caminho de inclusão pode ser definido usando a configuração php.ini ou o método set_include_path. Esse código solicita acesso às classes Zend_Gdata principais, Zend_Gdata_Query e 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

Em toda a biblioteca de cliente PHP, foi adicionado suporte para setters/getters mágicos para uma conveniência para os desenvolvedores. Isso permite que as propriedades de uma classe sejam acessadas com segurança usando os métodos setter/getter tradicionais ou as propriedades. Por exemplo, se $gdataObject for uma instância de um objeto nessa 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, métodos de fábrica mágicos facilitam a declaração de novos objetos. Em vez de se lembrar dos nomes de classes longos exigidos pela convenção de nomenclatura 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 mágicos e as fábricas são opcionais. Portanto, use a abordagem que funcionar melhor para você.

Outros recursos

Outros recursos para o componente de APIs de dados do Google do Zend Framework (Zend_Gdata):

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 particulares. Ele pode autenticar usando qualquer uma destas três abordagens: OAuth, autenticação de proxy AuthSub 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 dos exemplos nas seções subsequentes deste documento presume que você tem um objeto de cliente autenticado chamado $gdClient.

Autenticação OAuth

Para ver a documentação sobre a autenticação OAuth usando a biblioteca GData para PHP do Zend, consulte OAuth nas bibliotecas de cliente do protocolo de dados do Google (em inglês).

Autenticação via proxy do AuthSub

A autenticação por proxy BYOL é 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 MRAID especiais que permitem que ele atue em nome de um usuário específico. Para informações mais detalhadas, consulte a documentação do MRAID (em inglês).

Quando um usuário acessa seu aplicativo pela primeira vez, ele ainda não foi autenticado. Nesse caso, você precisa exibir algumas informações e um link que direciona o usuário a uma página do Google para autenticar sua solicitação de acesso aos blogs dele. 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 NGINXRequest:

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 StatefulSetRequest):

próxima
O URL da página para onde o Google deve 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/ (codificado em URL, obviamente).
seguro
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 esta 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.

Após a autenticação do usuário, o sistema StatefulSet redireciona o usuário para o URL especificado no parâmetro de consulta next desse URL. O sistema NGINX 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 vezes em que use 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 noindex 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 BYOL 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'].

Seu 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 acessar um objeto Zend_Http_Client que tenha a predefinição de cabeçalho Authorization para incluir credenciais do Tensorflow:

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

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

Use a autenticação GroupByKey se seu cliente for um cliente "instalado" independente e de usuário único (como um aplicativo de área de trabalho).

O código a seguir usa o método Zend_Gdata_ClientLogin::getHttpClient para executar uma solicitação ao serviço Systrace, 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 criar um objeto de serviço Zend_Gdata.

Observe que $accountType está 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 ConstraintLayout, incluindo exemplos de solicitações e respostas, 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 ConstraintLayout, a solicitação de autenticação pode falhar e solicitar um desafio de CAPTCHA. Se você quiser que o Google emita e lide com o desafio CAPTCHA, encaminhe o usuário para https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (e não para o URL de processamento de CAPTCHA fornecido na documentação do Systrace).

Como recuperar uma lista de blogs

A API de dados 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 um objeto $gdClient autenticado para recuperar 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 nenhum trabalho extra, mas a utilidade da classe Query 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++;
  }
}

Observe o URL usado pelo método getFeed. Esse é o URL de metafeed padrão. Ele retorna uma lista de blogs para o usuário autenticado no momento. Para acessar o feed de outro usuário, coloque o ID do usuário 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ê 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 blog 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

Com a API Blogger Data, você pode 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 serão exibidas como se tivessem sido criadas pelo usuário autenticado no momento.

Publicar uma postagem do blog

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

Primeiro, crie uma instância de entrada para representar a postagem do blog. Em seguida, defina o título, o conteúdo e outros atributos da postagem do blog. Por fim, chame o método insertEntry para inserir a postagem. Veja as instanciações mágicas da 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;
}

Como criar o rascunho de uma postagem do blog

Os rascunhos de postagens são criados da mesma forma que as públicas, mas é necessário definir o atributo de rascunho do objeto de entrada. Você pode criar uma postagem como rascunho adicionando as linhas destacadas às linhas a seguir:

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ê configura o título ou o conteúdo de uma postagem, cria novos objetos Zend_Gdata_App_Extension_Control e Zend_Gdata_App_Extension_Draft e os atribui ao atributo de controle da entrada.

Para transformar um rascunho de postagem do blog em uma publicada, basta recuperar a postagem de rascunho, definir o atributo de rascunho como no e atualizar a postagem. Abordaremos como recuperar e atualizar postagens nas próximas duas seções.

Recuperando postagens

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

Você pode consultar um feed público do Blogger sem autenticação. Portanto, não é necessário definir credenciais ou fazer a autenticação do StatefulSet antes de recuperar postagens de um blog público.

Recuperando 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 da postagem do blog desta vez:

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 Blogger Data, você pode solicitar um conjunto de entradas que correspondam 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 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 abaixo imprime o título e o conteúdo de cada postagem do blog publicada entre os horários 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 é o getQueryUrl(), que mostra o URL codificado que foi construído.

Observação: no momento, não há configuradores 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 oferece suporte aos seguintes parâmetros de consulta:

categories
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.
min-publicado, máx.-publicado
Os limites para as datas de publicação das inscrições.
start-index
O índice baseado 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 Blogger Data e o Guia de referência das APIs Google Data.

Atualizando postagens

Para atualizar uma postagem do blog, primeiro recupere a entrada que você quer atualizar, modifique-a e envie-a 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.

Excluindo postagens

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

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).

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 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.

Recuperando comentários

Você pode recuperar os comentários de uma postagem específica no URL do 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);
}

Ou você pode obter 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

Excluindo comentários

Para excluir um comentário, transmita o URL de edição dele ao método delete no objeto $gdClient da seguinte forma:

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