プロトコル リファレンス

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

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

Google Data Protocol の詳細については、デベロッパー ガイドの概要ページとプロトコルの基本に関するドキュメントをご覧ください。

対象者

このドキュメントは、Google Data Protocol を実装する API で使用される XML 形式とプロトコルの詳細を理解したい方を対象としています。

これらの API のいずれかを使用するだけのコードを作成する場合は、これらの詳細を知る必要はありません。言語固有のクライアント ライブラリを使用できます。

ただし、プロトコルの詳細については、こちらのドキュメントをご覧ください。たとえば、次の作業についてこのドキュメントをお読みください。

• Google Data Protocol アーキテクチャの評価
• 提供されたクライアント ライブラリを使用しないプロトコルを使用したコーディング
• 新しい言語でクライアント ライブラリを記述する

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

このドキュメントでは、特定のプログラミング言語に依存していません。HTTP リクエストの送信と XML ベースのレスポンスの解析が可能な任意のプログラミング言語を使用して、Google Data Protocol のメッセージを送受信できます。

プロトコルの詳細

このセクションでは、Google Data Protocol のドキュメント形式とクエリ構文について説明します。

ドキュメントの形式

Google Data Protocol と Atom は同じ基本データモデル（グローバル データと任意の数のエントリの両方を保持するコンテナ）を共有しています。形式はプロトコルごとにベーススキーマによって定義されますが、外部名前空間を使用して拡張することもできます。

Atom は Google Data Protocol のデフォルトの形式です。別の形式のレスポンスをリクエストするには、alt クエリ パラメータを使用します。詳細については、クエリ リクエストをご覧ください。

注: Atom 形式のほとんどの Google Data Protocol フィードでは、フィード要素に xmlns 属性を指定することで Atom 名前空間をデフォルトの名前空間として使用します（プロトコルの基本の例を参照）。したがって、このドキュメントの例では、Atom 形式のフィードの要素に atom: を明示的に指定していません。

次の表に、スキーマの要素の Atom 表現を示します。これらの表に記載されていないデータはすべて、プレーン XML として扱われます。特に明記しない限り、特定の列の XML 要素は Atom 名前空間にあります。

注: この概要では、標準の XPath 表記を使用します。特に、スラッシュは要素階層を示し、@ 記号は要素の属性を示します。

次の表では、ハイライト表示された項目は必須です。

次の表に、Google Data Protocol フィードの要素を示します。

フィード スキーマ アイテム	Atom 表現
フィードのタイトル	/feed/title
フィード ID	/feed/id
フィード HTML リンク	/feed/link[@rel="alternate"]\ [@type="text/html"]/@href
フィードの説明	/feed/subtitle
フィードの言語	/feed/@xml:lang
フィードの著作権	/feed/rights
フィードの作成者	/feed/author/name /feed/author/email （特定のケースでは必須。Atom の仕様を参照）。
フィードの最終更新日	/feed/updated （RFC 3339 形式）
フィード カテゴリ	/feed/category/@term
フィード カテゴリ スキーム	/feed/category/@scheme
フィード生成ツール	/feed/generator /feed/generator/@uri
フィード アイコン	/feed/icon
フィードのロゴ	/feed/logo

次の表に、Google Data Protocol の検索結果フィードの要素を示します。なお、このプロトコルでは、検索結果フィードで OpenSearch 1.1 レスポンス要素の一部が公開されています。

検索結果フィードのスキーマ アイテム	Atom 表現
検索結果数	/feed/openSearch:totalResults
検索結果の開始インデックス	/feed/openSearch:startIndex
ページあたりの検索結果数	/feed/openSearch:itemsPerPage

次の表に、Google Data Protocol エントリの要素を示します。

エントリ スキーマ アイテム	Atom 表現
エントリ ID	/feed/entry/id
エントリのタイトル	/feed/entry/title
エントリ リンク	/feed/entry/link
エントリの概要	/feed/entry/summary （特定のケースでは必須。Atom の仕様を参照）。
エントリの内容	/feed/entry/content （コンテンツ要素がない場合、エントリには少なくとも 1 つの <link rel="alternate"> 要素が含まれている必要があります）。
エントリの作成者	/feed/entry/author/name /feed/entry/author/email （特定のケースでは必須。Atom の仕様を参照）。
エントリー カテゴリ	/feed/entry/category/@term
応募カテゴリ スキーム	/feed/entry/category/@scheme
応募公開日	/feed/entry/published （RFC 3339）
入力更新日	/feed/entry/updated （RFC 3339）

Queries

このセクションでは、クエリシステムの使用方法について説明します。

クエリモデルの設計原則

クエリモデルは意図的に非常にシンプルです。基本原則は次のとおりです。

• クエリは、HTTP ヘッダーやペイロードの一部としてではなく、HTTP URI として表現されます。この方法のメリットの一つは、クエリにリンクできる点です。
• 述語のスコープは単一のアイテムです。したがって、「今日少なくとも 10 件のメールを送信した人からのメールをすべて見つける」などの相関クエリを送信することはできません。
• クエリで述語できるプロパティのセットは非常に限られています。ほとんどのクエリは単純に全文検索クエリです。
• 結果の順序は実装によって異なります。
• プロトコルは必然的に拡張可能です。サービスで追加の述語や並べ替えを公開する場合は、新しいパラメータを導入することで簡単に行うことができます。

クエリ リクエスト

クライアントは HTTP GET リクエストを発行して Google サービスにクエリを実行します。クエリ 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 Protocol は、HTTP の条件付き GET をサポートしています。プロトコルを実装する API は、返されたフィードまたはエントリの <atom:updated> 要素の値に基づいて、Last-Modified レスポンス ヘッダーを設定します。クライアントは、この値が変更されない場合に、コンテンツを再度取得しないように、If-Modified-Since リクエスト ヘッダーの値としてこの値を返すことができます。If-Modified-Since 以降にコンテンツが変更されていない場合、サービスは 304（Not Modified）HTTP レスポンスを返します。

