Руководство разработчика клиентской библиотеки .NET

В этом документе описывается, как использовать клиентскую библиотеку .NET для отправки запросов Google Data API («GData») и интерпретации возвращенных ответов.

Google предоставляет набор клиентских библиотек для взаимодействия с сервисами на базе GData на различных языках программирования. Используя эти библиотеки, вы можете создавать запросы к GData, отправлять их сервису и получать ответы.

В этом документе представлен набор примеров распространённого использования клиентской библиотеки C#, а также дополнительная информация о написании клиентов GData. В конце документа представлена ссылка на справочную документацию по клиентской библиотеке C# в формате NDoc.

Для использования этой клиентской библиотеки вам понадобится среда выполнения .NET 1.1, а также должны быть установлены все актуальные исправления.

Загрузите клиентскую библиотеку .NET.

Примеры в этом руководстве относятся к API Google Calendar, но оно не является точным или актуальным руководством по использованию API Calendar. Сведения об использовании клиентской библиотеки .NET с API данных конкретного сервиса см. в документации по данному сервису. Например, если вы работаете с Calendar, ознакомьтесь с Руководством разработчика по API данных Calendar .

Содержание

  1. Аудитория
  2. Обзор модели данных
  3. Учебное пособие и примеры
  4. Ссылка

Аудитория

Этот документ предназначен для программистов C#, которые хотят писать клиентские приложения, способные взаимодействовать со службами GData.

Предполагается, что этот документ знаком с общими идеями протокола Google Data API . Также предполагается, что вы умеете программировать на языке C#.

Обзор модели данных

Клиентская библиотека C# предоставляет набор классов, соответствующих элементам и типам данных, используемым в API Google Data. Например, существует класс Feed, соответствующий элементу <atom:feed> ; он содержит методы для создания записи, получения и установки значений различных подэлементов и так далее. Также существует класс Entry, соответствующий элементу <atom:entry> . Не каждый элемент, определённый в API Google Data, имеет собственный класс; подробности см. в справочной документации .

Библиотека может автоматически анализировать содержимое Atom и помещать значения элементов Atom в соответствующие объекты. Например, метод getFeed получает ленту, анализирует её и возвращает объект Feed с полученными значениями.

Чтобы отправить канал или запись в службу, вы создаете объект Feed или Entry, а затем вызываете библиотечный метод (например, метод insert ), чтобы автоматически перевести объект в XML и отправить его.

При желании вы можете самостоятельно анализировать и/или генерировать XML; проще всего это сделать с помощью соответствующей сторонней библиотеки.

Подобно тому, как синтаксис XML API Google Data является расширяемым, соответствующая объектная модель также является расширяемой. Например, клиентская библиотека предоставляет классы, соответствующие элементам, определённым в пространстве имён Google Data .

Учебное пособие и примеры

В следующих примерах показано, как отправлять различные запросы GData с помощью клиентской библиотеки C#.

Чтобы сделать примеры более конкретными, мы покажем, как взаимодействовать с конкретным сервисом: Google Calendar. Мы укажем на отличия Calendar от других сервисов Google, чтобы помочь вам адаптировать эти примеры для использования с другими сервисами. Подробнее о Calendar см. в документации по API данных Google Calendar .

Создание и запуск вашего клиента

Чтобы скомпилировать примеры в этом документе, вам необходимо использовать следующий оператор using:

using Google.GData.Client;

Запрос фида

Как описано в документации API данных Календаря Google , вы можете запросить канал Календаря, отправив следующий HTTP-запрос в Календарь:

GET http://www.google.com/calendar/feeds/userID/private/full

Конечно, вам необходимо заменить userID на адрес электронной почты пользователя; подробности см. в документе «Календарь». Вместо этого вы можете использовать специальный URL-адрес по умолчанию для взаимодействия с Календарем (как описано в документе «Календарь»), но в этом документе мы будем использовать закрытый URL-адрес полной ленты, содержащий идентификатор пользователя.

Вам также необходимо обеспечить соответствующую аутентификацию. Обратите внимание, что используемая здесь система аутентификации (известная как «Аутентификация Google для установленных приложений») подходит только для использования в установленных клиентских приложениях, таких как настольные клиенты, но не в веб-приложениях. Подробнее об аутентификации см. в документации по аутентификации аккаунта Google .

Чтобы запросить ленту календаря с помощью клиентской библиотеки C# для пользователя с адресом электронной почты «jo@gmail.com» и паролем «mypassword», используйте следующий код:

