LXF120:GDA

Материал из Linuxformat.

Google Data API Используйте службы поискового гиганта в собственных приложениях

GData: Курс молодого бойца

Давно перестали удивляться, увидев Карты Google на сайтах, не имеющих отношения к Google? И правильно: никаких секретов здесь нет. Евгений Крестников научит вас легко проделывать такие трюки.

В LXF117 мы уже писали про онлайн-сервисы Google. Их возможности сегодня не ограничиваются поиском информации в Сети и доступом к электронной почте: пользователь может хранить на серверах Google свои документы и фотоальбомы, работать с картами или вести свой блог. Популярный видеосервис YouTube – это тоже Google. Но нас сегодня будут интересовать не сами сервисы, а возможность вызывать и использовать их в своих собственных приложениях. Это реализуется посредством Google Data API (API данных Google, сокращенно – GData). Процитируем Майкла «Chewy» Тревеллу [Michael Trewhella], консультантаGoogle по вопросам разработок (LXF117): «Google Data API представляет собой набор интерфейсов чтения и записи данных для широкого спектра онлайн-сервисов Google, использующих единый протокол. С его помощью Google позволяет сторонним разработчикам расширять функциональные возможности своих продуктов. Вместо того, чтобы создать API, построенный на разрозненном наборе протоколов, мы решили использовать стандарт AtomPub, основанный на технологиях Atom/XML и HTTP. Это значительно упрощает процесс обучения персонала для сторонних разработчиков. С тех пор, как спецификации AtomPub были утверждены в RFC 5023, многие компании стали создавать API, основанные на этом стандарте. В тех случаях, когда использование подобных интерфейсов не имеет смысла (например, в нашем поиске или Картах), мы предлагаем разработчикам использовать API AJAX».

На следующих четырех страницах мы дадим введение в API данных Google, которое поможет вам понять основные принципы работы с этим замечательным инструментарием. Мы не будем подробно описывать протоколы индикации или способы установки клиентских библиотек, предполагая, что вы – достаточно опытный web-разработчик, знакомый с Linux и желающий освоить новую технологию. А разобраться в деталях вам поможет документация, доступная по адресу http://code.google.com/intl/ru/apis/gdata/.

С чего начать?

Создатели Google Data API рекомендуют начинать его освоение с основных принципов и понятий. Затем вам предлагается остановиться на одной из доступных на сайте клиентских библиотек (ее выбор зависит от используемого вами языка программирования) или работать непосредственно с XML/HTTP. Последним этапом станет выбор службы Google, с которой вы собираетесь взаимодействовать, и чтение соответствующего раздела руководства. Это выглядит вполне разумным, так что на данном уроке мы будем следовать методике, рекомендованной компанией.

Согласно определению Википедии, web-синдикация – одновременное распространение информации на различные страницы или web-сайты. Основной принцип синдикации заключается в передаче заголовков материалов и ссылок на них (можно, например, получить информацию о новых сообщениях на форуме). Первоначально технология использовалась на новостных ресурсах и в блогах, но постепенно сфера ее применения расширилась. Сегодня существуют два формата оповещения об изменении существующих данных, появлении новых и ретрансляции информации в Сети: созданный компанией Netscape RSS и конкурирующий стандарт Atom. Оба они основаны на XML. Google Data API позволяет разработчику использовать RSS 2.0, Atom 1.0 и Atom Publishing Protocol (AtomPub или APP). Формат Atom имеет ряд преимуществ перед RSS – он легко расширяется и обладает большими возможностями. С помощью APP можно отправить HTTP-запрос GET к конкретному ресурсу (например, каналу данных или отдельному сообщению). Ответ от сервера придет в формате синдикации Atom. Кроме того, APP позволяет создавать, редактировать и удалять ресурсы, используя запросы типа POST, PUT или DELETE. К сожалению, ни в одном из стандартов нет возможности отправить серверу запрос на выборку данных по определенному критерию и получить обратно ответ со списком соответствующих результатов. Однако у Atom есть стандартный механизм расширений, при помощи которого GData легко справляется с подобными задачами

Каналы GData позволяют работать с блогами, новостными лентами, электронной почтой и другими сервисами Google. Отправлять запросы и получать их результаты можно через собственные приложения, с помощью стандартных программ для чтения RSS или расширений браузера. Протокол GData нейтрален к языкам программирования – вы можете написать клиент на любом языке, который позволяет отправлять HTTP-запросы и принимать ответы на основе XML. Чтобы получить данные от службы, поддерживающей GData, вам нужно отправить запрос HTTP GET. При этом служба выдаст результат в виде канала Atom или RSS. Она также может поддерживать обновления данных при помощи запроса HTTP PUT. Разумеется, сервис может предоставлять каналы только для чтения (например, канал результатов поиска) или для чтения и записи (скажем, Google Calendar). Есть только одно ограничение: GData не позволяет создавать и удалять каналы – это может делать только служба.

