Google+ APIｷﾀ━━━━(ﾟ∀ﾟ)━━━━ｯ!!

やっとでました、Google+ API！これで今回のGDDもおもしろくなりそう！

APIを使用してできることはまだ情報の取得だけだけど、大体どんな感じのAPIになるかは想像できるし、Java、PHP、Python、Rubyのライブラリが既に存在するのも素晴らしい。（本音を言えばRuby版なんかは自分で作ってみたかった気もするけど・・・）

とりあえずドキュメントのトップページを訳してみました。

http://developers.google.com/+/api/

Google+ API

Goolge+ APIはGoogle+のためのプログラミングインターフェースです。このAPIを利用するとアプリケーションやウェブサイトをGoogle+と統合できます。これによってユーザーはあなたのアプリケーション内でGoogle+の機能を最大限に利用して相互に繋がることができます。

注: Google+ APIは現在のところ公開データへの読み込み専用アクセスしか提供していません。すべてのAPI呼び出しにOAuth2.0トークンかAPIキーが必要です。

クォータ

アウリケーションは優待利用クォータによって制限されています。これはAPIをプレビューしてアプリケーションをどのように構築したいかを考え始めるのに十分なアクセスを提供しているはずです。優待制限とアプリケーションのリクエストの上限についてはGoogle APIのコンソールを参照してください。詳細についてはGoogle APIコンソールヘルプを参照してください。

認可

多くのAPI呼び出しは、あなたのアプリケーションのユーザーによって彼らのデータにアクセスする許可を与えてもらう必要があります。GoogleはOAuth2.0プロトコルを使用してアプリケーションにユーザーデータにアクセスする許可を与えることができます。詳細についてはOAuthを参照して下さい。

API呼び出し

ほとんどのGoogle+ APIはRESTful APIデザインに従っています。つまり、標準的なHTTPメソッドを使ってリソースを取り出したり、操作したりできます。例えば、ユーザーのプロフィールを取り出すには、次のようなHTTPリクエストを送るといいでしょう:

GET https://www.googleapis.com/plus/v1/people/userId

共通のパラメータ

異なるAPIメソッドはURLパスの一部またはクエリパラメータとしてパラメータを要求します。さらに、いくつかのパラメータは全てのAPIエンドポイントで共通です。これらは全てオプショナルなクエリパラメータとして渡すことができます。

パラメータ名	値	説明
callback	文字列	JSONPでAPIを利用するためにレスポンスデータを渡すためのJavaScript関数を指定
fields	文字列	部分レスポンスにどのフィールドを含めるか指定するためのセレクタ
key	文字列	APIキー。APIキーはプロジェクトを識別し、APIへのアクセスとクォータ、レポートを提供します。OAuth 2.0トークンがなければ必須。
access_token	文字列	現在のユーザーのためのOAuth 2.0トークン。詳細については OAuth.
prettyPrint	真偽値	もし"true"に設定されていれば、読みやすくするためにデータの出力に改行とインデントが含まれます。"false"の設定されていれば、不要なホワイトスペースは削除され、レスポンスのサイズを節約します。デフォルトは"true"。
userIp	文字列	API呼び出しを作成したユーザーのIPアドレスを識別します。これによってサーバーサイドアプリケーションからのAPI呼び出しでもユーザー単位でのクォータが強制されます。詳細については Capping Usage。

データ形式

Google+ APIではリソースはJSON データ形式で表されます。例えば、ユーザーのプロフィールを取得するとレスポンスは次のようになるでしょう:

{
  "kind": "plus#person",
  "id": "118051310819094153327",
  "displayName": "Chirag Shah",
  "url": "https://plus.google.com/118051310819094153327",
  "image": {
    "url": "https://lh5.googleusercontent.com/-XnZDEoiF09Y/AAAAAAAAAAI/AAAAAAAAYCI/7fow4a2UTMU/photo.jpg"
  }
}

共通のプロパティ

さまざまなタイプのリソースがそれぞれ独自の形式を持っていますが、ほとんどすべてのリソースに見られる共通のプロパティもたくさんあります。

プロパティ名	値	説明
displayName	文字列	ユーザーのために表示するのに適したリソースの名前です。
id	文字列	リソースを一意に識別するためのプロパティです。与えられた種類（kind）の全リソースはユニークIDを持ちます。idが数値のように見えたとしても、常に文字列として扱われます。
kind	文字列	JSONオブジェクト表現のリソース種別を識別します。未知のオブジェクトをプログラム的にどのようにパースするかを決定する場合に特に有用です。
url	文字列	リソースの主URLまたはパーマリンクです。

ページネーション

例えばアクティビティリストのような、巨大な集合を返す可能性があるリクエストでは、maxResults（デフォルト値:20）を設定してレスポンスに含まれるアイテム数を制限できます。それぞれのレスポンスはまたnextPageTokenプロパティを返します。次のページのアイテムを取得するには、次のリクエストのpageTokenプロパティにこのnextPageTokeの値を与えなければいけません。この手順を繰り返すことで全ての集合を手に入れることができます。

例えば、アクティビティリスト呼び出しはnextPageTokenを含む次のようなレスポンスを返します:

{
  "kind": "plus#activityFeed",
  "title": "Plus Public Activities Feed",
  "nextPageToken": "CKaEL",
  "items": [
    {
      "kind": "plus#activity",
      "id": "123456789",
      ...
    },
    ...
  ]
  ...
}

次のページのアクティビティを取得するには、次のアクティビティリストリクエストにこのトークンの値を渡します:

https://www.googleapis.com/plus/v1/people/me/activities/public?pageToken=CKaEL

先と同様、このリクエストのレスポンスにもnextPageTokenが含まれ、さらに次のページの結果を得るために使用できます。新しいページを得るにはこのサイクルを繰り返します。最後のページでは"nextPageToken"は空白になります。

