FrontPage  Index  Search  Changes  RSS  Login

GData/Protocol

日本語訳について

このページは, Google Data APIs (Beta) Developer's Guide - Google Data APIs Protocol を対訳形式で和訳したものです.厳密さより読みやすさを優先し,意訳を多用しています.ご了承ください.

翻訳作業はたけまるが行いました.翻訳には誤りがある可能性があり,内容について一切保証をするものではありません.正確さを求める場合には必ず原文を参照してください.当方は,この文書によって利用者が被るいかなる損害の責任を負いません.

Google Data APIs Protocol/Google データ API プロトコル

This document describes the protocol used by the Google data APIs ("GData"), including information about what a query looks like, what results look like, and so on.

本文書では,クエリや結果といった Google データ API ("GData") で用いられるプロトコルについて説明する.

For other information about the Google data APIs, see the Google Data APIs Overview document.

Google データ API に関するその他の情報については,Google データ API 概要 (GData/Overview) を参照のこと.

Audience/対象とする読者

This document is intended for anyone wanting to understand the details of the XML format and protocol used by the Google data APIs.

本文書は,Google データ API で用いられる XML フォーマットやプロトコルの詳細を理解したい読者を対象としている.

If you just want to write code that uses the GData client APIs, then you don't need to know these details; instead, see the links in the sidebar to documentation for the language-specific client libraries.

GData クライアントAPI を用いたコードを書きたいだけであれば,詳細を知る必要はない.代わりに,サイドバーにある言語別クライアントライブラリについての文書を参照されたい.

If you want to understand the protocol, read this document. For example, you may want to read this document to help you with any of the following tasks:

  • evaluating the GData architecture
  • coding using the protocol without using the provided GData libraries
  • writing a client library in a new language

プロトコルを理解したければ,本文書を読むべきである.例えば,以下のようなことをしたければ本文書が助けになる.

  • GData アーキテクチャの評価する
  • 提供されている GData ライブラリを用いないコードを書く
  • 他の言語でクライアントライブラリを書く

This document assumes that you understand the basics of XML, namespaces, syndicated feeds, and the GET, POST, PUT, and DELETE requests in HTTP, as well as HTTP's concept of a "resource." For more information about those things, see the Additional resources section of this document.