// Create a query and service object:

FeedQuery query = new FeedQuery();
Service service = new Service("cl", "exampleCo-exampleApp-1"));
// Set your credentials:
service.setUserCredentials("jo@gmail.com", "mypassword");

// Create the query object:
query.Uri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Tell the service to query:
AtomFeed calFeed = service.Query(query);

Класс Service представляет собой клиентское подключение (с аутентификацией) к сервису GData. Общая процедура отправки запроса к сервису с использованием клиентской библиотеки состоит из следующих шагов:

  1. Получите или создайте соответствующий URL-адрес.
  2. Если вы отправляете данные в службу (например, если вы вставляете новую запись), преобразуйте необработанные данные в объекты, используя классы клиентской библиотеки. (Этот шаг неприменим, если вы просто запрашиваете канал, как мы делаем в этом примере.)
  3. Создайте новый экземпляр Service , задав имя службы (например, "cl" для календаря) и имя вашего приложения (в форме companyName - applicationName - versionID ).
  4. Установите соответствующие учетные данные.
  5. Вызовите метод для отправки запроса и получения результатов.

Метод service.setUserCredentials устанавливает свойство service.Credentials со стандартным объектом учётных данных .NET Network. Учётные данные содержат идентификатор и пароль пользователя, от имени которого ваш клиент отправляет запрос. В примерах в этом документе используется система аутентификации «Аутентификация для установленных приложений» ; дополнительную информацию о других системах аутентификации см. в документации по аутентификации учётной записи Google .

Чтобы запросить весь фид, вы вызываете метод service.Query , который принимает объект FeedQuery и возвращает весь фид, найденный по этому URL. Далее в этом документе мы покажем, как отправлять более конкретные запросы.

Как и другие методы класса Service , Query выполняет аутентификацию и перенаправления по мере необходимости.

Вставка нового элемента

Чтобы вставить элемент в ленту календаря, вы можете использовать следующий код:

AtomEntry entry = new AtomEntry();
AtomPerson author = new AtomPerson(AtomPersonType.Author);
author.Name = "Jo March"; 
author.Email = "jo@gmail.com";
entry.Authors.Add(author);
entry.Title.Text = "Tennis with Beth"; 
entry.Content.Content = "Meet for a quick lesson.";

Uri postUri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Send the request and receive the response:
AtomEntry insertedEntry = service.Insert(postUri, entry);

После установки URL мы создаем объект AtomEntry .

Заголовок записи представляет собой AtomTextConstruct — класс, содержащий текст в различных форматах (обычный текст, HTML или XHTML). Содержимое записи представлено объектом AtomContent — классом, который может содержать как обычный текст, так и другие форматы контента, включая XML и двоичные данные.

Каждый автор представлен именем, URI и адресом электронной почты. (В этом примере мы опускаем URI.) Чтобы добавить автора к записи, добавьте объект AtomAuthor в коллекцию Authors записи.

Мы используем тот же объект Service , который создали в предыдущем примере. В этом случае вызываемый метод — Insert , который отправляет элемент по указанному URL-адресу вставки.

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

Приведенный выше код эквивалентен отправке POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (с надлежащей аутентификацией) и предоставлению записи.

Запрос конкретной записи

Следующий код позволяет вам запросить конкретную запись, вставленную в предыдущем примере.

В контексте этой серии примеров извлечение этой записи на самом деле не является необходимым, поскольку Calendar уже вернул вставленную запись; но тот же метод можно применять в том случае, если вам известен URL-адрес записи.

FeedQuery singleQuery = new FeedQuery();
singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); 
AtomFeed newFeed = service.Query(singleQuery);
AtomEntry retrievedEntry = newFeed.Entries[0];

Вставленная запись имеет свойство SelfUri , которое возвращает объект AtomUri , который с помощью метода ToString() можно использовать для создания нового объекта URI.

Затем нам просто нужно вызвать метод Query сервиса, чтобы получить новый объект AtomFeed с одной записью в коллекции Entries.

Приведенный выше код эквивалентен отправке GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/ entryID в Календарь с надлежащей аутентификацией.

Поиск записи

Чтобы получить первое совпадение в полнотекстовом поиске, используйте следующий код:

