자바 클라이언트 라이브러리 사용

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

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

이 문서에서는 자바 클라이언트 라이브러리 사용에 관한 일반적인 정보와 몇 가지 일반적인 사용 사례를 제공합니다.

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

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

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

목차

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

대상

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

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

클라이언트 라이브러리에서 제공하는 클래스 및 메서드에 대한 자세한 내용은 자바 클라이언트 라이브러리 API 참조 (Javadoc 형식)를 참조하세요.

이 문서는 순서대로 읽어야 하며 각 예시는 이전 예시를 바탕으로 작성되었습니다.

데이터 모델 개요

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

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

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

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

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

튜토리얼 및 예시

다음 예는 자바 클라이언트 라이브러리를 사용하여 다양한 데이터 API 요청을 보내는 방법을 보여줍니다.

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

클라이언트 빌드 및 실행

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

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 문서에 설명된 대로 다음 HTTP 요청을 Calendar에 전송하여 Calendar 피드를 요청할 수 있습니다.

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

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

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

여기에서 사용하는 인증 시스템('설치된 애플리케이션에 대한 Google 인증')은 데스크톱 애플리케이션과 같이 설치된 클라이언트 애플리케이션에서만 사용할 수 있으며 웹 애플리케이션에서는 사용할 수 없습니다. 인증에 대한 자세한 내용은 Google 계정 인증 문서를 참고하세요.

자바 클라이언트 라이브러리를 사용하여 캘린더 피드를 요청하려면 이메일 주소가 '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는 <atom:entry> 요소를 나타내는 Entry 클래스의 상위 클래스인 추상 기본 클래스 BaseEntry에서 파생됩니다.

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

항목 제목은 TextConstruct입니다. 이 클래스는 다양한 텍스트 (일반 텍스트, HTML 또는 XHTML)로 텍스트를 보관합니다. 항목 콘텐츠는 Content 객체로 표현됩니다. 이 객체는 일반 텍스트나 XML 및 바이너리 데이터를 비롯한 다른 형태의 콘텐츠를 보유할 수 있습니다. 그러나 setContent 메서드는 TextConstruct도 허용할 수 있습니다.

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

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

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

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

위의 코드는 POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full를 적절한 인증과 함께 전송하여 이벤트 종류 형식의 항목을 제공하는 것과 같습니다.

특정 항목 요청

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

이러한 일련의 예시에서 컨텍스트에서는 항목이 이미 제출된 항목을 반환했으므로 실제로 해당 항목을 가져올 필요는 없습니다. 하지만 항목의 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를 Calendar로 전송하는 것과 같습니다.

항목 검색

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

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 메서드를 사용하여 항목의 제목을 검색하고 텍스트로 변환합니다.

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

카테고리별 쿼리

참고: 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를 전송하는 것과 같습니다.

항목 업데이트

기존 항목을 업데이트하려면 다음 코드를 사용합니다. 이 예에서는 이전에 검색한 항목의 제목을 이전 텍스트('Tarnis with Darcy')에서 '중요 회의'로 변경합니다.

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은 edit URL과 동일하므로 이 예는 이전 대신 update를 호출하는 대신 delete 메서드를 호출한다는 점을 제외하면 매우 유사합니다.

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

참조

클라이언트 라이브러리에서 제공하는 클래스 및 메서드에 대한 자세한 내용은 자바 클라이언트 라이브러리 API 참조(Javadoc 형식)를 참조하세요.

맨 위로