.NET 클라이언트 라이브러리 개발자 가이드

이 문서에서는 .NET 클라이언트 라이브러리를 사용하여 Google Data API('GData') 쿼리를 보내고 반환된 응답을 해석하는 방법을 설명합니다.

Google은 GData 지원 서비스와 상호작용하기 위한 다양한 클라이언트 라이브러리를 다양한 프로그래밍 언어로 제공합니다. 이러한 라이브러리를 사용하면 GData 요청을 구성하고 서비스에 요청을 보내고 응답을 수신할 수 있습니다.

이 문서에서는 C# 버전의 클라이언트 라이브러리를 일반적으로 사용하는 예와 일련의 GData 클라이언트 작성에 관한 정보를 제공합니다. 이 문서의 마지막 부분에는 C# 클라이언트 라이브러리의 참조 문서 링크가 NDoc 형식으로 되어 있습니다.

이 클라이언트 라이브러리를 사용하려면 .NET 1.1 런타임이 필요하며 모든 패치가 최신 상태여야 합니다.

.NET 클라이언트 라이브러리를 다운로드합니다.

이 가이드의 예는 Google Calendar API를 참조하지만 이 가이드는 Calendar API 사용에 대한 정확하고 최신 가이드가 아닙니다. 특정 서비스의 Data API에서 .NET 클라이언트 라이브러리를 사용하는 방법은 서비스별 문서를 참조하세요. 예를 들어 Calendar로 작업하는 경우 Calendar Data API 개발자 가이드를 읽어보세요.

목차

  1. 잠재고객
  2. 데이터 모델 개요
  3. 튜토리얼 및 예시
  4. Reference

대상

이 문서는 GData 서비스와 상호작용할 수 있는 클라이언트 애플리케이션을 작성하려는 C# 프로그래머를 대상으로 합니다.

이 문서에서는 사용자가 Google Data API 프로토콜에 관한 일반적인 개념을 이해하고 있다고 가정합니다. 또한 C# 프로그래밍 방법을 알고 있다고 가정합니다.

데이터 모델 개요

C# 클라이언트 라이브러리는 Google Data API에서 사용하는 요소 및 데이터 유형에 해당하는 클래스 집합을 제공합니다. 예를 들어 <atom:feed> 요소에 상응하는 피드 클래스가 있습니다. 이 클래스에는 항목을 만들고 다양한 하위 요소의 값을 가져오고 설정하는 등의 메서드가 있습니다. <atom:entry> 요소에 상응하는 Entry 클래스도 있습니다. Google Data API에 정의된 모든 요소에 자체 클래스가 있는 것은 아닙니다. 자세한 내용은 참조 문서를 확인하세요.

라이브러리는 Atom 콘텐츠를 자동으로 파싱하고 Atom 요소의 값을 적절한 객체에 넣을 수 있습니다. 예를 들어 getFeed 메서드는 피드를 가져와서 파싱한 후 결과 값과 함께 피드 객체를 반환합니다.

서비스에 피드 또는 항목을 보내려면 피드 또는 항목 객체를 만든 다음 라이브러리 메서드 (예: insert 메서드)를 호출하여 객체를 자동으로 XML로 변환하고 전송합니다.

원하는 경우 XML을 직접 파싱하거나 생성할 수 있습니다. 가장 쉬운 방법은 적절한 타사 라이브러리를 사용하는 것입니다.

Google Data API의 XML 구문이 확장 가능한 것처럼 해당 객체 모델도 확장 가능합니다. 예를 들어 클라이언트 라이브러리는 Google 데이터 네임스페이스에 정의된 요소에 해당하는 클래스를 제공합니다.

튜토리얼 및 예시

다음 예는 C# 클라이언트 라이브러리를 사용하여 다양한 GData 요청을 보내는 방법을 보여줍니다.

좀 더 구체적으로 만들기 위해 이 예시에서는 Google Calendar와 같은 특정 서비스와 상호작용하는 방법을 보여줍니다. 이 예제를 다른 서비스에 맞춰 조정할 수 있도록 Calendar가 다른 Google 서비스와 다른 위치를 알려 드리겠습니다. Calendar에 관한 자세한 내용은 Google Calendar Data API 문서를 참고하세요.

