Ten dokument opisuje, jak używać biblioteki klienta .NET do wysyłania zapytań do interfejsu Google Data API („GData”) i interpretowania zwróconych odpowiedzi.
Google udostępnia zestaw bibliotek klienckich do interakcji z usługami obsługiwanymi przez 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 korzystania z biblioteki klienta w wersji C# wraz z innymi informacjami o tworzeniu 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 oraz korzystać ze wszystkich poprawek.
Pobierz bibliotekę klienta .NET.
Przykłady w tym przewodniku odnoszą się do interfejsu Google Calendar API, ale nie jest on dokładny ani aktualny. Informacje o używaniu biblioteki klienta .NET z interfejsem Data API konkretnej usługi znajdziesz w dokumentacji tej usługi. Jeśli na przykład korzystasz z Kalendarza, przeczytaj Przewodnik dla programistów korzystających z interfejsu Calendar Data API.
Spis treści
Odbiorcy
Ten dokument jest przeznaczony dla programistów C#, którzy chcą tworzyć aplikacje klienckie, które mogą korzystać z usług GData.
W tym dokumencie założono, że rozumiesz ogólne pojęcia związane z protokołem interfejsów API danych Google. Zakładamy też, że wiesz, jak programować w języku C#.
Omówienie modelu danych
Biblioteka klienta C# zawiera zestaw klas odpowiadających elementom i typom danych używanym przez interfejsy API danych Google. Występuje na przykład klasa pliku danych, która odpowiada elementowi <atom:feed>, zawiera metody tworzenia wpisu, pobierania i ustawiania wartości różnych elementów podrzędnych itd. Istnieje też klasa wpisów odpowiadająca elementowi <atom:entry>. Nie każdy element zdefiniowany w interfejsach Google Data API ma własną klasę. Szczegółowe informacje znajdziesz w dokumentacji.
Biblioteka może automatycznie analizować zawartość Atom i umieszczać wartości elementów Atom w odpowiednich obiektach. Na przykład metoda getFeed pobiera plik danych, analizuje go i zwraca wynikowy plik danych z uzyskanymi wartościami.
Aby wysłać kanał lub wpis do usługi, musisz utworzyć obiekt kanału lub wpisu, a potem wywołać metodę biblioteki (np. metodę insert), by automatycznie przetłumaczyć obiekt na format XML i wysłać go.
Jeśli chcesz, możesz przeanalizować lub wygenerować plik XML samodzielnie. Najłatwiej zrobić to za pomocą odpowiedniej biblioteki zewnętrznej.
Tak jak w przypadku składni XML interfejsu API danych Google, również można stosować tę samą strukturę obiektów. Na przykład biblioteka klienta udostępnia klasy odpowiadające elementom zdefiniowanym w przestrzeni nazw danych Google.
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 zobaczyć bardziej szczegółowe informacje, poniżej znajdziesz przykłady interakcji z konkretną usługą: Kalendarz Google. Wskażemy miejsca, w których Kalendarz różni się od innych usług Google. Ułatwi to dostosowanie tych przykładów 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ć następującego oświadczenia:
using Google.GData.Client;
Żądanie pliku danych
Zgodnie z dokumentacją interfejsu API danych Kalendarza Google możesz poprosić o dostęp do kanału Kalendarza, wysyłając do niego to żądanie HTTP:
GET http://www.google.com/calendar/feeds/userID/private/full
Oczywiście adres userID użytkownika należy zastąpić adresem e-mail użytkownika. Szczegółowe informacje znajdziesz w dokumencie Kalendarz. Zamiast niego możesz używać specjalnego domyślnego adresu URL do interakcji z Kalendarzem (jak opisano w dokumencie Kalendarz), ale w tym dokumencie będziemy używać prywatnego pełnego adresu URL kanału, który zawiera identyfikator użytkownika.
Musisz też podać odpowiednie dane o uwierzytelnieniu. Pamiętaj, że używany przez nas system uwierzytelniania (określany jako „Uwierzytelnianie Google dla zainstalowanych aplikacji”) jest odpowiedni tylko w przypadku zainstalowanych aplikacji klienckich, takich jak klienty komputerowe, a nie w aplikacjach internetowych. Więcej informacji o uwierzytelnianiu znajdziesz w dokumentacji uwierzytelniania konta Google.
Aby poprosić o dostęp do kanału Kalendarza przy użyciu biblioteki klienta w języku C#, użyj następującego kodu dla adresu e-mail „jo@gmail.com” i hasła „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);
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 składa się z następujących kroków:
- Uzyskaj lub utwórz odpowiedni adres URL.
- Jeśli wysyłasz dane do usługi (np. wstawiając nowy wpis), przekształć nieprzetworzone dane w obiekty za pomocą klas biblioteki klienta. (Ten krok nie ma zastosowania, gdy prosisz tylko o plik danych – robimy to w przykładzie).
- Utwórz nową instancję
Service, ustawiając nazwę usługi (np."cl"w przypadku Kalendarza) i nazwę aplikacji (w formaciecompanyName-applicationName-versionID). - Ustaw odpowiednie dane logowania.
- Wywołaj metodę wysłania żądania i otrzymywania wyników.
Metoda service.setUserCredentials ustawia właściwość service.Credentials ze standardowym obiektem danych uwierzytelniających .NET Network.
Dane logowania są ustawione na identyfikator i hasło użytkownika, w imieniu którego klient wysyła zapytanie. W przykładach w tym dokumencie używany jest system uwierzytelniania „Uwierzytelnianie dla zainstalowanych aplikacji”. Więcej informacji o innych systemach uwierzytelniania znajdziesz w dokumentacji uwierzytelniania konta Google.
Aby zażądać całego pliku, wywołujesz metodę service.Query, która pobiera obiekt FeedQuery i zwraca cały kanał znaleziony pod tym adresem URL. W dalszej części tego artykułu pokażemy, jak wysyłać bardziej szczegółowe zapytania.
Tak jak inne metody klasy Service, Query obsługuje uwierzytelnianie i przekierowania w razie potrzeby.
Wstawianie nowego elementu
Aby wstawić element do kanału Kalendarza, możesz użyć następującego 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 klasa AtomTextConstruct, która zawiera tekst w różnych postaciach (zwykły tekst, HTML lub XHTML). Treść wpisu jest reprezentowana przez obiekt AtomContent – klasa, która może zawierać zwykły tekst lub inne rodzaje treści, w tym dane XML i binarne.
Każdy autor jest reprezentowany jako nazwa, identyfikator URI i adres e-mail. (W tym przykładzie pominiemy identyfikator URI). Autora dodajesz do wpisu, dodając obiekt AtomAuthor do jego kolekcji Authors.
Używamy tego samego obiektu Service, który utworzyliśmy w poprzednim przykładzie. W tym przypadku jest to metoda Insert, która wysyła element pod określony wstawiony adres URL.
Usługa zwraca nowo utworzony wpis, który może zawierać dodatkowe elementy wygenerowane przez serwer, takie jak adres URL edycji wpisu.
Powyższy kod jest odpowiednikiem wysyłania POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (z odpowiednim uwierzytelnianiem) i dostarczania wpisu.
Prośba o określony wpis
Ten kod pozwala zażądać konkretnej pozycji wstawionej w poprzednim przykładzie.
W kontekście serii przykładów pobranie tego wpisu nie jest konieczne, ponieważ Kalendarz zwrócił już wstawiony wpis. Tę samą metodę można jednak 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 zostać użyty do utworzenia nowego obiektu URI.
Następnie musimy wywołać metodę Query usługi, aby uzyskać nowy obiekt AtomFeed z kolejną pozycją w kolekcji wpisów.
Powyższy kod jest odpowiednikiem wysyłania GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID do Kalendarza z odpowiednim uwierzytelnianiem.
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;
}
Ten przykład zaczyna się od utworzenia obiektu FeedQuery, który składa się głównie z adresu URL i powiązanych parametrów zapytania. Każdy ze standardowych parametrów zapytania GData ma właściwość.
Po utworzeniu FeedQuery przekazujemy go do metody Query usługi, która zwraca plik danych z wynikami zapytania. Możesz też utworzyć adres URL samodzielnie (dołączając parametry zapytania do adresu URL kanału), a następnie wywołać metodę Query, przy czym metoda FeedQuery dostarcza użyteczną warstwę abstrakcji, która nie wymaga samodzielnego tworzenia adresu URL.
Kolekcja Entries pliku danych zwraca listę pozycji w kanale, a Entries.Count zwraca liczbę pozycji w kanale.
W tym przypadku, jeśli zapytanie zwróciło jakieś wyniki, do obiektu AtomEntry przypisujemy pierwszy pasujący wynik. Następnie używamy właściwości Title klasy AtomEntry, aby pobrać tytuł wpisu.
Powyższy kod jest odpowiednikiem wysyłania GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis do Kalendarza.
Zapytania według kategorii
Uwaga: Kalendarz Google nie wiąże etykiet z wydarzeniami, więc ten przykład nie działa w przypadku Kalendarza.
Aby pobrać kanał zawierający wszystkie wpisy, które pasują do wcześniejszego wyszukiwania pełnotekstowego i należą do określonej kategorii lub mają określoną etykietę, użyj następującego 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 zostanie użyta w filtrze kategorii. Klasa QueryCategory może zawierać wiele kategorii, ale w tym przypadku tworzymy filtr mający tylko jedną kategorię.
Następnie dodaj ten filtr do istniejącego zapytania, które nadal zawiera pełny ciąg zapytania z poprzedniego przykładu.
Ponownie używamy metody Query do wysłania zapytania do usługi.
Jeśli Kalendarz zezwoli na wyszukiwanie kategorii, powyższy kod będzie odpowiednikiem wysłania GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis do Kalendarza.
Aktualizowanie elementu
Aby zaktualizować istniejący element, użyj tego kodu. W poniższym przykładzie zmieniamy tytuł pobranego wcześniej wpisu ze starego tekstu („Tenis z Beth”) na „Ważne spotkanie”.
retrievedEntry.Title.Text = "Important meeting"; retrievedEntry.Update();
Najpierw ustawiamy nowy tytuł pobranego wcześniej. Następnie wywołujemy metodę Upate, aby przesłać zaktualizowany wpis do usługi.
Usługa zwraca zaktualizowany wpis, w tym nowy adres URL nowej wersji tego wpisu. Więcej informacji o wersjach wpisów znajdziesz w sekcji dotyczącej optymalizacji równoczesności w dokumentacji referencyjnej protokołu v1.
Powyższy kod jest zbliżony do wysyłania do usługi PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID razem z nowym wpisem (w formacie Atom), aby zastąpić oryginalny wpis.
Usuwanie elementu
Aby usunąć istniejący element, użyj tego kodu:
updateEntry.Delete();
Adres URL używany do usunięcia jest taki sam jak edytowany adres URL, więc ten przykład jest bardzo podobny do poprzedniego, z wyjątkiem wywołania metody Delete zamiast Update.
Powyższy kod jest odpowiednikiem wysłania DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID do usługi.
Korzystanie z kanałów Kalendarza Google
W powyższych przykładach opisujemy, jak używać interfejsu Google Data C# API do pracy z ogólnymi plikami danych GData. Jeśli jednak pracujesz z plikiem danych w Kalendarzu Google, zawiera on wiele danych specyficznych dla kalendarza, które nie są łatwo dostępne przy użyciu standardowych obiektów Atom w podstawowej bibliotece API. Aby ułatwić Ci korzystanie z tych plików danych, udostępniamy te rozszerzenia:
using Google.GData.Extensions; using Google.GData.Calendar;
Ogólnie przestrzeń nazw rozszerzeń obsługuje rozszerzenia; przestrzeń nazw Kalendarza 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:
- Zapytanie dotyczące zdarzenia
- Podklasa FeedQuery, która umożliwia ustawienie 2 parametrów niestandardowych dla usługi Kalendarz (min. min. i początek maks.).
- Usługa Kalendarza
- Podklasa usługi, która może zwracać plik danych o zdarzeniach.
- Plik danych o zdarzeniach
- Podklasa AtomFeed z dostępem do klasy EventEntries.
- Wstęp zdarzenia
- Podklasa AtomEntry z dodatkowymi właściwościami związanymi z danymi kalendarza.
Więcej informacji o tych specjalnych zajęciach znajdziesz w dokumentacji interfejsu API i w przykładowym programie.
Materiały referencyjne
Więcej informacji o bibliotece klienta C# znajdziesz w dokumentacji.