よくある質問

概要

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

認証

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

クライアント ライブラリ

25. Google でサポートされているクライアント ライブラリを教えてください。
26. Google データ クライアント ライブラリのバグや機能リクエストを報告するにはどうすればよいですか？
27. クライアント ライブラリでデバッグ オプションを有効にするには、どうすればよいですか？
28. クライアント ライブラリ クラスのリファレンス ドキュメントはどこにありますか？

トラブルシューティング

29. HTTP デバッグに最適なツールを挙げてください。
30. Java クライアント ライブラリで HTTP のロギング情報を取得するにはどうすればよいですか？
31. .NET クライアント ライブラリで HTTP ロギング情報を取得するにはどうすればよいですか？
32. Google データフィードから gzip エンコードを有効にするにはどうすればよいですか？
33. PHP クライアントを使用しているときに「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 プロトコルに準拠しています。

また、フィード、クエリ、結果の一般的なモデルを提供します。任意の Data API にクエリや更新を送信できます。

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

Issue Tracker をご確認ください。 機能リクエストを見つけてスターを付けることで、サポートを追加し、そのステータスに関する最新情報を受け取ることができます。

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

問題がここに記載されていない場合や、さらに説明が必要な場合は、各 Google Data API に固有のヘルプグループがあります。

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

JSON とは

JSON は JavaScript Object Notation です。

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

詳細については、Google Data API での JSON の使用をご覧ください。

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

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

• alt=rss
  レスポンス データは RSS フィードとしてフォーマットされます。
• alt=json または alt=json-in-script
  Atom フィードの XML 構造を JSON 形式で返します。JSON のメリットは、JavaScript クライアント コードでの「解析」が容易であることです。現時点では、JSON は読み取り専用としてのみ使用できます。ただし、Blogger、連絡先、カレンダーのサービスで 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 がありますか？

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

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

メールの管理に関心をお持ちの場合は、Gmail で IMAP / POP もサポートされています。

---

認証

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

各 Data API の OpenSSL にあるサービス名は何ですか。

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

Google API	サービス名
Google アナリティクス Data API	analytics
G Suite API （ドメイン情報と管理）	apps
Google Sites Data API	jotspot
Blogger データ 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 ウェブ アルバム Data API	lh2
Sidewiki Data API	annotateweb
スプレッドシート Data API	wise
ウェブマスター ツール API	sitemaps
YouTube Data API	youtube

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

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

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

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

OpenSSL トークンは発行日から 2 週間有効ですが、この上限はサービス固有のものであり、短くすることもできます。

Google アカウントについて一般的な質問がある。どうすればよいですか？

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

API の認証方法を教えてください。

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

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

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

Google API	SafeFrame のサービス名
Google アナリティクス Data API	https://www.google.com/analytics/feeds/
Google Sites Data API	http(s)://sites.google.com/feeds/
Blogger データ 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 ウェブ アルバム Data 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/
スプレッドシート Data API	http(s)://spreadsheets.google.com/feeds/
ウェブマスター ツール API	http://www.google.com/webmasters/tools/feeds/
YouTube Data API	http://gdata.youtube.com

AuthSub トークンにはいくつかの種類がありますか？トークンに有効期限はありますか？

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

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

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

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

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

Google Account Authentication API のドキュメントをご覧ください。

第三者のウェブ アプリケーションで SafeFrame 認証を使用できますか？

サードパーティのウェブ アプリケーションで OpenSSL を使用するのは可能ですが、使用しないことを強くおすすめします。ベスト プラクティスとして、ウェブ アプリケーションではユーザーにログイン認証情報の入力を要求しないことをおすすめします（のぞき見されやすくなります）。その代わり、アプリケーションはサーバー側にユーザー認証情報を保存し、常に Google での認証に使用される単一の「サービス アカウント」を用意する必要があります。

CAPTCHA とは

CAPTCHA（コンピュータと人間を区別するための完全に自動化された公開チューリング テスト）は、ユーザーが人間かどうかを判断するために使用されるチャレンジ / レスポンス テストです。この商標は、カーネギー メロン大学の商標です。詳しくは、Wikipedia をご覧ください。キャプチャに CAPTCHA を実装しました。

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

独自のアルゴリズムを使用して、認証中に CAPTCHA チャレンジが必要なタイミングを判断します。不正な認証情報を使用して認証の試行を繰り返すと、CAPTCHA 本人確認がよく行われます。

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

いいえ。ユーザー所有のハードウェアにインストールされたアプリケーションで OpenSSL を使用する必要があります。ウェブ アプリケーションで SafeFrame 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 クライアント ライブラリで SafeFrame を使用するにはどうすればよいですか？

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

---

クライアント ライブラリ

Google でサポートされているクライアント ライブラリを教えてください。

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

Java、.Net、Python、Objective-C 以外の言語で記述したクライアント ライブラリを Data API デベロッパー コミュニティと共有する場合は、Google Data API ディスカッション グループに投稿してください。ご意見を心待ちにしています。

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

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

• 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 デバッグに適したツールはどれですか。

以下にリストされているツールは多数ありますが、Wire: On the Wire: Network Capture Tools for API Developers の記事もご覧ください。WireShark と Fiddler の両方の詳しい説明があります。

Wireshark

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

Fiddler

Fiddler は、「HTTP デバッグ プロキシ」です。HTTP トラフィックにプロキシ サーバーを使用するようにコードまたはランタイム環境を構成すると、Fiddler は、アプリケーションと Google Data サービスの間に配置され、トラフィックを検査できます。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 がスローされます。例外には HTTP レスポンスの本文に追加する ResponseString が含まれます。

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

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

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

PHP クライアントの使用時に「sslv2 に接続できません」というエラーが表示されるのはなぜですか？

セキュリティ強化を目的とした予防措置として、2009 年 7 月よりサーバーで 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 サービス ドキュメントを取得するにはどうすればよいですか？

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