Java 클라이언트 라이브러리 사용

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

Google에서는 데이터 API가 있는 서비스와 상호작용할 수 있도록 다양한 프로그래밍 언어로 된 클라이언트 라이브러리 세트를 제공합니다. 이러한 라이브러리를 사용하여 GData 요청을 구성하고, 서비스에 전송하고, 응답을 받을 수 있습니다.

이 문서에서는 Java 클라이언트 라이브러리 사용에 관한 일반적인 정보와 함께 일반적인 사용 사례의 예를 제공합니다.

이 클라이언트 라이브러리를 사용하려면 Java 1.5를 실행해야 합니다.

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

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

목차

  1. 시청자층
  2. 데이터 모델 개요
  3. 튜토리얼 및 예시
    1. 클라이언트 빌드 및 실행
    2. 피드 요청
    3. 새 항목 삽입하기
    4. 특정 항목 요청
    5. 항목 검색
    6. 카테고리별 쿼리
    7. 항목 업데이트
    8. 항목 삭제
  4. 참조

잠재고객

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

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

클라이언트 라이브러리에서 제공하는 클래스 및 메서드에 관한 참조 정보는 Java 클라이언트 라이브러리 API 참조 (Javadoc 형식)를 참고하세요.

이 문서는 순서대로 읽도록 설계되었습니다. 각 예시는 이전 예시를 바탕으로 빌드됩니다.

데이터 모델 개요

Java 클라이언트 라이브러리는 클래스 집합을 사용하여 Google Data API에서 사용하는 요소를 나타냅니다. 예를 들어 <atom:feed> 요소에 해당하는 피드 클래스가 있습니다. 이 클래스에는 항목을 만들고, 다양한 하위 요소의 값을 가져오고 설정하는 등의 메서드가 있습니다. <atom:entry> 요소에 해당하는 Entry 클래스도 있습니다. Google Data API에 정의된 모든 요소에 자체 클래스가 있는 것은 아닙니다. 자세한 내용은 참조 문서를 참고하세요.

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

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

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

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

튜토리얼 및 예

다음 예에서는 Java 클라이언트 라이브러리를 사용하여 다양한 데이터 API 요청을 전송하는 방법을 보여줍니다.

이러한 예는 구체성을 높이기 위해 Google Calendar와 같은 특정 서비스와 상호작용하는 방법을 보여줍니다. 다른 서비스에서 이러한 예시를 사용할 수 있도록 캘린더가 다른 Google 서비스와 다른 부분을 지적해 드리겠습니다. Calendar에 대한 자세한 내용은 Google Calendar Data API 문서를 참고하세요.

클라이언트 빌드 및 실행

이 문서의 예시를 컴파일하려면 다음 가져오기 문을 사용해야 합니다.

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;
import java.net.URL;

피드 요청

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

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

물론 userID를 사용자의 이메일 주소로 바꿔야 합니다. 자세한 내용은 캘린더 문서를 참고하세요. 대신 캘린더 문서에 설명된 대로 캘린더와 상호작용하기 위한 특수 기본 URL을 사용할 수 있지만 이 문서에서는 사용자 ID가 포함된 비공개 전체 피드 URL을 사용합니다.

적절한 인증도 제공해야 합니다. 이 예와 Calendar 문서의 첫 번째 예의 주요 차이점은 (1) 이 예에는 인증이 포함되어 있고 (2) 이 예에서는 Calendar 전용 CalendarService 클래스 대신 더 일반적인 GoogleService 클래스를 사용한다는 것입니다.

여기에서 사용하는 인증 시스템('설치된 애플리케이션용 Google 인증'이라고 함)은 웹 애플리케이션이 아닌 데스크톱 클라이언트와 같은 설치된 클라이언트 애플리케이션에서만 사용해야 합니다. 인증에 대한 자세한 내용은 Google 계정 인증 문서를 참고하세요.

