よくある質問

概要

1. Google Data API とは何ですか？
2. 機能リクエストまたはバグレポートがあります。どこに投稿すればよいですか？
3. 特定の API について質問するにはどうすればよいですか？
4. JSON とは
5. XML を使用する必要がありますか？他のデータ形式は利用できますか？
6. REST を使用している理由
7. 一般的な問題に関するヒントや短いサンプルコードはありますか？
8. Gmail に Data API はありますか？

認証

9. 各 Data API の ClientLogin のサービス名は何ですか？
10. ユーザーがアプリケーションからログアウトしたときに、API サーバーに通知する必要がありますか？
11. ClientLogin 認証トークンに有効期限はありますか？
12. Google アカウントについて一般的な質問があります。どこに行けばよいですか？
13. API に対して認証するにはどうすればよいですか？
14. AuthSub/OAuth 1 のスコープ パラメータにはどのような値を使用すればよいですか？
15. AuthSub トークンにはさまざまな種類がありますか？トークンに有効期限はありますか？
16. ClientLogin と AuthSub/OAuth 1 の主な違いは何ですか？
17. サードパーティのウェブ アプリケーションで ClientLogin 認証を使用できますか？
18. CAPTCHA とは
19. CAPTCHA チャレンジを生成するにはどうすればよいですか？
20. ウェブ アプリケーションで ClientLogin を使用する必要がありますか？
21. AuthSub/OAuth 1 を使用している場合、ユーザーのユーザー名を確認するにはどうすればよいですか？
22. Google Data API クライアント ライブラリで OAuth 1 を使用するにはどうすればよいですか？
23. Google Data API クライアント ライブラリで AuthSub を使用するにはどうすればよいですか？
24. Google Data API クライアント ライブラリで ClientLogin を使用するにはどうすればよいですか？

クライアント ライブラリ

25. Google がサポートしているクライアント ライブラリは、どのプログラミング言語で用意されていますか？
26. Google Data クライアント ライブラリのバグや機能リクエストを報告するにはどうすればよいですか？
27. クライアント ライブラリでデバッグ オプションを有効にするにはどうすればよいですか？
28. クライアント ライブラリ クラスのリファレンス ドキュメントはどこで確認できますか？

トラブルシューティング

29. HTTP デバッグに役立つツールを教えてください。
30. Java クライアント ライブラリで HTTP ロギング情報を取得するにはどうすればよいですか？
31. .NET クライアント ライブラリで HTTP ロギング情報を取得するにはどうすればよいですか？
32. Google データフィードから gzip エンコードを有効にするにはどうすればよいですか？
33. PHP クライアントを使用しているときに「Unable to Connect to sslv2」というエラーが表示されるのはなぜですか？
34. フィードを記述する Atom サービス ドキュメントを取得するにはどうすればよいですか？

---

概要

Google Data API とは

Google Data API は、Google Data プロトコルに基づく API です。Google Data プロトコルは、Atom 1.0 と RSS 2.0 のシンジケーション形式と、Atom Publishing Protocol（APP）に基づいています。

Google Data プロトコルは、標準に組み込まれた拡張メカニズムを使用して、さまざまな方法でこれらの標準を拡張します。フィードは Atom または RSS のシンジケーション形式に準拠している。公開モデルは Atom Publishing Protocol に準拠しています。

このプロトコルは、フィード、クエリ、結果の一般的なモデルも提供します。これを使用して、任意の Data API にクエリと更新を送信できます。

機能リクエストまたはバグレポートがあります。どこに投稿すればよいですか？

Issue Tracker をご覧ください。機能リクエストを探して星を付け、サポートを追加してステータスの最新情報を受け取ります。

特定の API について質問するには、どこに問い合わせればよいですか？

問題がここに記載されていない場合や、さらに詳しい説明が必要な場合は、各 Google Data API に固有のディスカッション グループがあります。

• G Suite（G Suite ファミリー内の個々の API を参照）
• ベース
• Blogger
• カレンダー
• コード検索
• 連絡先
• Google サイト
• スプレッドシート
• ドキュメント リスト
• フェデレーション ログイン / OpenID
• 財務
• 健康
• Picasa ウェブ アルバム
• ウェブマスター ツール
• YouTube