本文書を読むために必要なことは,XML や名前空間, シンジケーションフィードを理解し,HTTP の「リソース」という概念や GET/POST/PUT/DELETE リクエストを理解していることである.これらについては,本文書の参考文献 (GData/Protocol#l21) を参考にされたい.

This document doesn't rely on any particular programming language; you can send and receive GData messages using any programming language that lets you issue HTTP requests and parse XML-based responses.

本文書は特定のプログラミング言語に依存しない.HTTP リクエストを送信し,XML レスポンスを解析できれば,GData メッセージの送受信にどのようなプログラミング言語を用いてもよい.

Examples/例

The following examples show bare GData protocol requests you might send and the GData-formatted results you might receive. For examples of how to send the requests using Java and C#, see the language-specific client library links in the sidebar. For information about using GData with specific Google services, see the service-specific links in the sidebar.

以下では,生の GData プロトコルリクエストと,GData 形式の結果の例を示す.Java や C# を用いてリクエストを送信する例については,サイドバーの言語別クライアントライブラリへのリンクを参照されたい.Google のサービスにおける GData の利用については,サイドバーのサービス別文書へリンクを参照されたい.

Requesting a feed or other resource/フィードやその他のリソースに対する要求

Assume there's a feed called /myFeed, and assume that it currently doesn't happen to contain any entries. To see it, send the following request to the server:

ここでは /myFeed という空の (エントリのない) フィードがあると仮定する.そのフィードを得るために,サーバに対して次のようなリクエストを送信する.

GET /myFeed

The server responds:

サーバは次のように応答する.

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>

Note that although the feed doesn't contain any entries, it does contain metadata, such as a title and an author's name.

フィードにはエントリが含まれていないが,タイトルや著者名といったメタデータは含まれている.

Inserting a new entry/新エントリの挿入

To create a new entry, send a POST request, and supply a new entry in GData format:

新エントリを作成するために,POST リクエストで GData 形式のエントリを送信する.

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>

Note that you don't supply id, link, or updated elements; the server creates those in response to your POST request. Also note that the author of a feed doesn't have to be the same person as the author of an entry.

なお,id, link, updated 要素は不要である.サーバは,POST リクエストに応答してエントリリソースを作成する.フィードとエントリの著者は一致していなくてもよい.

The server responds:

サーバは次のように応答する.

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

Searching for a string/文字列の検索

To do a full-text search for a particular string, send a GET request with the q parameter. For more information about query parameters, see Query requests.

全文検索を行うために,q パラメータのある GET リクエストを送信する.クエリパラメータの詳細については,クエリリクエストの節 (GData/Protocol#l13) を参照されたい.

GET /myFeed?q=This

The server responds with all the entries that match the search string "This". (In this case there's only one.)

サーバは "This" という文字列を含むすべてのエントリを返す (この例ではひとつだけである).

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>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>

Updating an entry/エントリの更新

To update an existing entry, use PUT, using the entry's edit URI (as provided by the server in the previous example).

存在するエントリを更新するために,エントリの Edit URI (先の例でサーバが提供している) に対して PUT を送信する.

(If your firewall does not allow PUT, then do an HTTP POST and set the method override header as follows: X-HTTP-Method-Override: PUT)

(ファイアウォールが PUT を通さないようなら,"X-HTTP-Method-Override: PUT" のように上書きヘッダ (Override Header) をセットする)

In the following example, we're changing the entry's text from its old value ("This is my entry") to a new value ("This is my first entry."):

以下の例では,エントリの文章を "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>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>

The server responds:

サーバは次のように応答する.

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

Note that the edit URI has changed; it now ends with "/2/" instead of "/1/". The final number in the edit URI is a version number. For more information about versions, see the Optimistic concurrency section of this document.

Edit URI が変更され,"/1/" ではなく "/2/" で終わっている.Edit URI の最後の数字はバージョン番号である.バージョンについての詳細については,本文書の楽観的並行処理の節 (GData/Protocol#l17) を参照されたい.

To see the new entry in context, request the entire resource again:

続いて新エントリを得るために,再度エントリリソースを要求する.

GET /myFeed

The server responds:

サーバは次のように応答する.

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>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>

Deleting an entry/エントリの削除

To delete an existing entry, send a DELETE request, using the entry's edit URI (as provided by the server in the previous example).

存在するエントリを削除するために,エントリの Edit URI (先の例でサーバが提供している) に対して DELETE を送信する.

(If your firewall does not allow DELETE, then do an HTTP POST and set the method override header as follows: X-HTTP-Method-Override: DELETE.)

(ファイアウォールが DELETE を通さないようなら,"X-HTTP-Method-Override: DELETE" のように上書きヘッダ (Override Header) をセットする)

DELETE /myFeed/1/2/

The server responds:

サーバは次のように応答する.

200 OK

Do another GET to see that the feed now contains no entries:

空のフィードを得るために,続けて GET を送信する.

GET /myFeed

The server responds:

サーバは次のように応答する.

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>

If the deletion fails, then the server responds with an error code. For more information, see HTTP status codes, later in this document.

削除に失敗すると,サーバはエラーコードを伴ったレスポンスを返す.詳細については,本文書の後半にある HTTP ステータスコードを参照されたい.

Protocol details/プロトコル詳細

This section describes the GData document format and query syntax.

本節では,GData 文書形式とクエリ構文を説明する.

Document format/文書フォーマット

GData, Atom, and RSS 2.0 all share the same basic data model: a container that holds both some global data and any number of entries. For each protocol, the format is defined by a base schema, but it can be extended using foreign namespaces.

GData と Atom, RSS 2.0 は,同じデータモデルに基づいている.全体についてのデータと任意の数のエントリを格納するコンテナである.いずれのフォーマットでもベースとなるスキーマは定義されているが,外部名前空間による拡張が可能である.

GData can use either the Atom syndication format (for both reads and writes) or the RSS format (for reads only).

GData では,Atom シンジケーションフォーマット (読み書き可能) か RSS フォーマット (読みのみ) のいずれかを用いる.

Atom is GData's default format. To request a response in RSS format, use the /alt=rss/ parameter; for more information, see Query requests.

Atom は GData のデフォルトフォーマットである.RSS フォーマットを要求するためには,/alt=rss/ というパラメータを用いる.詳細はクエリリクエストの節 (GData/Protocol#l12) を参照されたい.

When you request data in RSS format, GData supplies a feed (or other representation of the resource) in RSS format. If there's no equivalent RSS property for a given GData property, GData uses the Atom property, labeling it with an appropriate namespace to indicate that it's an extension to RSS.

RSS フォーマットを要求すると,GData は RSS 形式のフィード (あるいは他のリソース表現) を返す.GData のプロパティに一致するものが RSS にないときは,RSS を拡張して Atom のプロパティを用いる.Atom のプロパティは,その名前空間を示すラベルで示される.

Note: Most GData feeds in Atom format use the Atom namespace as the default namespace by specifying an xmlns attribute on the feed element; see the examples section for examples of how to do that. Thus, the examples in this document don't explicitly specify atom: for elements in an Atom-format feed.

Atom 形式に基づくほとんどの GData フィードでは,feed 要素の xmlns 属性で Atom をデフォルトの名前空間に指定する.その方法については例 (GData/Protocol#l3) を参照されたい.本文書では,Atom 要素に atom: という接頭辞を付けない.

The following tables show the Atom and RSS representations of the elements of the schema. All data not mentioned in these tables is treated as plain XML and shows up the same in both representations. Unless indicated otherwise, the XML elements in a given column are in the namespace corresponding to that column. This summary uses standard XPath notation: in particular, slashes show the element hierarchy, and an @ sign indicates an attribute of an element.

下表は,スキーマ要素の Atom と RSS による表現を示す.どちらのフォーマットにおいても,表にないデータが現れたときはただの XML として扱う.特に明示されない限り,各要素はそれぞれの列に対応する名前空間に属している.表では XPath 記法を用いている.スラッシュは要素階層を表す.@ は属性を表す.

In each of the following tables, the highlighted items are required.

以下の表では,必須項目をハイライトで示す.

The following table shows the elements of a GData feed:

下表に GData のフィード要素を示す.

Feed Schema Item Atom Representation RSS Representation
Feed Title /feed/title /rss/channel/title
Feed ID /feed/id /rss/channel/atom:id
Feed HTML Link /feed/link[@rel="alternate"][@type="text/html"]/@href /rss/channel/link
Feed Description /feed/subtitle /rss/channel/description
Feed Language /feed/@xml:lang /rss/channel/language
Feed Copyright /feed/rights /rss/channel/copyright
Feed Author /feed/author/name /feed/author/email (Required in certain cases; see Atom specification.) /rss/channel/managingEditor
Feed Last Update Date /feed/updated (RFC 3339 format) /rss/channel/lastBuildDate (RFC 822 format)
Feed Category /feed/category/@term /rss/channel/category
Feed Category Scheme /feed/category/@scheme /rss/channel/category/@domain
Feed Generator /feed/generator /feed/generator/@uri /rss/channel/generator
Feed Icon /feed/icon /rss/channel/image/url (unless there's also a logo, in which case the icon isn't included in the feed)
Feed Logo /feed/logo /rss/channel/image/url
フィードスキーマ項目 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
著者 /feed/author/name /feed/author/email (必須になることもある.Atom 仕様書参照.) /rss/channel/managingEditor
最終更新日時 /feed/updated (RFC 3339 format) /rss/channel/lastBuildDate (RFC 822 format)
カテゴリ /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

The following table shows the elements of a GData search-results feed. Note that GData exposes some of the OpenSearch 1.1 Response elements in its search-results feeds.

下表に GData 検索結果フィードの要素を示す.なお,いくつかの OpenSearch 1.1 レスポンス要素が用いられている.

Search Result Feed Schema Item Atom Representation RSS/OpenSearch Representation
Number of Search Results /feed/openSearch:totalResults /rss/channel/openSearch:totalResults
Search Result Start Index /feed/openSearch:startIndex /rss/channel/openSearch:startIndex
Number of Search Results Per Page /feed/openSearch:itemsPerPage /rss/channel/openSearch:itemsPerPage
検索結果フィードスキーマ項目 Atom 表現 RSS/OpenSearch 表現
検索結果数 /feed/openSearch:totalResults /rss/channel/openSearch:totalResults
検索結果開始番号 /feed/openSearch:startIndex /rss/channel/openSearch:startIndex
ページあたりの検索結果数 /feed/openSearch:itemsPerPage /rss/channel/openSearch:itemsPerPage

The following table shows the elements of a GData entry:

下表に GData のエントリ要素を示す.

Entry Schema Item Atom Representation RSS Representation
Entry ID /feed/entry/id /rss/channel/item/guid
Entry Version ID Optionally embedded in EditURI (see the Optimistic concurrency section of this document). -
Entry Title /feed/entry/title /rss/channel/item/title
Entry Link /feed/entry/link /rss/channel/item/link /rss/channel/item/enclosure /rss/channel/item/comments
Entry Summary /feed/entry/summary (Required in certain cases; see Atom specification.) /rss/channel/item/atom:summary
Entry Content /feed/entry/content (If no content element, then entry must contain at least one <link rel="alternate"> element.) /rss/channel/item/description
Entry Author /feed/entry/author/name /feed/entry/author/email (Required in certain cases; see Atom specification.) /rss/channel/item/author
Entry Category /feed/entry/category/@term /rss/channel/item/category
Entry Category Scheme /feed/entry/category/@scheme /rss/channel/item/category/@domain
Entry Publication Date /feed/entry/published (RFC 3339) /rss/channel/item/pubDate (RFC 822)
Entry Update Date /feed/entry/updated (RFC 3339) /rss/channel/item/atom:updated (RFC 3339)
エントリスキーマ項目 Atom 表現 RSS 表現
ID /feed/entry/id /rss/channel/item/guid
バージョン ID Optionally embedded in EditURI (本文書の楽観的並行処理の節 (GData/Protocol#l17) を参照) -
タイトル /feed/entry/title /rss/channel/item/title
リンク /feed/entry/link /rss/channel/item/link /rss/channel/item/enclosure /rss/channel/item/comments
要約 /feed/entry/summary (必須になることもある.Atom 仕様書参照.) /rss/channel/item/atom:summary
内容 /feed/entry/content (この要素を持たないエントリは,一つ以上の <link rel="alternate"> 要素を持たなければならない.) /rss/channel/item/description
著者 /feed/entry/author/name /feed/entry/author/email (必須になることもある.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/クエリ

This section describes how to use the query system.

本節ではクエリシステムの使い方を説明する.

Query model design tenets/クエリモデルの設計原理

The query model is intentionally very simple. The basic tenets are:

  • Queries are expressed as HTTP URIs, rather than as HTTP headers or as part of the payload. One benefit of this approach is that you can link to a query.
  • Predicates are scoped to a single item. Thus, there's no way to send a correlation query such as "find all emails from people who sent me at least 10 emails today."
  • The set of properties that queries can predicate on is very limited; most queries are simply full text search queries.
  • Result ordering is up to the implementation.
  • The protocol is naturally extensible. If you want to expose additional predicates or sorting in your service, you can do so easily through the introduction of new parameters.

クエリモデルは意図的にシンプルにしてある.基本原理は,

  • クエリは,HTTP ヘッダやペイロードの一部ではなく,HTTP URI として表される.このアプローチの利点は,クエリにリンクできることである.
  • 単一の問い合わせに限られる.よって,"今日,私に10通のメールを送った人物からの全メール" といった複合クエリを送ることはできない.
  • 問い合わせられる属性はとても限られる.ほとんどのクエリは単純な全文検索である.
  • 結果の順序は実装による.
  • このプロトコルは拡張できる.追加の問い合わせや並べ替えを提供したければ,新しいパラメータを導入することで簡単に実現できる.

Query requests/クエリリクエスト

A client queries a GData service by issuing an HTTP GET request. The query URI consists of the resource's URI (called FeedURI in Atom) followed by query parameters. Most query parameters are represented as traditional ?name=value[&...] URL parameters. Category parameters are handled differently; see below.

クライアントは,HTTP GET リクエストを発行して GData サービスに問い合わせを行う.クエリ URI では,リソースの URI (Atom FeedURI) の後にクエリパラメータが続く.ほとんどのクエリパラメータは,伝統的な ?name=value[&...] という URL パラメータ形式で表される.カテゴリパラメータには違う形式が使われる (後述).

For example, if the FeedURI is http://www.example.com/feeds/jo, then you might send a query with the following URI:

たとえば,FeedURI が http://www.example.com/feeds/jo であれば,次のURI でクエリを送信する.

http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00

GData services support HTTP Conditional GET. They set the Last-Modified response header based upon the value of the <atom:updated> element in the returned feed or entry. A client can send this value back as the value of the If-Modified-Since request header to avoid retrieving the content again if it hasn't changed. If the content hasn't changed since the If-Modified-Since time, then the GData service returns a 304 (Not Modified) HTTP response.

GData サービスは HTTP 条件付き GET に対応している.GData サービスは,返答するフィードやエントリの <atom:updated> 要素の値に基づいて,Last-Modified レスポンスヘッダを設定する.変更される前に再取得することを避けるために,クライアントは Last-Modified の値を If-Modified-Since リクエストヘッダに設定することができる.If-Modified-Since の値以降に変更されていなければ,GData サービスは 304 (Not Modified) HTTP レスポンスを返す.

A GData service must support category queries and alt queries; support for other parameters is optional. Passing a standard parameter not understood by a given service results in a 403 Forbidden response. Passing an unsupported nonstandard parameter results in a 400 Bad Request response. For information on other status codes, see the HTTP status codes section of this document.

GData サービスはカテゴリクエリと alt クエリをサポートしなければならない.その他のパラメータは任意である.GData 標準ではあるが処理できないパラメータがあるときは,403 Forbidden を返す.非標準かつ処理できないパラメータには 400 Bad Request を返す.その他のステータスコードについては,本文書の HTTP ステータスコードの節 (GData/Protocol#l16) を参照のこと.

The standard query parameters are summarized in the following table. All parameter values need to be URL encoded.

下表に GData 標準クエリパラメータをまとめる.すべてのパラメータは URL エンコードされる必要がある.

Parameter Meaning Notes
q Full-text query string When creating a query, list search terms separated by spaces, in the form q=term1 term2 term3. (As with all of the query parameter values, the spaces must be URL encoded.) The GData service returns all entries that match all of the search terms (like using AND between terms). Like Google's web search, a GData service searches on complete words (and related words with the same stem), not substrings.
To search for an exact phrase, enclose the phrase in quotation marks: q="exact phrase".
To exclude entries that match a given term, use the form q=-term.
The search is case-insensitive.
Example: to search for all entries that contain the exact phrase "Elizabeth Bennet" and the word "Darcy" but don't contain the word "Austen", use the following query: ?q="Elizabeth Bennet" Darcy -Austen
/category Category filter List each category as if it were part of the resource's URI, in the form /categoryname/・this is an exception to the usual name=value form.
List all categories before any other query parameters.
Precede the first category with /-/ to make clear that it's a category. For example, if Jo's feed has a category for entries about Fritz, you could request those entries like this: http://www.example.com/feeds/jo/-/Fritz. This allows the implementation to distinguish category-predicated query URIs from resource URIs.
You can query on multiple categories by listing multiple category parameters, separated by slashes. The GData service returns all entries that match all of the categories (like using AND between terms). For example: http://www.example.com/feeds/jo/-/Fritz/Laurie returns entries that match both categories.
To do an OR between terms, use a pipe character (|), URL-encoded as %7C. For example: http://www.example.com/feeds/jo/-/Fritz%7CLaurie returns entries that match either category.
An entry matches a specified category if the entry is in a category that has a matching term or label, as defined in the Atom specification. (Roughly, the "term" is the internal string used by the software to identify the category, while the "label" is the human-readable string presented to a user in a user interface.)
To exclude entries that match a given category, use the form /-categoryname/.
To query for a category that has a scheme・such as <category scheme="urn:google.com" term="public"/>・you must place the scheme in curly braces before the category name. For example: /{urn:google.com}public. To match a category that has no scheme, use an empty pair of curly braces. If you don't specify curly braces, then categories in any scheme will match.
The above features can be combined. For example: /A%7C-{urn:google.com}B/-C means (A OR (NOT B)) AND (NOT C).
author Entry author The service returns entries where the author name and/or email address match your query string.
alt Alternative representation type If you don't specify an alt parameter, the service returns an Atom feed. This is equivalent to alt=atom.
alt=rss returns an RSS 2.0 result feed.
updated-min, updated-max Bounds on the entry update date Use the RFC 3339 timestamp format. For example: 2005-08-09T10:57:00-08:00.
The lower bound is inclusive, whereas the upper bound is exclusive.
published-min, published-max Bounds on the entry publication date Use the RFC 3339 timestamp format. For example: 2005-08-09T10:57:00-08:00.
The lower bound is inclusive, whereas the upper bound is exclusive.
start-index 1-based index of the first result to be retrieved Note that this isn't a general cursoring mechanism. If you first send a query with ?start-index=1&max-results=10 and then send another query with ?start-index=11&max-results=10, the service cannot guarantee that the results are equivalent to ?start-index=1&max-results=20, because insertions and deletions could have taken place in between the two queries.
max-results Maximum number of results to be retrieved For any service that has a default max-results value (to limit default feed size), you can specify a very large number if you want to receive the entire feed.
entryID ID of a specific entry to be retrieved If you specify an entry ID, you can't specify any other parameters.
The form of the entry ID is determined by the GData service.
Unlike most of the other query parameters, entry ID is specified as part of the URI, not as a name=value pair.
Example: http://www.example.com/feeds/jo/entry1.
パラメータ 意味 説明
q 全文検索文字列 クエリを生成するときには,q=term1 term2 term3 のように検索語をスペースで区切って列挙する (すべてのクエリパラメータ値がそうであるように,スペースを URL エンコードしなければならない).GData サービスは検索語に合致するエントリをすべて返す (AND 検索).Google のウェブ検索のように,GData サービスは部分文字列ではなく単語 (と関連語) に対して検索を行う.
フレーズ検索を行うためには,q="exact phrase" のように引用区で囲う.
検索語に一致するエントリを除外するには,q=-term のようにする.
大文字小文字を区別しない.
例: "Elizabeth Bennet" というフレーズと "Carcy" という言葉を含み,"Austen" という言葉を含まないエントリを検索するには,次のようなクエリを用いる.?q="Elizabeth Bennet" Darcy -Austen
/category Category filter リソース URI の一部のように,各カテゴリを /カテゴリ名/ という形式で列挙する.これは,通常の 名前=値 という形式から外れる.
カテゴリはクエリパラメータより前に列挙する.
カテゴリであることを明確にするために,ひとつめのカテゴリの前には /-/ を置く.たとえば,Jo のフィードに Fritz についてのエントリがあるとすれば,次のようにしてそのエントリを要求できる.http://www.example.com/feeds/jo/-/Fritz. このようにして,GDataの実装は,カテゴリを問い合わせる URI とリソース URI を区別する.
スラッシュで区切れば,複数のカテゴリを問い合わせることができる.GData サービスはカテゴリに合致するエントリをすべて返す (AND 検索).たとえば,http://www.example.com/feeds/jo/-/Fritz/Laurie であれば,両方のカテゴリに合致するエントリを返す.
OR 検索を行うときは,パイプ (|) を URL エンコードした %7C を用いる.たとえば,http://www.example.com/feeds/jo/-/Fritz%7CLaurie であれば,いずれかのカテゴリに合致するエントリを返す.
Atom 仕様で定義されているように,カテゴリの言葉 (term) かラベルが合致すると,そのエントリは合致していると言える.(大雑把に言うと,"言葉 (term)" とはソフトウェアがカテゴリの識別に用いる内部的な文字列であり,"ラベル (label)" とは人間が読むための形式で表された文字列である).
あるカテゴリに合致するエントリを除外するには,/-カテゴリ名/ のようにする.
<category scheme="urn:google.com" term="public"/> のようにスキームを伴ってカテゴリを指定するときには,スキームを波括弧で括って,カテゴリ名の前に置く.たとえば,/{urn:google.com}public のようにする.スキームを伴わないカテゴリに合致させるには,空の波括弧を用いる.波括弧がなければ,あらゆるスキームのカテゴリに合致する.
以上の検索方法は組み合わせて使うことができる.たとえば,/A%7C-{urn:google.com}B/-C というクエリは (A OR (NOT B)) AND (NOT C) という意味である.
author エントリの著者 GData サービスによって,著者名か電子メールアドレスがクエリ文字列に合致するエントリが返される.
alt 代替表現 alt パラメータをしてしなければ,GData サービスは Atom フィードを返す.これは,alt=atom を指定したことと同じである.
alt=rss であれば RSS 2.0 フィードを返す.
updated-min, updated-max エントリ更新日時の範囲 RFC 3339 に記載のフォーマットを用いる.たとえば,2005-08-09T10:57:00-08:00 である.
下限はその値を含み,上限は含まない.
published-min, published-max エントリ発行日時の範囲 RFC 3339 に記載のフォーマットを用いる.たとえば,2005-08-09T10:57:00-08:00 である.
下限はその値を含み,上限は含まない.
start-index 取得した結果のうち,ひとつめの結果の通し番号 (1から数える) この位置指定方法は常に機能するわけではない.まず最初に ?start-index=1&max-results=10 というクエリを送信し,続いて ?start-index=11&max-results=10 というクエリを送ったとしても, GData サービスが ?start-index=1&max-results=20 と同じ結果を返すとは限らない.これは,ふたつのクエリの間に,追加や削除が行われる可能性があるためである.
max-results 取得する結果の最大数 GData サービスには,この値のデフォルト値が設定されている (デフォルトのフィードサイズを制限するため).フィード全体を取得したいときは,大きな値を指定しておく.
entryID 取得するエントリの ID エントリ ID を指定するならば,他のパラメータは不要である.
エントリ ID の形式は,各 GData サービスによる.
他のほとんどのパラメータと異なり,名前=値 という形式ではなく,URI の一部として指定する.
たとえば,http://www.example.com/feeds/jo/entry1 である.

About category queries/カテゴリクエリについて

We decided to specify a slightly unusual format for category queries. Instead of a query like the following:

カテゴリクエリにはやや異なるフォーマットを採用した.以下のようなクエリの代わりに,

http://example.com/jo?category=Fritz&category=2006

we use:

次のようなクエリを用いる.

http://example.com/jo/-/Fritz/2006

This approach identifies a resource without using query parameters, and it produces cleaner URIs. We chose this approach for categories because we think that category queries will be the most common queries.

このアプローチではリソースの識別にクエリパラメータを用いないため,キレイな URI となる.もっともよく使われると考え,カテゴリクエリにこのアプローチを採用した.

The drawback to this approach is that we require you to use /-/ in category queries, so that GData services can distinguish category queries from other resource URIs, such as http://example.com/jo/MyPost/comments.

このアプローチの欠点は,カテゴリクエリに /-/ を含めなければならない点である.これにより GData サービスは,http://example.com/jo/MyPost/comments といった他のリソース URI とカテゴリクエリを区別する.

Query responses/クエリレスポンス

Queries return an Atom feed, an Atom entry, or an RSS feed, depending on the request parameters.

クエリを送信すると,リクエストパラメータによって,Atom フィード, Atom エントリ, RSS フィードのいずれかが返される.

Query results contain the following OpenSearch elements directly under the feed or channel element (depending on whether results are Atom or RSS):

クエリ結果では,feed あるいは channel 要素に次の OpenSearch 要素が格納される (要素名は Atom か RSS かによる).

  • openSearch:totalResults
    • The total number of search results for the query (not necessarily all present in the results feed).
    • クエリに対する検索結果数 (フィードに表れる結果数とは限らない).
  • openSearch:startIndex
    • The 1-based index of the first result.
    • ひとつめの結果の通し番号 (1から数える)
  • openSearch:itemsPerPage
    • The maximum number of items that appear on one page. This allows clients to generate direct links to any set of subsequent pages. However, for a possible pitfall in using this number, see the note regarding start-index in the table in the Query requests section.
    • ページあたりの最大項目数.これにより,クライアントは残りの結果に対して直リンクをはることができる.この数値を用いるときの留意点については,クエリリクエストの節 (GData/Protocol#l13) の start-index を参照のこと.

The Atom response feed and entries may also include any of the following Atom and GData elements (as well as others listed in the Atom specification):

Atom フィードとエントリは,(Atom 仕様にある要素に加えて) 以下の Atom と GData の要素を持つ.

  • <link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>
    • Specifies the URI where the complete Atom feed can be retrieved.
    • 上の link 要素は,Atom フィード全体を取得できる URI を示す.
  • <link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>
    • Specifies the Atom feed's PostURI (where new entries can be posted).
    • 上の link 要素は,Atom フィードの POST URI を示す (新しいエントリを送信する).
  • <link rel="self" type="..." href="..."/>
    • Contains the URI of this resource. The value of the type attribute depends on the requested format. If no data changes in the interim, sending another GET to this URI returns the same response.
    • 上の link 要素は,そのリソース自身の URI を示す.type 属性の値はリクエストしたフォーマットによって変わる.データが変更される前にこの URI に対して再度 GET を行えば,同じレスポンスが返る.
  • <link rel="previous" type="application/atom+xml" href="..."/>
    • Specifies the URI of the previous chunk of this query result set, if it is chunked.
    • 上の link 要素は,クエリ結果が分割されているときに,ひとつ前の URI を示す.
  • <link rel="next" type="application/atom+xml" href="..."/>
    • Specifies the URI of the next chunk of this query result set, if it is chunked.
    • 上の link 要素は,クエリ結果が分割されているときに,次の URI を示す.
  • <link rel="edit" type="application/atom+xml" href="..."/>
    • Specifies the Atom entry's EditURI (where you send an updated entry).
    • 上の link 要素は,Atom エントリの Edit URI を示す (更新したエントリを送信する).

Here's a sample response body, in response to a search query:

以下は,検索クエリに対するレスポンスボディの例である.

<?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>

If the requested feed is in the Atom format, if no query parameters are specified, and if the result doesn't contain all the entries, the following element is inserted into the top-level feed: <link rel="next" type="application/atom+xml" href="..."/>. It points to a feed containing the next set of entries. Subsequent sets contain a corresponding <link rel="previous" type="application/atom+xml" href="..."/> element. By following all the next links, a client can retrieve all entries from a feed.

Atom フォーマットをリクエストし,クエリパラメータを指定せず,結果にすべてのエントリが含まれていないときは,feed 要素には次の要素がなければならない <link rel="next" type="application/atom+xml" href="..."/>.この URL は,結果の続きを含むフィードを示す.後続の結果には,対応する要素 <link rel="previous" type="application/atom+xml" href="..."/> が含まれる.この next というリンクを順に辿っていくことで,クライアントはすべての結果を得ることができる.

HTTP status codes/HTTP ステータスコード

The following table describes what various HTTP status codes mean in the context of GData.

下表は GData における HTTP ステータスコードの意味である.

Code Explanation
200 OK No error.
201 CREATED Creation of a resource was successful.
304 NOT MODIFIED The resource hasn't changed since the time specified in the request's If-Modified-Since header.
400 BAD REQUEST Invalid request URI or header, or unsupported nonstandard parameter.
401 UNAUTHORIZED Authorization required.
403 FORBIDDEN Unsupported standard parameter, or authentication or authorization failed.
404 NOT FOUND Resource (such as a feed or entry) not found.
409 CONFLICT Specified version number doesn't match resource's latest version number.
500 INTERNAL SERVER ERROR Internal error. This is the default code that is used for all unrecognized errors.
コード 説明
200 OK エラーなし.
201 CREATED リソースの作成に成功した.
304 NOT MODIFIED リクエストの If-Modified-Since ヘッダで指定された日時以降,リソースは変更されていない.
400 BAD REQUEST リクエストの URI やヘッダが不正である,あるいはサポートしていない非標準パラメータが用いられている.
401 UNAUTHORIZED 認証が必要.
403 FORBIDDEN サポートしていない標準パラメータが用いられているか,認証・認可に失敗した.
404 NOT FOUND (フィードやエントリなどの) リソースが見つからない.
409 CONFLICT 指定されたバージョン番号が,リソースの最新バージョンに一致しない.
500 INTERNAL SERVER ERROR 内部エラー.認識できないすべてのエラーに用いられる.

Optimistic concurrency (versioning)/楽観的並行処理 (バージョン管理)

Sometimes it is important to ensure that multiple clients don't inadvertently overwrite one another's changes. This is most easily accomplished by ensuring that the current version of an entry that a client is modifying is the same as the version that the client is basing its modifications on. If a second client makes an update before the first client does, then the first client's update is denied, because the first client is no longer basing its modifications on the latest version.

あるクライアントが行った変更を,他のクライアントが気付かずに上書きするのを回避することは,ときに重要である.エントリの現バージョンと,クライアントが変更を加えたバージョンが同じであることを確認すれば,簡単にチェックすることができる.最初のクライアントがエントリを更新する前に,2番目のクライアントが更新すると,最初のクライアントの更新は拒否される.最初のクライアントは最新ではないバージョンに対して変更を行ったためである.

In GData feeds that support versioning, we achieve these semantics by appending a version ID to each entry's EditURI. Note that only the EditURI is affected, not the entry ID. In this scheme, each update changes the entry's EditURI, thus guaranteeing that subsequent updates based on the original version fail. Deletes, of course, are identical to updates with respect to this feature; if you send a delete with an old version number, the delete fails.

バージョン管理されている GData フィードでは,エントリの EditURI にバージョン ID を追加することで,上述の上書き問題を回避する.なお,これによって影響を受けるのは EditURI のみであり,エントリ ID には影響がない.この方法により,更新を行うたびにエントリの EditURI が変わるため,前のバージョンに対する変更はできなくなる.もちろん,削除も更新と同じである.古いバージョンに対して削除を行うことはできない.

Not all GData feeds support optimistic concurrency. In a feed that does support it, if the server detects a version conflict on PUT or DELETE, the server responds with 409 Conflict. The body of the response contains the current state of the entry (an Atom entry document). The client is advised to resolve the conflict and resubmit the request, using the EditURI from the 409 response.

すべての GData フィードが楽観的並行処理に対応しているわけではない.対応しているフィードでは,サーバが PUT や DELETE に対してバージョンの衝突を検出すると,サーバは 409 Conflict を返す.レスポンスボディには,現状のエントリ (Atom エントリ文書) が含まれる.クライアントは 409 レスポンスに書かれた EditURI を用いて,衝突を解決してから,リクエストを再送する.

Motivation and design notes/動機とデザインについて

This approach to optimistic concurrency allows us to implement the semantics we want without requiring new markup for version IDs, which makes GData's responses compatible with non-GData Atom endpoints.

この楽観的並行処理に対するアプローチは,新しいマークアップやバージョン ID なしに所望の機能を実装することができる.GData に対応していない Atom エンドポイントと互換性がある.

Instead of specifying version IDs, we could have chosen to look at the update timestamp on each entry (/atom:entry/atom:updated). However, there are two problems with using the update timestamp:

  • It only works for updates and not deletions.
  • It forces applications to use date/time values as version IDs, which would make it harder to retrofit GData on top of many existing data stores.

バージョン ID を指定する代わりに,エントリの更新タイムスタンプをチェックすることもできる (/atom:entry/atom:updated).しかし,更新タイムスタンプを用いるとふたつの問題がある.

  • 更新には使えるが,削除には使えない.
  • バージョン ID として日時を使わせると,既存データストアに GData を追加実装することが難しくなる.

Authentication/認証

When a client tries to access a service, it may need to provide the user's credentials to the service, to demonstrate that the user has the authority to perform the action in question.

クライアントが GData サービスにアクセスを試みるときには,ユーザの認証情報を送信し,そのアクションを実行する権限を持っていることを示さなければならない.

The approach that a client should use for authentication depends on the type of client:

  • A desktop application should use a Google-specific authentication system called Authentication for Installed Applications (also known as "ClientLogin"). (Web-based clients should not use this system.)
  • A web-based client, such as a third-party front end to a GData service, should use a Google-specific authentication system called Account Authentication Proxy for Web-Based Applications (also known as "AuthSub").

クライアントの種類によって,用いるべき認証アプローチは異なる.

  • デスクトップアプリケーションは,"Authentication for Installed Applications (ClientLogin としても知られる)" と呼ばれる Google 特有の認証システムを用いるべきである.(ウェブクライアントはこのシステムを用いるべきではない)
  • Google 以外が提供する GData サービスに対するフロントエンドのようなウェブクライアントでは,"Account Authentication Proxy for Web-Based Applications (AuthSub としても知られる)" と呼ばれる Google 特有の認証システムを用いるべきである.

In the ClientLogin system, the desktop client asks the user for their credentials, and then sends those credentials to the Google authentication system.

ClientLogin システムでは,デスクトップクライアントがユーザに認証情報を尋ね,Google 認証システムに送信する.

If authentication succeeds, then the authentication system returns a token that the client subsequently uses (in an HTTP Authorization header) when it sends GData requests.

認証に成功すると,認証システムはトークンを返す.以降,クライアントがGData リクエストを送信するときには,HTTP 認証ヘッダにこのトークンを設定する.

If authentication fails, then the server returns a 403 Forbidden status code, along with a WWW-Authenticate header containing a challenge applicable to the authentication.

認証に失敗すると,サーバは認証用のチャレンジを設定した WWW-Authenticate ヘッダとともに,403 Forbidden ステータスコードを返す.

The AuthSub system works similarly, except that instead of asking the user for their credentials, it connects the user to a Google service that requests credentials. The service then returns a token that the web application can use; the advantage of this approach is that Google (rather than the web front end) securely handles and stores the user's credentials.

AuthSub システムも同様に動作する.ただし,ユーザに認証情報を尋ねるのではなく,ユーザを Google に接続し,そこで認証情報を入力させる.Google はウェブアプリケーションが利用するトークンを返す.このアプローチの利点は,ウェブフロントエンドではなく Google のみがユーザの認証情報を扱う点にある.

For details about these authentication systems, see the Google Account Authentication documentation.

認証システムの詳細は Google アカウント認証文書を参照のこと.

Session state/セッション状態

Many business logic implementations require session stickiness - keeping track of the state of a user's session.

多くのビジネスロジックではセッションの継続性 (ユーザのセッション状態を管理し続けること) が求められる.

Google tracks session state in two ways: using cookies, and using a token that can be sent as a query parameter. Both methods achieve the same effect. We recommend that clients support one of these session-state tracking methods (either one is sufficient). If a client doesn't support either of these methods, then that client will still work with GData services, but performance may suffer compared to clients that do support these methods. Specifically, if a client doesn't support these methods, then every request results in a redirect, and therefore every request (and any associated data) is sent to the server twice, which affects the performance of both the client and the server.

Google はセッション状態をふたつの方法で管理する.ひとつは Cookie であり,もうひとつはクエリパラメータとして送られるトークンである.どちらの方法も同じように機能する.Google としては,クライアントがどちらかのセッション状態管理方法に対応することを推奨する (どちらかひとつで十分である).クライアントがどちらの方法にも対応していなくても,GData サービスを受けることはできる.しかし,対応している場合に比べて,パフォーマンスが低下することがある.非対応クライアントが送るリクエストはかならず転送される,つまり,リクエストと付随するデータがサーバに2回送信されることになり,クライアントとサーバのパフォーマンスに影響を与える.

The Google client libraries handle session state for you, so if you use our libraries, you don't have to do anything to get session state support.

Google クライアントライブラリはセッション状態を管理する.ライブラリを使えば,セッション状態に関してなにもする必要がない.

Additional resources/参考文献

You may find the following third-party documents useful:

Google 以外が提供する有用な文書を紹介する.

  • Comparison of Atom and RSS from intertwingly
  • Overview of Atom from IBM
  • Dublin Core extensions to RSS
  • HTTP 1.1 method definitions; specification for GET, POST, PUT, and DELETE
  • HTTP 1.1 status code definitions
  • How to Create a REST Protocol
  • Building Web Services the REST Way
  • A Technical Introduction to XML
  • XML Namespaces by Example
Last modified:2014/10/31 11:24:06
Keyword(s):
References:[GData/CommonElements] [GData/Protocol] [GData/Overview]