Google Data Protocol を実装する API は、alt クエリをサポートする必要があります。他のパラメータのサポートは任意です。あるサービスで認識されない標準パラメータを渡すと、403 Forbidden レスポンスが返されます。サポートされていない標準以外のパラメータを渡すと、400 Bad Request レスポンスが返されます。その他のステータス コードについては、このドキュメントの HTTP ステータス コードのセクションをご覧ください。

次の表に、標準のクエリ パラメータの概要を示します。パラメータの値はすべて URL エンコードする必要があります。

パラメータ	意味	備考
alt	代替表現タイプ	alt パラメータを指定しない場合、サービスは Atom フィードを返します。alt=atom と同じです。 alt=rss は、RSS 2.0 の結果フィードを返します（読み取り専用）。RSS 形式のサービスにデータをリクエストすると、サービスによって RSS 形式のフィード（またはその他のリソースの表現）が提供されます。特定の Data API プロパティに対応する RSS プロパティがない場合、サービスは Atom プロパティを使用して、適切な名前空間でラベル付けし、RSS の延長であることを示します。 alt=json は、フィードの JSON 表現を返します。詳細 alt=json-in-script: スクリプトタグに JSON をラップするレスポンスをリクエストします。詳細 alt=atom-in-script スクリプトタグに XML 文字列をラップする Atom レスポンスをリクエストします。 alt=rss-in-script: スクリプトタグで XML 文字列をラップする RSS レスポンスをリクエストします。 alt=atom-service: フィードを説明する Atom サービス ドキュメントをリクエストします。
author	エントリの作成者	このサービスでは、作成者名やメールアドレスがクエリ文字列と一致しているエントリが返されます。
category	カテゴリクエリのフィルタ	カテゴリ フィルタを使用する別の方法です。2 つのメソッドは同等です。 キーワードの間に OR を付けるには、%7C としてエンコードされたパイプ文字（|）を使用します。たとえば、http://www.example.com/feeds?category=Fritz%7CLaurie は、いずれかのカテゴリに一致するエントリを返します。 キーワードの間に AND を含めるには、カンマ（,）を使用します。たとえば、http://www.example.com/feeds?category=Fritz,Laurie は両方のカテゴリに一致するエントリを返します。
/-/category	カテゴリクエリのフィルタ	リソースの URI の一部であるかのように、各カテゴリを一覧表示します。これは通常の name=value 形式の例外です。 他のクエリ パラメータよりも前にすべてのカテゴリを一覧表示します。 最初のカテゴリの前に /-/ を付けて、カテゴリであるかどうかを確認します。たとえば、木田さんのフィードに Fritz に関するカテゴリがある場合は、http://www.example.com/feeds/jo/-/Fritz のようにリクエストできます。これにより、実装でカテゴリで予測されたクエリ URI とリソース URI を区別できます。 複数のカテゴリを取得するには、複数のカテゴリ パラメータをスラッシュで区切って指定します。このサービスは、すべてのカテゴリに一致するエントリを返します（キーワードの間に AND を使用するなど）。たとえば、http://www.example.com/feeds/jo/-/Fritz/Laurie は両方のカテゴリに一致するエントリを返します。 キーワードの間に OR を付けるには、URL エンコードされた %7C というパイプ文字（|）を使用します。たとえば、http://www.example.com/feeds/jo/-/Fritz%7CLaurie は、いずれかのカテゴリに一致するエントリを返します。 Atom 仕様で定義されているように、一致する語句またはラベルを持つカテゴリのエントリの場合は、指定したカテゴリと一致します。（大まかに言うと、「用語」はカテゴリを識別するためにソフトウェアが使用する内部文字列で、「ラベル」はユーザー インターフェースに表示される人間可読文字列です）。 特定のカテゴリに一致するエントリを除外するには、/-categoryname/ の形式を使用します。 スキームを持つカテゴリ（<category scheme="urn:google.com" term="public"/> など）をクエリするには、スキームをカテゴリ名の前に中かっこで囲む必要があります。例: /{urn:google.com}public。スキームにスラッシュ文字（/）が含まれている場合は、%2F として URL エンコードする必要があります。スキームのないカテゴリと一致させるには、空の中かっこを使用します。中かっこを指定しない場合、すべてのスキームでカテゴリが一致します。 上記の機能は組み合わせることができます。たとえば、/A%7C-{urn:google.com}B/-C は (A OR (NOT B)) AND (NOT C) を意味します。
entryID	取得する特定のエントリの ID	エントリ ID を指定した場合、他のパラメータは指定できません。 エントリ ID の形式はサービスによって決まります。 他のほとんどのクエリ パラメータとは異なり、エントリ ID は name=value のペアとしてではなく、URI の一部として指定します。 （例: http://www.example.com/feeds/jo/entry1）。
fields	レスポンス フィルタ	完全なリソース表現ではなく、リクエストされたフィールドのみを返します。次に例を示します。 http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit'])) サーバーはこのリクエストを受信すると、フィードのリンク要素とエントリ要素のみを含むレスポンスを返します。また、返されるエントリ要素は、ETag、ID、更新、編集リンクの関係のみを含む部分的なエントリになります。 すべてのクエリ パラメータ値と同様に、フィールドの値は URL エンコードする必要があります。 詳細については、部分レスポンス セクションをご覧ください。 現在このパラメータは試験運用版です。
max-results	取得する結果の最大数	デフォルトの max-results 値を持つサービス（デフォルトのフィードサイズを制限するため）にフィード全体を受け取る場合は、非常に大きな値を指定できます。
prettyprint	ID と改行を含む XML レスポンスを返す	prettyprint=true の場合、サーバーから返される XML は人が読める形式になります（出力されます）。 デフォルト: prettyprint=false
published-min、published-max	エントリ公開日の境界	RFC 3339 のタイムスタンプ形式を使用します。例: 2005-08-09T10:57:00-08:00。 下限は含まれますが、上限は含まれません。
q	クエリ文字列の全文	クエリを作成する際は、q=term1 term2 term3 の形式で検索語句をスペースで区切ります。（すべてのクエリ パラメータ値と同様に、スペースは URL エンコードする必要があります）。このサービスは、すべての検索キーワードに一致するすべてのエントリを返します（キーワード間に AND を使用するなど）。Google のウェブ検索と同様に、サービスは部分文字列ではなく、完全な単語（および同じ要素を含む関連単語）で検索します。 完全に一致する語句を検索するには、q="exact phrase". のように引用符で囲みます 特定の語句に一致するエントリを除外するには、q=-term の形式を使用します。 検索で大文字と小文字は区別されません。 例: 「Elizabeth Bennet」という単語と「Darcy」という単語を含むが、「Austen」という単語を含まないすべてのエントリを検索するには、次のクエリを使用します。?q="Elizabeth Bennet" Darcy -Austen
start-index	最初に取得する結果の 1 から始まるインデックス	なお、これは一般的なカーソル移動メカニズムではありません。最初に ?start-index=1&max-results=10 でクエリを送信し、次に ?start-index=11&max-results=10 で別のクエリを送信した場合、2 つのクエリの間に挿入と削除を行う可能性があるため、サービスは ?start-index=1&max-results=20 と同等の結果を保証できません。
strict	厳格なクエリ パラメータのチェック	strict=true を設定して、各クエリ パラメータがサービスによって認識されることを確認します。パラメータが認識されない場合はエラーが返されます。 デフォルト: strict=false
updated-min、updated-max	エントリの更新日の境界	RFC 3339 のタイムスタンプ形式を使用します。例: 2005-08-09T10:57:00-08:00。 下限は含まれますが、上限は含まれません。 場合によっては（Calendar Data API の v2.1 以降を使用しているときなど）、過去に遠すぎる updated-min を指定すると、HTTP 410（Gone）ステータスが返されることがあります。

