Conheça o Protocolo da Federação do Google Wave e participe
Um robô é um participante automatizado de uma onda. Um robô pode ler o conteúdo de uma onda da qual participa, modificar o conteúdo dela, adicionar ou remover participantes e criar novos blips e novas ondas. Em resumo, um robô pode executar muitas das ações que qualquer outro participante pode.
Use o robô para executar as seguintes ações:
Você pode fazer muito mais coisas com os robôs além dessas listadas aqui. Além disso, conforme ampliamos os recursos da API, os robôs serão capazes de tirar proveito deles.
O desenvolvimento de robôs do Google Wave exige uma biblioteca-cliente adequada. Atualmente, temos bibliotecas-cliente para as linguagens de programação Java™ e Python.
Descubra mais informações sobre as bibliotecas-cliente, arquive problemas e faça solicitações de recursos na página inicial de Recursos do Google Wave na Hospedagem de projetos do Google. Essa página também contém links para download das bibliotecas-cliente mais recentes.
Um robô (diferentemente de um gadget) participa ativamente da onda por meio de solicitações HTTP e responde usando o protocolo de robôs do Google Wave. Não é necessário conhecer as particularidades desse protocolo, pois oferecemos bibliotecas-cliente Java e Python que você pode usar para criar e gerenciar os seus robôs. A documentação do protocolo HTTP subjacente do robô do Google Wave chegará em breve.
Atualmente, o Google Wave oferece suporte para robôs criados com o Google App Engine, o ambiente de aplicativo da web escalonável. O Google AppEngine identifica aplicativos da web que usam um endereço de web application.appspot.com. Ao criar robôs usando o Google AppEngine, você também define implicitamente uma interface HTTP no URL http://application.appspot.com. O Google Wave usa esse endereço ao se comunicar com o robô (e esse endereço define implicitamente um robô nesse momento).
As biblioteca-cliente Java e Python permitem desenvolver o robô sem se preocupar em manipular e gerenciar as solicitações HTTP individuais. Como essa é uma versão inicial de desenvolvedor, o código pode (e provavelmente irá) mudar no futuro. No entanto, as bibliotecas-cliente foram elaboradas para serem bastante estáveis. Se desejar usar o protocolo de rede diretamente, pode fazer isso, mas entenda que esse protocolo pode mudar no futuro.
Um usuário (ou uma extensão de interface de usuário) adiciona um robô a uma wavelet como adiciona qualquer outro participante, usando o ID de aplicativo do Google App Engine do robô seguido por @appspot.com como o seu endereço de participante da onda. Por exemplo, se o ID de aplicativo do Google App Engine de um robô for parrotybot, o endereço de participante da onda para o robô será parrotybot@appspot.com. O robô é adicionado pelo que parece ser um endereço de e-mail, embora a API do Google Wave use um mecanismo HTTP para entrar em contato com ele.
Observação: Nesta versão de previsualização do desenvolvedor, todos os robôs do Google Wave devem ser implementados como aplicativos do Google App Engine. Uma futura versão introduzirá a capacidade de hospedar robôs com qualquer host da web, em qualquer endereço.
Defina o comportamento do seu robô definindo os eventos sobre os quais deseja que ele seja notificado. O Google Wave entra em contato com o robô sempre que um desses eventos ocorre, como uma alteração feita em uma onda da qual o robô participa. O robô especifica em quais eventos se interessa em um arquivo de configuração capabilities.xml, que o Google Wave recupera do robô na primeira vez que ele é adicionado a uma onda.
Um arquivo capabilities.xml de exemplo é mostrado abaixo:
|
<?xml version="1.0"?>
<w:robot xmlns:w="http://wave.google.com/extensions/robots/1.0">
<w:capabilities>
<w:capability name="wavelet_participants_changed"/>
</w:capabilities>
</w:robot>
Observação: esse arquivo capabilities.xml é gerado automaticamente pela biblioteca-cliente Python. Os usuários da biblioteca-cliente Java precisam criar esse arquivo por conta própria.
Observe que esse arquivo contém um elemento <capabilities> único, que consiste em um ou mais elementos <capability>. Cada recurso consiste em um evento no qual o robô indica ter interesse para o Google Wave. Quando ocorre um evento desse tipo, o Google Wave envia uma solicitação HTTP para o robô.
Esse documento sobre recursos não somente descreve os eventos que o robô pode manipular, mas outras informações de perfil que identificam o robô como participante de uma wavelet, tais como nome e imagem do avatar. Cada robô deve oferecer o seu arquivo de configuração no seguinte caminho de URL:
http://applicationURL/_wave/capabilities.xml
Os seguintes eventos para os quais um robô pode se inscrever são particularmente importantes:
wavelet_blip_created dispara quando um novo blip da onda é criado. wavelet_participants_changed dispara sempre que um participante (incluindo outro robô) é adicionado à onda ou removido dela.wavelet_title_changed dispara sempre que o título da wavelet é alterado.blip_contributors_changed dispara sempre que os editores de um blip são alterados.blip_deleted dispara sempre que um blip é excluído da wavelet.blip_submitted dispara sempre que um blip é enviado. Esse evento é disparado somente quando o usuário clica em Concluído ou se move para outro blip.document_changed dispara sempre que um conteúdo é adicionado a um blip, em vários intervalos.Além de ser orientado por eventos, um robô pode solicitar que o Google Wave entre em contato com ele em intervalos regulares, especificando uma programação no arquivo de configuração. Esses eventos do cron permitem ao robô executar ações que não estão em resposta direta a alterações de uma onda, como atualizar uma onda com novas informações de um sistema externo.
Um robô não consegue entrar em contato com o Google Wave diretamente. Ele pode responder somente a eventos relacionados a uma onda e a eventos do cron.
Quando ocorre um evento, o Google Wave faz uma solicitação HTTP ao aplicativo do robô usando um POST HTTP, o mesmo método usado quando alguém envia um formulário da web. Todos os eventos relacionados a alterações nos dados da onda usam o seguinte caminho de URL ao entrar em contato com o robô:
http://applicationURL/_wave/robot/jsonrpc
Cada solicitação para esse URL a partir do Google Wave pode encapsular mais de um evento sobre uma única wavelet. Eventos recentes podem ser agrupados. Uma vez que o robô receba um evento, ele pode decidir se (e como) responde, encapsulando uma resposta em uma operação.
Uma solicitação da web a partir do Google Wave inclui informações sobre um ou mais eventos. O robô pode responder com instruções para atualizar qualquer onda da qual participa ou para criar novas wavelets por meio de operações no sistema de eventos da onda.
Um robô pode executar operações em qualquer wavelet da qual participa e também criar novas wavelets e ondas. As operações executadas por um robô não são informadas de volta ao robô que as fez, embora elas sejam informadas aos outros participantes das wavelets afetadas, incluindo outros robôs.
As operações são manipuladas na ordem em que são recebidas e os robôs não têm privilégios especiais sobre os outros usuários. As operações de robôs são enviadas ao Google Wave e executadas de modo assíncrono. Não há garantia de que outros participantes não possam executar suas próprias operações no tempo interveniente. Consequentemente, é melhor manter as suas operações o mais atômicas possíveis e entender que as operações aplicadas na onda podem não ser aplicadas imediatamente. Uma onda é uma entidade histórica e o seu conteúdo consiste em conteúdo original mais as operações acumulativas que ocorrem nesses dados.
As bibliotecas-cliente de aplicativo Java e Python oferecem uma interface completa para manipular eventos e executar operações. Por exemplo, o manipulador de evento Java usa um servlet da web para responder às solicitações do Google Wave, analisando os dados do evento nos objetos e chamando um método no servlet para cada evento. O método gera operações ao manipular objetos que representam o modelo de dados do Google Wave. Quando o método retorna, o servlet envia todas as operações de volta ao Google Wave para ser aplicadas aos dados.
Observação: O formato dos dados dos eventos de entrada e dos dados das operações de saída fazem parte do protocolo de rede do robô do Google Wave. Durante a versão de pré-visualização do desenvolvedor, os detalhes do protocolo de rede podem mudar. Uma vez que esse protocolo esteja estável, publicaremos uma especificação descrevendo os formatos de mensagem. Enquanto isso, você pode usar bibliotecas-cliente Java e Python para analisar eventos e gerar operações.
Os robôs dentro da API do Google Wave agora têm um número de versão. Isso permite ao sistema do Google Wave detectar quando robôs são alterados e/ou têm seus recursos alterados. Se modificar os recursos de um robô (adicionando ou removendo eventos monitorados, por exemplo), você deve alterar também o identificador da versão do robô (que é, atualmente, apenas uma string de texto).
Esse identificador de versão está dentro do arquivo capabilities.xml do robô (no Java) ou indicado no construtor do robô (no Python). Esse identificador da versão do robô não está relacionado ao sistema de criação do número de versão do Google App Engine (as versões do Google App Engine permitem a implementação de várias versões de código em diferentes clientes).
Os robôs podem ter, adicionalmente, uma variedade de informações meta anexadas a eles. Você pode solicitar essas informações do robô usando a seguinte solicitação HTTP:
http://applicationURL/_wave/robot/profile
Um robô, por padrão, não fornece informações de perfil. Para fornecer essas informações, em Java é preciso adicionar um servlet de perfil ao seu aplicativo que responda a esses dados. Em Python, forneça essas informações no construtor de robô. Consulte a documentação da biblioteca-cliente para obter mais informações.
Agradecemos os seus comentários durante esta pré-visualização de desenvolvedor! Poste os seus comentários e sugestões no grupo da API do Google Wave.
A arquitetura do robô é nova e ferramentas de depuração completas ainda não estão disponíveis. No entanto, se tiver problemas durante o desenvolvimento do seu robô, os seguintes testes podem ser úteis:
capabilities.xml do seu robô está ativo? Você pode testar se o arquivo está adequadamente implementado acessando o robô em http://robotname.appspot.com/_wave/capabilities.xml. Se receber uma resposta em XML, saberá que o seu robô foi implementado adequadamente no Google App Engine.capabilities.xml.capabilities.xml, o seu robô está configurado para receber os eventos corretos?https://appengine.google.com para a implementação do seu robô. Se receber um erro, provavelmente tem um erro de codificação.