자주 묻는 질문(FAQ)

    개요

  1. Google Data API란 무엇인가요?
  2. 기능 요청 또는 버그 신고가 있습니다. 어디에 게시해야 하나요?
  3. 특정 API에 관한 질문은 어디에 해야 하나요?
  4. JSON이란 무엇인가요?
  5. XML을 사용해야 하나요? 다른 데이터 형식을 사용할 수 있나요?
  6. REST를 사용하는 이유는 무엇인가요?
  7. 일반적인 문제에 관한 팁이나 짧은 샘플 코드가 있나요?
  8. Gmail에 데이터 API가 있나요?

    9. 인증

  9. 각 데이터 API의 ClientLogin 서비스 이름은 무엇인가요?
  10. 사용자가 애플리케이션에서 로그아웃할 때 API 서버에 알려야 하나요?
  11. ClientLogin 인증 토큰에 만료일이 있나요?
  12. Google 계정에 대한 일반적인 질문이 있습니다. 어디로 가야 하나요?
  13. API에 인증하려면 어떻게 해야 하나요?
  14. AuthSub/OAuth 1 범위 매개변수에 어떤 값을 사용해야 하나요?
  15. AuthSub 토큰에는 여러 유형이 있나요? 토큰이 만료되나요?
  16. ClientLogin과 AuthSub/OAuth 1의 주요 차이점은 무엇인가요?
  17. 서드 파티 웹 애플리케이션에서 ClientLogin 인증을 사용할 수 있나요?
  18. 보안문자란 무엇인가요?
  19. 보안문자 챌린지는 어떻게 생성하나요?
  20. 웹 애플리케이션에서 ClientLogin을 사용해야 하나요?
  21. AuthSub/OAuth 1을 사용할 때 사용자의 사용자 이름을 어떻게 알 수 있나요?
  22. Google Data API 클라이언트 라이브러리에서 OAuth 1을 사용하려면 어떻게 해야 하나요?
  23. Google Data API 클라이언트 라이브러리와 함께 AuthSub를 사용하려면 어떻게 해야 하나요?
  24. Google Data API 클라이언트 라이브러리와 함께 ClientLogin을 사용하려면 어떻게 해야 하나요?

    25. 클라이언트 라이브러리

  25. Google에서 지원하는 클라이언트 라이브러리가 있는 프로그래밍 언어는 무엇인가요?
  26. Google 데이터 클라이언트 라이브러리의 버그나 기능 요청을 신고하려면 어떻게 해야 하나요?
  27. 클라이언트 라이브러리에서 디버깅 옵션을 사용 설정하려면 어떻게 해야 하나요?
  28. 클라이언트 라이브러리 클래스의 참조 문서는 어디에서 찾을 수 있나요?

    29. 문제 해결

  29. HTTP 디버깅에 유용한 도구는 무엇인가요?
  30. Java 클라이언트 라이브러리에서 HTTP 로깅 정보를 가져오려면 어떻게 해야 하나요?
  31. .NET 클라이언트 라이브러리에서 HTTP 로깅 정보를 가져오려면 어떻게 해야 하나요?
  32. Google 데이터 피드에서 gzip 인코딩을 사용 설정하려면 어떻게 해야 하나요?
  33. PHP 클라이언트를 사용할 때 'sslv2에 연결할 수 없음' 오류가 표시되는 이유는 무엇인가요?
  34. 피드를 설명하는 Atom 서비스 문서를 가져오려면 어떻게 해야 하나요?

개요

Google Data API란 무엇인가요?

Google Data API는 Google 데이터 프로토콜을 기반으로 하는 API입니다. Google 데이터 프로토콜은 Atom 1.0 및 RSS 2.0 신디케이션 형식과 Atom 게시 프로토콜 (APP)을 기반으로 합니다.

