Сегодня рассмотрим пример добавления нового события в календарь Google. Но в начале несколько слов об устройстве самого сервиса Google Календарь в целом.
Итак, Google Calendar предназначен для планирования своего времени, а также для планирования времени, например группы разработчиков. Вы можете создавать в своем календаре открытые мероприятия, приглашать друзей (открывать им доступ), при этом действия по добавлению друзей в календарь сильно напоминает работу с подписчиками в блоге, за одним исключением — вы сами должны добавить подписчика. Для удобства работы с сервисом Google дает возможность пользователю создать на одном аккаунте несколько календарей, например один — для личного пользования, другой — для друзей, третий — для планирования рабочего времени и т.д. И именно это обстоятельство (множество календарей на одном аккаунте) следует учитывать при работе с API Google Calendar.
Теперь, что касается устройства сервиса с точки зрения разработчика. Здесь все предельно стандартно (что естественно при работи с любым API Google) — вся работа с сервисом основывается двух видах документов (или частях документ, как угодно) — Feed и Entry. Каждый Feed будет содержать как минимум всю служебную информацию, например, название генератора документа, сведения об авторе и т.д., а также один или несколько элементов Entry. В зависимости от того какой запрос отправляется на сервер, Entry могу содержать (применительно к Google Caledar API):
- Информацию по календарю
- Информацию по событиям календаря
- Информацию о владельцах календаря (уровни доступа)
- Информацию о подписчиках
Таким образом для того, чтобы добавить новое мероприятие в календарь нам необходимо выполнить следующие действия:
- Авторизоваться в сервисе (для этого у нас уже есть готовый модуль GoogleLogin)
- Получить список календарей или Feed отдельного календаря
- Сформировать правильный элемент Entry, содержащий информацию по мероприятию
- Отправить Entry на правильный адрес.
Последовательность запросов к серверу может быть следующей:
1. Запрашиваем список всех календарей на аккаунте отправив GET на адрес
http://www.google.com/calendar/feeds/default/allcalendars/full
При этом следует учитывать, что Feed будет содержать абсолютно все календари, включая и те, что доступны только на чтение, например календарь погоды. И при работе с этим списком надо будет проводить анализ уровней доступа к отдельно взятому календарю. Если Вас такой вариант работы не устраивает, то можно получить список календарей пользователя для которых установлен режим и чтения и записи. Для этого необходимо отправить тот же GET на адрес:
http://www.google.com/calendar/feeds/default/owncalendars/full
В полученом Feed’е будут календари в которые можно будет добавлять мероприятия без лишних проверок.
2. Получаем данные календаря, необходимые для того, чтобы добавить мероприятие.
В описании Google Celendar API дается пример добавления нового мероприятия в календарь по-умолчанию. Т.е. POST-запрос предлагается отправить на один из следующих адресов:
http://www.google.com/calendar/feeds/default/private/full
http://www.google.com/calendar/feeds/UserID/private/full
где UserID — идентификатор пользователя (e-mail).
То есть не важно сколько у Вас календарей — мероприятие попадет в первый календарь. Чтобы избежать такой ситуации и добавить новое в мероприятия именно в тот календарь, который нам нужен, необходимо провести простой анализ узлов links в элементе Entry отдельного календаря.
Обычно Entry содержит несколько узлов Links, которые выглядят следующим образом:
Каждый из этих узлов несет определенную информацию. Применительно к нашему случаю, нам необходимо получить атрибут href из узла link у которого атрибут rel имеет следующее значение:
rel="http://schemas.google.com/gCal/2005#eventFeed"
и именно на этот адрес (из атрибута href) следует отправлять POST-запрос. В этом случае мероприятие окажется в том календаре, в котором надо.
Теперь у нас есть авторизация в аккаунте, выбран календарь и есть URL на который мы будем отправлять запрос. Осталось этот запрос правильно сформировать.
3. Формируем запрос
Запрос должен содержать элемент Entry, который описывает новое мероприятие, т.е. название, описание, даты начала и окончания, статус (отменено, подтверждено, запланировано). Как формировать документ с Entry, чтобы не возникало ошибок я рассматривал в посте «XML в Delphi и недействительные пространства имен (xmlns).«. В описании API дается следующий пример Entry для мероприятия:
Tennis with Beth Meet for a quick lesson.
Это самый общий вариант Entry. Дополнительно для нового мероприятия можно указать метод оповещения (СМС, почта, всплывающее окно). Чтобы указать метод оповещения, необходимо добавить один или несколько узлов gd:reminder в документ. И здесь есть один момент, которые следует учитывать.
Дело в том, что у Календаря Google есть два вида мероприятий: одиночное, т.е. то которое возникает один раз за всё время и повторяющееся, то которое будет повторяться, например еженедельно, ежедневно и т.д. Об этих мероприятиях я говорил вчера. Момент, который следует учитывать, заключается в том, что при создании одиночного мероприятия все узлы gd:reminder необходимо делать дочерними для узла gd:when, а при повторяющемся — дочерними узлами для узла entry. Если этого не учитывать, то новое мероприятие не добавиться в список.
И последнее. При отправке запросов к серверу необходимо всегда контролировать, возвращаемый сервером код статуса. Дело даже не в том, что по коду можно определить успешность или ошибку отправки запроса. Дело в том, Google при запросе может (не знаю уж для чего) сделать перенаправление на другой адрес. Столкнулся я с этим буквально вчера — при запросе списка календарей меня перенаправили на другой адрес при том, что ДО вчерашнего дня никаких перенаправлений не было. При отправке новых мероприятия тоже самое — один раз запрос проходит нормально, в другой раз — перенаправляет. Но, по большому счёту, учёт перенаправлений — мелочи :).
На данный момент продолжаю работать с мероприятиями в календаре. Добавление сделано, осталось поработать с зпросами на изменения и удаление мероприятий.