Przewodnik programisty dotyczący biblioteki klienta .NET

W tym dokumencie opisano, jak za pomocą biblioteki klienta .NET wysyłać zapytania do interfejsu Google Data API („GData”) i interpretować zwracane odpowiedzi.

Google udostępnia zestaw bibliotek klienta do interakcji z usługami obsługującymi GData w różnych językach programowania. Za pomocą tych bibliotek możesz tworzyć żądania GData, wysyłać je do usługi i otrzymywać odpowiedzi.

Ten dokument zawiera zestaw przykładów typowych zastosowań biblioteki klienta w wersji C#, a także inne informacje o pisaniu klientów GData. Na końcu tego dokumentu znajduje się link do dokumentacji referencyjnej biblioteki klienta C# w formacie NDoc.

Aby korzystać z tej biblioteki klienta, musisz mieć środowisko wykonawcze .NET 1.1 i wszystkie najnowsze poprawki.

Pobierz bibliotekę klienta .NET

Przykłady w tym przewodniku odnoszą się do interfejsu Google Calendar API, ale nie jest to dokładny ani aktualny przewodnik po korzystaniu z tego interfejsu. Informacje o korzystaniu z biblioteki klienta .NET z interfejsem Data API konkretnej usługi znajdziesz w dokumentacji tej usługi. Jeśli na przykład pracujesz z Kalendarzem, przeczytaj przewodnik dla programistów korzystających z interfejsu Calendar Data API.

Spis treści

  1. Odbiorcy
  2. Omówienie modelu danych
  3. Samouczek i przykłady
  4. Produkty

Odbiorcy

Ten dokument jest przeznaczony dla programistów C#, którzy chcą pisać aplikacje klienckie, które mogą wchodzić w interakcje z usługami GData.

W tym dokumencie zakładamy, że znasz ogólne założenia protokołu interfejsów API danych Google. Zakładamy też, że znasz język C#.

Omówienie modelu danych

Biblioteka klienta C# udostępnia zestaw klas odpowiadających elementom i typom danych używanym przez interfejsy Google Data API. Na przykład klasa Feed odpowiada elementowi <atom:feed> i ma metody tworzenia wpisu, pobierania i ustawiania wartości różnych elementów podrzędnych itp. Jest też klasa Entry, która odpowiada elementowi <atom:entry>. Nie każdy element zdefiniowany w interfejsach Google Data API ma własną klasę. Szczegółowe informacje znajdziesz w dokumentacji referencyjnej.

Biblioteka może automatycznie analizować treść Atom i umieszczać wartości elementów Atom w odpowiednich obiektach. Na przykład metoda getFeed pobiera plik danych, analizuje go i zwraca obiekt Feed z wynikowymi wartościami.

Aby wysłać plik danych lub wpis do usługi, utwórz obiekt Feed lub Entry, a następnie wywołaj metodę biblioteki (np. metodę insert), aby automatycznie przetłumaczyć obiekt na XML i go wysłać.

Jeśli wolisz, możesz samodzielnie analizować lub generować pliki XML. Najłatwiej to zrobić za pomocą odpowiedniej biblioteki innej firmy.

Podobnie jak składnia XML interfejsu Google Data API jest rozszerzalna, tak samo jest rozszerzalny odpowiadający jej model obiektowy. Na przykład biblioteka klienta udostępnia klasy odpowiadające elementom zdefiniowanym w przestrzeni nazw Google Data.

Samouczek i przykłady

Poniższe przykłady pokazują, jak wysyłać różne żądania GData za pomocą biblioteki klienta w języku C#.

Aby były bardziej konkretne, te przykłady pokazują, jak korzystać z określonej usługi: Kalendarza Google. Wskażemy miejsca, w których Kalendarz różni się od innych usług Google, aby pomóc Ci dostosować te przykłady do innych usług. Więcej informacji o Kalendarzu znajdziesz w dokumentacji interfejsu Google Calendar Data API.

Tworzenie i uruchamianie klienta

Aby skompilować przykłady w tym dokumencie, musisz użyć tego stwierdzenia:

using Google.GData.Client;

Prośba o plik danych

Zgodnie z dokumentacją interfejsu Google Calendar Data API możesz poprosić o plik danych Kalendarza, wysyłając do Kalendarza to żądanie HTTP:

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

Oczywiście musisz zastąpić userID adresem e-mail użytkownika. Szczegółowe informacje znajdziesz w dokumencie Kalendarza. Zamiast tego możesz użyć specjalnego domyślnego adresu URL do interakcji z Kalendarzem (zgodnie z opisem w dokumencie Kalendarza), ale w tym dokumencie będziemy używać prywatnego pełnego adresu URL kanału, który zawiera identyfikator użytkownika.