Google 데이터 프로토콜은 표준에 내장된 확장 메커니즘을 사용하여 다양한 방식으로 이러한 표준을 확장합니다. 피드는 Atom 또는 RSS 신디케이션 형식을 준수합니다. 게시 모델은 Atom 게시 프로토콜을 준수합니다.

이 프로토콜은 피드, 쿼리, 결과에 대한 일반 모델도 제공합니다. 이를 사용하여 모든 Data API에 쿼리와 업데이트를 전송할 수 있습니다.

기능 요청 또는 버그 신고가 있습니다. 어디에 게시해야 하나요?
문제 추적기를 확인하세요. 기능 요청을 찾아 별표를 표시하여 지원을 추가하고 상태 업데이트를 받으세요.
특정 API에 관해 질문하려면 어디에 문의해야 하나요?
문제가 여기에 나열되어 있지 않거나 추가 설명이 필요한 경우 각 Google 데이터 API에 대한 토론 그룹이 있습니다.
JSON이란 무엇인가요?

JSON은 JavaScript Object Notation을 의미합니다.

JSON은 단순성으로 인해 웹 개발자 사이에서 널리 사용되는 경량 데이터 교환 형식입니다. 읽고 쓰기가 쉽습니다. 어떤 프로그래밍 언어를 사용하든 파싱할 수 있으며, 구조가 대부분의 프로그래밍 언어에서 사용되는 데이터 구조에 직접 매핑됩니다.

Google 데이터 API에서 JSON 사용에 대해 자세히 알아보세요.

XML을 사용해야 하나요? 다른 데이터 형식을 사용할 수 있나요?
Google Data API의 기본 데이터 형식은 Atom 피드 형식의 XML입니다. 하지만 피드를 요청할 때 alt 쿼리 매개변수를 사용하여 대체 형식을 지정할 수 있습니다.
  • alt=rss
    응답 데이터가 RSS 피드로 형식이 지정됩니다.
  • alt=json 또는 alt=json-in-script
    Atom 피드의 XML 구조의 JSON 표현을 반환합니다. JSON의 추가 이점은 JavaScript 클라이언트 코드에서 '파싱'하기가 더 쉽다는 것입니다. 현재 JSON 사용은 읽기 전용 옵션으로만 제공됩니다. 하지만 Blogger, Contacts 또는 Calendar 서비스와 함께 JavaScript 클라이언트 라이브러리를 사용하면 데이터를 읽고 쓸 수 있습니다.

    JSON 피드 요청 및 사용에 대해 자세히 알아보세요.

  • alt=atom-in-script
    alt=json-in-script와 유사하지만 결과가 JSON이 아닌 Atom XML 문자열로 반환됩니다.
  • alt=rss-in-script
    alt=atom-in-script와 유사하지만 결과가 Atom이 아닌 RSS XML 문자열로 반환됩니다.

대체 형식에 대한 자세한 내용은 Google 데이터 참조 가이드를 참고하세요.

REST를 사용하는 이유는 무엇인가요?
REST는 간단하고 가벼우며 확장 가능하고 데이터를 표현하고 노출하는 데 매우 적합합니다.
일반적인 문제에 대한 도움말이나 짧은 샘플 코드가 있나요?
클라이언트 라이브러리와 원시 요청에 관한 도움말은 Google Data API 팁 블로그를 참고하세요.
Gmail에 데이터 API가 있나요?

아니요. 하지만 AuthSub 또는 OAuth 1과 함께 Gmail의 Atom 피드를 사용하여 사용자의 읽지 않은 메일에 대한 읽기 전용 액세스를 요청할 수 있습니다. 범위는 https://mail.google.com/mail/feed/atom/로 설정해야 합니다. 예를 들어 다음과 같은 쿼리를 사용할 수 있습니다.

GET https://mail.google.com/mail/feed/atom/

메일 관리에 관심이 있다면 Gmail에서 IMAP/POP도 지원합니다.

인증