Java 클라이언트 라이브러리를 사용하여 이메일 주소가 'liz@gmail.com'이고 비밀번호가 'mypassword'인 사용자의 캘린더 피드를 요청하려면 다음 코드를 사용하세요.

// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");

// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());

// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);

GoogleService 클래스는 GData 서비스에 대한 클라이언트 연결 (인증 포함)을 나타냅니다. 클라이언트 라이브러리를 사용하여 서비스에 쿼리를 전송하는 일반적인 절차는 다음 단계로 구성됩니다.

  1. 적절한 URL을 가져오거나 구성합니다.
  2. 서비스에 데이터를 전송하는 경우 (예: 새 항목을 삽입하는 경우) 클라이언트 라이브러리 클래스를 사용하여 원시 데이터를 객체로 변환합니다. (이 예와 같이 피드만 요청하는 경우에는 이 단계가 적용되지 않습니다.)
  3. 서비스 이름 (예: 캘린더의 경우 "cl")과 애플리케이션 이름 (companyName-applicationName-versionID 형식)을 설정하여 새 GoogleService 인스턴스를 만듭니다.
  4. 적절한 사용자 인증 정보를 설정합니다.
  5. 라이브러리가 반환된 피드를 올바르게 파싱할 수 있도록 피드에서 사용할 확장 프로그램을 클라이언트 라이브러리에 표시합니다.
  6. 메서드를 호출하여 요청을 보내고 결과를 수신합니다.

setUserCredentials 메서드는 클라이언트가 쿼리를 전송하는 사용자의 ID와 비밀번호를 지정합니다. 이 문서의 예에서는 '설치된 애플리케이션 인증' 인증 시스템을 사용합니다. 인증 시스템에 관한 자세한 내용은 Google 계정 인증 문서를 참고하세요.

사용자 인증 정보를 설정한 후 declareExtensions 메서드를 호출하여 피드에서 사용할 확장 프로그램을 나타냅니다. 이 경우 피드가 이벤트 피드이므로 이벤트 종류에 의해 정의된 확장 프로그램을 사용한다고 말하는 것입니다.

전체 피드를 요청하려면 URL을 가져와 해당 URL에서 찾은 전체 피드를 반환하는 getFeed 메서드를 호출합니다. 이 문서의 뒷부분에서는 더 구체적인 질문을 보내는 방법을 보여줍니다.

GoogleService 클래스의 다른 메서드와 마찬가지로 getFeed은 인증을 처리하고 필요한 경우 리디렉션합니다.

새 항목 삽입

새 캘린더 일정을 만들려면 다음 코드를 사용할 수 있습니다.

URL postUrl =
  new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();

myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));

Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);

DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);

// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);

URL을 설정한 후 EventEntry 객체를 구성합니다. EventEntry은 추상 기본 클래스 BaseEntry에서 파생되며, 이는 <atom:entry> 요소를 나타내는 Entry 클래스의 상위 클래스이기도 합니다.

EventEntry 클래스는 이벤트 종류를 나타냅니다. 자세한 내용은 종류 문서를 참고하세요. Calendar 이외의 서비스의 경우 반환된 항목을 EventEntry 객체가 아닌 Entry 객체에 할당할 수 있습니다.

항목 제목은 다양한 형식 (일반 텍스트, HTML 또는 XHTML)으로 텍스트를 보유하는 클래스인 TextConstruct입니다. 항목 콘텐츠는 일반 텍스트 또는 XML, 바이너리 데이터 등 기타 형식의 콘텐츠를 보유할 수 있는 클래스인 Content 객체로 표현됩니다. (하지만 setContent 메서드는 TextConstruct도 허용할 수 있습니다.)

각 작성자는 이름, URI, 이메일 주소로 표시됩니다. (이 예에서는 URI를 생략합니다.) 항목의 getAuthors().add 메서드를 호출하여 항목에 작성자를 추가합니다.

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

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

HTTP 상태 코드는 예외로 반환됩니다.