클라이언트 빌드 및 실행

이 문서의 예를 컴파일하려면 다음 using 문을 사용해야 합니다.

using Google.GData.Client;

피드 요청

Google Calendar Data API 문서에 설명된 대로 다음 HTTP 요청을 Calendar에 전송하여 Calendar 피드를 요청할 수 있습니다.

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

물론 userID를 사용자의 이메일 주소로 바꿔야 합니다. 자세한 내용은 Calendar 문서를 참고하세요. 대신 Calendar 문서에 설명된 대로 Calendar와 상호작용하기 위한 특수 기본 URL을 사용할 수 있지만 이 문서에서는 사용자 ID가 포함된 비공개 전체 피드 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. 서비스 이름 (예: 캘린더의 경우 "cl")과 애플리케이션 이름 (companyName-applicationName-versionID 형식)을 설정하여 새 Service 인스턴스를 만듭니다.
  4. 적절한 사용자 인증 정보를 설정합니다.
  5. 요청을 보내고 결과를 수신하는 메서드를 호출합니다.

service.setUserCredentials 메서드는 service.Credentials 속성을 표준 .NET 네트워크 사용자 인증 정보 객체로 설정합니다. 사용자 인증 정보는 클라이언트가 쿼리를 전송하는 사용자의 ID와 비밀번호로 설정됩니다. 이 문서의 예에서는 '설치된 애플리케이션 인증' 인증 시스템을 사용합니다. 다른 인증 시스템에 대한 자세한 내용은 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를 생략합니다. 항목의 Authors 컬렉션에 AtomAuthor 객체를 추가하여 항목에 작성자를 추가합니다.

이전 예에서 만든 것과 동일한 Service 객체를 사용합니다. 이 경우 호출할 메서드는 Insert입니다. 이 메서드는 지정된 삽입 URL에 항목을 전송합니다.

서비스가 새로 생성된 항목을 반환하며 항목의 수정 URL과 같은 서버 생성 요소가 추가로 포함될 수 있습니다.

위의 코드는 적절한 인증과 함께 POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full를 보내고 항목을 제공하는 것과 같습니다.

특정 항목 요청

다음 코드를 사용하면 이전 예에서 삽입한 특정 항목을 요청할 수 있습니다.

이러한 일련의 예시에서 컨텍스트에서는 이미 삽입된 항목을 반환했으므로 실제로 해당 항목을 가져올 필요는 없지만 항목의 URL을 알고 있을 때마다 동일한 기법을 적용할 수 있습니다.

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

삽입된 항목에는 ToString() 메서드를 사용하여 새 URI 객체를 만드는 데 사용할 수 있는 AtomUri 객체를 반환하는 SelfUri 속성이 있습니다.

그런 다음 항목의 Query 메서드를 호출하여 항목 컬렉션에 항목 하나만 있는 새 AtomFeed 객체를 가져오기만 하면 됩니다.

위의 코드는 적절한 인증으로 GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID를 Calendar로 전송하는 것과 같습니다.

항목 검색

전체 텍스트 검색에서 첫 번째 일치 항목을 검색하려면 다음 코드를 사용합니다.

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

이 예에서는 주로 URL과 관련 쿼리 매개변수로 구성된 FeedQuery 객체를 구성합니다. 각 표준 GData 쿼리 매개변수에는 속성이 있습니다.

FeedQuery를 구성한 후 쿼리 결과를 포함하는 피드를 반환하는 서비스의 Query 메서드에 전달합니다. 대체 방법은 피드 매개변수를 쿼리 URL에 추가하여 URL을 직접 구성한 후 Query 메서드를 호출하는 것입니다. 하지만 FeedQuery 메서드는 유용한 추상화 레이어를 제공하므로 URL을 직접 구성하지 않아도 됩니다.

피드의 Entries 컬렉션은 피드의 항목 목록을 반환하고 Entries.Count는 피드의 항목 수를 반환합니다.

이 경우 쿼리가 결과를 반환하면 일치하는 첫 번째 결과를 AtomEntry 객체에 할당합니다. 그런 다음 AtomEntry 클래스의 Title 속성을 사용하여 항목의 제목을 검색합니다.