JSON とは

JSON は JavaScript Object Notation を指します。

JSON は軽量のデータ交換形式であり、そのシンプルさからウェブ デベロッパーの間で広く使用されています。読み書きが簡単で、任意のプログラミング言語で解析できます。また、その構造は、ほとんどのプログラミング言語で使用されるデータ構造に直接マッピングされます。

Google Data APIs で JSON を使用するをご覧ください。

XML を使用する必要がありますか？他のデータ形式は利用できますか？

Google Data API のデフォルトのデータ形式は、Atom フィード形式の XML です。ただし、フィードをリクエストする際に、alt クエリ パラメータを使用して別の形式を指定できます。

• alt=rss
  レスポンス データは RSS フィードとしてフォーマットされます。
• alt=json または alt=json-in-script
  : Atom フィードの XML 構造の JSON 表現を返します。JSON のもう 1 つの利点は、JavaScript クライアント コードで「解析」しやすいことです。現時点では、JSON の使用は読み取り専用オプションとしてのみ使用できます。ただし、Blogger、Contacts、Calendar サービスで JavaScript クライアント ライブラリを使用すると、データの読み取りと書き込みの両方が可能になります。

  詳しくは、JSON フィードのリクエストと使用をご覧ください。

• alt=atom-in-script
alt=json-in-script と同様ですが、結果は JSON ではなく Atom XML 文字列として返されます。
• alt=rss-in-script
alt=atom-in-script と同様ですが、結果は Atom ではなく RSS XML 文字列として返されます。

代替形式について詳しくは、Google データ リファレンス ガイドをご覧ください。

REST を使用する理由

REST はシンプルで軽量、スケーラブルであり、データの表現と公開に非常に適しています。

一般的な問題に関するヒントや短いサンプルコードはありますか？

クライアント ライブラリと未加工のリクエストの作成の両方については、Google Data API のヒントブログをご覧ください。

Gmail に Data API はありますか？

いいえ。ただし、AuthSub または OAuth 1 で Gmail の Atom フィードを使用すると、ユーザーの未読メッセージへの読み取り専用アクセスをリクエストできます。スコープは https://mail.google.com/mail/feed/atom/ に設定する必要があります。クエリの例を次に示します。

GET https://mail.google.com/mail/feed/atom/

メールの管理に関心がある場合は、Gmail で IMAP/POP をサポートすることもできます。

---

認証

Google Data APIs のドキュメントでは、「OAuth」は OAuth 1 を指します。OAuth 2.0 の詳細については、個々の API のドキュメントをご覧ください。

各 Data API の ClientLogin のサービス名は何ですか？

「サービス名」は、ClientLogin 認証システムが Google サービスを識別するために使用する短い文字列です。

Google API	サービス名
Google アナリティクス Data API	analytics
G Suite API （ドメイン情報と管理）	apps
Google Sites Data API	jotspot
Blogger Data API	blogger
Book Search Data API	print
Calendar Data API	cl
Google Code Search Data API	codesearch
Contacts Data API	cp
Content API for Shopping	structuredcontent
Documents List Data API	writely
Finance Data API	finance
Gmail Atom フィード	mail
Health Data API	health weaver（H9 サンドボックス）
Maps Data API	local
Picasa ウェブ アルバム データ API	lh2
Sidewiki Data API	annotateweb
スプレッドシート データ API	wise
Webmaster Tools API	sitemaps
YouTube Data API	youtube

ClientLogin リクエストで使用されるその他のパラメータの詳細については、ClientLogin のドキュメントをご覧ください。

ユーザーがアプリケーションからログアウトした場合、API サーバーに通知する必要がありますか？

いいえ。ユーザーがアプリケーションからログアウトしたときに Google Data API に通知する必要はありません。ただし、発行された AuthSub トークンをアプリケーションで使用する必要がなくなった場合は、トークンを取り消す必要があります。

ClientLogin 認証トークンに有効期限はありますか？

