このドキュメントでは、クエリの概要や表示内容など、Google Data API で使用されるプロトコルについて説明します。
Google Data API について詳しくは、Google Data デベロッパー ガイドとプロトコル ガイドをご覧ください。
対象者
このドキュメントは、Google Data API で使用される XML 形式とプロトコルの詳細を理解したい方を対象としています。
Google Data クライアント API を使用するだけのコードを作成する場合は、これらの詳細を知る必要はありません。言語固有のクライアント ライブラリを使用できます。
ただし、プロトコルの詳細については、こちらのドキュメントをご覧ください。たとえば、次の作業についてこのドキュメントをお読みください。
- Google のデータ アーキテクチャの評価
- 提供された Google データ クライアント ライブラリを使用せずにプロトコルでコーディングする
- 新しい言語でクライアント ライブラリを記述する
このドキュメントは、HTTP における XML、名前空間、シンジケート フィード、GET、POST、PUT、DELETE リクエストの基礎と、HTTP の「リソース」の概念を理解していることを前提としています。これらの要素について詳しくは、このドキュメントのその他のリソースをご覧ください。
このドキュメントでは、特定のプログラミング言語に依存していません。HTTP リクエストの送信や XML ベースのレスポンスの解析が可能な任意のプログラミング言語を使用して、Google データ メッセージの送受信が可能です。
プロトコルの詳細
このセクションでは、Google データ ドキュメントの形式とクエリ構文について説明します。
ドキュメントの形式
Google Data、Atom、RSS 2.0 はすべて同じ基本データモデル（一部のグローバル データと任意の数のエントリを保持するコンテナ）を共有します。形式はプロトコルごとにベーススキーマによって定義されますが、外部名前空間を使用して拡張することもできます。
Google Data API では、Atom シンジケーション形式（読み取りと書き込みの両方）または RSS 形式（読み取りのみ）を使用できます。
Atom は Google データのデフォルト形式です。RSS 形式のレスポンスをリクエストするには、/alt=rss/ パラメータを使用します。詳細については、クエリ リクエストをご覧ください。
RSS 形式のデータをリクエストすると、Google データは RSS 形式のフィード（またはその他のリソースの表現）を提供します。特定の Google データ プロパティに相当する RSS プロパティがない場合、Google Data は 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 |
| エントリの内容 |
（コンテンツ要素がない場合、エントリには少なくとも 1 つの |
/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） |
Queries
このセクションでは、クエリシステムの使用方法について説明します。
クエリモデルの設計原則
クエリモデルは意図的に非常にシンプルです。基本原則は次のとおりです。
- クエリは、HTTP ヘッダーやペイロードの一部としてではなく、HTTP URI として表現されます。この方法のメリットの一つは、クエリにリンクできる点です。
- 述語のスコープは単一のアイテムです。したがって、「今日少なくとも 10 件のメールを送信した人からのメールをすべて見つける」などの相関クエリを送信することはできません。
- クエリで述語できるプロパティのセットは非常に限られています。ほとんどのクエリは単純に全文検索クエリです。
- 結果の順序は実装によって異なります。
- プロトコルは必然的に拡張可能です。サービスで追加の述語や並べ替えを公開する場合は、新しいパラメータを導入することで簡単に行うことができます。
クエリ リクエスト
クライアントは、HTTP GET リクエストを発行して Google Data サービスにクエリを実行します。クエリ 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 Data サービスは、HTTP の条件付き GET をサポートしています。返されたフィードまたはエントリの <atom:updated> 要素の値に基づいて、Last-Modified レスポンス ヘッダーを設定します。クライアントは、この値が変更されない場合に、コンテンツを再度取得しないように、If-Modified-Since リクエスト ヘッダーの値としてこの値を返すことができます。Google データサービスは、If-Modified-それ以降
Google データサービスでは、カテゴリクエリと alt クエリをサポートする必要があります。他のパラメータのサポートは任意です。あるサービスで認識されない標準パラメータを渡すと、403 Forbidden レスポンスが返されます。サポートされていない標準以外のパラメータを渡すと、400 Bad Request レスポンスが返されます。その他のステータス コードについては、このドキュメントの HTTP ステータス コードのセクションをご覧ください。
次の表に、標準のクエリ パラメータの概要を示します。パラメータの値はすべて URL エンコードする必要があります。
| パラメータ | 意味 | 備考 |
|---|---|---|
q |
クエリ文字列の全文 |
|
/-/category |
カテゴリ フィルタ |
|
category |
カテゴリ フィルタ |
|
author |
エントリの作成者 |
|
alt |
代替表現タイプ | |
updated-min、updated-max |
エントリの更新日の境界 |
|
published-min、published-max |
エントリ公開日の境界 |
|
start-index |
最初に取得する結果の 1 から始まるインデックス |
|
max-results |
取得する結果の最大数 | デフォルトの max-results 値を持つサービス（デフォルトのフィードサイズを制限するため）にフィード全体を受け取る場合は、非常に大きな値を指定できます。 |
| entryID | 取得する特定のエントリの ID |
|
カテゴリに関するクエリについて
カテゴリ クエリにはやや異常な形式を指定することにしました。次のようなクエリの代わりに、
http://example.com/jo?category=Fritz&category=2006
使用:
http://example.com/jo/-/Fritz/2006
この方法では、クエリ パラメータを使用せずにリソースを識別し、よりクリーンな URI を生成します。Google では、カテゴリクエリが最も一般的なクエリであると思われるため、このカテゴリを使用することにしました。
このアプローチの欠点は、Google Data サービスがカテゴリクエリを他のリソース URI（http://example.com/jo/MyPost/comments など）と区別できるように、カテゴリクエリで /-/ を使用する必要があることです。
クエリのレスポンス
クエリは、リクエスト パラメータに応じて Atom フィード、Atom エントリ、RSS フィードを返します。
クエリ結果には、以下の OpenSearch 要素が <feed> 要素または <channel> 要素の直下に含まれています（結果が Atom か RSS かによって異なります）。
openSearch:totalResults- 検索クエリの検索結果の合計数（検索結果フィードにすべてが表示されるわけではありません）。
openSearch:startIndex- 最初の結果の 1 から始まるインデックス。
openSearch:itemsPerPage- 1 つのページに表示される最大アイテム数。これにより、クライアントはそれ以降の任意のページへの直接リンクを生成できます。ただし、この数を使用する際に生じる可能性がある注意点については、クエリ リクエストの表の表にある
start-indexに関する注意事項をご覧ください。
Atom レスポンス フィードとエントリには、次のいずれかの Atom 要素と Google Data 要素を含めることもできます（この仕様には 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 チャンクの 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="..."/> 要素が含まれています。すべての next リンクをたどることで、クライアントはフィードからすべてのエントリを取得できます。
HTTP ステータス コード
次の表に、Google データサービスにおける HTTP ステータス コードの意味を示します。
| コード | 解説 |
|---|---|
| 200 OK | エラーはありません。 |
| 201 作成済み | リソースを作成しました。 |
| 304 未修正 | リソースが、If-Modified-After リクエストのヘッダーに指定された時刻から変更されていない。 |
| 400 件の不正なリクエスト | リクエスト URI またはヘッダーが無効であるか、サポートされていない標準以外のパラメータです。 |
| 401 不正 | 承認が必要です。 |
| 403 FORBIDDEN（未承認） | サポートされていない標準パラメータ、または認証または認可に失敗しました。 |
| 404 見つかりません | リソース（フィードやエントリなど）が見つかりません。 |
| 409 競合 | 指定されたバージョン番号がリソースの最新のバージョン番号と一致しません。 |
| 500 INTERNAL SERVER ERROR（内部サーバーエラー） | 内部エラーが発生しました。これは、認識できないすべてのエラーに使用されるデフォルトのコードです。 |
オプティミスティック同時実行（バージョニング）
複数のクライアントによる変更が誤って上書きされないようにするため、重要な場合があります。これは、クライアントが変更しているエントリの現在のバージョンが、その変更のベースとなっているバージョンと同じであることを確認することによって、簡単に実現できます。2 つ目のクライアントが更新を行う前に 1 つ目のクライアントによって更新が行われると、最初のクライアントでは更新がベースとされなくなるため、更新は拒否されます。
バージョニングをサポートする Google データフィードでは、各エントリの EditURI にバージョン ID を付加することで、これらのセマンティクスを実現します。EditURI のみが影響を受け、エントリ ID は影響を受けないことに注意してください。このスキームでは、更新のたびにエントリの EditURI が変更されるため、元のバージョンに基づく更新は失敗します。削除は、もちろんこの機能に関する更新と同じです。古いバージョン番号で削除を送信すると、削除は失敗します。
すべての Google データフィードがオプティミスティック同時実行をサポートしているわけではありません。これをサポートするフィードで、サーバーが PUT または DELETE のバージョンの競合を検出した場合、サーバーは 409 Conflict を返します。レスポンスの本文にはエントリの現在の状態（Atom エントリのドキュメント）が含まれます。409 レスポンスの EditURI を使用して、競合を解決してリクエストを再送信するようクライアントにアドバイスします。
モチベーションとデザインに関するメモ
オプティミスティック同時実行に対するこのアプローチにより、バージョン ID の新しいマークアップを必要とせずに、必要なセマンティクスを実装できます。これにより、Google データのレスポンスが Google Data Atom 以外のエンドポイントと互換性を持つようになります。
バージョン ID を指定する代わりに、各エントリの更新タイムスタンプ（/atom:entry/atom:updated）を参照できます。ただし、更新タイムスタンプの使用には次の 2 つの問題があります。
- この方法は更新でのみ機能します。削除では機能しません。
- アプリケーションが日付/時刻の値をバージョン ID として使用することを余儀なくされるため、多くの既存のデータストアに Google データを組み込むことが難しくなります。
認証
クライアントがサービスにアクセスしようとすると、ユーザーがそのアクションを実行する権限を持っていることを示すために、サービスに対してユーザーの認証情報を提供する必要が生じる場合があります。
クライアントが認証に使用する方法は、クライアントの種類によって異なります。
- デスクトップ アプリケーションでは、インストール型アプリケーションに対するアカウント認証（別名「gclid」）という Google 固有の認証システムを使用する必要があります。（ウェブベースのクライアントはこのシステムを使用しないでください）。
- ウェブベースのクライアント（Google データ サービスへのサードパーティのフロントエンドなど）は、ウェブベースのアプリケーション用のアカウント認証プロキシ（「AuthSub」とも呼ばれます）と呼ばれる Google 固有の認証システムを使用する必要があります。
OpenSSL システムで、デスクトップ クライアントはユーザーに認証情報を求め、その認証情報を Google 認証システムに送信します。
認証が成功した場合、認証システムは Google Data のリクエストの送信時にクライアントが HTTP 認証ヘッダーで使用するトークンを返します。
認証に失敗すると、サーバーは 403 Forbidden ステータス コードと、認証に適用されるチャレンジを含む WWW-Authenticate ヘッダーを返します。
AuthSub システムも同じように動作しますが、ユーザーに認証情報を尋ねるのではなく、認証情報を要求する Google サービスにユーザーを接続します。次に、ウェブ アプリケーションで使用可能なトークンを返します。この方法の利点は、（ウェブ フロントエンドではなく）Google がユーザーの認証情報を安全に処理して保存することです。
これらの認証システムについて詳しくは、Google データ認証の概要または Google アカウント認証のドキュメントをご覧ください。
セッション状態
多くのビジネス ロジックの実装では、セッション持続性（ユーザーのセッション状態の追跡）が必要です。
Google は 2 つの方法でセッション状態をトラッキングします。1 つは Cookie を使用する方法、もう 1 つはクエリ パラメータとして送信可能なトークンを使用する方法です。どちらの方法でも効果は同じです。クライアントでは、これらのセッション状態のトラッキング方法のいずれかを使用することをおすすめします（どちらか一方でも十分）。どちらの方法もサポートしていないクライアントでも Google データサービスは利用できますが、サポートしているクライアントと比較してパフォーマンスが低下する可能性があります。具体的には、クライアントがこれらのメソッドをサポートしていない場合、すべてのリクエストはリダイレクトされるため、すべてのリクエスト（および関連するデータ）はサーバーに 2 回送信されます。これは、クライアントとサーバーの両方のパフォーマンスに影響します。
Google のクライアント ライブラリはセッションの状態を処理します。そのため、Google のライブラリを使用する場合は、セッション状態のサポートを利用するために何もする必要はありません。
参考情報
次のサードパーティ ドキュメントが役立つ場合があります。
- Atom と RSS の相互比較
- IBM の Atom の概要
- RSS の Dublin Core 拡張機能
- HTTP 1.1 のメソッド定義。
GET、POST、PUT、DELETEの仕様です。 - HTTP 1.1 ステータス コードの定義
- REST プロトコルの作成方法
- REST 方式のウェブサービスの構築
- XML の技術的な概要
- サンプル XML 名前空間