これだけ押さえておけばあらゆるAPIを呼び出せる！ Google APIを使用するための基本

　本連載では、Googleが提供するプラットフォームやサービスに関する情報を定期的に紹介していきます。今回は「Google APIs」と呼ばれる、各種リソースへアクセスするAPIの基礎となる部分を紹介します。Googleは様々なAPIを提供していますが、今回説明する「基本」を学んでおけば、あらゆるAPIを簡単に使うことができるようになります。

---

目次

対象読者

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を簡単に実行してみることが可能です。

Google API Explorer

　API Explorerは、多くのAPIのリファレンスにも埋め込まれています。そうしたリファレンスの画面では、説明されているAPIを実行してみることができます。

Discovery basedな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といったメソッドが並んでいることが確認できます。

Calendars.events

　また、こうしたメソッドには、Google APIの間でかなり共通性があります。例えば、次の表のとおりです。listやgetといったメソッドは、Calendar API以外にも提供されています。

Google APIで共通するメソッド

メソッド	機能
list	一覧を取得する
get	IDを指定して、一件取得する
insert	新規作成する
update	上書きする
patch	部分的に上書きする
delete	指定したIDに対応するものを削除する

　各リソースに対する操作は「リソース名.メソッド名」という表現で定義されています。

　また、これらの操作を複数まとめて一括実行する操作が可能な場合もあります。これはbatchリクエストと呼ばれ、複数の操作を連続して実行する場合に使うと効果的です。Google APIのbatchリクエストにはOData batch processingという通信方式が採用されています。