部分レスポンス

デフォルトでは、リクエスト処理の後にリソースの完全な形式を送り返します。パフォーマンスを向上させるため、サーバーに本当に必要なフィールドだけを送り返すように依頼して、部分的なレスポンスを代わりに受け取ることができます。

部分レスポンスをリクエストするには、fieldsリクエストパラメータを使用して返して欲しいフィールドを指定します。このパラメータはレスポンスボディを返すすべてのリクエストで使用できます。

例

次の例でGoogle+ APIのfieldsパラメータをどう利用するかが分かります。

単純なリクエスト: このHTTP GETリクエストはfieldsパラメータがなく何十ものフィールドを含む全アクティビティリソースを返します。

https://www.googleapis.com/plus/v1/activities/z12gtjhq3qn2xxl2o224exwiqruvtda0i?key=YOUR-API-KEY

部分レスポンスリクエスト: このHTTP GETリクエストは上記のリソースを返しますが、fieldsパラメータを使用していて、返されるデータの量を大幅に削減しています。

https://www.googleapis.com/plus/v1/activities/z12gtjhq3qn2xxl2o224exwiqruvtda0i?fields=url,object(content,attachments/url)&key=YOUR-API-KEY

上のリクエストのレスポンスとして、サーバーはurlフィールドと、contentとattachments.urlだけを含む軽量なobjectだけを含むJSON形式を返します。

{
 "url": "https://plus.google.com/102817283354809142195/posts/F97fqZwJESL",
 "object": {
  "content": "A picture... of a space ship... launched from earth 40 years ago.",
  "attachments": [
   {
    "url": "http://apod.nasa.gov/apod/ap110908.html"
   }
  ]
 }
}

レスポンスは選択されたフィールドとそれを包む親オブジェクトだけを含むJSONオブジェクトになることに注意して下さい。

fieldsパラメータのシンタックスは次で説明します。レスポンスに何が返されるかについての詳細はさらにその後にあります。

fieldsパラメータのシンタックスまとめ

fieldsリクエストパラメータの値の形式は大雑把にXPath シンタックスに基づいています。サポートされるシンタックスを下にまとめ、続く節で追加の例を紹介します。

カンマで分割されたリストは複数のフィールドを選択するために使用します。
a/bはフィールドaにネストされたフィールドbを選択するために使用します。bにさらに含まれるフィールドcを選ぶにはa/b/cを使用して下さい。
特定のサブフィールドだけを要求するフィールドサブセレクタは任意の選択されたフィールドの後に括弧"( )"を追加して指定できます。
例えば: fields=items(id,object/content)はitems配列要素のそれぞれについてアイテムidとobjectのcontentだけを返します。
必要であればフィールドの選択にワイルドカードが使用できます。
例えば: fields=items/object/* はobjectの中のすべてのアイテムを選択します。

さらにfieldsパラメータを使用する例

次の例はfieldsパラメータの値がどのようにレスポンスに影響を与えるかの説明を含みます。

注: すべてのクエリパラメータの値と同様に、fieldsパラメータもURLエンコードされていなければいけません。読みやすさのために、このドキュメントの例ではエンコーディングを省略しています。

フィールド選択: 返して欲しいフィールドを指定。

fieldsリクエストパラメータの値はフィールドのカンマ分割されたリストで、それぞれのフィールドはレスポンスのルートからの相対位置で指定されます。従って、もしリストオペレーションを実行しているならレスポンスは集合で一般的にはリソースの配列を含みます。もし単一のリソースを返す操作を実行しているならフィールドはリソースの相対位置で指定しなければいけません。もしあなたが選択したフィールド（か、もしくはその一部）が配列なら、サーバーは配列の全要素の選択された部分を返します。

以下はactivities.listから取ったいくつかの集合レベルの例です:

例	効果
items	items配列に含まれる全ての要素とそれぞれの要素に含まれる全てのフィールドを返しますが、その他のフィールドは返しません。
updated,items	updatedフィールドと、items配列の全要素を返します。
items/title	items配列の全要素のtitleフィールドだけを返します。 Whenever a nested field is returned, the response includes the enclosing parent objects. The parent fields do not include any other child fields unless they are also selected explicitly.

以下はactivitiesから取ったいくつかのリソースレベルの例です:

例	効果
title	リクエストされたリソースのtitleフィールドを返します。
actor/displayName	リクエストされたリソースのactorオブジェクトのdisplayNameサブフィールドを返します。
object/attachments/url	objectオブジェクトにネストされたattachments配列の全メンバーのurlフィールドだけを返します。

フィールドサブ選択: 選択された要素の一部分を要求。

デフォルトでは、特定のオブジェクトを指定すると、サーバーはオブジェクトを丸ごと返します。選択されたオブジェクトのあるサブフィールドだけを含むようなレスポンスを要求することもできます。それには次の例のように "( )" サブ選択シンタックスを使用して下さい。

例	効果
items(id,url)	items配列に含まれるそれぞれの要素についてidとurlフィールドの値だけを返します。

部分レスポンスを扱う

サーバーはfieldsクエリパラメータを含む妥当なリクエストを処理した後で、要求されたデータと共にHTTP 200 OKステータスコードを送り返します。fieldsクエリパラメータがエラーを発生するか、不当な場合には、サーバーはfields選択の何が間違っているかを伝えるエラーメッセージ（例えば、"Invalid field selection a/b"）と共にHTTP 400 Bad Requestステータスコードを返します。

注: 可能な場合はいつでも、それぞれのクエリの結果を管理できるサイズに抑えられるようにmaxResultsを使用しましょう。そうしなければ、部分レスポンスによって得られるパフォーマンスは実感できないでしょう。