FeedQuery myQuery = new Query(feedUrl);
myQuery.Query = "Tennis"; 
AtomFeed myResultsFeed = myService.Query(myQuery);
if (myResultsFeed.Entries.Count > 0) {
  AtomEntry firstMatchEntry = myResultsFeed.Entries[0]; 
  String myEntryTitle = firstMatchEntry.Title.Text; 
}

Этот пример начинается с создания объекта FeedQuery , который состоит в основном из URL-адреса и связанных с ним параметров запроса. Каждый стандартный параметр запроса GData имеет свойство.

После создания FeedQuery мы передаём его методу Query сервиса, который возвращает фид, содержащий результаты запроса. Альтернативный подход — самостоятельно сформировать URL (добавив параметры запроса к URL фида) и затем вызвать метод Query , но метод FeedQuery предоставляет полезный уровень абстракции, так что вам не придётся создавать URL самостоятельно.

Коллекция Entries фида возвращает список записей в фиде; Entries.Count возвращает количество записей в фиде.

В этом случае, если запрос вернул какие-либо результаты, мы присваиваем первый совпадающий результат объекту AtomEntry . Затем мы используем свойство Title класса AtomEntry для получения заголовка записи.

Приведенный выше код эквивалентен отправке GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis в Календарь.

Запрос по категории

Примечание : Google Calendar не связывает метки с событиями, поэтому этот пример не работает с Календарем.

Чтобы получить канал, состоящий из всех записей, соответствующих предыдущему полнотекстовому поиску и относящихся к определенной категории или имеющих определенную метку, используйте следующий код:

AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);

Класс AtomCategory , конечно же, представляет категорию, используемую в фильтре категорий. Класс QueryCategory может содержать несколько категорий, но в данном случае мы создаём фильтр только с одной категорией.

Затем мы добавляем этот фильтр к существующему запросу, который по-прежнему содержит строку полнотекстового запроса из предыдущего примера.

Мы снова используем метод Query для отправки запроса в службу.

Если бы Календарь допускал поиск по категориям, указанный выше код был бы эквивалентен отправке GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis в Календарь.

Обновление элемента

Чтобы обновить существующую запись, используйте следующий код. В следующем примере мы меняем заголовок ранее полученной записи со старого текста («Теннис с Бет») на «Важная встреча».

retrievedEntry.Title.Text = "Important meeting";
retrievedEntry.Update();

Сначала мы устанавливаем новый заголовок для ранее полученной записи. Затем мы просто вызываем метод Upate , чтобы отправить обновлённую запись сервису.

Служба возвращает обновлённую запись, включая новый URL для новой версии этой записи. (Дополнительную информацию о версиях записей см. в разделе «Оптимистичный параллелизм» справочного документа протокола v1 .)

Приведенный выше код примерно эквивалентен отправке PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/ entryID в службу вместе с новой записью (в формате Atom) для замены исходной записи.

Удаление элемента

Чтобы удалить существующий элемент, используйте следующий код:

updateEntry.Delete();

URL-адрес, используемый для удаления, тот же, что и URL-адрес редактирования, поэтому этот пример очень похож на предыдущий, за исключением того, что мы вызываем метод Delete вместо Update .

Приведенный выше код примерно эквивалентен отправке DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/ entryID в службу.

Работа с лентами Google Календаря

Приведённые выше примеры показывают, как использовать API Google Data на C# для работы с общими лентами GData. Однако при работе с лентой Google Календаря этот канал содержит множество специфичных для календаря данных, к которым сложно получить доступ с помощью стандартных объектов Atom в базовой библиотеке API. Для взаимодействия с этими лентами мы предлагаем следующие расширения: 

using Google.GData.Extensions;
using Google.GData.Calendar;

Пространство имён Extensions отвечает за расширения в целом; пространство имён Calendar предоставляет доступ к настраиваемому сервису календаря, ленте новостей и объектам запросов. Более подробный пример использования этих расширений можно найти в подкаталоге /Samples каталога установки API C#. Добавляются следующие объекты:

EventQuery
Подкласс FeedQuery, который позволяет вам задавать два пользовательских параметра для службы календаря (start-min и start-max).
CalendarService
Подкласс сервиса, который может возвращать ленту событий.
EventFeed
Подкласс AtomFeed, предоставляющий EventEntries.
EventEntry
Подкласс AtomEntry, имеющий дополнительные свойства, связанные с данными календаря.

Более подробную информацию об этих специальных классах можно найти в документации API и примерах программ.

Ссылка

Справочную информацию о клиентской библиотеке C# см. в справочной документации .

Вернуться наверх