Google Data API 문서에서 'OAuth'는 OAuth 1을 의미합니다. OAuth 2.0에 대한 자세한 내용은 개별 API 문서를 참고하세요.

각 데이터 API의 ClientLogin 서비스 이름은 무엇인가요?
'서비스 이름'은 ClientLogin 인증 시스템에서 Google 서비스를 식별하는 데 사용하는 짧은 문자열입니다.
Google API 서비스 이름
Google 애널리틱스 Data API analytics
G Suite API
(도메인 정보 및 관리)		 apps
Google Sites Data API jotspot
Blogger Data API blogger
Book Search Data API print
Calendar Data API cl
Google Code Search Data API codesearch
Contacts Data API cp
Content API for Shopping structuredcontent
Documents List Data API writely
Finance Data API finance
Gmail Atom 피드 mail
Health Data API health
weaver (H9 샌드박스)
Maps Data API local
Picasa Web Albums Data API lh2
Sidewiki Data API annotateweb
Spreadsheets Data API wise
Webmaster Tools API sitemaps
YouTube Data API youtube

ClientLogin 요청에 사용되는 다른 매개변수에 대한 자세한 내용은 ClientLogin 문서를 참고하세요.

사용자가 애플리케이션에서 로그아웃할 때 API 서버에 알려야 하나요?
아니요. 사용자가 애플리케이션에서 로그아웃할 때 Google Data API에 알릴 필요는 없습니다. 하지만 애플리케이션에서 더 이상 발급된 AuthSub 토큰을 사용할 필요가 없는 경우 토큰을 취소해야 합니다.
ClientLogin 인증 토큰에 만료일이 있나요?
ClientLogin 토큰은 발급일로부터 2주 동안 지속될 수 있지만 이 제한은 서비스에 따라 다르며 더 짧을 수 있습니다.
Google 계정에 대한 일반적인 질문이 있습니다. 어디로 가야 하나요?
Google 계정 고객센터를 방문하세요.
API에 인증하려면 어떻게 해야 하나요?
HTTP 요청에는 ClientLogin, AuthSub 또는 OAuth 1을 사용하여 획득한 토큰이 포함된 승인 헤더가 포함되어야 합니다.
AuthSub/OAuth 1 범위 매개변수에 어떤 값을 사용해야 하나요?
A scope 매개변수는 AuthSub 및 OAuth 1에서 애플리케이션이 액세스할 Google 서비스(들)을 식별하는 데 필요합니다. OAuth 2.0에 관한 자세한 내용은 특정 API의 문서를 참고하세요.

Google API ClientLogin 서비스 이름
Google Analytics Data API https://www.google.com/analytics/feeds/
Google Sites Data API http(s)://sites.google.com/feeds/
Blogger Data API http://www.blogger.com/feeds/
Book Search Data API http://www.google.com/books/feeds/
Calendar Data API http(s)://www.google.com/calendar/feeds/
Contacts Data API http(s)://www.google.com/m8/feeds/
Content API for Shopping https://www.googleapis.com/auth/structuredcontent
Documents List Data API http(s)://docs.google.com/feeds/
Finance Data API http://finance.google.com/finance/feeds/
Gmail Atom 피드 https://mail.google.com/mail/feed/atom/
Health Data API https://www.google.com/health/feeds/
https://www.google.com/h9/feeds/ (H9 샌드박스)
Maps Data API http://maps.google.com/maps/feeds/
Picasa Web Albums Data API http://picasaweb.google.com/data/
Portable Contacts API http://www-opensocial.googleusercontent.com/api/people
Sidewiki Data API http://www.google.com/sidewiki/feeds/
Spreadsheets Data API http(s)://spreadsheets.google.com/feeds/
Webmaster Tools API http://www.google.com/webmasters/tools/feeds/
YouTube Data API http://gdata.youtube.com
AuthSub 토큰에는 여러 유형이 있나요? 토큰이 만료되나요?
AuthSub 토큰에는 두 가지 유형이 있습니다. 첫 번째는 'token' 쿼리 매개변수를 통해 웹 애플리케이션에 제공되는 일회용 토큰입니다. 이 토큰은 발급된 서비스와 함께 처음 사용되거나 세션 토큰으로 교환될 때 만료됩니다.