カテゴリに関するクエリについて

カテゴリ クエリにはやや珍しい形式を適用することにしました。次のようなクエリを要求するのではなく、

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

そのおかげで、

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

この方法では、クエリ パラメータを使用せずにリソースを識別し、よりクリーンな URI を生成します。Google では、カテゴリのクエリが最も一般的なクエリになると考えられるため、このアプローチをカテゴリに選びました。

このアプローチの欠点は、サービスがカテゴリクエリを他のリソース 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 要素と Data API 要素を含めることもできます（この仕様には 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="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <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 gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'>
    <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 gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'>
    <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 ステータス コード

次の表に、Data API のコンテキストにおけるさまざまな HTTP ステータス コードの意味を示します。

コード	解説
200 OK	エラーはありません。
201 作成済み	リソースを作成しました。
304 未修正	リソースが、If-Modified-After リクエストのヘッダーに指定された時刻から変更されていない。
400 件の不正なリクエスト	リクエスト URI またはヘッダーが無効であるか、サポートされていない標準以外のパラメータです。
401 不正	承認が必要です。
403 FORBIDDEN（未承認）	サポートされていない標準パラメータ、または認証または認可に失敗しました。
404 見つかりません	リソース（フィードやエントリなど）が見つかりません。
409 競合	指定されたバージョン番号がリソースの最新のバージョン番号と一致しません。
410 存在しません	リクエストされた変更履歴はサーバー上で利用できなくなりました。詳細については、サービス固有のドキュメントをご覧ください。
500 INTERNAL SERVER ERROR（内部サーバーエラー）	内部エラーが発生しました。これは、認識できないすべてのサーバーエラーに使用されるデフォルトのコードです。

リソースのバージョニング（ETag）

場合によっては、特定のエントリの特定のバージョンを参照できるようにする必要があります。

これは特に 2 つのケースで重要です。

• 「条件付き取得」を行い、クライアントがエントリをリクエストし、クライアントが最後にリクエストした後にエントリが変更された場合にのみ、サーバーからエントリを送信する。
• 複数のクライアントによって、変更内容が意図せず上書きされないようにするため。Data API では、クライアントが古いバージョン識別子のエントリを指定している場合、更新と削除が失敗します。

Google Data API は、HTTP の標準部分である ETag を使用して、この両方のケースを処理します。

ETag は、特定のエントリの特定のバージョンを指定する識別子です。サーバーは、クライアントに送信するエントリ要素とフィード要素に ETag を添付します。エントリまたはフィードが変更されると、その ETag も変更されます。

Google Data API では ETag を、ETag HTTP ヘッダーと、<feed> 要素と <entry> 要素の gd:etag 属性という 2 つの場所で提供します。

Google Data API では通常、ETag は英字と数字の文字列で、ハイフンやピリオドが含まれることもあります。通常、文字列は引用符で囲みます。（引用符は ETag の一部です）。たとえば、Data API エントリの ETag は "S0wCTlpIIip7ImA0X0QI" です。

ETag には「強く」と「弱」の 2 種類があります。強力な ETag は、特定のエントリの特定のバージョンを識別するもので、他のクライアントによる変更の上書きを回避するために使用できます。Google Data API のコンテキストにおける弱い ETag は、条件付きの取得にのみ使用されます。弱い ETag は常に W/ で始まります。例: W/"D08FQn8-eil7ImA9WxZbFEw."

すべての Google Data API が強力な ETag をサポートしているわけではありません。その場合、強力な ETag はエントリにのみ使用されます。フィードの ETag は常に弱いものです。

強力な ETag をサポートするサービスから取得したフィードの例を次に示します（HTTP ヘッダーの一部を含む）。

GData-Version: 2.0
ETag: W/"C0QBRXcycSp7ImA9WxRVFUk."
...
<?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."'>
  ...
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    ...
  </entry>
</feed>

Data API のバージョン 2 をサポートするクライアント ライブラリでは、ETag が透過的に処理されます。次の情報は、クライアント ライブラリを使用しないクライアント、およびプロトコル レベルでのバージョニング方法に関心がある方を対象としています。