Musisz też zapewnić odpowiednie uwierzytelnianie. Pamiętaj, że system uwierzytelniania, którego tu używamy (znany jako „Uwierzytelnianie Google w przypadku zainstalowanych aplikacji”), jest odpowiedni tylko do użytku w zainstalowanych aplikacjach klienckich, takich jak aplikacje na komputery, a nie w aplikacjach internetowych. Więcej informacji o uwierzytelnianiu znajdziesz w dokumentacji Uwierzytelnianie konta Google.

Aby poprosić o plik danych Kalendarza za pomocą biblioteki klienta C# dla użytkownika o adresie e-mail „jo@gmail.com” i haśle „mypassword”, użyj tego kodu:

// 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);

Klasa Service reprezentuje połączenie klienta (z uwierzytelnianiem) z usługą GData. Ogólna procedura wysyłania zapytania do usługi za pomocą biblioteki klienta obejmuje te kroki:

  1. Uzyskaj lub utwórz odpowiedni adres URL.
  2. Jeśli wysyłasz dane do usługi (np. wstawiasz nowy wpis), przekształć surowe dane w obiekty za pomocą klas biblioteki klienta. (Ten krok nie ma zastosowania, jeśli tylko prosisz o plik danych, jak w tym przykładzie).
  3. Utwórz nową instancję Service, ustawiając nazwę usługi (np. "cl" dla Kalendarza) i nazwę aplikacji (w formacie companyName-applicationName-versionID).
  4. Ustaw odpowiednie dane logowania.
  5. Wywołaj metodę, aby wysłać żądanie i otrzymać wyniki.

Metoda service.setUserCredentials ustawia właściwość service.Credentials za pomocą standardowego obiektu .NET Network credentials. Dane logowania są ustawione na identyfikator i hasło użytkownika, w imieniu którego klient wysyła zapytanie. Przykłady w tym dokumencie korzystają z systemu uwierzytelniania „Uwierzytelnianie w przypadku aplikacji zainstalowanych”. Więcej informacji o innych systemach uwierzytelniania znajdziesz w dokumentacji Uwierzytelnianie konta Google.

Aby poprosić o cały plik danych, wywołaj metodę service.Query, która przyjmuje obiekt FeedQuery i zwraca cały plik danych znaleziony pod tym adresem URL. W dalszej części tego dokumentu pokażemy, jak wysyłać bardziej szczegółowe zapytania.

Podobnie jak inne metody klasy Service, metoda Query obsługuje uwierzytelnianie i przekierowania w razie potrzeby.

Wstawianie nowego elementu

Aby wstawić element do pliku danych Kalendarza, możesz użyć tego kodu:

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);

Po ustawieniu adresu URL tworzymy obiekt AtomEntry.

Tytuł wpisu to AtomTextConstruct, czyli klasa zawierająca tekst w różnych formach (zwykły tekst, HTML lub XHTML). Treść wpisu jest reprezentowana przez obiekt AtomContent, czyli klasę, która może zawierać zwykły tekst lub inne formy treści, w tym dane XML i binarne.

Każdy autor jest reprezentowany przez nazwę, identyfikator URI i adres e-mail. (W tym przykładzie pomijamy identyfikator URI). Aby dodać autora do wpisu, dodaj obiekt AtomAuthor do kolekcji Authors wpisu.

Używamy tego samego obiektu Service, który został utworzony w poprzednim przykładzie. W tym przypadku wywoływana metoda to Insert, która wysyła element do określonego adresu URL wstawienia.

Usługa zwraca nowo utworzony wpis, który może zawierać dodatkowe elementy wygenerowane przez serwer, takie jak adres URL do edycji wpisu.

Powyższy kod jest równoznaczny z wysłaniem POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (z odpowiednim uwierzytelnieniem) i podaniem wpisu.

Prośba o konkretny wpis

Poniższy kod umożliwia przesłanie żądania konkretnego wpisu, który został wstawiony w poprzednim przykładzie.

W kontekście tej serii przykładów pobieranie tego wpisu nie jest konieczne, ponieważ Kalendarz już zwrócił wstawiony wpis. Jednak tę samą technikę można zastosować, gdy znasz adres URL wpisu.

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

Wstawiony wpis ma właściwość SelfUri, która zwraca obiekt AtomUri, który za pomocą metody ToString() może służyć do tworzenia nowego obiektu URI.

Następnie musimy tylko wywołać metodę Query usługi, aby uzyskać nowy obiekt AtomFeed z tylko jednym wpisem w kolekcji Entries.

Powyższy kod jest odpowiednikiem wysłania do Kalendarza wartości GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID z odpowiednim uwierzytelnieniem.

Wyszukiwanie wpisu

Aby pobrać pierwsze dopasowanie w wyszukiwaniu pełnotekstowym, użyj tego kodu:

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; 
}

W tym przykładzie zaczynamy od utworzenia obiektu FeedQuery, który składa się głównie z adresu URL i powiązanych z nim parametrów zapytania. Każdy standardowy parametr zapytania GData ma właściwość.

