このページは Cloud Translation API によって翻訳されました。

プロトコルの基本

警告: このページは、Google の古い API である Google Data API を対象としています。Google Data API ディレクトリに記載されている API のみを対象としており、その多くは新しい API に置き換えられています。特定の新しい API については、その新しい API のドキュメントをご覧ください。新しい API を使用してリクエストを承認する方法については、Google アカウントの認証と承認をご覧ください。

このドキュメントでは、クエリの概要や表示内容など、さまざまな Google API で使用される Google Data Protocol の基本事項について説明します。

Google Data Protocol の詳細については、デベロッパーガイドの概要ページとプロトコルリファレンスをご覧ください。

対象者

このドキュメントは、Google Data API で使用される XML 形式とプロトコルに関する一般的な概念を理解したいと考えている方を対象としています。

言語固有のクライアントライブラリを使用するコードを記述するだけであっても、このドキュメントを読んで、クライアントライブラリの抽象化レイヤの下で何が起きているかを理解することができます。

このドキュメントは、HTTP における XML、名前空間、シンジケートフィード、GET、POST、PUT、DELETE リクエストの基礎と、HTTP の「リソース」の概念を理解していることを前提としています。これらの要素について詳しくは、このドキュメントのその他のリソースをご覧ください。

このドキュメントは、特定のプログラミング言語に依存していません。クライアントは、HTTP リクエストを発行し、XML ベースのレスポンスを解析できる任意のプログラミング言語を使用して、サーバーとやり取りできます。

コードを一切書かずにこのドキュメントの例を試す場合は、コマンドラインユーティリティの cURL または Wget を使用できます。詳しくは、各ユーティリティのマニュアルページや、cURL の使用に関するドキュメントで Google データプロトコルを使用するサービスをご確認ください。

例

次の例は、Google Data Protocol API プロトコルを使用して汎用サービスに直接送信する HTTP リクエストと、受け取る結果を示しています。さまざまなプログラミング言語を使用してリクエストを送信する方法の例については、言語固有のサンプルおよびクライアントライブラリをご覧ください。特定の Google サービスで Google Data Protocol を使用する方法については、各サービスのドキュメントをご覧ください。

フィードまたはその他のリソースのリクエスト

/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 に一致するすべてのエントリを含むフィードを返します。（このケースは 1 つだけです）。

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>

エントリの更新

既存のエントリを更新するには、次の手順を行う必要があります。

更新するエントリを取得します。
必要に応じて変更します。
メッセージ本文を更新して、PUT リクエストをエントリの編集 URI に送信します。編集 URI は、上記の例では <link rel='edit'> 要素の href 属性です。

また、他のユーザーが変更を上書きしないように、元のエントリの ETag を指定する必要があります。

次の例では、エントリのテキストを古い値（「This is my entry」）から新しい値（「This is my first entry」）に変更します。

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 で送信するデータは、特定の規則に従う必要があります。ただし、セマンティクスは柔軟であり、1 回のリクエストでターゲットリソースのデータの置換、リソースへの追加、削除が可能です。

注: 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 のセマンティクスは、部分表現を既存のリソースに統合することに注意してください。値を更新するために、必ずしもフィールドを削除する必要はありません。

フィールドがターゲットエントリ内に 1 回だけ存在している場合、統合時に、部分表現内のフィールドがターゲットエントリ内の対応するフィールドを上書きします。
ターゲットエントリに複数のフィールドが存在する場合は、結合の際に部分フィールドがターゲットエントリに追加されます。

繰り返しフィールドと非繰り返しフィールドのマージ方法の違いを次の例に示します。この例では、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 ではエントリごとに 1 つのタイトルしか許可されないため、新しいタイトルで既存の値が上書きされます。
Atom ではエントリごとに複数の作成者を使用できるため、ターゲットリソースにすでに存在する作成者要素のリストに新しい著者が追加されます。

注: すべての API が Atom 標準に準拠しているわけではありません。たとえば、一部の API でエントリごとに 1 つの <author> 要素のみを使用できる場合と、フィードレベルからエントリ作成者を継承する場合があり、このフィールドは読み取り専用になります。

サーバーは有効な PATCH リクエストを処理した後、HTTP 200 ステータスコードと、更新されたエントリの完全な表現のコピーを返します。

サーバーが特定の要素または属性のみを返すようにする場合は、PATCH で fields クエリパラメータを使用して、部分レスポンスをリクエストします。

参考情報

次のサードパーティドキュメントが役立つ場合があります。

IBM の Atom の概要
HTTP 1.1 のメソッド定義。GET、POST、PUT、DELETE の仕様です。
HTTP 1.1 ステータスコードの定義
REST プロトコルの作成方法
REST 方式のウェブサービスの構築
XML の技術的な概要
サンプル XML 名前空間

トップへ戻る