対象読者
- GoogleのサービスやAPIに興味のある方、悩んだことがある方
- Google Cloud Platformに興味のある方
- GoogleではないAPIの経験がある方（推奨）
必要な環境
- Googleアカウント
- Webブラウザ
- サンプルコードを実行する場合は、Javaの開発環境
Google APIの基礎知識
Googleが提供する大抵のプラットフォームやサービスは、それらのリソースへアクセスするためのAPI（以下、Google API）を提供しています。まずは、Google APIを理解するための基礎となる事項を押さえておきましょう。
APIとの通信方式とDiscovery Document
Google APIと通信する方式には次の2つがあります。
- OAuth1でアクセス許可を得て、ATOM書式で通信する
- OAuth2でアクセス許可を得て、JSON書式でhttpsを使って通信する
前者は古いAPIの通信方式で、徐々に後者に置き換えられています。新たに公開されるAPIは全て後者になっています。今回紹介するAPIも後者であるとします。
後者のAPIはDiscovery based APIと呼ばれます。Discovery based APIの仕様はDiscovery Documentと呼ばれるJSON文書で定義されており、この仕様に準拠しているAPIの大部分は、Google APIs Discovery Serviceという「APIを探すAPI」を使って探すことができます。
また、JSON文書であるDiscovery Documentは、プログラムで処理することができます。これを利用して、Discovery Documentで定義されているAPIを使用するWebアプリケーションを、自動的に生成することもできます。
この仕組みを利用したツールにGoogle API Explorerがあります。Google API Explorerは、Google APIs Discovery Serviceを使ってAPIを取得し、一覧表示してくれますが、それだけにとどまりません。一覧にあるAPIを簡単に実行してみることが可能です。
API Explorerは、多くのAPIのリファレンスにも埋め込まれています。そうしたリファレンスの画面では、説明されているAPIを実行してみることができます。
Discovery basedなAPIは、Googleが提供しているものを利用するだけではなく、自分でも利用できます。Google Cloud PlatformのCloud Endpointsという機能を使えば、API Explorerのようなシンプルなクライアントはもちろん、WebアプリケーションとAndroidとiOS向けのクライアントライブラリを自動生成することもできます。
APIの種類
Googleの様々なプラットフォームやサービスがAPIを提供していますが、どの持ち主のリソースを操作するか、という観点から次の3タイプに分類できます。
Webサービス向けのAPI
最も一般的なAPIで、GmailやGoogle Drive、Google Calendarなどの「個人が使用するWebサービス」のリソースに対するアクセスが提供されます。
例えば、アクセス権限を取得したユーザに対するGmailのスレッドを取得したり、スレッドにラベルをつけたり、Calendarに予定を作ったりというように、特定のユーザが所有するリソースを操作できます。
プラットフォーム向けのAPI
Google Cloud Platformなどで使用するリソースに対するアクセスを提供するもので、Developer Console（後述）のプロジェクトが所有するリソースに対するアクセスが提供されます。
例えば、プロジェクトで使用しているストレージ領域にファイルを書き込んだり、Compute Engineなどのリソースの状態を操作したりできます。
Google Apps向けのAPI
企業向けのプロダクトプラットフォームであるGoogle Appsのリソースに対するアクセスが提供されます。
GmailやGoogle Calendarなどの組織内のユーザが所有するリソースはもちろん、組織内のユーザやグループ、組織情報などの組織が所有リソースも操作できます。
APIで提供される操作の共通性
Google APIで提供される各リソースに対する操作は、RESTに似たメソッドで提供されています。次の画面は、Calendar APIのリファレンスです。左側の"API Reference"から"Events"を選択すると、listやgetといったメソッドが並んでいることが確認できます。
また、こうしたメソッドには、Google APIの間でかなり共通性があります。例えば、次の表のとおりです。listやgetといったメソッドは、Calendar API以外にも提供されています。
| メソッド | 機能 |
|---|---|
| list | 一覧を取得する |
| get | IDを指定して、一件取得する |
| insert | 新規作成する |
| update | 上書きする |
| patch | 部分的に上書きする |
| delete | 指定したIDに対応するものを削除する |
各リソースに対する操作は「リソース名.メソッド名」という表現で定義されています。
また、これらの操作を複数まとめて一括実行する操作が可能な場合もあります。これはbatchリクエストと呼ばれ、複数の操作を連続して実行する場合に使うと効果的です。Google APIのbatchリクエストにはOData batch processingという通信方式が採用されています。
