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

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

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

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

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

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

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

Содержание

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

Аудитория

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

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

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

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

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

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

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

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

Учебник и примеры

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

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

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

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

using Google.GData.Client;

Запрос фида

Как описано в документации по Google Calendar Data API , вы можете запросить ленту календаря, отправив Календарю следующий 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 не связывает ярлыки с событиями, поэтому этот пример не работает с Календарем.

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

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 Календаря

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

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

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

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

Дополнительные сведения об этих специальных классах см. в документации по API и в программе примеров.

Ссылка

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

Вернуться к вершине