Библиотеки и программирование

Давайте сразу же договоримся, что мы не будем рассматривать вариант работы с XML/HTTP напрямую: он обладает наибольшей гибкостью (и трудоемкостью), но на Google Code есть ссылки на специализированные библиотеки практически для всех языков программирования: Java, .NET, PHP, Python, Objective-C, JavaScript; наиболее заметным исключением из этого списка является Perl. Они значительно упрощают процесс разработки, предоставляя высокоуровневый интерфейс, позволяющий абстрагироваться от деталей. Подробное описание всех форматов и протоколов на английском языке доступно на сайте http://code.google.com/intl/ru/apis/gdata/docs/2.0/reference.html.

Помимо официально представленных на сайте Google, в Сети можно найти другие клиентские библиотеки GData. Разумеется, описать все средства разработчика мы не в состоянии (для этого пришлось бы посвятить им весь номер), поэтому сосредоточимся на клиентской библиотеке PHP, поскольку многие динамические сайты в Сети разработаны с использованием именно этого языка программирования.

Клиентская библиотека для языка PHP предоставляется компанией Zend в рамках проекта Zend Framework, однако она может быть установлена отдельно. Рассмотрим последний вариант. Нам потребуется компьютер с Linux (другие операционные системы поддерживаются тоже, но нас они интересовать не будут) и PHP5 версии не ниже чем 5.2.4. Приводить подробную инструкцию по установке PHP также не станем: об этом написано в соответствующем разделе документации вашего дистрибутива (например, в Ubuntu достаточно набрать команду sudo apt-get install php5). Вместо этого сразу перейдем к процессу инсталляции библиотеки.

Для начала необходимо скачать ее последнюю версию со страницы http://framework.zend.com/ (на момент написания статьи была доступна Zend Gdata 1.8.3, но к моменту, когда вы будете читать эту статью, ситуация, естественно, может измениться) и распаковать архивный файл (в нашем случае – ZendGdata-1.8.3.tar.gz) в один из каталогов жесткого диска. После этого вы увидите несколько подкаталогов:

• demos – примеры приложений;
• documentation – документация по библиотеке;
• library – исходные тексты;
• tests – файлы для автоматического тестирования.

Кроме того, в корне архива есть несколько текстовых файлов – в частности, инструкция по установке. Инсталляция библиотеки не должна вызывать затруднений у опытных пользователей Linux (вам может потребоваться активировать некоторые расширения PHP, в первую очередь, openssl и iconv, если вы этого еще не сделали). Для начала работы достаточно добавить директорию библиотеки (подкаталог library из архива) в переменную PHP include_path. Это можно сделать через файл php.ini, конфигурационный файл Apache .htaccess или динамически, при помощи PHP-функции set_include_path() или ключа -d в командной строке.

Теперь нам необходимо проверить работоспособность установленного ПО. Для этого можно воспользоваться скриптом demos/Zend/Gdata/InstallationChecker.php. Как и прочие примеры из каталога demos/Zend/Gdata, он работает и как CGI-сценарий, и из командной строки. Если установка прошла успешно, вы увидите на экране результат, представленный на рисунке 1 (или аналогичный, но менее красочный вывод в консоли).

Выбираем сервис

Мы уже достаточно поговорили о доступных стороннему разработчику API данных Google в целом – теперь остановимся на них подробнее. API данных служб Google может быть использован для управления доменами, а также для интеграции решений Google и существующей ИТ-инфраструктуры. Google Base – это масштабируемая база данных, в которой пользователь может хранить общедоступную структурированную информацию. В сущности, сервис можно рассматривать как еще один способ закачивать данные в базы данных Google. Здесь можно разместить весь контент, который Google будет хранить и индексировать для специализированного интернет-поиска. В зависимости от релевантности, ваш контент может также быть включен и в главный поисковый индекс, и в другие продукты Google. API данных Google Base позволяет разработчикам запрашивать информацию, а также вводить данные и управлять ими из своих программ.

Blogger – сервис Google для создания блогов. С помощью API данных Blogger клиентские приложения могут добавлять, удалять или изменять записи, а также производить поиск по определенным критериям. Данные API позволяют добавить на сайт динамический список записей и комментариев, создать модуль расширения для публикации записей или агрегатор блога.

API данных Календаря Google позволяет создавать клиентские приложения для просмотра и обновления событий календаря в форме каналов API данных Google. С их помощью можно, например, разработать web-интерфейс для просмотра информации Календаря Google через внешний сайт, включить напоминание о предстоящих событиях, настроить синхронизацию Календаря Google с мобильным устройством и так далее. Логически примыкающие к нему API данных Контактов Google дают клиентским приложениям возможность просматривать и обновлять контактные данные. Если вы хотите, скажем, настроить синхронизацию списка контактов мобильного устройства с Контактами Google, можете воспользоваться им.