세션 토큰은 사용자 또는 AuthSubRevokeToken API 호출을 통해 토큰이 명시적으로 취소되지 않는 한 만료되지 않습니다. 일회용 토큰은 원래 AuthSubRequest URL이 session=1을 쿼리 매개변수로 지정한 경우에만 세션 토큰으로 교환할 수 있습니다.
ClientLogin과 AuthSub/OAuth 1의 주요 차이점은 무엇인가요?

AuthSub는 웹 애플리케이션용으로 설계되었습니다. 이를 통해 사용자 인증 정보가 서드 파티 웹사이트를 통하지 않고 사용자의 웹브라우저에서 Google 서버로 직접 안전하게 전송됩니다.

ClientLogin은 설치된 데스크톱 애플리케이션용입니다. 요청 애플리케이션이 사용자 대신 사용자 인증 정보를 Google에 전송해야 합니다.

Google 계정 인증 API에 관한 문서를 참고하세요.

서드 파티 웹 애플리케이션에서 ClientLogin 인증을 사용할 수 있나요?
서드 파티 웹 애플리케이션에서 ClientLogin을 사용하는 것은 허용되지만 적극적으로 권장하지는 않습니다. 일반적으로 웹 애플리케이션은 사용자에게 로그인 사용자 인증 정보를 요청해서는 안 됩니다 (스누핑에 취약할 수 있음). 대신 애플리케이션은 사용자 인증 정보를 서버 측에 저장하고 Google로 인증하는 데 항상 사용되는 단일 '서비스 계정'을 보유해야 합니다.
보안문자란 무엇인가요?
보안문자 (Completely Automated Public Turing test to tell Computers and Humans Apart)는 사용자가 사람인지 여부를 확인하는 데 사용되는 챌린지-응답 테스트의 한 유형입니다. 이 용어는 카네기 멜런 대학교에서 상표를 등록했습니다. 자세한 내용은 위키백과를 참고하세요. ClientLogin에 보안 문자를 구현했습니다.
보안문자 챌린지는 어떻게 생성하나요?
인증 중에 보안문자 챌린지가 필요한 시점을 결정하는 데 독점 알고리즘이 사용됩니다. 잘못된 사용자 인증 정보로 인증을 반복적으로 시도하면 CAPTCHA 챌린지가 생성되는 경우가 많습니다.
웹 애플리케이션에서 ClientLogin을 사용해야 하나요?
아니요. ClientLogin은 사용자 소유 하드웨어에 설치된 애플리케이션에서 사용해야 합니다. 웹 애플리케이션에서 ClientLogin API를 사용하는 것은 안전하지 않으므로 사용하지 않는 것이 좋습니다.
AuthSub/OAuth 1을 사용할 때 사용자의 사용자 이름을 어떻게 알 수 있나요?
사용자의 피드에 대한 액세스 권한을 부여하는 토큰만 Google에서 제공되므로 사용자 이름을 알 수 없습니다. 사용하려는 피드 URL에 사용자 이름이 포함되어 있는 경우 문제가 될 수 있습니다. 이 경우 특수 사용자 이름 default를 사용하여 '인증 토큰을 사용 중인 사용자'를 의미할 수 있습니다.
Google Data API 클라이언트 라이브러리에서 OAuth 1을 사용하려면 어떻게 해야 하나요?
Google 데이터 API 클라이언트 라이브러리에서 OAuth 1 사용 도움말을 참고하세요.
Google Data API 클라이언트 라이브러리와 함께 AuthSub를 사용하려면 어떻게 해야 하나요?
Google Data API 클라이언트 라이브러리에서 AuthSub 사용하기 도움말을 참고하세요.
Google Data API 클라이언트 라이브러리와 함께 ClientLogin을 사용하려면 어떻게 해야 하나요?
Google 데이터 API 클라이언트 라이브러리에서 ClientLogin 사용 도움말을 참고하세요.

