프로토콜 기본사항

경고: 이 페이지는 Google의 이전 API인 Google Data API에 관한 것으로, Google Data API 디렉터리에 표시된 API 중 상당수가 최신 API로 대체된 API입니다. 특정 새 API에 대한 자세한 내용은 새 API 문서를 참조하세요. 최신 API를 사용하여 요청을 승인하는 방법은 Google 계정 인증 및 승인을 참고하세요.

이 문서에서는 쿼리가 표시되는 방식, 결과의 모습 등을 포함하여 여러 Google API에서 사용하는 Google 데이터 프로토콜의 기본사항을 설명합니다.

Google 데이터 프로토콜에 대한 자세한 내용은 개발자 가이드 개요 페이지와 프로토콜 참조를 참고하세요.

대상

이 문서는 Google 데이터 API에서 사용하는 XML 형식 및 프로토콜에 대한 일반적인 개념을 이해하려는 사용자를 대상으로 합니다.

언어별 클라이언트 라이브러리를 사용하는 코드를 작성하려는 경우에도 이 문서를 읽으면서 클라이언트 라이브러리 추상화 레이어의 내용을 이해하는 것이 좋습니다.

이 문서에서는 사용자가 HTTP, XML, 네임스페이스, 신디케이션 피드, GET, POST, PUT, DELETE 요청의 기본사항과 HTTP의 '리소스' 개념을 이해하고 있다고 가정합니다. 이에 대한 자세한 내용은 이 문서의 추가 리소스 섹션을 참고하세요.

이 문서에서는 특정 프로그래밍 언어를 사용하지 않습니다. 클라이언트는 HTTP 요청을 보내고 XML 기반 응답을 파싱할 수 있는 프로그래밍 언어를 사용하여 서버와 상호작용할 수 있습니다.

코드를 작성하지 않고 이 문서의 예를 사용해 보고 싶은 경우 명령줄 유틸리티 cURL 또는 Wget을 사용하면 도움이 됩니다. 자세한 내용은 이러한 유틸리티의 매뉴얼 페이지 또는 cURL을 사용하여 Google 데이터 프로토콜을 사용하는 서비스와 상호작용하는 문서를 참고하세요.

예

다음 예는 Google Data Protocol API 프로토콜을 직접 사용하여 일반 서비스에 보낼 수 있는 HTTP 요청과 수신할 수 있는 결과를 보여줍니다. 다양한 프로그래밍 언어를 사용하여 요청을 보내는 방법의 예는 언어별 샘플 및 클라이언트 라이브러리를 참고하세요. 특정 Google 서비스에서 Google 데이터 프로토콜을 사용하는 방법에 대한 자세한 내용은 서비스별 문서를 참고하세요.

피드 또는 기타 리소스 요청

/myFeed라는 피드가 있다고 가정하고 현재 그 항목이 포함된 항목이 없다고 가정합니다. 이를 확인하려면 다음 HTTP 요청을 서버로 전송합니다.

GET /myFeed

서버가 다음과 같이 응답합니다.

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

피드에는 항목이 포함되지 않지만 제목 및 작성자 이름과 같은 메타데이터는 포함됩니다. 또한 HTTP ETag 형식의 버전 식별자를 포함합니다.

새 항목 삽입

새 항목을 만들려면 POST 요청을 보내고 새 항목의 XML 표현을 제공합니다.

POST /myFeed

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

표준 Atom <id>, <link> 또는 <updated> 요소를 제공하지 않습니다. 서버는 POST 요청에 대한 응답으로 이러한 요소를 만듭니다. 또한 피드의 작성자가 항목의 작성자와 같을 필요는 없습니다.

서버가 다음과 같이 응답합니다.

201 CREATED

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/1/'/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

문자열 검색

특정 문자열에 대해 전체 텍스트 검색을 수행하려면 전체 텍스트 검색을 지원하는 서비스를 사용할 때 q 매개변수와 함께 GET 요청을 전송합니다. 쿼리 매개변수에 대한 자세한 내용은 프로토콜 참조 문서의 쿼리 요청을 참조하세요.

GET /myFeed?q=This

서버는 검색 문자열 This와 일치하는 모든 항목이 포함된 피드로 응답합니다. (이 경우 하나만 있습니다.)

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"S0wCTlpIIip7ImA0X0QI"'>
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my entry</content>
  </entry>
</feed>

항목 업데이트

기존 항목을 업데이트하려면 다음 단계를 수행해야 합니다.

1. 업데이트하려는 항목을 검색합니다.
2. 원하는 대로 수정합니다.
3. 메시지 본문의 업데이트된 항목과 함께 PUT 요청을 항목의 수정 URI에 전송합니다. 이전 URI에서는 수정 URI가 <link rel='edit'> 요소의 href 속성으로 표시됩니다.