위 코드는 POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (적절한 인증 포함)를 전송하고 Event 종류 형식으로 항목을 제공하는 것과 같습니다.

특정 항목 요청

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

이 예시 시리즈의 맥락에서는 삽입된 항목을 캘린더에서 이미 반환했으므로 해당 항목을 검색할 필요가 없지만 항목의 URI를 알고 있을 때는 언제든지 동일한 기법을 적용할 수 있습니다.

URL entryUrl = new URL(insertedEntry.getSelfLink().getHref());
EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);

삽입된 항목에는 항목의 URL을 포함하는 Link 객체를 반환하는 메서드 getSelfLink가 있습니다. Link 클래스에는 URL을 String로 반환하는 getHref 메서드가 있으며, 이 메서드에서 URL 객체를 만들 수 있습니다.

그런 다음 서비스의 getEntry 메서드를 호출하여 항목을 가져오면 됩니다.

EventEntry.class를 getEntry에 매개변수로 제공하여 서비스가 일반 항목이 아닌 이벤트를 반환하도록 특별히 요청합니다. Calendar 이외의 서비스의 경우 Entry.class만 전달하면 됩니다.

위 코드는 적절한 인증을 통해 캘린더에 GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID를 전송하는 것과 같습니다.

항목 검색

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

Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
  Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
  String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}

이 예에서는 URL과 연결된 쿼리 매개변수로 구성된 Query 객체를 생성하는 것으로 시작합니다. 각 표준 GData 쿼리 매개변수에는 setter 메서드가 있습니다. addCustomParameter 메서드를 사용하여 특정 서비스의 맞춤 쿼리 매개변수를 설정할 수도 있습니다.

Query를 구성한 후 서비스의 query 메서드에 전달합니다. 이 메서드는 쿼리 결과가 포함된 피드를 반환합니다. 피드 URL에 쿼리 매개변수를 추가하여 URL을 직접 구성한 다음 getFeed 메서드를 호출하는 방법도 있지만 query 메서드는 URL을 직접 구성하지 않아도 되도록 유용한 추상화 계층을 제공합니다.

피드의 getEntries 메서드는 피드의 항목 목록을 반환하고 getEntries().size는 피드의 항목 수를 반환합니다.

이 경우 쿼리에서 결과를 반환하면 일치하는 첫 번째 결과를 Entry 객체에 할당합니다. 그런 다음 Entry 클래스의 getTitle().getPlainText 메서드를 사용하여 항목의 제목을 가져와 텍스트로 변환합니다.

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

카테고리별 쿼리

참고: Google Calendar는 라벨을 일정과 연결하지 않으므로 이 예는 Calendar에서 작동하지 않습니다.

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

Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);

물론 Category 클래스는 카테고리 필터에 사용될 카테고리를 나타냅니다. Query.CategoryFilter 클래스에는 여러 카테고리가 포함될 수 있지만, 이 경우 카테고리가 하나만 있는 필터를 구성합니다.

그런 다음 이전 예의 전체 텍스트 쿼리 문자열이 여전히 포함된 기존 쿼리에 해당 필터를 추가합니다.

여기에서도 query 메서드를 사용하여 서비스에 쿼리를 전송합니다.

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

항목 업데이트

기존 항목을 업데이트하려면 다음 코드를 사용하세요. 이 예에서는 이전에 가져온 항목의 제목을 이전 텍스트 ('다르시와 테니스')에서 '중요한 회의'로 변경합니다.

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

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

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

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

항목 삭제

업데이트된 항목을 삭제하려면 다음 코드를 사용하세요.

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

삭제에 사용할 URL은 수정 URL과 동일하므로 이 예는 update 대신 delete 메서드를 호출한다는 점을 제외하고 이전 예와 매우 유사합니다.

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

참조

클라이언트 라이브러리에서 제공하는 클래스 및 메서드에 관한 참조 정보는 Java 클라이언트 라이브러리 API 참조 (Javadoc 형식)를 참고하세요.

맨 위로