注: バージョン 1.0 の Data API で使用されているリソース バージョニング システムについては、1.0 リファレンス ガイドをご覧ください。

条件付き取得

取得済みのエントリを後で取得する場合、エントリの前回の取得以降にエントリが変更された場合にのみサーバーに送信するようサーバーに指示することで、効率を改善できます。

このような条件付き取得を行うには、HTTP If-None-Match ヘッダーを含む HTTP GET リクエストを送信します。ヘッダーでエントリの ETag を指定します。

If-None-Match ヘッダーの例を次に示します。

If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."

サーバーはこのリクエストを受け取ると、リクエストしたエントリの ETag が指定した ETag と同じかどうかがチェックされます。ETag が一致する場合、エントリは変更されておらず、HTTP 304 Not Modified ステータス コードが返されます。

ETag が一致しない場合、エントリを最後にリクエストした後にエントリが変更され、サーバーからエントリが返されます。

エントリの更新

別のクライアントの変更内容を上書きする最も簡単な方法は、クライアントが更新したエントリを送信したときに、クライアントが開始したエントリのバージョンが、サーバーに保存されている現在のバージョンと同じになるようにすることです。2 番目のクライアントが更新を行う前に更新を行うと、そのクライアントは更新をベースとしていないため、クライアントの更新は拒否されます。

クライアントが強力な ETag をサポートするサービスからデータを取得する場合、各エントリには、そのエントリの一意のバージョン識別子として機能する ETag があります。

注: ETag を使った更新は、強力な ETag を使用している場合にのみ機能します。弱い ETag を提供するサービスの場合、他のユーザーがエントリを取得してから更新したかどうかにかかわらず、すべての更新が成功します。以前の更新は、常に最新の更新で上書きされます。そのため、更新や削除の際に脆弱な ETag を送信しないでください。送信しようとすると、エラー メッセージが表示されます。

そのため、クライアントが ETag サービスに更新を送信する際は、更新するエントリのバージョンを指定する必要があります。これを行うには 2 つの方法があります。

• If-Match HTTP ヘッダーを使用します。
• <atom:entry> 要素で gd:etag 属性を使用します。

可能な場合は、If-Match アプローチをおすすめします。

If-Match を使用してエントリを更新するには、更新するエントリを取得することから始めましょう。エントリに必要な変更を加え、変更されたエントリを含む新しい PUT リクエストを作成します。（使用する URL について詳しくは、サービス固有のドキュメントをご覧ください）。

PUT を送信する前に、元のエントリの ETag を含む HTTP If-Match ヘッダーを追加します。

If-Match: "S0wCTlpIIip7ImA0X0QI"

次に、PUT リクエストを送信します。

更新が成功すると、サーバーは HTTP 200 OK ステータス コードと更新されたエントリのコピーを返します。

指定した ETag がエントリの現在の ETag と一致しないために更新に失敗した場合（つまり、最後にエントリを取得した後にエントリがサーバーで変更された場合）、HTTP ステータス コード 412 Precondition Failed が返されます。

HTTP ヘッダーを簡単に記述できない場合や、If-Match ヘッダーの使用を避ける理由がある場合は、代わりに gd:etag 属性を使用できます。

If-Match ヘッダーを送信しない場合、サーバーは更新されたエントリの gd:etag 属性値を暗黙の If-Match 値として使用します。

バージョニング システムをオーバーライドし、他のユーザーが取得後にそのエントリを更新したかどうかに関係なくエントリを更新するには、ヘッダーに ETag を指定する代わりに、If-Match: * を使用します。

強力な ETag をサポートしているサービスについては、移行ガイドをご覧ください。

エントリの削除

強力な ETag を使用するエントリを削除する方法は、更新する場合とほぼ同じです。

強力な ETag を持つエントリを削除するには、まず削除するエントリを取得してから、そのエントリの編集 URL に DELETE リクエストを送信します。

取得後に別のクライアントによって変更されたエントリを削除しないようにする場合は、元のエントリの ETag 値を含む HTTP If-Match ヘッダーを含めます。

バージョニング システムをオーバーライドし、他のユーザーがエントリを取得した後にそのエントリを更新したかどうかにかかわらず、そのエントリを削除する場合は、ヘッダーで ETag を指定する代わりに、If-Match: * を使用します。

エントリに強力な ETag がない場合、DELETE リクエストは常に成功します。

部分レスポンス（試験運用版）

デフォルトでは、サーバーはリクエストを処理した後、ターゲット リソース全体を返します。部分レスポンスでは、完全なリソース表現ではなく、関心のある要素や属性のみをリクエストできます。これにより、クライアント アプリケーションで不要なフィールドの転送、解析、保存が行われなくなるため、ネットワーク、CPU、メモリのリソースをより効率的に使用できます。

使用しているプロダクトで部分レスポンスが利用可能かどうかを確認するには、API ドキュメントをご覧ください。

部分レスポンスをリクエストするには、fields クエリ パラメータを使用して、返したい要素または属性を指定します。次に例を示します。

http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))

サーバーのレスポンスには、フィードのリンク要素とエントリ要素のみが含まれます。エントリ要素には、ETag、ID、更新、編集のリンク情報のみが含まれます。fields クエリ パラメータの構文については、以降のセクションで説明します。レスポンスの詳細については、部分レスポンスの処理をご覧ください。

注: データを返す任意のリクエストで fields クエリ パラメータを使用できます。GET に加えて、POST、PUT（および部分更新を行うために使用される PATCH）が含まれます。ただし、fields クエリ パラメータは、レスポンス データにのみ影響します。指定する必要があるデータ、更新または作成されるフィールドには影響しません。

fields パラメータの構文のまとめ

fields クエリ パラメータ値の形式は XPath 構文に基づいていますが、有効な XPath 式のサブセットのみがサポートされています。サポートされている構文を以下にまとめます。その後のセクションで追加の例を挙げて説明します。