ClientLogin トークンの有効期間は発行日から 2 週間ですが、この制限はサービス固有であり、より短くなる可能性があります。

Google アカウントについて一般的な質問があります。どこに行けばよいですか？

Google アカウントのヘルプセンターをご覧ください。

API に対して認証するにはどうすればよいですか？

HTTP リクエストには、ClientLogin、AuthSub、または OAuth 1 のいずれかを使用して取得したトークンを含む Authorization ヘッダーを含める必要があります。

AuthSub/OAuth 1 のスコープ パラメータにはどのような値を使用すればよいですか？

AuthSub と OAuth 1 では、アプリケーションがアクセスする Google サービスを識別するために scope パラメータが必要です。OAuth 2.0 の詳細については、特定の API のドキュメントをご覧ください。

Google API	ClientLogin サービス名
Google Analytics Data API	https://www.google.com/analytics/feeds/
Google Sites Data API	http(s)://sites.google.com/feeds/
Blogger Data API	http://www.blogger.com/feeds/
Book Search Data API	http://www.google.com/books/feeds/
Calendar Data API	http(s)://www.google.com/calendar/feeds/
Contacts Data API	http(s)://www.google.com/m8/feeds/
Content API for Shopping	https://www.googleapis.com/auth/structuredcontent
Documents List Data API	http(s)://docs.google.com/feeds/
Finance Data API	http://finance.google.com/finance/feeds/
Gmail Atom フィード	https://mail.google.com/mail/feed/atom/
Health Data API	https://www.google.com/health/feeds/ https://www.google.com/h9/feeds/（H9 サンドボックス）
Maps Data API	http://maps.google.com/maps/feeds/
Picasa ウェブ アルバム データ API	http://picasaweb.google.com/data/
Portable Contacts API	http://www-opensocial.googleusercontent.com/api/people
Sidewiki Data API	http://www.google.com/sidewiki/feeds/
スプレッドシート データ API	http(s)://spreadsheets.google.com/feeds/
Webmaster Tools API	http://www.google.com/webmasters/tools/feeds/
YouTube Data API	http://gdata.youtube.com

AuthSub トークンにはさまざまな種類がありますか？トークンに有効期限はありますか？

AuthSub トークンには 2 種類あります。1 つ目は、'token' クエリ パラメータを介してウェブ アプリケーションに提示される 1 回限りのトークンです。このトークンは、発行されたサービスで初めて使用されたとき、またはセッション トークンと交換されたときに期限切れになります。

ユーザーまたは AuthSubRevokeToken API 呼び出しでトークンが明示的に取り消されない限り、セッション トークンは期限切れになりません。1 回限りのトークンは、元の AuthSubRequest URL で session=1 がクエリ パラメータとして指定されている場合にのみ、セッション トークンと交換できます。

ClientLogin と AuthSub/OAuth 1 の主な違いは何ですか？

AuthSub はウェブ アプリケーション向けに設計されています。これにより、ユーザーの認証情報がサードパーティのウェブサイトを介してではなく、ユーザーのウェブブラウザから Google のサーバーに直接安全に送信されます。

ClientLogin は、インストールされたデスクトップ アプリケーション用です。この設定では、リクエスト元のアプリケーションがユーザーの代わりにユーザーの認証情報を Google に送信する必要があります。

Google アカウント認証 API のドキュメントをご覧ください。

サードパーティのウェブ アプリケーションで ClientLogin 認証を使用できますか？

サードパーティのウェブ アプリケーションで ClientLogin を使用することは可能ですが、強く推奨されません。ウェブ アプリケーションでは、ユーザーにログイン認証情報を尋ねるべきではありません（盗聴される可能性があります）。代わりに、アプリケーションはユーザーの認証情報をサーバーサイドに保存し、Google との認証に常に使用される単一の「サービス アカウント」を持つ必要があります。

CAPTCHA とは

CAPTCHA（Completely Automated Public Turing test to tell Computers and Humans Apart）は、ユーザーが人間かどうかを判定するために使用されるチャレンジ レスポンス型のテストの一種です。この用語はカーネギー メロン大学の商標です。詳しくは、Wikipedia をご覧ください。ClientLogin に CAPTCHA を実装しました。