클라이언트 라이브러리

Google에서 지원하는 클라이언트 라이브러리가 있는 프로그래밍 언어는 무엇인가요?

Java, .NET, Python, Objective-C 클라이언트 라이브러리는 Google에서 공식적으로 지원합니다. 또한 파트너인 Zend에서 PHP 클라이언트 라이브러리를 작성했습니다. 이러한 라이브러리를 사용하여 Google 데이터 프로토콜 요청을 구성하고, 서비스에 전송하고, 서버 응답을 처리할 수 있습니다. 현재 Blogger, Calendar, Google 주소록만 지원하는 JavaScript 클라이언트 라이브러리도 있습니다.

Java, .Net, Python 또는 Objective-C 이외의 언어로 클라이언트 라이브러리를 작성하고 데이터 API 개발자 커뮤니티와 공유하려면 Google 데이터 API 토론 그룹에 게시하세요. 여러분의 많은 의견을 기다리겠습니다.

클라이언트 라이브러리의 버그나 기능 요청을 신고하려면 어떻게 해야 하나요?

클라이언트 라이브러리의 버그 또는 기능 요청은 다음 위치에서 신고할 수 있습니다.

버그를 게시한 후 적절한 API의 개발자 포럼에서 스레드를 만듭니다.

Google Data API 클라이언트 라이브러리에서 디버깅 옵션을 사용 설정하려면 어떻게 해야 하나요?
일부 클라이언트 라이브러리를 사용하여 디버깅을 사용 설정하는 방법에 대한 자세한 내용은 Google 데이터 API 클라이언트 디버깅: 프로그램 내 트래픽 탐색을 참고하세요.
클라이언트 라이브러리 클래스의 참조 문서는 어디에서 찾을 수 있나요?
클라이언트 라이브러리 참조 가이드
자바 Javadoc
자바스크립트 JSdoc
.NET NDoc
PHP phpDoc
Python PyDoc

문제 해결

HTTP 디버깅에 유용한 도구는 무엇인가요?

아래에 여러 도구가 나열되어 있지만 On the Wire: API 개발자를 위한 네트워크 캡처 도구 도움말을 읽어보는 것이 좋습니다. 이 도움말에서는 WireShark와 Fiddler의 예를 자세히 설명합니다.

Wireshark
Wireshark는 '네트워크 프로토콜 분석기'입니다. 네트워크 트래픽을 캡처하고 콘텐츠를 분석하는 기능을 제공합니다. HTTP 요청 및 응답 스트림에 직접 액세스할 수 없는 라이브러리에서 발생하는 트래픽을 디버깅하는 데 매우 유용합니다. 통신이 SSL을 사용하여 암호화되므로 Wireshark를 사용하여 애플리케이션과 인증 서비스 간의 트래픽을 분석할 수 없습니다. Wireshark는 tcpdump와 같은 도구를 사용하여 캡처한 트래픽을 분석하는 데도 사용할 수 있습니다. Wireshark는 개발자가 소스 코드와 Windows 설치 프로그램으로 제공합니다. 서드 파티 패키지는 여러 플랫폼에서 사용할 수 있습니다.
Fiddler
Fiddler는 'HTTP 디버깅 프록시'입니다. HTTP 트래픽에 프록시 서버를 사용하도록 코드 또는 런타임 환경을 구성할 수 있는 경우 Fiddler가 애플리케이션과 Google 데이터 서비스 사이에 위치하여 트래픽을 검사할 수 있습니다. Fiddler 2에는 SSL 지원이 포함되어 있습니다. Fiddler는 현재 Windows에서만 사용할 수 있습니다.
cURL
cURL은 HTTP/HTTPS 요청을 실행할 수 있는 명령줄 도구입니다. 클라이언트에서 먼저 HTTP 지원을 빌드하지 않고 서비스와의 상호작용을 빠르게 테스트하는 데 매우 유용합니다.
Java 클라이언트 라이브러리에서 HTTP 로깅 정보를 가져오려면 어떻게 해야 하나요?

