Google People APIを使ってみる


Google APIに[People API](https://developers.google.com/people/)が公開されたようです。
細かいところは[リファレンス](https://developers.google.com/people/)を見てもらうとして簡単な解説を記載していきます。

## 概要
[Google+ API](https://developers.google.com/+/web/api/rest/)と[Contacts API](https://developers.google.com/google-apps/contacts/v3/)を合わせたようなAPIです。
~~ただし **情報取得に特化**しています。
既存のAPIの上位互換ではないため置き換えるものではありません。~~

**2017-07-06 追記**
登録・更新・削除機能が追加されたようです。
Contacts APIを置き換えると明言されたので、People APIで置き換えられるなら順次対応した方が良いでしょう。（まだContacts APIにあってPeople APIにない機能がある？）
[G Suite Developers Blog: Google People API now supports updates to Contacts and Contact Groups](https://gsuite-developers.googleblog.com/2017/07/google-people-api-now-supports-updates.html)


## API
以下の３つがあります。

* people.get
* people.getBatchget
* people.connections.list

### people.get
ユーザーのプロフィール情報を取得します。
URLで言うとここに出ている情報ですね。
https://aboutme.google.com/u/0/


```REST
GET https://people.googleapis.com/v1/{resourceName=people/*}
```

**e.g.**
Google+のIDを使用した場合、対象ユーザーの公開情報が取得できます。
※このIDはGoogle+プロフィールを表示した時のURL末尾の数字です。Google Apps For WorkであればDirectory APIでのUser.idになります。

```REST
GET https://people.googleapis.com/v1/people/101136005779153122515
```

```json:response
{
 "resourceName": "people/101136005779153122515",
 "etag": "xALpYbJ7M+s=",
 "metadata": {
  "sources": [
   {
    "type": "PROFILE",
    "id": "101136005779153122515"
   },
   {
    "type": "DOMAIN_PROFILE",
    "id": "101136005779153122515"
   }
  ],
  "objectType": "PERSON"
 },
 "locales": [
  {
   "metadata": {
    "primary": true,
    "source": {
     "type": "ACCOUNT",
     "id": "101136005779153122515"
    }
   },
   "value": "ja"
  }
 ],
 "--省略--": ""
}
```


またresourceNameに``people/me``を指定することで認可したユーザーのプロフィールが取得できます。``me``が自身のGoogle+IDのエイリアスということですね。

```REST
GET https://people.googleapis.com/v1/people/me
```


### people.getBatchget
people.getの複数取得バージョンです。
resourceNamesパラメータに複数のresourceNameを指定します。

```REST
GET https://people.googleapis.com/v1/people:batchGet
```


**e.g.**
見やすさのためにURLデコードして記載しています。

```REST
GET https://people.googleapis.com/v1/people:batchGet?resourceNames=people/101136005779153122515&resourceNames=people/101136005779153122515
```

レスポンスはpeople.getと似たような感じなので省略します


### people.connections.list
こちらは連絡先から一覧情報を取得するためのものです。
また、responseには連絡先情報とGoogle+へのリンクが表示されます。（連絡先とGoogle+情報の概要一覧が出てくる感じです）

```REST
GET https://people.googleapis.com/v1/{resourceName=people/*}/connections
```

resourceNameには``people/me``しか指定できないと書かれています。
他人の連絡先みえたらまずいですからね。

※ただし2016/3/1現在バグってるみたいです。people/*にマッチしていればどんなresouceNameであれpeople/meとして扱われています。


**e.g.**

```REST
GET https://people.googleapis.com/v1/people/me/connections
```

```json:response
{
 "connections": [
  {
   "resourceName": "people/c7216717323740958786",
   "etag": "fw5i0/N+AXQ=",
   "metadata": {
    "sources": [
     {
      "type": "CONTACT",
      "id": "6426ee2b8dfcd042"
     }
    ],
    "objectType": "PERSON"
   },
   "names": [
    {
     "metadata": {
      "primary": true,
      "source": {
       "type": "CONTACT",
       "id": "6426ee2b8dfcd042"
      }
     },
     "displayName": "連絡先に登録したユーザー",
     "givenName": "連絡先に登録したユーザー"
    }
   ]
  },
  "--省略--": ""
}
```

電話番号やアドレスは出ません。表示されるのはあくまで概要です。
詳細を取得するためにはresourceNameの``people/CXXXXXXX``をつかって先ほどのpeople.getを叩きます。
※getBatchgetが用意されているのは1件1件叩くのは非効率だからでしょうね。

**e.g.**

```REST
GET https://people.googleapis.com/v1/people/c7216717323740958786
```

```json:response

{
 "resourceName": "people/c7216717323740958786",
 "etag": "bXmHGvSA/ms=",
 "metadata": {
  "sources": [
   {
    "type": "CONTACT",
    "id": "6426ee2b8dfcd042"
   }
  ],
  "objectType": "PERSON"
 },
 "names": [
  {
   "metadata": {
    "primary": true,
    "source": {
     "type": "CONTACT",
     "id": "6426ee2b8dfcd042"
    }
   },
   "displayName": "連絡先に登録したユーザー",
   "givenName": "連絡先に登録したユーザー"
  }
 ],
 "addresses": [
  {
   "metadata": {
    "primary": true,
    "source": {
     "type": "CONTACT",
     "id": "6426ee2b8dfcd042"
    }
   },
   "formattedValue": "住所！",
   "type": "work",
   "formattedType": "Work",
   "streetAddress": "住所！"
  }
 ],
 "emailAddresses": [
  {
   "metadata": {
    "primary": true,
    "source": {
     "type": "CONTACT",
     "id": "6426ee2b8dfcd042"
    }
   },
   "value": "contactuser01@example.com",
   "type": "work",
   "formattedType": "Work"
  }
 ],
  "--省略-- ": ""
}
```


## 余談
今までのGoogleAPIのパターンではpeople/まで固定で{peopleId}部分が可変（キー）という書き方をしていたのですが本APIは{people/*}が可変という書き方をしているのでちょっと違和感がありますね。
またmaxResultsではなくpageSizeというパラメータで件数を制御しているのも違和感が。設計方針の変更なんでしょうかね。


## 参考サイト
https://developers.google.com/people/