또한 원래 항목의 ETag를 지정하여 다른 사용자의 변경사항을 덮어쓰지 않도록 해야 합니다.

다음 예에서는 항목의 텍스트를 이전 값('This is my entry')에서 새 값('This is my first entries')으로 변경합니다.

PUT /myFeed/1/1/

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

서버가 다음과 같이 응답합니다.

200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

ETag가 변경되었습니다. 리소스 버전에 대한 자세한 내용은 프로토콜 참조 문서의 리소스 버전 관리 (ETag) 섹션을 참고하세요.

컨텍스트에서 새 항목을 보려면 전체 리소스를 다시 요청하세요.

GET /myFeed

서버가 다음과 같이 응답합니다.

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D08FQn8-eil7ImA9WxZbFEw."'>
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my first entry.</content>
  </entry>
</feed>

참고: 방화벽에서 PUT을 허용하지 않으면 HTTP POST를 실행하고 메서드 재정의 헤더를 다음과 같이 설정합니다.

X-HTTP-Method-Override: PUT

항목 삭제

기존 항목을 삭제하려면 항목의 수정 URI를 사용하여 DELETE 요청을 전송합니다 (이전 예시의 서버에서 제공).

방화벽이 DELETE를 허용하지 않으면 HTTP POST를 실행하고 메서드 재정의 헤더를 다음과 같이 설정합니다.

X-HTTP-Method-Override: DELETE

항목을 삭제할 때 조건부 삭제 (항목을 마지막으로 검색한 이후 항목이 변경되지 않은 경우에만 삭제) 또는 비조건부 삭제 중에서 선택할 수 있습니다. 자세한 내용은 프로토콜 참조 문서의 리소스 버전 관리 (ETag) 섹션을 참고하세요. 조건부 삭제를 수행하려면 다음 HTTP 헤더를 설정합니다.

If-Match: *

다음 예에서는 항목을 삭제합니다 (헤더가 적절하게 설정된 경우).

DELETE /myFeed/1/

서버가 다음과 같이 응답합니다.

200 OK

다른 GET를 실행하여 이제 피드에 항목이 없음을 확인합니다.

GET /myFeed

서버는 메타데이터만 포함된 피드로 응답합니다.

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

삭제에 실패하면 서버에서 오류 코드로 응답합니다. 자세한 내용은 프로토콜 참조 문서의 HTTP 상태 코드를 참고하세요.

부분 피드 또는 항목 요청(실험용)

이 문서에 나와 있는 간단한 예시 피드와 달리 실제로는 피드가 매우 복잡할 수 있습니다. 일부 API에서는 전체 리소스 표현 대신 원하는 요소나 속성만 요청할 수 있습니다. 불필요한 데이터를 검색하고 파싱하지 않아도 되므로 클라이언트 애플리케이션의 효율성을 크게 개선할 수 있습니다.

부분 응답을 요청하려면 fields 쿼리 매개변수를 사용하여 반환하려는 요소 또는 속성을 지정합니다. 자세한 내용은 프로토콜 참조 문서의 부분 응답을 참고하세요.

다음 예에서는 피드 ID와 각 피드 항목의 작성자와 제목만 요청합니다.

GET /myFeed?fields=id,entry(author)

서버가 다음과 같이 응답합니다.

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.example.com/myFeed</id>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
  </entry>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 2</title>
  </entry>
</feed>

fields 매개변수는 데이터를 반환하는 모든 종류의 요청과 함께 사용할 수 있습니다. 여기에는 GET 외에 POST 및 PUT (부분 업데이트 요청에 사용되는 PATCH)도 포함됩니다.

참고: fields 쿼리 매개변수는 요청에 대한 응답으로 다시 전송되는 데이터만 제어합니다. PUT, POST, PATCH 요청의 본문에 제공해야 하는 데이터에는 영향을 미치지 않습니다.

다음은 POST 및 PUT의 예입니다.

• 부분 응답에 대해 POST 요청을 하는 경우에도 새 항목 삽입에 설명된 것과 동일한 데이터를 제공해야 합니다. 다음 예시에서는 새로 만든 항목의 제목만 포함된 부분 응답을 요청합니다.

  POST /myFeed?fields=title
        
  ...data...
  

  서버가 다음과 같이 응답합니다.

  200 OK
  
  <?xml version='1.0' encoding='utf-8'?>
  <entry xmlns='http://www.w3.org/2005/Atom'>
    <title type='text'>Entry 1</title>
  </entry>