CAPTCHA チャレンジを生成するにはどうすればよいですか？

認証時に CAPTCHA チャレンジが必要かどうかを判断するために、独自のアルゴリズムが使用されます。無効な認証情報で認証を繰り返し試行すると、多くの場合、CAPTCHA チャレンジが生成されます。

ウェブ アプリケーションで ClientLogin を使用すべきですか？

いいえ。ClientLogin は、ユーザー所有のハードウェアにインストールされたアプリケーションで使用する必要があります。ウェブ アプリケーションでの ClientLogin API の使用は安全ではなく、強く推奨されません。

AuthSub/OAuth 1 を使用しているときにユーザーのユーザー名を確認するにはどうすればよいですか？

Google からユーザーのフィードへのアクセスを許可するトークンのみが提供されるため、ユーザー名がわからない場合があります。使用するフィード URL にユーザー名が含まれている場合、問題が発生する可能性があります。この場合、特別なユーザー名 default を使用して、「認証トークンを使用しているユーザー」を意味できます。

Google Data API クライアント ライブラリで OAuth 1 を使用するにはどうすればよいですか？

Google Data API クライアント ライブラリで OAuth 1 を使用するをご覧ください。

Google Data API クライアント ライブラリで AuthSub を使用するにはどうすればよいですか？

記事 Google Data API クライアント ライブラリで AuthSub を使用するをご覧ください。

Google Data API クライアント ライブラリで ClientLogin を使用するにはどうすればよいですか？

Google Data API クライアント ライブラリで ClientLogin を使用するの記事をご覧ください。

---

クライアント ライブラリ

Google でサポートされているクライアント ライブラリは、どのプログラミング言語で用意されていますか？

Java、.NET、Python、Objective-C のクライアント ライブラリは、Google によって公式にサポートされています。また、パートナーの Zend が PHP クライアント ライブラリを作成しています。これらのライブラリを使用すると、Google Data プロトコル リクエストを作成してサービスに送信し、サーバー レスポンスを処理できます。現在、Blogger、カレンダー、Google コンタクトのみをサポートする JavaScript クライアント ライブラリもあります。

Java、.Net、Python、Objective-C 以外の言語でクライアント ライブラリを作成し、Data API デベロッパー コミュニティと共有する場合は、Google Data APIs ディスカッション グループに投稿してください。皆様からのフィードバックをお待ちしております。

クライアント ライブラリのバグや機能リクエストを報告するにはどうすればよいですか？

クライアント ライブラリのバグや機能リクエストは、次の場所で報告できます。

• Java
• JavaScript
• .NET
• PHP
• Python
• Objective-C

バグを投稿したら、適切な API のデベロッパー フォーラムでスレッドを作成します。

Google Data API クライアント ライブラリでデバッグ オプションを有効にするにはどうすればよいですか？

一部のクライアント ライブラリでデバッグを有効にする方法については、Google Data API クライアントのデバッグ: プログラム内からのトラフィックの調査

をご覧ください。

クライアント ライブラリ クラスの参照ドキュメントはどこで確認できますか？

クライアント ライブラリ	リファレンス ガイド
Java	Javadoc
JavaScript	JSdoc
.NET	NDoc
PHP	phpDoc
Python	PyDoc

---

トラブルシューティング

HTTP デバッグに役立つツールを教えてください。

以下にいくつかのツールを挙げますが、WireShark と Fiddler の両方の例を詳しく説明している On the Wire: Network Capture Tools for API Developers という記事もご覧ください。

Wireshark

Wireshark は「ネットワーク プロトコル アナライザー」です。ネットワーク トラフィックをキャプチャしてコンテンツを分析する機能を提供します。HTTP リクエストとレスポンスのストリームに直接アクセスできないライブラリで発生するトラフィックのデバッグに非常に役立ちます。アプリケーションと認証サービス間のトラフィックは、通信が SSL で暗号化されているため、Wireshark を使用して分析できません。Wireshark は、tcpdump などのツールを使用してキャプチャされたトラフィックの分析にも使用できます。Wireshark は、デベロッパーからソースコードと Windows インストーラの両方で入手できます。サードパーティ パッケージは、多くのプラットフォームで利用できます。