API данных Блокнота Google, как нетрудно догадаться по его названию, обеспечивает приложениям возможность доступа к содержимому Блокнота Google. С его помощью программа-клиент может запросить список общедоступных блокнотов пользователя или содержание существующего блокнота.

API данных Таблиц Google предназначены для просмотра и обновления содержания электронных таблиц в виде каналов GData. Клиентская программа может получить список таблиц пользователя, а также представлять, редактировать или удалять содержание книги в существующей таблице. API данных Документов Google позволяет загружать документы и сохранять их как каналы API данных Google. Кроме того, можно запросить список документов пользователя, а также изучать содержание существующего документа.

API данных web-альбомов Picasa дает пользователю возможность работать с альбомами Picasa из клиентской программы: получать список альбомов, комментариев и тэгов пользователя, а также просматривать, редактировать и удалять содержимое существующей записи. С их помощью легко, например, добавить свои общедоступные фотографии на собственный сайт и дать посетителям возможность комментировать их, сохраняя комментарии в альбомах Picasa.

API данных YouTube предоставляет доступ практически ко всему функционалу сервиса. С его помощью вы можете добавлять видео, изменять избранное, метаданные комментарии и настройки, а также осуществлять поиск роликов по заданным критериям и многое другое.

Google Docs из PHP5

Работу с онлайн-сервисами Google при помощи Zend Gdata 1.8.3 мы рассмотрим на примере Google Docs. Искушенный web-разработчик, пожалуй, назовет наш пример чересчур простым – и, возможно, он будет прав. Однако излишняя функциональность (а также проверка возникающих ошибок, совершенно необходимая при разработке реального приложения) будет только мешать основной цели – получению представления о Google Data API, а наш сценарий, несмотря на кажущуюся простоту, включает все ключевые элементы «настоящей» программы: открытие сессии, чтение данных, предоставляемых службой Google, и их изменение. Говоря более конкретно, наша программа будет получать список документов, имеющихся у некоторого пользователя в службе Google Docs, печатать их имена в стандартный вывод, а затем выгружать на сервер новый файл.

Большинство служб Google (и Документы – не исключение) требуют авторизации. Для этих целей в GData предусмотрено три метода: ClientLogin, OAuth и AuthSub. Первый из них наиболее прост в реализации и может быть рекомендован в тех случаях, когда ваша программа может напрямую запросить имя учетной записи и пароль у пользователя. Если это по каким-либо причинам нежелательно (что часто имеет место в случае web-приложений), можно прибегнуть к услугам посредника, который выполнит за вас идентификацию посетителя и сообщит, тот ли он, за кого себя выдает.

01: <?php
 02: require_once 'Zend/Loader.php';
 03: Zend_Loader::loadClass('Zend_Gdata_Docs');
 04: Zend_Loader::loadClass('Zend_Gdata_Docs_Query');
 05: Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
 06: $login = 'user.name@gmail.com';
 07: $password = 'password';
 08: $srv = Zend_Gdata_Docs::AUTH_SERVICE_NAME;
 09: try {
 10: $client = Zend_Gdata_ClientLogin::getHttpClient($login, $password, $srv);
 11: }
 12: catch (Zend_Gdata_App_Exception $e) {
 13: echo “Ошибка: $e->getMessage()\n”;
 14: exit(1);
 15: }