위 코드는 Calendar에 GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis를 전송하는 것과 같습니다.

카테고리별 쿼리

참고: Google Calendar에서는 라벨을 이벤트와 연결하지 않으므로 이 예에서는 Calendar에 적용할 수 없습니다.

이전의 전체 텍스트 검색과 일치하고 특정 카테고리에 속하거나 특정 라벨이 지정된 모든 항목으로 구성된 피드를 검색하려면 다음 코드를 사용합니다.

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

AtomCategory 클래스는 카테고리 필터에서 사용할 카테고리를 나타냅니다. QueryCategory 클래스에는 여러 카테고리가 포함될 수 있지만 이 경우 하나의 카테고리로만 필터를 구성합니다.

그런 다음 이 필터를 이전 쿼리에 추가합니다. 여기에는 이전 예시의 전체 텍스트 쿼리 문자열이 계속 포함되어 있습니다.

다시 Query 메서드를 사용하여 서비스에 쿼리를 전송합니다.

Calendar에서 카테고리 검색을 허용하는 경우 위 코드는 Calendar에 GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis를 전송하는 것과 같습니다.

항목 업데이트

기존 항목을 업데이트하려면 다음 코드를 사용합니다. 다음 예에서는 이전에 가져온 항목의 제목을 이전 텍스트("Tennis with Beth")에서 "중요 회의"로 변경합니다.

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

먼저 이전에 가져온 항목의 새 제목을 설정합니다. 그런 다음 Upate 메서드를 호출하여 업데이트된 항목을 서비스로 전송합니다.

서비스가 이 항목의 새 버전에 대한 새 URL을 비롯한 업데이트된 항목을 반환합니다. 항목 버전에 대한 자세한 내용은 v1 프로토콜 참조 문서의 낙관적 동시 실행 섹션을 참조하세요.

위 코드는 원래 항목을 대체하는 새 항목 (Atom 형식)과 함께 PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID를 서비스에 전송하는 것과 거의 동일합니다.

항목 삭제

기존 항목을 삭제하려면 다음 코드를 사용합니다.

updateEntry.Delete();

삭제에 사용할 URL은 edit URL과 동일하므로 이 예는 이전 대신 Update를 호출하는 대신 Delete 메서드를 호출한다는 점을 제외하면 매우 유사합니다.

위 코드는 서비스에 DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID를 전송하는 것과 거의 동일합니다.

Google Calendar 피드 사용하기

위의 예에서는 Google Data C# API를 사용하여 일반 GData 피드로 작업하는 방법을 간략하게 설명합니다. 특히 Google Calendar 피드를 사용하는 경우 피드에는 기본 API 라이브러리의 표준 Atom 지향 객체를 사용하여 쉽게 액세스할 수 없는 캘린더 관련 데이터가 많이 포함됩니다. 피드와 상호작용할 수 있도록 Google에서는 다음 확장 프로그램을 제공합니다.

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

확장 프로그램 네임스페이스는 일반적으로 확장 프로그램을 처리합니다. 캘린더 네임스페이스를 사용하면 맞춤설정된 캘린더 서비스, 피드, 쿼리 객체에 액세스할 수 있습니다. C# API 설치의 /Samples 하위 디렉터리에서 이러한 확장 프로그램이 사용되는 자세한 예를 확인할 수 있습니다. 다음 객체가 추가됩니다.

이벤트 쿼리
Calendar 서비스의 두 가지 맞춤 매개변수 (start-min 및 start-max)를 설정할 수 있는 FeedQuery의 서브클래스입니다.
캘린더 서비스
이벤트 피드를 반환할 수 있는 서비스의 서브클래스입니다.
이벤트 피드
AtomFeed의 서브클래스로 EventEntries를 노출합니다.
이벤트 항목
AtomEntry의 서브클래스로, 캘린더 데이터와 관련된 추가 속성을 포함합니다.

이러한 특수 클래스에 관한 자세한 내용은 API 문서와 샘플 프로그램을 참고하세요.

참조

C# 클라이언트 라이브러리에 대한 참조 정보는 참조 문서를 확인하세요.

맨 위로