Fiddler

Fiddler は「HTTP デバッグ プロキシ」です。HTTP トラフィックにプロキシ サーバーを使用するようにコードまたはランタイム環境を構成できる場合、Fiddler はアプリケーションと Google データ サービスの間で動作し、トラフィックを検査できます。Fiddler 2 には SSL のサポートが含まれています。Fiddler は現在、Windows でのみご利用いただけます。

cURL

cURL は、HTTP/HTTPS リクエストを実行できるコマンドライン ツールです。これは、クライアントで HTTP サポートを最初に構築しなくても、サービスとのインタラクションをすばやくテストするのに非常に便利です。

Java クライアント ライブラリで HTTP ロギング情報を取得するにはどうすればよいですか？

Java クライアント ライブラリは、java.util.logging パッケージを使用して HTTP リクエストのロギングを有効にします。これにより、リクエストとレスポンスのヘッダー、ステータス コード、リクエスト URL のロギングを有効にできます。現時点では、リクエストとレスポンスのストリーム全体はログに記録されません。これらのログに使用されるロガー名は com.google.gdata.client.http.HttpGDataRequest です。

サーバーからエラーコードが返された場合は、例外がスローされます。例外クラスは com.google.gdata.util.ServiceException から継承され、getResponseBody() というパブリック メソッドを含みます。詳しくは、Javadoc をご覧ください。

.NET クライアント ライブラリで HTTP ロギング情報を取得するにはどうすればよいですか？

.NET ライブラリは、トレースが有効になっている場合、System.Diagnostics トレース メソッドを使用して実行パスをログに記録します。また、エラーが発生した場合は、GDataRequestException がスローされます。例外には ResponseString が含まれており、HTTP レスポンスの本文にアクセスできます。

Google データフィードから gzip エンコードを有効にするにはどうすればよいですか？

Google Data API のいずれかから gzip でエンコードされたレスポンスを受け取るには、2 つの準備作業が必要です。1 つは「Accept-Encoding」ヘッダーを設定すること、もう 1 つはユーザー エージェントに「gzip」という文字列を追加することです。正しい形式のヘッダーの例:

User-Agent: my program (gzip)
Accept-Encoding: gzip

PHP クライアントを使用しているときに「Unable to Connect to sslv2」というエラーが表示されるのはなぜですか？

2009 年 7 月より、セキュリティ強化の予防措置として、Google のサーバーで SSLv2 を無効化しました。残念ながら、2007 年 7 月より前にリリースされた PHP クライアント ライブラリの初期バージョン（バージョン 1.0.0 以前）には、接続で SSLv2 を強制的に使用するバグがあります。SSLv2 が無効になっているサーバーに接続すると、次のエラーが発生します。

PHP Fatal error:  Uncaught exception 'Zend_Http_Client_Adapter_Exception' with message 'Unable to Connect to sslv2://www.google.com:443.'

このエラーを修正するには、http://framework.zend.com/download から入手できる PHP クライアント ライブラリの新しいリリースにアップグレードします。

新しいリリースにアップグレードできない場合は、次のコードをアプリケーションに追加することで修正できます。ここで、$gdata は Zend_Gdata（または適切なサブクラス）の既存のインスタンスです。

$gdata->getHttpClient()->setConfig(array('ssltransport' => 'ssl'));

フィードを記述する Atom サービス ドキュメントを取得するにはどうすればよいですか？

リクエストで alt=atom-service パラメータを渡すと、Atom サービス ドキュメントを取得できます。注: Google Data APIs のバージョン 2 のみで、AtomPub サービス ドキュメントの構文に準拠したサービス ドキュメントが返されます。Google Data APIs のバージョン 1 は引き続きサービス ドキュメントを返しますが、以前の AtomPub ドラフト仕様に基づいています（2 つのバージョン間では構文と名前空間が変更されています）。