Google Data API プロトコルの基本

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

Google Data API について詳しくは、Google Data デベロッパー ガイドとリファレンス ガイドをご覧ください。

対象者

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

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

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

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

例

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

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

/myFeed というフィードがあり、現在のところエントリが存在しないとします。これを確認するには、サーバーに次のリクエストを送信します。

GET /myFeed

サーバーが応答します。

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>

このフィードにはエントリは含まれませんが、タイトルや著者名などのメタデータが含まれます。

新しいエントリを挿入する

新しいエントリを作成するには、POST リクエストを送信し、新しいエントリの XML 表現を指定します。

POST /myFeed

<?xml version="1.0"?>
<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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <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"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <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>
</feed>

エントリの更新

既存のエントリを更新するには、PUT をエントリの編集 URI（前の例のサーバーで <link rel="edit"> 要素に指定）とともに使用します。

ファイアウォールで PUT が許可されていない場合は、HTTP POST を実行して、メソッドのオーバーライド ヘッダーを次のように設定します。

X-HTTP-Method-Override: PUT

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

PUT /myFeed/1/1/

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <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>

編集 URI が変更され、末尾が「/1/」ではなく「/2/」になっていることに注意してください。編集 URI の最後の番号はバージョン番号です。バージョンの詳細については、プロトコル リファレンス ドキュメントの楽観的同時実行のセクションをご覧ください。

新しいエントリをコンテキストで表示するには、リソース全体を再度リクエストします。

GET /myFeed

サーバーが応答します。

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <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>

エントリの削除

既存のエントリを削除するには、エントリの編集 URI（前の例のサーバーで指定）を使用して、DELETE リクエストを送信します。

ファイアウォールで DELETE が許可されていない場合は、HTTP POST を実行して、メソッドのオーバーライド ヘッダーを次のように設定します。

 X-HTTP-Method-Override: DELETE

次の例では、エントリを削除します。

DELETE /myFeed/1/2/

サーバーが応答します。

200 OK

別の GET を実行して、フィードにエントリがないことを確認します。

GET /myFeed

サーバーが応答します。

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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 ステータス コードをご覧ください。

参考情報

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

トップへ戻る