Po utworzeniu obiektu FeedQuery przekazujemy go do metody Query usługi, która zwraca plik danych zawierający wyniki zapytania. Innym rozwiązaniem jest samodzielne utworzenie adresu URL (przez dodanie parametrów zapytania do adresu URL pliku danych) i wywołanie metody Query, ale metoda FeedQuery zapewnia przydatną warstwę abstrakcji, dzięki czemu nie musisz samodzielnie tworzyć adresu URL.

Kolekcja Entries pliku danych zwraca listę wpisów w pliku danych, a Entries.Count zwraca liczbę wpisów w pliku danych.

W takim przypadku, jeśli zapytanie zwróciło jakiekolwiek wyniki, przypisujemy pierwszy pasujący wynik do obiektu AtomEntry. Następnie używamy właściwości Title klasy AtomEntry, aby pobrać tytuł wpisu.

Powyższy kod jest odpowiednikiem wysłania do Kalendarza wartości GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis.

Wyszukiwanie według kategorii

Uwaga: Kalendarz Google nie przypisuje etykiet do wydarzeń, więc ten przykład nie działa w Kalendarzu.

Aby pobrać plik danych zawierający wszystkie wpisy pasujące do wcześniejszego wyszukiwania pełnotekstowego i należące do określonej kategorii lub mające określoną etykietę, użyj tego kodu:

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

Klasa AtomCategory reprezentuje oczywiście kategorię, która będzie używana w filtrze kategorii. Klasa QueryCategory może zawierać wiele kategorii, ale w tym przypadku tworzymy filtr z tylko jedną kategorią.

Następnie dodajemy ten filtr do istniejącego zapytania, które nadal zawiera ciąg zapytania pełnotekstowego z poprzedniego przykładu.

Ponownie używamy metody Query, aby wysłać zapytanie do usługi.

Gdyby Kalendarz umożliwiał wyszukiwanie kategorii, powyższy kod byłby równoznaczny z wysłaniem do niego znaku GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis.

Aktualizowanie elementu

Aby zaktualizować istniejący element, użyj tego kodu. W poniższym przykładzie zmieniamy tytuł wcześniej pobranego wpisu z „Tenis z Bethem” na „Ważne spotkanie”.

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

Najpierw ustawiamy nowy tytuł dla pobranego wcześniej wpisu. Następnie wywołujemy metodę Upate, aby wysłać zaktualizowany wpis do usługi.

Usługa zwraca zaktualizowany wpis, w tym nowy URL nowej wersji tego wpisu. (Więcej informacji o wersjach wpisów znajdziesz w sekcji Optymistyczne współbieżność w  dokumencie referencyjnym protokołu v1).

Powyższy kod jest w przybliżeniu równoważny wysłaniu do usługi kodu PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID wraz z nowym wpisem (w formacie Atom), który zastąpi oryginalny wpis.

Usuwanie elementu

Aby usunąć istniejący element, użyj tego kodu:

updateEntry.Delete();

Adres URL do usunięcia jest taki sam jak adres URL do edycji, więc ten przykład jest bardzo podobny do poprzedniego, z tym wyjątkiem, że wywołujemy metodę Delete zamiast Update.

Powyższy kod jest w przybliżeniu odpowiednikiem wysłania do usługi znaku DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID.

Praca z feedami Kalendarza Google

Powyższe przykłady pokazują, jak używać interfejsu Google Data C# API do pracy z ogólnymi plikami danych GData. Jeśli jednak pracujesz z plikiem danych Kalendarza Google, zawiera on wiele danych specyficznych dla kalendarza, które nie są łatwo dostępne przy użyciu standardowych obiektów zorientowanych na Atom w podstawowej bibliotece interfejsu API. Aby ułatwić Ci korzystanie z tych plików danych, udostępniamy te rozszerzenia:

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

Przestrzeń nazw Extensions dotyczy rozszerzeń ogólnie, a przestrzeń nazw Calendar zapewnia dostęp do dostosowanej usługi kalendarza, kanału i obiektu zapytania. Bardziej szczegółowy przykład użycia tych rozszerzeń znajdziesz w podkatalogu /Samples instalacji interfejsu C# API. Dodano te obiekty:

EventQuery
Podklasa FeedQuery, która umożliwia ustawienie 2 niestandardowych parametrów usługi Kalendarz (start-min i start-max).
CalendarService
Podklasa usługi, która może zwracać kanał wydarzeń.
EventFeed
Podklasa AtomFeed, która udostępnia EventEntries.
EventEntry
Podklasa AtomEntry, która ma dodatkowe właściwości związane z danymi kalendarza.

Więcej informacji o tych specjalnych klasach znajdziesz w dokumentacji interfejsu API i w programie przykładowym.

Dokumentacja

Informacje referencyjne o bibliotece klienta C# znajdziesz w dokumentacji.

Powrót do góry