В строках 2–5 мы подключаем библиотеку и загружаем из нее необходимые нам классы: Zend_Gdata_Docs (работа с документами Google), Zend_Gdata_Docs_Query (поиск по запросу) и Zend_Gdata_ClientLogin (авторизация пользователя по первому методу). Реквизиты задаются в строках 6 и 7; переменная $login должна содержать полный e-mail адрес пользователя. Переменная $srv, определяемая в строке 8, задает имя службы Google, в которой вы хотите авторизоваться. Здесь оно представлено символьной константой Zend_Gdata_Docs::AUTH_SERVICE_NAME, которая (на момент написания статьи) просто равна строке ‘writely’ (если вы забыли, откуда ведет свою родословную Google Docs, спросите у Википедии: http://ru.wikipedia.org/wiki/Google_Docs, и этот набор букв обретет смысл). Статический метод getHttpClient(), вызываемый в строке 10, возвращает объект Zend_Gdata_HttpClient, который используется для доступа к данным Google Docs. Он может выбрасывать ряд исключений, в том числе Zend_Gdata_App_AuthException (ошибка авторизации) или Zend_Gdata_App_CaptchaRequiredException (для завершения процесса авторизации пользователь должен ввести текст, указанный на картинке, дабы подтвердить свою человеческую природу). Здесь мы не делаем разницы между этими (и другими) исключительными ситуациями, а просто пишем не слишком информативное сообщение об ошибке и выходим из программы.

Далее, давайте попробуем получить список документов учетной записи. Для этого нам потребуется создать главный объект программы: Zend_Gdata_Docs (обратите внимание, что его конструктор принимает в качестве параметра ссылку на объект HTTP-клиента, полученную ранее). Для тестирования программы мы создали специального пользователя – список его документов и вывод скрипта можно видеть на рисунках 2 и 3:

$mydocuments = new Zend_Gdata_Docs($client);
 $myfeed = $mydocuments->getDocumentListFeed();
 echo “Список документов аккаунта:\n”;
 foreach ($myfeed->entries as $entry)
  { echo “----> $entry->title\n”;
 }

Здесь все просто: объект со списком документов возвращается методом getDocumentListFeed(). Его элементы (то есть отдельные документы) доступны как $myfeed->entries; $entry->title возвращает название документа.

Последнее, что мы сделаем – загрузим новый документ на сервер; результат выполнения этой операции можно видеть на рисунках 4 и 5.

$localname=“/tmp/test.txt”;
 $googledoc=“test.txt”;
 $newdoc = $mydocuments->uploadFile($localname, $googledoc, null, Zend_Gdata_Docs::DOCUMENTS_LIST_FEED_URI);
 echo “Загружен документ: $newdoc->title\n”;
 ?>

Мы берем локальный файл /tmp/test.txt (предполагается, что он существует) и выгружаем его на сервер под именем test.txt. Два оставшихся аргумента метода uploadFile() задают mime-тип выгружаемого файла и URI службы, которая принимает его (константа Zend_Gdata_Docs::DOCUMENTS_LIST_FEED_URI или, что то же самое, http://docs.google.com/feeds/documents/private/full).

В такой форме наша программа имеет одну неприятную особенность: после выполнения ее N раз подряд вы обнаружите в своих Документах Google N штук файлов test.txt. Если это не то, чего вы желаете, перед выгрузкой документа на сервер следует проверить наличие старой версии и, при необходимости, удалить ее. Это делает следующий код (его нужно разместить сразу после объявления переменных $localname и $googledoc):

$query = new Zend_Gdata_Docs_Query();
 $query->setTitle($googledoc);
 $query->setTitleExact(“true”);
 try {
   $doc = $mydocuments->getDocumentListEntry($query);
   $docExists = true;
 } catch (Exception $e) {
   $docExists = false;
 }
 if ($docExists) {
   echo “Удаляю предыдущую версию документа $doc->title\n”;
   $doc->delete();
 }

Объект Zend_Gdata_Docs_Query представляет собой запрос к службе Google Docs. Запросы – это просто специально сформированные URL (наш, например, будет иметь вид http://docs.google.com/feeds/documents/private/full?title=test.txt&title-exact=true), но для удобства работы с ними мы вновь применяем высокоуровневый API. Метод setTitle() задает название документа, который мы ищем, а setTitleExact() указывает, что нас интересует только точное соответствие, а не совпадение с подстрокой.

Удивительно, но в случае отсутствия требуемого документа метод getDocumentListEntry(), выполняющий поиск, не возвращает null или пустой объект Zend_Gdata_Docs_DocumentListEntry, а выбрасывает исключение. Это не очень удобно, поэтому мы используем специальную логическую переменную $docExists, чтобы удалить старую версию файла с сервера, если она уже существует.

Что дальше?

Вот так, вкратце, выглядят Google Data API. Если вас заинтересовали технологии Google, советуем вам изучить сайт http://code.google.com/ – там находится, пожалуй, самое полное руководство по GData. Его посещение будет полезно не только начинающим «гуглокодерам», но и знатокам, поскольку продукты и сервисы поискового гиганта развиваются очень быстрыми темпами и, соответственно, регулярно обновляется и API. Так, пока мы писали эту статью, компания анонсировала сразу два интересных проекта: Webelements и Wave. Первый имеет непосредственное отношение ко GData – пройдя по ссылке http://www.google.com/webelements/, пользователь может выбрать интересующий его сервис (поддерживаются: Календарь, Карты, Google Talk, поиск в Web, лента новостей, новости YouTube, а также презентации и таблицы Google Docs) и получить готовый код для своего сайта, позволяющий встроить сервис Google в виде плавающего фрейма. В рамках второго планируется разработать альтернативный транспорт для обмена сообщениями, который (по замыслу компании) заменит электронную почту и сервисы IM (ICQ и иже с ними). Так что держите руку на пульсе, а мы постараемся в этом вам помочь, регулярно публикуя обзоры новых возможностей открытого ПО. LXF