デベロッパー ガイドの概要

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

Google の使命は世界中の情報を整理し、世界中の人々がアクセスできて使えるようにすることです。これには、ウェブブラウザ以外のコンテキストで情報にアクセスし、Google 以外のサービスからアクセス可能にすることも含まれます。

Google Data Protocol は、エンドユーザーが Google の各種サービスに保存されているデータにアクセスして更新できる新しいアプリケーションを作成するための安全な手段です。外部デベロッパーは Google Data Protocol を直接使用するか、クライアント ライブラリで提供される任意のプログラミング言語を使用できます。

対象者

このドキュメントは、Google データ プロトコルについて理解したいと考えている方を対象としています。言語固有のクライアント ライブラリを使用するコードを記述するだけであっても、クライアント ライブラリ抽象化レイヤの下で何が起こっているのかを把握したい場合があります。

特定の API に関するデベロッパー ガイドについては、Google Data Protocol API ディレクトリをご覧ください。

任意のプログラミング言語で API にアクセスしたい場合は、クライアント ライブラリのダウンロード ページにアクセスします。

背景

カレンダーやスプレッドシートなどのさまざまな Google サービスは、Google データ プロトコルに基づいた API を提供しています。デベロッパーはこれらの API を使用して、エンドユーザーが Google サービスに保存されているデータにアクセスして操作するための新しい方法を提供するクライアント アプリケーションを作成できます。

注: API を提供する Google サービスは、これらに関連するドキュメントでは「サービス」と呼ばれることもあります。

Google Data Protocol を直接使用するコードを記述すると、GETPOST などの HTTP リクエストを使用して API にアクセスします。こうしたリクエストでは、Google サービスに保存されたデータが、データフィードの形式でネットワーク上で送受信されます。データフィードは、データを含む単純なリストです。これまで、メインフィードの形式は AtomPub XML でしたが、現在は JSON(JavaScript Object Notation)も代替形式として利用可能です。

HTTP リクエストを直接行うコードを記述しない場合は、用意されているクライアント ライブラリ セットで利用可能なプログラミング言語のいずれかを使用してクライアント アプリケーションをプログラムできます。その場合、HTTP リクエストの詳細がクライアント ライブラリで処理されます。ここでは、クライアント ライブラリで提供される言語固有のメソッドとクラスを使用して、より概念的なレベルでコードを記述します。

使用している API または API バージョンで対応している具体的な言語の詳細については、各プロダクトのドキュメントをご覧ください。

プロトコルのバージョン

プロトコル バージョン 2.0 とプロトコル バージョン 1.0

Google Data Protocol の最初のバージョンは、Atom Publishing Protocol の最終決定前に開発されました。Google Data Protocol の 2 番目のバージョンは AtomPub RFC 5023 標準に完全に対応しています。

Google Data Protocol バージョン 2.0 では、次の機能もサポートされています。

  • HTTP ETag。クライアント アプリケーションで HTTP キャッシュをより有効に活用するためのウェブ標準です。プロトコル v2.0 をサポートするクライアント ライブラリに含まれるサービスは、ETag を自動的に処理します。
  • 部分レスポンス部分更新(試験運用版)。データを転送する際のリクエスト量を減らす機能。実際に必要な情報のみをリクエストするか、実際に変更が必要なデータのみを含む更新データを送信することで、ネットワーク、CPU、メモリのリソースをより効率的に使用できます。現在、部分レスポンスと部分更新は一部のプロダクトでのみ利用できます。ご利用の API でサポートされているかどうかを確認するには、プロダクト固有のドキュメントをご覧ください。

アプリケーションを更新する

使用している API が最新バージョンのプロトコルに基づいて構築されている場合、Protocol v2.0 の機能がドキュメントに含まれています。一般的には、クライアント アプリケーションは API で利用できる最新バージョンにアップグレードすることをおすすめします。

クライアント ライブラリ ベースのクライアントの更新

Java クライアント ライブラリや .NET クライアント ライブラリなどのクライアント ライブラリをクライアント アプリケーションで使用している場合は、Protocol v2.0 の機能をサポートするバージョンの API が含まれている可能性があります。詳しくは、以下の Google サービスの API ドキュメントをご参照ください。

  • Google Data Protocol v2.0 の機能をサポートする API バージョンがあります。
  • 使用しているクライアント ライブラリも、その API バージョンをサポートしています。

クライアント ライブラリがサポートされていて、既存のアプリケーションを更新する場合は、クライアント ライブラリの最新バージョンをダウンロードして使用します。すべてのコードは引き続き機能し、クライアント ライブラリは内部で Protocol v2.0 の変更を行います。

未加工の HTTP クライアントの更新

Google Data Protocol を直接使用してクライアント アプリケーションを作成した場合は、次の変更を行う必要があります。

  • デフォルト以外のバージョンのリクエスト。送信する HTTP リクエストに HTTP バージョンのヘッダー(GData-Version: X.0)を追加します。X は、Google Data Protocol v2.0 の機能をサポートする API のバージョンです。または、すべてのリクエストの URL にクエリ パラメータ(v=X.0)を追加します。ここで、X は正しいバージョンの API です。これより後のバージョンを指定しない場合、デフォルトで、サポートされている最も古いバージョンの API にリクエストが送信されます。
  • オプティミスティック同時実行。最適化スコアに基づく楽観的同時実行をサポートするバージョンの API を使用していた場合、ETag を使用するには更新とコードの削除が必要になることがあります。詳しくは、Google Data Protocol リファレンス ドキュメントの ETags、クライアント アプリケーションが使用する Service のプロトコル デベロッパー ガイドの「更新と削除」をご覧ください。
  • URI の自己編集、編集。クライアントがフィードやエントリの URI や編集 URI をトラッキングしている場合、それらの URI が変更されている可能性があります。新しい URI を取得するには、古い URI を使用してアイテムを再リクエストしますが、リクエストをバージョン X.0 リクエストとしてマークします。X は Google Data Protocol v2.0 の機能をサポートする API のバージョンです。サーバーがエントリの新しい表現を返します。これには、古い URI の代わりに保存できます。
  • 名前空間 URI。クライアントが Google Data Protocol API の名前空間 URI をローカルに保存している場合、またはそれらをハードコードしている場合は、更新する必要があります。
    • AtomPub 名前空間(接頭辞 app)を http://purl.org/atom/app から http://www.w3.org/2007/app に変更しました。
    • OpenSearch 名前空間(接頭辞 openSearch)を http://a9.com/-/spec/opensearchrss/1.0/ から http://a9.com/-/spec/opensearch/1.1/ に変更しました。