• 複数のフィールドを選択する場合は、カンマ区切りのリストを使用する。
• a/b を使用して、要素 a 内にネストされている要素 b を選択します。a/b/c を使用して、b 内にネストされている要素 c を選択します。
• '@' 接頭辞を使用して、指定した名前の属性を識別します。要素を参照する場合は、'@' 接頭辞を省略します。
• 特定の条件と一致する要素を選択するには、制限する要素の後にかっこ「[ ]」を追加して式を置き、フィールド条件を適用します。

  たとえば、fields=entry[author/name='Elizabeth'] は、エリザベスが著者であるフィード エントリのみを返します。

• 特定の属性またはサブ要素のみをリクエストするフィールド サブセレクタを指定するには、選択した要素の後ろに「( )」という式を入れます。

  たとえば、fields=entry(id,author/email) は、各フィード エントリの ID と投稿者のメールアドレスのみを返します。

• 文字列は、二重引用符または単一引用符 で区切ることができます。
  
  二重引用符または単一引用符をエスケープするには、 のように引用符を繰り返します。たとえば、"""Hello,"" he said" は文字列 "Hello," he said を生成し、'''Hello,'' he said' は文字列 'Hello,' he said を生成します。
• フィールドの選択ではワイルドカードを使用できます。

  たとえば、entry/gd:* は gd 名前空間のすべてのエントリの子要素を選択し、entry/@gd:* は同じ名前空間の子要素属性を選択します。

fields クエリ パラメータは出力フィルタとして機能します。つまり、部分レスポンスは、クエリの残りの部分の処理後にのみ計算されます。たとえば、1 ページあたり 20 件の結果が必要なことを示す max-results クエリ パラメータも指定した場合、最初の 20 件の結果が生成され、そこから部分レスポンスが計算されます。fields 仕様がクエリで選択された最初の 20 個のエントリのいずれにも一致しない場合は、空のフィードが返されます。最初の 20 個の一致エントリは返されません。

注: フィールド条件をクエリセレクタとして使用しないでください。つまり、完全なフィードを取得してフィールド条件を適用し、巨大なデータセットから対象のアイテムを除外しないでください。可能であれば、start-index や max-results などのクエリ パラメータを使用して、各クエリの結果を適切なサイズに制限してください。そうしないと、部分レスポンスによるパフォーマンスの向上が、不適切な使用による重大なパフォーマンスの低下よりも重大になる可能性があります。

fields パラメータ値の形式

次のガイドラインでは、fields クエリ パラメータ値の構成方法について説明します。各ガイドラインには例が示され、パラメータ値がレスポンスに与える影響の説明が記載されています。

注: 他のすべてのクエリ パラメータの値と同じように、fields パラメータ値には URL エンコードを使用する必要があります。読みやすくするために、以下の例ではエンコードを省略しています。

返して欲しいフィールドを特定する（フィールド選択を行う）

fields クエリ パラメータ値は要素または属性のカンマ区切りのリスト（総称して「フィールド」）であり、各フィールドは、リソース表現のルート要素を基準にして指定します。したがって、フィードを取得する場合、フィールドは <feed> 要素を基準に指定し、単一のエントリを取得する場合は、フィールドは <entry> 要素を基準に指定します。選択した要素がフィード内の繰り返し要素である場合（またはその要素の一部である場合）、このサービスはその要素のすべてのインスタンスを返します。

フィードレベルの例を以下に示します。

例	効果
entry	<entry> 要素とそのエントリのすべてのサブ要素を返しますが、<feed> の他の子要素は返しません。
id,entry	フィード <id> とすべての <entry> 要素の両方を返します。
entry/title	すべてのフィード エントリの <title> 要素を返します。 ネストされた要素が返される場合、レスポンスには の親要素を含むタグが含まれます。他の子要素または属性を含める場合は、その子タグも明示的に選択する必要があります。
entry/author/uri	すべてのフィード エントリについて、<author> 要素の <uri> サブ要素のみを返します。
entry/*:rating	すべてのフィード エントリについて、名前空間内でローカル名 rating を持つサブ要素のみを返します。

エントリレベルの例を以下に示します。

例	効果
author	ターゲット エントリの <author> 子要素を返します。
@gd:etag	ターゲット エントリの etag 属性を返します。
author/uri	ターゲット エントリの <author> 要素の <uri> サブ要素を返します。
media:group/media:*	ターゲット エントリの media 名前空間にある <media:group> のすべてのサブフィールドを返します。

特定の条件に一致する選択項目のみにレスポンスを制限するか、フィールド条件を使用します。

デフォルトでは、リクエストで複数回発生する要素が指定されている場合、部分レスポンスにはその要素のすべてのインスタンスが含まれます。以下の例に示すように、レスポンスに特定の属性値を持つ要素のみ、「[ ]」構文を使用した他の条件を満たす要素のみを含めるように指定することもできます。詳しくは、フィールド条件の構文をご覧ください。

例	効果
entry[link/@rel='edit']	rel 属性の値が 'edit' の <link> 要素を含むフィード エントリを返します。
entry/title[text()='Today']	コンテンツが 'Today' の場合、フィード エントリ内のすべての <title> 要素を返します。
entry/author[name='Jo']	フィード エントリ内のすべての <author> 要素（コンテンツ 'Jo' を含む <name> サブ要素がある場合）を返します。
author[name='Jo']	コンテンツ 'Jo' を持つ <name> サブ要素がある場合、ターゲット エントリの <author> 要素を返します。

選択した要素の一部のみをリクエストするか、フィールドのサブ選択を使用します。

デフォルトでは、リクエストで特定の要素が指定されている場合、サービスはその要素全体を返します。選択した要素内の特定のサブ要素のみを含めるように指定できます。それには、下の例のように「( )」というサブ選択の構文を使用します。

例	効果
entry/author(uri)	フィード エントリの作成者の <uri> サブ要素のみを返します。
entry/author[name='Jo'](uri)	作成者名が 'Jo' のエントリに対しては、<author> の <uri> サブ要素のみを返します。
entry(link(@rel,@href))	フィード エントリ内の各 <link> 要素の rel 属性と href 属性の値のみを返します。
entry(title,link[@rel='edit'])	各フィード エントリの rel 属性を編集した <title> 要素と <link> 要素のみを返します。
entry(title,author(uri)	フィード エントリごとに <title> 要素と作成者 <uri> 要素の両方を返します。

フィールド条件の構文の詳細

フィールド条件は、フィールドまたはサブフィールドで使用できます。選択したフィールドが結果に含まれるには、条件が true と評価される必要があります。フィールド条件がない場合は、選択したタイプのすべてのフィールドが含まれます。

選択したフィールドのテキスト値が比較に使用されます。ここで、フィールドが要素の場合はテキスト値が内容であり、フィールドが属性の場合はテキスト値が属性の値です。フィールドにテキスト値がない場合、比較は失敗し、フィールドは結果に含まれません。

フィールド条件でサポートされている XPath 演算子と演算子の例を次の表に示します。

演算子	構文	例
文字列の比較	=、eq !=、ne	属性 rel が「self'」に設定された <link> 要素が含まれている場合、エントリ全体を返します。     entry[link/@rel='self'] コンテンツが文字列 'unknown' と等しい <title> 要素を含むエントリ全体を返します。     entry[title eq 'unknown'] コンテンツが 'unknown' でない場合は、<title> 要素全体を返します。     title[text() != 'unknown']
論理比較	and or not	属性 rel が 'self' または 'edit' に設定されているリンクを返します。     link[@rel='self' or @rel='edit'] 属性 rel が 'self' に、属性 type が 'application/atom+xml' に設定されているリンクを返します。     link[@rel='self' and @type='application/atom+xml'] 値 'self' を持つ属性 rel のないリンクを返します。     link[not(@rel='self')] XPath と同様に、not は関数呼び出しのように見えることに注意してください。
数値比較	= または eq != または ne > または gt >= または ge < または lt <= または le	整数 5 に変換可能な value 属性を持つ <gd:rating> 要素を返します。     gd:rating[@value=5] 4.3 より大きい浮動小数点数に変換可能な average 属性を持つ <gd:rating> 要素を返します。     gd:rating[@average gt 4.3]
期間の比較	例に示すように、数値比較演算子を使用します。	日付または日時を比較するには、要素、属性、または文字列リテラルを xs:date または xs:dateTime にキャストします。xs:dateTime の場合、デフォルトのタイムゾーンは UTC ですが、タイムゾーンを明示的に指定することをおすすめします。 2005 年 1 月 1 日以降の日付を含む <yt:recorded> 要素を返します。     yt:recorded[xs:date(text())>=xs:date('2005-01-01')] UTC タイムゾーンで指定された日時より後に更新されたエントリを返します。     entry[xs:dateTime(updated)>xs:dateTime('2008-07-25T08:19:37.549Z')]
存在	例に示すように、要素または属性の名前を使用します。	属性 rel を持つリンクを含むエントリを返します。     entry[link/@rel] value という属性を持つすべての <gd:rating> 要素を返します。     entry/gd:rating[@value]
ブール値	true() false()	テストでブール値を使用すると、フィールドの条件を強制的に true または false の状態にできます。 任意の <link> 要素を返します。     link[true()]

部分レスポンスの処理

部分レスポンスをサポートするサーバーは、fields クエリ パラメータを含む有効なリクエストを処理した後、リクエストされた属性または要素とともに HTTP 200 OK ステータス コードを返します。fields クエリ パラメータにエラーがある場合、またはパラメータが無効な場合、サーバーは HTTP 400 Bad Request ステータス コードを返します。

レスポンスのルート要素は、ターゲット URI に応じて <feed> または <entry> です。ルート要素のコンテンツには、そのフィードまたはエントリで選択したフィールドと、親要素のタグが含まれます。

リクエストの fields クエリ パラメータの値は、次の 2 つの方法でエコーバックできます。

• ルート要素に、リクエストで指定された fields クエリ パラメータの値を示す gd:fields 属性があります。
• ターゲット URI がフィードの場合は、編集可能な各エントリに gd:fields 属性があり、適用される fields 選択部分が表示されます。

注: これらの gd:fields 属性値を部分レスポンスで表示するには、fields クエリ パラメータの仕様に含める必要があります。明示的に指定するには、@gd:fields を使用するか、ETag 情報を含む一般的な @gd:* を使用します。

次のクエリは、gd 名前空間（フィードレベルとエントリレベルの両方）の属性と、フィード ID、タイトル、各フィード エントリの編集リンクを含むドキュメントを返すようサーバーに要求しています。

http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])

サーバーは、200 Successful HTTP ステータス コードとともに次の部分レスポンスを返します。

<?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/"DEAEQH47eCp7IWA9WxBVGUo."'
    gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
  <id>http://example.com/myFeed</id>
  <entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <title>This year</title>
  </entry>
  <entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/2/'/>
    <title>Last year</title>
  </entry>
  <entry d:etag='"EksPQAxHeCp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/3/'/>
    <title>Today</title>
  </entry>
</feed>

選択したフィールドが一致しない場合、サービスは 200 Successful HTTP ステータス コードを返しますが、部分レスポンスは空のフィードです。

<?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/"DEAEQH47eCp7IWA9WxBVGUo."'
  gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
</feed>

部分更新（試験運用版）

部分レスポンスと編集が可能なリソースをサポートする Google サービスでは、部分更新も利用できます。部分更新では、更新するフィールド全体を送信するのではなく、更新するフィールドのみを送信します。これにより、クライアント アプリケーションの更新時や、部分レスポンスを使用したデータ取得時の効率が向上します。

ただし、部分更新を行う際は、PUT ではなく PATCH リクエストを使用する必要があります。PATCH のセマンティクスは、1 つのリクエストで特定のエントリに特定のフィールドを追加、置換、削除するのに十分強力です。

使用しているプロダクトで部分更新が可能かどうかについては、各プロダクトのドキュメントをご覧ください。

部分更新リクエストの送信

部分更新リクエストを送信するには、リソースの更新に PUT で通常使用する URL と同じ URL に HTTP PATCH リクエストを送信します。PATCH リクエストの本文は、追加または変更するフィールドを指定する部分的な <entry> 要素です。エントリの gd:fields 属性は、削除するフィールドを示します。

サーバーは PATCH リクエストを特定の順序で処理します。

1. まず、 gd:fields 属性で指定されたフィールドをリソース表現から削除します。

   gd:fields 属性の構文は、部分レスポンスをリクエストするときに使用される fields クエリ パラメータと同じです。詳しくは、サポートされる構文をご覧ください。

2. 次に、リクエストの本文で提供されるデータを既存のリソース表現にマージします。

   データのマージについて詳しくは、後述のフィールドを追加または更新するをご覧ください。

注: PATCH の本文は通常 Atom Syndication Format に準拠していないため、PATCH リクエストに使用する Content-Type は application/xml です。

部分更新リクエストの例を次に示します。

PATCH /myFeed/1/1/
Content-Type: application/xml

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

この PATCH リクエストは、ターゲット URI のエントリ用にサーバーに保存されているリソース表現を次のように変更します。

• <description> 要素を削除します。
• <title> 要素を更新します。

部分更新リクエストの意味

エントリ内の特定のフィールドを削除、追加、更新する PATCH リクエストを設定する手順は以下のとおりです。1 つの PATCH リクエストで、これらのオペレーションの任意の組み合わせを実行できます。

• フィールドを削除しています。<entry> 要素の gd:fields 属性を使用して、リソースから削除するフィールドを指定します。次のサンプル リクエストでは、エントリに関連付けられているタイトルと概要を削除します。ただし、リクエストによってエントリのその他のデータが追加または更新されることはありません。

  PATCH /myfeed/1/1/
  Content-Type: application/xml
  
  <entry xmlns='http://www.w3.org/2005/Atom'
      xmlns:gd='http://schemas.google.com/g/2005'
      gd:fields='title,summary'/>
  

• フィールドを追加または更新します。<entry> 要素の本文を使用して、リソースに追加または更新するデータを指定します。これらのフィールドは、削除後に次のルールに従って、リソースの既存のデータにマージされます。

  • まだ存在していないフィールドも追加されます。リソースデータでフィールドの値がまだ指定されていない場合は、既存のデータにフィールドが追加されます。たとえば、エントリにタイトルがなく、PATCH リクエストに <title> 要素が含まれている場合、新しいタイトルがエントリに追加されます。

  • すでに存在するフィールドは置換または追加されます。リソースデータですでに指定されているフィールドを統合する具体的な動作は、フィールドの特性によって異なります。

    • 繰り返しのないフィールドは置き換えられます。繰り返しなし要素の値がすでにリソースデータで指定されている場合、PATCH リクエストで指定した値によって、その要素の既存の値が置き換えられます。たとえば、以下の例では、既存のタイトルを新しいタイトルに置き換えます。

      PATCH /myFeed/1/1/
      Content-Type: application/xml
      
        <entry xmlns='http://www.w3.org/2005/Atom'
          xmlns:gd='http://schemas.google.com/g/2005'>
        <title>New Title</title>
      </entry>

      複雑な例を以下に示します。この例では、エントリの作成者は 1 人だけであり、ターゲット リソースには作成者の名前とメールアドレスの値がすでにあるとします。<author> 要素には 2 つの子フィールドがありますが、提供されるデータには <name> 要素のみ存在します。そのため、そのフィールドの値のみが上書きされます。<email> 要素の値は、指定したデータにないので変更されません。

      PATCH /myfeed/1/1/
      Content-Type: application/xml
      
      <entry xmlns='http://www.w3.org/2005/Atom'
          xmlns:gd='http://schemas.google.com/g/2005'>
        <author>
          <name>New Name</name>
        </author>
      </entry>

    • 繰り返しフィールドが追加されます。リソースデータで繰り返し要素の値がすでに指定されている場合は、指定した新しい要素が既存の値のセットに追加されます。

      繰り返し要素の新しいインスタンスを追加する以外の作業が必要になることがあります。たとえば、次のいずれかを行います。

      • 繰り返し要素のリスト全体を置き換えます。gd:fields 属性（gd:fields='ns:accessControl' など）を使用してすべての繰り返しフィールドを削除し、置換フィールドの完全なセットを指定できます。既存のすべての要素が先に削除されるため、指定した一連のフィールドは、追加されても既存の値と競合しません。

      • 繰り返し要素の既存の値セット内の 1 つの値を置き換えます。この場合、保持する必要がある他の値が削除されないように gd:fields の値を十分に定義することにより、単一の要素を削除します。たとえば、action が embed であるアクセス制御のみを削除するには、gd:fields='ns:accessControl[@action="embed"]' を使用します。次に、置換する単一のフィールドを <entry> 要素の本文で指定します。

        PATCH /myfeed/1/1/
        Content-Type: application/xml
        
        <entry xmlns='http://www.w3.org/2005/Atom'
            xmlns:gd='http://schemas.google.com/g/2005'
            gd:fields='ns:accessControl[@action="embed"]>
          <ns:accessControl action="embed" permission="allowed" />
        </entry>

部分更新に対するレスポンスを処理する

有効な部分更新リクエストを処理すると、API は 200 OK HTTP レスポンス コードを返します。デフォルトでは、レスポンスの本文は更新したエントリ全体です。サーバーは、PUT の場合と同様に、PATCH リクエストが正常に処理されると ETag 値を更新します。

PATCH リクエストの結果、構文的または意味的に無効な新しいリソース状態になると、サーバーは HTTP 400 Bad Request または 422 Unprocessable Entity HTTP ステータス コードを返します。リソースの状態は変更されません。たとえば、必須項目を削除しようとしても置換を行わなかった場合、サーバーからエラーが返されます。

注: 各フィールドの相互関係を理解することが重要です。相互依存する値の一部のみを更新することで、リソースを整合させないことも可能です。たとえば、開始時刻を終了時間よりも後の値に更新できます。API はエラーコードを返すはずですが、このような状態を完全にテストして一貫性を確保することをおすすめします。

PATCH がサポートされていない場合の代替表記

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

POST /myfeed/1/1/
X-HTTP-Method-Override: PATCH
Content-Type: application/xml
...

部分更新で部分レスポンスを使用する

部分レスポンスは、後続の部分更新リクエストの基礎として使用できます。これを行うには、@gd:* に加えて、編集リンクを含む fields クエリ パラメータを指定します。これにより、部分レスポンスに ETag や gd:fields 属性値などの情報が含まれるようになります。これらの情報は、後続のリクエストで重要となります。

部分的なレスポンスを返す例を次に示します。これは、将来の部分的な更新のベースとして使用できます。

http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who

サーバーが応答します。

<?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='"E0UKRAREeCp7IWA6WhJT"'
    gd:fields="@gd;*,link[@rel='edit'](@href),gd:who">
  <link href='http://example.com/myFeed/1/1/'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='jo@gmail.com'/>
  <gd:who email='jane@gmail.com'/>
</entry>

メールアドレスが 'jane@gmail.com' のユーザーを削除し、メールアドレスが 'will@gmail.com' のユーザーを追加して、現在 'jo@gmail.com' となっているユーザーのメールアドレスを 'josy@gmail.com' に変更するとします。

これらの変更を行うには、単に前のレスポンスの結果から始めて、異なるフィールドのみを変更し、変更した部分エントリを PATCH リクエストの本文として送信します。この例では、必要な修正は次のとおりです。

• 指定された要素のリストから <gd:who email='jane'/> を削除します。
• 指定された要素のリストに <gd:who email='will@gmail.com'/> を追加します。
• <gd:who email='jo@gmail.com'/> は、<gd:who email='josy@gmail.com'/> に置き換えます。

部分的なレスポンスに基づく PATCH リクエストを以下に示します。

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who"
    gd:etag="FE8LQQJJeSp7IWA6WhVa">
  <link href='http://example.com/myFeed/1/1'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='josy@gmail.com'/>
  <gd:who email='will@gmail.com'/>
</entry>

注: この方法では、エントリの部分的なレスポンスに含まれる gd:fields 属性と gd:etag 属性（サポートされている場合）に依存します。部分的なエントリの本文には、明示的に削除したいフィールドと部分レスポンスに含まれていたすべてのフィールドと属性を保持する必要があります。本体の既存のフィールドを新しい値で更新したり、追加したい新しいフィールドを含めたりできます。

認証

クライアントがサービスにアクセスしようとすると、ユーザーがそのアクションを実行する権限を持っていることを示すために、サービスに対してユーザーの認証情報を提供する必要が生じる場合があります。

クライアントが認証に使用する方法は、クライアントの種類によって異なります。

• デスクトップ アプリケーションでは、インストール型アプリケーションに対するアカウント認証（別名「gclid」）という Google 固有の認証システムを使用する必要があります。（ウェブベースのクライアントはこのシステムを使用しないでください）。
• サードパーティのクライアント（Google サービスへのサードパーティ フロントエンドなど）などのウェブベースのクライアントは、ウェブベースのアプリケーション用のアカウント認証プロキシ（「AuthSub」とも呼ばれます）と呼ばれる Google 固有の認証システムを使用する必要があります。

OpenSSL システムで、デスクトップ クライアントはユーザーに認証情報を求め、その認証情報を Google 認証システムに送信します。

認証が成功した場合、認証システムが Data API リクエストを送信するときにクライアントが HTTP 認証ヘッダーで使用するトークンを返します。

認証に失敗すると、サーバーは 403 Forbidden ステータス コードと、認証に適用されるチャレンジを含む WWW-Authenticate ヘッダーを返します。

AuthSub システムも同じように動作しますが、ユーザーに認証情報を尋ねるのではなく、認証情報を要求する Google サービスにユーザーを接続します。次に、ウェブ アプリケーションで使用可能なトークンを返します。この方法の利点は、（ウェブ フロントエンドではなく）Google がユーザーの認証情報を安全に処理して保存することです。

これらの認証システムについて詳しくは、Google Data API の認証の概要または Google アカウント認証のドキュメントをご覧ください。

セッション状態

多くのビジネス ロジックの実装では、セッション持続性（ユーザーのセッション状態の追跡）が必要です。

Google は 2 つの方法でセッション状態をトラッキングします。1 つは Cookie を使用する方法、もう 1 つはクエリ パラメータとして送信可能なトークンを使用する方法です。どちらの方法でも効果は同じです。クライアントでは、これらのセッション状態のトラッキング方法のいずれかを使用することをおすすめします（どちらか一方でも十分）。これらのメソッドのいずれかをサポートしていないクライアントでは、引き続き Data API を使用できますが、それらのメソッドをサポートするクライアントに比べてパフォーマンスが低下する可能性があります。具体的には、クライアントがこれらのメソッドをサポートしていない場合、すべてのリクエストはリダイレクトされるため、すべてのリクエスト（および関連するデータ）はサーバーに 2 回送信されます。これは、クライアントとサーバーの両方のパフォーマンスに影響します。

Google のクライアント ライブラリはセッションの状態を処理します。そのため、Google のライブラリを使用する場合は、セッション状態のサポートを利用するために何もする必要はありません。

参考情報

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

• Atom と RSS の相互比較
• IBM の Atom の概要
• RSS の Dublin Core 拡張機能
• HTTP 1.1 のメソッド定義。GET、POST、PUT、DELETE の仕様です。
• HTTP 1.1 ステータス コードの定義
• REST プロトコルの作成方法
• REST 方式のウェブサービスの構築
• XML の技術的な概要
• サンプル XML 名前空間
• HTTP 仕様の ETag セクション

トップへ戻る