• 부분 응답에 대해 PUT 요청을 하는 경우에도 항목 업데이트에 설명된 대로 전체 리소스 표현의 수정된 버전을 제공해야 합니다. 다음 예에서는 수정된 항목의 새 ETag 값만 포함된 부분 응답을 요청합니다.

  PUT /myFeed/1/1?fields=@gd:etag
    
  ...data...

  서버가 다음과 같이 응답합니다.

  200 OK
  
  <?xml version='1.0' encoding='utf-8'?>
  <entry xmlns='http://www.w3.org/2005/Atom'
    gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>

특정 필드 업데이트(실험용)

사용 중인 API가 부분 응답을 지원하고 편집 가능한 필드가 있는 경우 항목 수정 시 불필요한 데이터를 전송하지 않을 수도 있습니다. 부분 업데이트를 사용하면 변경할 필드의 데이터만 전송할 수 있습니다.

부분 업데이트를 사용하려면 PUT에서 사용하는 것과 동일한 수정 URI에 PATCH 요청을 보냅니다. PATCH를 사용하여 전송하는 데이터는 특정 규칙을 따라야 합니다. 그러나 시맨틱스는 대상 요청의 데이터를 교체하거나, 추가하거나, 단일 요청으로 삭제할 수 있을 만큼 유연합니다.

참고: PUT와 마찬가지로 다른 사람의 변경사항을 덮어쓰지 않도록 하려면 원래 항목의 ETag를 지정해야 합니다.

PATCH 및 시맨틱스에 대한 자세한 내용은 프로토콜 참조 문서의 부분 업데이트를 참고하세요.

이 예에서는 항목의 제목을 수정하는 부분 업데이트 요청을 보여줍니다.

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag="EksPTg1Bfyp7IWA6WhJT"
    gd:fields='title'>
  <title>New Title</title>
</entry>

서버는 PATCH 요청을 받으면 먼저 항목의 gd:fields 속성으로 지정된 모든 필드 (있는 경우)를 삭제한 다음 요청 본문에 제공된 모든 데이터를 대상 리소스와 병합합니다. 이 예에서는 제목 요소를 먼저 대상 리소스에서 삭제한 다음 새 제목 값을 병합합니다. 이 요청은 이전 제목을 새 제목으로 교체하는 것이 좋습니다.

그러나 PATCH의 시맨틱스는 부분 표현을 기존 리소스에 병합하는 것입니다. 값을 업데이트하기 위해 항상 필드를 삭제할 필요는 없습니다.

• 필드가 대상 항목에 한 번만 존재할 경우 병합 시 부분 표현의 필드가 대상 항목의 해당 필드를 덮어씁니다.
• 필드가 대상 항목에 두 번 이상 존재할 수 있는 경우 병합 시 부분 필드가 대상 항목에 추가됩니다.

반복 필드와 반복되지 않는 필드의 병합 방식 차이점은 다음 예를 참고하세요. 먼저 gd:fields 속성을 사용하여 새 제목과 저자 중 하나를 삭제하지 않고 항목에 추가합니다.

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:edtag="EksPTg1Bfyp7IWA6WhJT">
  <title>A new title</title>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>darcy@gmail.com</email>
  </author>
</entry>

부분 항목 표현에는 gd:fields 속성이 없으므로 필드가 삭제되지 않습니다. 하지만 <title> 및 <author> 요소의 새 값은 대상 리소스와 병합됩니다.

• Atom은 항목당 하나의 제목만 허용하므로 새 제목이 기존 값을 덮어씁니다. 
• Atom은 항목당 여러 명의 작성자를 허용하므로 새 작성자가 이미 대상 리소스에 있는 작성자 요소 목록에 추가됩니다.
  

  참고: 모든 API가 Atom 표준을 준수하는 것은 아닙니다. 예를 들어 일부 API는 항목당 하나의 <author> 요소만 허용하며 피드 수준에서 항목 작성자를 상속하는 필드는 읽기 전용으로 설정합니다.

서버는 유효한 PATCH 요청을 처리한 후 HTTP 200 상태 코드와 함께 업데이트된 항목의 전체 표현 사본을 반환합니다.

서버에서 특정 요소나 속성만 반환하도록 하려면 PATCH와 함께 fields 쿼리 매개변수를 사용하여 부분 응답을 요청하면 됩니다.

추가 리소스

다음과 같은 타사 문서가 유용할 수 있습니다.

• IBM Atom 개요
• HTTP 1.1 메서드 정의: GET, POST, PUT, DELETE 사양
• HTTP 1.1 상태 코드 정의
• REST 프로토콜을 만드는 방법
• REST 방식으로 웹 서비스 빌드하기
• XML의 기술 소개
• XML 네임스페이스 예

맨 위로