이 문서에서는 쿼리의 모습, 표시되는 결과 등에 대한 정보를 포함하여 Google Data API에서 사용하는 프로토콜을 설명합니다.
Google 데이터 API에 관한 자세한 내용은 Google 데이터 개발자 가이드 문서 및 프로토콜 가이드를 참고하세요.
대상
이 문서는 Google 데이터 API에서 사용하는 XML 형식과 프로토콜의 세부정보를 확인하려는 사용자를 대상으로 합니다.
Google 데이터 클라이언트 API를 사용하는 코드만 작성하려는 경우 이러한 세부정보를 알 필요가 없습니다. 대신 언어별 클라이언트 라이브러리를 사용하면 됩니다.
프로토콜을 이해하려면 이 문서를 읽어보세요. 예를 들어 다음과 같은 작업에 도움이 되도록 이 문서를 읽어볼 수 있습니다.
- Google 데이터 아키텍처 평가
- 제공된 Google 데이터 클라이언트 라이브러리를 사용하지 않고 프로토콜을 사용하여 코딩
- 새로운 언어로 클라이언트 라이브러리 작성
이 문서에서는 사용자가 HTTP, XML, 네임스페이스, 신디케이션 피드, GET
, POST
, PUT
, DELETE
요청의 기본사항과 HTTP의 '리소스' 개념을 이해하고 있다고 가정합니다. 이에 대한 자세한 내용은 이 문서의 추가 리소스 섹션을 참고하세요.
이 문서에서는 특정 프로그래밍 언어를 사용하지 않습니다. HTTP 요청을 보내고 XML 기반 응답을 파싱할 수 있는 프로그래밍 언어를 사용하여 Google 데이터 메시지를 주고받을 수 있습니다.
프로토콜 세부정보
이 섹션에서는 Google 데이터 문서 형식과 쿼리 구문을 설명합니다.
문서 형식
Google 데이터, Atom 및 RSS 2.0은 모두 동일한 기본 데이터 모델을 공유합니다. 컨테이너는 일부 전역 데이터와 모든 항목을 보유하는 컨테이너입니다. 각 프로토콜의 형식은 기본 스키마에 의해 정의되지만 외부 네임스페이스를 사용하여 확장될 수 있습니다.
Google Data API는 Atom 신디케이션 형식 (읽기 및 쓰기 모두) 또는 RSS 형식 (읽기 전용)을 사용할 수 있습니다.
Atom은 Google 데이터의 기본 형식입니다. RSS 형식으로 응답을 요청하려면 /alt=rss/
매개변수를 사용합니다. 자세한 내용은 쿼리 요청을 참고하세요.
RSS 형식으로 데이터를 요청하면 Google 데이터는 RSS 형식으로 피드 (또는 리소스의 기타 표현)를 제공합니다. 특정 Google 데이터 속성에 상응하는 RSS 속성이 없는 경우 Google 데이터는 Atom 속성을 사용하여 적절한 네임스페이스로 라벨을 지정하여 RSS에 대한 확장 프로그램임을 나타냅니다.
참고: Atom 형식의 대부분의 Google 데이터 피드는 피드 요소에 xmlns
속성을 지정하여 기본 네임스페이스로 Atom 네임스페이스를 사용합니다. 방법 예시 예를 참조하세요. 따라서 이 문서의 예에서는 Atom 형식 피드의 요소에 atom:
를 명시적으로 지정하지 않습니다.
다음 표에서는 스키마 요소의 Atom 및 RSS 표현을 보여줍니다. 이 표에서 언급되지 않은 모든 데이터는 일반 XML로 취급되며 두 표현에서 동일하게 표시됩니다. 달리 명시되지 않는 한 특정 열의 XML 요소는 해당 열에 해당하는 네임스페이스에 있습니다. 이 요약에서는 표준 XPath 표기법을 사용합니다. 특히 슬래시는 요소 계층 구조를, @ 기호는 요소의 속성을 나타냅니다.
다음 각 표에 강조표시된 항목이 필요합니다.
다음 표에는 Google 데이터 피드의 요소가 나와 있습니다.
피드 스키마 항목 | Atom 표현 | RSS 표현 |
---|---|---|
피드 제목 | /feed/title |
/rss/channel/title |
피드 ID | /feed/id |
/rss/channel/atom:id |
피드 HTML 링크 | /feed/link[@rel="alternate"] [@type="text/html"]/@href |
/rss/channel/link |
피드 설명 | /feed/subtitle |
/rss/channel/description |
피드 언어 | /feed/@xml:lang |
/rss/channel/language |
피드 저작권 | /feed/rights |
/rss/channel/copyright |
피드 작성자 |
특정 경우에 필요합니다. Atom 사양을 참조하세요. |
/rss/channel/managingEditor |
피드 최종 업데이트 날짜 | /feed/updated (RFC 3339 형식) |
/rss/channel/lastBuildDate (RFC 822 형식) |
피드 카테고리 | /feed/category/@term |
/rss/channel/category |
피드 카테고리 체계 | /feed/category/@scheme |
/rss/channel/category/@domain |
피드 생성기 | /feed/generator /feed/generator/@uri |
/rss/channel/generator |
피드 아이콘 | /feed/icon |
/rss/channel/image/url (로고도 없는 경우 아이콘이 피드에 포함되지 않는 경우) |
피드 로고 | /feed/logo |
/rss/channel/image/url |
다음 표는 Google 데이터 검색결과 피드의 요소를 보여줍니다. Google 데이터에서는 검색결과 피드에 OpenSearch 1.1 응답 요소 중 일부를 노출합니다.
검색결과 피드 스키마 항목 | Atom 표현 | RSS/OpenSearch 표현 |
---|---|---|
검색결과 수 | /feed/openSearch:totalResults |
/rss/channel/openSearch:totalResults |
검색결과 시작 색인 | /feed/openSearch:startIndex |
/rss/channel/openSearch:startIndex |
페이지당 검색결과 수 | /feed/openSearch:itemsPerPage |
/rss/channel/openSearch:itemsPerPage |
다음 표에는 Google 데이터 항목의 요소가 나와 있습니다.
항목 스키마 항목 | Atom 표현 | RSS 표현 |
---|---|---|
항목 ID | /feed/entry/id |
/rss/channel/item/guid |
항목 버전 ID | 선택적으로 EditURI에 삽입됩니다 (이 문서의 낙관적 동시 실행 섹션 참조). | — |
항목 제목 | /feed/entry/title |
/rss/channel/item/title |
항목 링크 | /feed/entry/link |
/rss/channel/item/link /rss/channel/item/enclosure /rss/channel/item/comments |
항목 요약 |
특정 경우에 필요합니다. Atom 사양을 참조하세요. |
/rss/channel/item/atom:summary |
응모 콘텐츠 |
콘텐츠 요소가 없으면 항목에 |
/rss/channel/item/description |
항목 작성자 |
특정 경우에 필요합니다. Atom 사양을 참조하세요. |
/rss/channel/item/author |
항목 카테고리 | /feed/entry/category/@term |
/rss/channel/item/category |
항목 카테고리 체계 | /feed/entry/category/@scheme |
/rss/channel/item/category/@domain |
항목 게시 날짜 | /feed/entry/published (RFC 3339) |
/rss/channel/item/pubDate (RFC 822) |
항목 업데이트 날짜 | /feed/entry/updated (RFC 3339) |
/rss/channel/item/atom:updated (RFC 3339) |
쿼리
이 섹션에서는 쿼리 시스템을 사용하는 방법을 설명합니다.
모델 설계 원칙 쿼리
쿼리 모델은 의도적으로 매우 간단합니다. 기본 원칙은 다음과 같습니다.
- 쿼리는 HTTP 헤더 또는 페이로드의 일부가 아니라 HTTP URI로 표현됩니다. 이 접근 방식의 한 가지 이점은 쿼리에 연결할 수 있다는 것입니다.
- 조건자의 범위는 단일 항목으로 지정됩니다. 따라서 '오늘 저에게 이메일을 10개 이상 보낸 사람의 모든 이메일을 찾아보세요'와 같은 상관관계 검색어를 보낼 수 있는 방법은 없습니다.
- 검색어를 예측할 수 있는 속성 집합은 매우 제한적입니다. 대부분의 검색어는 단순히 전체 텍스트 검색어입니다.
- 결과 순서는 구현에 따라 결정됩니다.
- 프로토콜은 기본적으로 확장 가능합니다. 서비스에서 추가 조건자 또는 정렬을 노출하려는 경우 새 매개변수를 도입하여 쉽게 할 수 있습니다.
쿼리 요청
클라이언트는 HTTP GET
요청을 실행하여 Google 데이터 서비스를 쿼리합니다. 쿼리 URI는 리소스 URI (Atom에서는 FeedURI)와 그 뒤에 나오는 쿼리 매개변수로 구성됩니다. 대부분의 쿼리 매개변수는 기존 ?name=value[&...]
URL 매개변수로 표현됩니다. 카테고리 매개변수는 다르게 처리됩니다(아래 참고).
예를 들어, FeedURI가 http://www.example.com/feeds/jo
이면 다음 URI를 사용하여 쿼리를 보낼 수 있습니다.
http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z
Google 데이터 서비스는 HTTP 조건부 GET
를 지원합니다. 반환된 피드 또는 항목의 <atom:updated>
요소 값을 기반으로 Last-Modified 응답 헤더를 설정합니다. 클라이언트는 콘텐츠가 변경되지 않았다면 콘텐츠가 다시 검색되지 않도록 이 값을 If-Modified-Since 요청 헤더의 값으로 다시 전송할 수 있습니다. If-Modified-Since 이후 콘텐츠가 변경되지 않으면 Google 데이터 서비스에서 304 (Not Modified) HTTP 응답을 반환합니다.
Google 데이터 서비스는 카테고리 쿼리 및 alt
쿼리를 지원해야 하며, 다른 매개변수에 대한 지원은 선택사항입니다. 특정 서비스에서 인식하지 못하는 표준 매개변수를 전달하면 403 Forbidden
응답이 발생합니다. 지원되지 않는 비표준 매개변수를 전달하면 400 Bad Request
응답이 발생합니다. 다른 상태 코드에 대한 자세한 내용은 이 문서의 HTTP 상태 코드 섹션을 참조하세요.
표준 쿼리 매개변수는 다음 표에 요약되어 있습니다. 모든 매개변수 값은 URL로 인코딩해야 합니다.
매개변수 | 의미 | 메모 |
---|---|---|
q |
전체 텍스트 쿼리 문자열 |
|
/-/category |
카테고리 필터 |
|
category |
카테고리 필터 |
|
author |
항목 작성자 |
|
alt |
대체 표현 유형 | |
updated-max updated-min |
항목 업데이트 날짜 범위 |
|
published-max published-min |
항목 게시 날짜의 경계 |
|
start-index |
가져올 첫 번째 결과의 1 기반 색인입니다. |
|
max-results |
가져올 최대 결과 수 | 기본 피드 크기를 제한하기 위해 기본 max-results 값이 있는 서비스의 경우 전체 피드를 수신하려면 매우 큰 수를 지정할 수 있습니다. |
항목 ID | 가져올 특정 항목의 ID |
|
카테고리 검색어에 대한 정보
Google에서는 카테고리 쿼리에 대해 약간 특이한 형식을 지정하기로 했습니다. 다음과 같은 쿼리 대신,
http://example.com/jo?category=Fritz&category=2006
다음을 사용합니다.
http://example.com/jo/-/Fritz/2006
이 접근 방식은 쿼리 매개변수를 사용하지 않고 리소스를 식별하며 더 깔끔한 URI를 생성합니다. Google에서는 카테고리 검색어가 가장 일반적인 검색어라고 생각하기 때문에 카테고리에 이 접근 방식을 선택했습니다.
이 접근 방식의 단점은 Google 데이터 서비스가 카테고리 쿼리를 http://example.com/jo/MyPost/comments
와 같은 다른 리소스 URI와 구분할 수 있도록 카테고리 쿼리에 /-/
를 사용해야 한다는 것입니다.
쿼리 응답
쿼리는 요청 매개변수에 따라 Atom 피드, Atom 항목 또는 RSS 피드를 반환합니다.
쿼리 결과에 <feed>
또는 <channel>
요소 바로 아래에 다음과 같은 OpenSearch 요소가 포함됩니다 (결과가 Atom인지 RSS인지에 따라 다름).
openSearch:totalResults
- 쿼리의 총 검색결과 수입니다 (결과 피드에 반드시 포함되는 것은 아님).
openSearch:startIndex
- 첫 번째 결과의 1부터 시작하는 색인입니다.
openSearch:itemsPerPage
- 한 페이지에 표시되는 최대 항목 수입니다. 이렇게 하면 클라이언트가 임의의 후속 페이지 세트에 대한 직접 링크를 생성할 수 있습니다. 하지만 이 숫자 사용에 문제가 발생할 경우 쿼리 요청 섹션의 표에서
start-index
관련 참고사항을 확인하세요.
Atom 응답 피드 및 항목에는 다음과 같은 Atom 및 Google 데이터 요소와 Atom 사양에 나열된 다른 요소도 포함될 수 있습니다.
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>
- 전체 Atom 피드를 가져올 수 있는 URI를 지정합니다.
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>
- Atom 피드의 PostURI (새 항목이 게시될 수 있음)를 지정합니다.
<link rel="self" type="..." href="..."/>
- 이 리소스의 URI를 포함합니다.
type
속성의 값은 요청된 형식에 따라 다릅니다. 그때까지 데이터가 변경되지 않으면 이 URI에 다른 GET을 전송하면 동일한 응답이 반환됩니다. <link rel="previous" type="application/atom+xml" href="..."/>
- 청크된 경우 이 쿼리 결과 집합의 이전 청크 URI를 지정합니다.
<link rel="next" type="application/atom+xml" href="..."/>
- 청크된 경우 이 쿼리 결과 세트의 다음 청크 URI를 지정합니다.
<link rel="edit" type="application/atom+xml" href="..."/>
- Atom 항목의 EditURI (업데이트된 항목을 보내는 위치)를 지정합니다.
다음은 검색어에 대한 응답으로 표시되는 샘플 응답 본문입니다.
<?xml version="1.0" encoding="UTF-8"?> <feed xmlns:atom="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"> <id>http://www.example.com/feed/1234.1/posts/full</id> <updated>2005-09-16T00:42:06Z</updated> <title type="text">Books and Romance with Jo and Liz</title> <link rel="alternate" type="text/html" href="http://www.example.net/"/> <link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="http://www.example.com/feed/1234.1/posts/full"/> <link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="http://www.example.com/feed/1234.1/posts/full"/> <link rel="self" type="application/atom+xml" href="http://www.example.com/feed/1234.1/posts/full"/> <author> <name>Elizabeth Bennet</name> <email>liz@gmail.com</email> </author> <generator version="1.0" uri="http://www.example.com">Example Generator Engine</generator> <openSearch:totalResults>2</openSearch:totalResults> <openSearch:startIndex>0</openSearch:startIndex> <entry> <id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id> <published>2005-01-09T08:00:00Z</published> <updated>2005-01-09T08:00:00Z</updated> <category scheme="http://www.example.com/type" term="blog.post"/> <title type="text">This is the title of entry 1009</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div> </content> <link rel="alternate" type="text/html" href="http://www.example.com/posturl"/> <link rel="edit" type="application/atom+xml" href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/> <author> <name>Elizabeth Bennet</name> <email>liz@gmail.com</email> </author> </entry> <entry> <id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id> <published>2005-01-07T08:00:00Z</published> <updated>2005-01-07T08:02:00Z</updated> <category scheme="http://www.example.com/type" term="blog.post"/> <title type="text">This is the title of entry 1007</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div> </content> <link rel="alternate" type="text/html" href="http://www.example.com/posturl"/> <link rel="edit" type="application/atom+xml" href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/> <author> <name>Elizabeth Bennet</name> <email>liz@gmail.com</email> </author> </entry> </feed>
요청된 피드가 Atom 형식이고 쿼리 매개변수가 지정되지 않았고 결과에 모든 항목이 포함되지 않은 경우 다음 요소가 최상위 피드에 삽입됩니다. <link rel="next" type="application/atom+xml" href="..."/>
다음 항목 세트가 포함된 피드를 가리킵니다. 후속 세트에는 상응하는 <link rel="previous" type="application/atom+xml" href="..."/>
요소가 포함됩니다. 클라이언트는 모든 다음 링크를 따라 피드에서 모든 항목을 검색할 수 있습니다.
HTTP 상태 코드
다음 표에서는 Google 데이터 서비스와 관련하여 다양한 HTTP 상태 코드의 의미를 설명합니다.
코드 | 설명 |
---|---|
200 확인 | 오류가 없습니다. |
201 생성됨 | 리소스를 만들었습니다. |
304 수정되지 않음 | 요청의 If-Modified-Since 헤더에 지정된 시간 이후 리소스가 변경되지 않았습니다. |
400개의 잘못된 요청 | 잘못된 요청 URI 또는 헤더 또는 지원되지 않는 비표준 매개변수입니다. |
401 승인되지 않음 | 인증이 필요합니다. |
403 금지됨 | 지원되지 않는 표준 매개변수 또는 인증 또는 승인에 실패했습니다. |
404 찾을 수 없음 | 리소스 (예: 피드 또는 항목)를 찾을 수 없습니다. |
409 충돌 | 지정된 버전 번호가 리소스의 최신 버전 번호와 일치하지 않습니다. |
500 내부 서버 오류 | 내부 오류입니다. 인식할 수 없는 모든 오류에 사용되는 기본 코드입니다. |
낙관적 동시 실행 (버전 관리)
여러 클라이언트가 의도치 않게 서로의 변경사항을 덮어쓰지 않도록 하는 것이 중요한 경우도 있습니다. 가장 간단한 방법은 고객이 수정하는 항목의 현재 버전이 해당 수정의 기반이 되는 버전과 일치하는지 확인하는 것입니다. 두 번째 클라이언트가 첫 번째 클라이언트를 업데이트하기 전에 업데이트를 수행하는 경우, 첫 번째 클라이언트가 더 이상 최신 버전을 기반으로 수정되지 않기 때문에 첫 번째 클라이언트의 업데이트가 거부됩니다.
버전 관리를 지원하는 Google 데이터 피드에서 각 항목의 EditURI에 버전 ID를 추가하여 이러한 시맨틱스를 적용합니다. EditURI만 영향을 받으며 항목 ID는 영향을 받지 않습니다. 이 스키마에서 각 업데이트는 항목의 EditURI를 변경하므로 원래 버전을 기반으로 하는 후속 업데이트가 실패합니다. 삭제는 이 기능과 관련된 업데이트와 동일합니다. 이전 버전 번호로 삭제를 전송하면 삭제가 실패합니다.
일부 Google 데이터 피드는 낙관적 동시 실행을 지원하지 않습니다. 이를 지원하는 피드에서 서버가 PUT 또는 DELETE의 버전 충돌을 감지하면 서버는 409 Conflict
로 응답합니다. 응답 본문에는 항목의 현재 상태 (Atom 항목 문서)가 포함됩니다. 클라이언트는 409 응답의 EditURI를 사용하여 충돌을 해결하고 요청을 다시 제출하는 것이 좋습니다.
동기 및 디자인 노트
낙관적 동시 실행에 대한 이러한 접근 방식을 통해 버전 ID에 대한 새로운 마크업을 요구하지 않고 원하는 시맨틱스를 구현할 수 있으며, 이는 Google 데이터의 응답이 Google 데이터 Atom이 아닌 엔드포인트와 호환되도록 합니다.
버전 ID를 지정하는 대신 각 항목 (/atom:entry/atom:updated
)에서 업데이트 타임스탬프를 확인할 수 있습니다. 하지만 업데이트 타임스탬프 사용에는 다음과 같은 두 가지 문제가 있습니다.
- 업데이트에만 작동하며 삭제에는 적용되지 않습니다.
- 애플리케이션이 날짜/시간 값을 버전 ID로 사용하도록 강제하므로 기존 데이터 저장소 위에 Google 데이터를 재구성하기가 더 어려워집니다.
인증
클라이언트가 서비스에 액세스하려고 할 때 서비스에 사용자의 사용자 인증 정보를 제공하여 사용자에게 해당 작업을 실행할 권한이 있음을 증명해야 합니다.
클라이언트가 인증에 사용해야 하는 접근 방식은 클라이언트 유형에 따라 다릅니다.
- 데스크톱 애플리케이션은 설치된 애플리케이션에 대한 계정 인증('ClientLogin'이라고도 함)이라는 Google 전용 인증 시스템을 사용해야 합니다. (웹 기반 클라이언트는 이 시스템을 사용해서는 안 됩니다.)
- Google 데이터 서비스의 타사 프런트엔드와 같은 웹 기반 클라이언트는 웹 기반 애플리케이션용 계정 인증 프록시('AuthSub'라고 함)라는 Google 전용 인증 시스템을 사용해야 합니다.
ClientLogin 시스템에서 데스크톱 클라이언트는 사용자에게 사용자 인증 정보를 요청한 다음 해당 사용자 인증 정보를 Google 인증 시스템으로 전송합니다.
인증에 성공하면 인증 시스템에서 클라이언트가 Google 데이터 요청을 보낼 때 HTTP 승인 헤더에 사용하는 토큰을 반환합니다.
인증에 실패하면 서버에서 403 Forbidden 상태 코드와 함께 인증에 적용할 수 있는 본인 확인 요청을 포함하는 WWW-Authenticate 헤더를 반환합니다.
AuthSub 시스템은 이와 비슷하게 작동하지만, 사용자에게 사용자 인증 정보를 요청하는 대신 사용자 인증 정보를 요청하는 Google 서비스에 사용자를 연결한다는 점이 다릅니다. 그런 다음 서비스는 웹 애플리케이션에서 사용할 수 있는 토큰을 반환합니다. 이 접근 방법의 장점은 웹 프런트엔드가 아닌 Google에서 사용자의 사용자 인증 정보를 안전하게 처리하고 저장한다는 것입니다.
이러한 인증 시스템에 관한 자세한 내용은 Google 데이터 인증 개요 또는 Google 계정 인증 문서를 참고하세요.
세션 상태
많은 비즈니스 로직 구현 시 세션 유지, 사용자 세션의 상태 추적이 필요합니다.
Google에서는 두 가지 방법으로 세션 상태를 추적합니다. 하나는 쿠키를 사용하고, 다른 하나는 쿼리 매개변수로 전송할 수 있는 토큰을 사용하는 것입니다. 두 방법 모두 동일한 효과를 냅니다. 클라이언트는 다음 세션 상태 추적 방법 중 하나를 지원하는 것이 좋습니다 (둘 중 한 가지로 충분함). 위 방법 중 하나를 지원하지 않는 클라이언트라도 Google 데이터 서비스를 사용할 수는 있지만 이러한 방법을 지원하는 클라이언트에 비해 성능이 저하될 수 있습니다. 특히 클라이언트가 이러한 메서드를 지원하지 않으면 모든 요청이 리디렉션되므로 모든 요청 (및 관련 데이터)이 두 번 서버로 전송되어 클라이언트와 서버의 성능에 영향을 미칩니다.
Google 클라이언트 라이브러리는 세션 상태를 처리하므로 Google의 라이브러리를 사용하면 세션 상태 지원을 받기 위해 별도의 조치를 취할 필요가 없습니다.
추가 리소스
다음과 같은 타사 문서가 유용할 수 있습니다.
- Atom과 RSS의 비교
- IBM Atom 개요
- RSS에 대한 더블린 코어 확장 프로그램
- HTTP 1.1 메서드 정의:
GET
,POST
,PUT
,DELETE
사양 - HTTP 1.1 상태 코드 정의
- REST 프로토콜을 만드는 방법
- REST 방식으로 웹 서비스 빌드하기
- XML의 기술 소개
- XML 네임스페이스 예