Java 클라이언트 라이브러리는 java.util.logging 패키지를 사용하여 HTTP 요청 로깅을 사용 설정합니다. 이렇게 하면 요청 및 응답의 헤더와 상태 코드 및 요청 URL의 로깅을 사용 설정할 수 있습니다. 현재 전체 요청 및 응답 스트림은 로깅되지 않습니다. 이러한 로그에 사용되는 로거 이름은 com.google.gdata.client.http.HttpGDataRequest입니다.

서버에서 오류 코드가 반환되는 경우 예외가 발생합니다. 예외 클래스는 com.google.gdata.util.ServiceException에서 상속되며 getResponseBody()라는 공개 메서드를 포함합니다. 자세한 내용은 Javadoc을 참고하세요.

.NET 클라이언트 라이브러리에서 HTTP 로깅 정보를 가져오려면 어떻게 해야 하나요?
.NET 라이브러리는 추적을 사용 설정한 경우 System.Diagnostics 추적 메서드를 사용하여 실행 경로를 로깅합니다. 또한 오류가 발생하면 GDataRequestException이 발생합니다. 예외에는 HTTP 응답의 본문에 액세스할 수 있는 ResponseString이 포함됩니다.
Google 데이터 피드에서 gzip 인코딩을 사용 설정하려면 어떻게 해야 하나요?

Google 데이터 API 중 하나에서 gzip으로 인코딩된 응답을 받으려면 'Accept-Encoding' 헤더를 설정하고 사용자 에이전트에 'gzip' 문자열이 포함되도록 수정해야 합니다. 적절하게 구성된 헤더의 예:

User-Agent: my program (gzip)
Accept-Encoding: gzip
PHP 클라이언트를 사용할 때 'sslv2에 연결할 수 없음' 오류가 표시되는 이유는 무엇인가요?

2009년 7월부터 보안을 개선하기 위한 예방 조치로 Google 서버에서 SSLv2를 사용 중지하기 시작했습니다. 2007년 7월 이전에 출시된 PHP 클라이언트 라이브러리의 초기 버전 (버전 1.0.0 이하)에는 연결에서 SSLv2를 사용하도록 강제하는 버그가 있습니다. SSLv2가 사용 중지된 서버에 연결하면 다음 오류가 발생합니다.

PHP Fatal error:  Uncaught exception 'Zend_Http_Client_Adapter_Exception' with message 'Unable to Connect to sslv2://www.google.com:443.'

이 오류를 수정하려면 http://framework.zend.com/download에서 제공되는 최신 버전의 PHP 클라이언트 라이브러리로 업그레이드하세요.

최신 버전으로 업그레이드할 수 없는 경우 $gdata이 기존 Zend_Gdata 인스턴스 (또는 적절한 하위 클래스)인 애플리케이션에 다음 코드를 추가하여 이 문제를 해결할 수 있습니다.

$gdata->getHttpClient()->setConfig(array('ssltransport' => 'ssl'));
피드를 설명하는 Atom 서비스 문서를 가져오려면 어떻게 해야 하나요?

요청에 alt=atom-service 매개변수를 전달하여 Atom 서비스 문서를 가져올 수 있습니다. 참고: Google Data API 버전 2만 AtomPub 서비스 문서 문법을 준수하는 서비스 문서를 반환합니다. Google Data API 버전 1은 서비스 문서를 계속 반환하지만 이전 AtomPub 초안 사양을 기반으로 합니다(두 버전 간에 구문 및 네임스페이스 변경사항이 있음).