Узнайте о федеративном протоколе Google Wave и примите участие
Робот является автоматизированным участником волны. Робот может считывать содержание волны, участником которой он является, изменять его, добавлять и удалять участников, а также создавать всплески и волны. Проще говоря, робот может выполнять большинство действий, которые могут выполнять другие участники.
Робота можно использовать для выполнения следующих действий:
Этот список не является исчерпывающим: роботы позволяют выполнять намного больше различных действий. Помимо перечисленного, по мере расширения возможностей API роботы смогут пользоваться новыми функциями.
Для разработки роботов Google Wave необходима соответствующая клиентская библиотека. На данный момент существуют библиотеки для языков программирования Java™ и Python.
Чтобы получить дополнительную информацию о клиентских библиотеках, сообщить о проблемах и запросить функции, посетите главную страницу Ресурсов Google Wave на Хостинге проектов Google. На этой же странице находятся ссылки для загрузки новейших версий клиентских библиотек.
Робот (в отличие от гаджета) активно участвует в волне посредством HTTP-запросов и ответов, отправляемых по протоколу роботов Google Wave. Вам необязательно знать тонкости этого протокола, поскольку мы предоставляем клиентские библиотеки Java и Python, которые можно использовать для создания роботов и управления ими. Вскоре будет опубликована документация о базовом HTTP-протоколе роботов Google Wave.
В настоящее время Google Wave поддерживает роботов, встроенных с помощью Google App Engine, масштабируемой среды веб-приложений. App Engine определяет веб-приложения по веб-адресу application.appspot.com. Кроме того, создавая роботов с помощью App Engine, можно неявным образом определить HTTP-интерфейс по URL http://application.appspot.com. Волна будет использовать этот адрес для взаимодействия с роботом (на данный момент этот адрес неявным образом определяет самого робота).
Благодаря клиентским библиотекам Java и Python можно создавать роботов, не беспокоясь об обработке отдельных HTTP-запросов и управлении ими. Поскольку этот код выпускается на ранней стадии разработки, впоследствии он может быть (и скорее всего будет) изменен. Тем не менее, при разработке клиентских библиотек подразумевалась их относительная стабильность. Используя проводной протокол напрямую, не стоит забывать о возможных изменениях в будущем.
Пользователь (или расширение пользовательского интерфейса) добавляет робота в вейвлет так же, как и другого участника, т.е. с помощью идентификатора приложения App Engine робота, за которым следует @appspot.com, в качестве адреса участника волны. Например, если идентификатор приложения App Engine для робота – parrotybot, то адрес участника волны для него – parrotybot@appspot.com. Обратите внимание, что робот добавляется, можно сказать, по адресу электронной почты, однако для взаимодействия с ним API Google Wave будет использовать механизм HTTP.
Примечание. В этом предварительном выпуске для разработчиков все роботы Google Wave должны быть реализованы в виде приложений Google App Engine. В будущем будет обеспечена возможность размещения роботов на любых веб-хостах по любым URL-адресам.
Чтобы задать поведение робота, необходимо определить события, о которых его следует уведомлять. Волна взаимодействует с роботом при возникновении одного из этих событий, например при изменении волны, участником которой является робот. События, которые отслеживает робот, указываются в файле конфигурации capabilities.xml, который Google Wave получает у робота при его первом добавлении в волну.
Ниже показан пример файла capabilities.xml:
| 
<?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>
Примечание. Этот файл capabilities.xml автоматически создан клиентской библиотекой Python. Пользователи клиентской библиотеки Java должны создать файл самостоятельно.
Обратите внимание, что файл содержит единственный элемент <capabilities>, состоящий из одного или нескольких элементов <capability>. Каждая возможность представляет собой событие, о котором робот сообщает Google Wave. При возникновении события такого типа Google Wave передает роботу HTTP-запрос.
Помимо событий, обрабатываемых роботом, этот документ содержит другую информацию о его профиле, определяющую его в качестве участника вейвлета, такую как имя и аватар. Файл конфигурации робота должен быть доступен по следующему URL-адресу:
http://applicationURL/_wave/capabilities.xml
Ниже перечислены важные события, на которые может подписаться робот:
wavelet_blip_created вызывается при создании всплеска волны. wavelet_participants_changed вызывается при добавлении или удалении участника (в том числе робота) из волны.wavelet_title_changed вызывается при изменении вейвлета.blip_contributors_changed вызывается при изменении редакторов всплеска.blip_deleted вызывается при удалении всплеска из вейвлета.blip_submitted вызывается при отправке всплеска. Обратите внимание, что это событие возникает, только если пользователь нажимает Готово или переходит к другому всплеску.document_changed вызывается при добавлении содержания в всплеск через разные промежутки времени.Помимо вызова робота по событиям, Google Wave может вызывать робота через регулярные промежутки времени. Для этого нужно составить расписание в файле конфигурации робота. Эти события cron позволят роботу выполнять действия, не являющиеся ответными на изменения в волне, например обновление волны путем добавления новой информации из внешней системы.
Обратите внимание, что робот не может взаимодействовать с Google Wave напрямую. Он может только отвечать на события cron и события, происходящие в волне.
При возникновении события Google Wave выполняет HTTP-запрос к приложению робота с помощью HTTP-метода POST. Этот же метод используется при отправке веб-форм. Все события, связанные с изменениями в данных волны, для связи с роботом используют следующий URL-адрес:
http://applicationURL/_wave/robot/jsonrpc
Каждый запрос по этому URL-адресу из Google Wave может содержать несколько событий одного вейвлета. Недавние события можно объединять вместе. Получив событие, робот определяет, отвечать ли на него (и каким образом), предоставляя ответ в операции.
Веб-запрос из Google Wave содержит информацию об одном или нескольких событиях. В ответ робот может отправить указания обновить все волны, участником которых он является, или создать вейвлеты с помощью операций в системе событий волны.
Робот может выполнять операции во всех вейвлетах, участником которых он является, а также создавать вейвлеты и волны. Робот не получает уведомлений о выполненных операциях. Однако о них уведомляются остальные участники измененных вейвлетов, в том числе и другие роботы.
Операции обрабатываются в порядке их получения. Роботы не обладают особыми преимуществами по сравнению с другими пользователями. Операции роботов отправляются в Google Wave и выполняются асинхронно. Нет никаких гарантий, что другие участники не будут в это же время выполнять свои операции. В итоге, лучше всего использовать атомарные операции и не забывать о том, что запрошенные операции могут быть применены не сразу. Волна представляет собой исторический объект. Она включает исходное содержание, а также последующие операции, выполненные над данными.
Клиентские библиотеки приложений Java и Python предоставляют полноценный интерфейс для обработки событий и выполнения операций. Например, обработчик событий Java использует веб-сервлет для ответа на запросы Google Wave, преобразуя данные событий в объекты и вызывая для каждого из них метод в сервлете. Метод создает операции, обрабатывая объекты, представляющие модель данных Google Wave. После выполнения метода сервлет отправляет все операции обратно в Google Wave для применения к данным.
Примечание. Формат данных входящего события и исходящих операций определяется в проводном протоколе Google Wave для роботов. За время использования этого предварительного выпуска для разработчиков сведения о протоколе могут измениться. Как только протокол станет стабильным, будет опубликована спецификация, описывающая форматы сообщений. Тем временем, для анализа событий и вызова операций можно использовать клиентские библиотеки Java и Python.
На данный момент роботам в API Google Wave присваиваются версии. Это позволяет системе Google Wave определять изменения роботов и их возможностей. Изменив возможности робота (например, добавив или удалив отслеживаемые события), необходимо также изменить идентификатор его версии (который сейчас представляется в виде текстовой строки).
Обратите внимание, что идентификатор версии хранится в файле робота capabilities.xml (для Java) и указывается в конструкторе робота (для Python). Этот идентификатор версии робота не связан с системой контроля версий App Engine. (Версии App Engine позволяют развертывать несколько версий кода на различных клиентах.)
Помимо прочего для роботов можно указывать разнообразные метаданные. Эту информацию можно запросить у робота с помощью следующего HTTP-запроса:
http://applicationURL/_wave/robot/profile
По умолчанию робот не предоставляет информацию о профиле. Чтобы это выполнялось, в приложение Java нужно добавить сервлет Profile, который передает эти данные. В Python эту информацию нужно указать в конструкторе робота. Подробную информацию можно получить в документации по клиентским библиотекам.
Будем рады получить от вас отзывы в ходе этого предварительного выпуска для разработчиков! Отправляйте свои комментарии и предложения в группу API Google Wave.
Архитектура роботов новая, и полноценных инструментов для отладки пока не существует. Тем не менее, в случае выявления проблемы в ходе разработки робота вам могут пригодиться следующие тесты:
capabilities.xml? Чтобы проверить, правильно ли развернут файл, нужно вызвать робота по адресу http://robotname.appspot.com/_wave/capabilities.xml. Получение XML-ответа указывает, что робот правильно развернут в App Engine.capabilities.xml.)capabilities.xml правильные события для получения роботом?https://appengine.google.com для развертывания своего робота. Если получите ошибку, то вероятно, что у вас ошибка в коде.