今まで、Cloud Monitoring のカスタムメトリックスを打つために、サンプルを改造する程度の理解しか無かったのですが、ある程度自分の頭で整理出来たので残します。GCP(Google)におけるAPIクライアントライブラリについて、入門からAWSとの違いについて。

Google API Client Library概要

Google(GCP) の各種サービスのAPIを呼び出すためのライブラリです。 ここで言うGCPには、GAE, GCEは勿論、G-Suite(旧Apps) や Mapsも含みます。

主に何をやってくれる？

まず、基本的な部分の説明ですが、APIを呼び出すためには

1.認証 (ヘッダなどに込める)
2.https による RESTfulな操作

が必要です。といいますか、これだけあれば他は不要です。 つまり、AWSだろうがGoogleだろうが、 curl(にかぎらず httpsが喋れるクライアント) があれば、あとは認証情報さえどうにかすれば完了です。 Google API Client Library (API Clientと略) は、シンプルに 上記機能を提供します。特に面倒な 1. 認証 が大きな役目であり、それ以外の機能はとても 薄い実装 といえます。

理論よりさきに実装

書いていて先にコードを書いたほうがいいと思ったので晒します。(文章の流れは無視)

import httplib2
from apiclient import discovery
from oauth2client.client import GoogleCredentials

credentials = GoogleCredentials.get_application_default()
service = discovery.build('monitoring', 'v3', credentials=credentials)
req = service.projects().timeSeries().list(
        name=project_resource,
        filter=filter_strings,
        interval_endTime=end_time.isoformat(),
        interval_startTime=start_time.isoformat(),
        fields="timeSeries.points.value"
        )
ret = req.execute()

project_resource など、service.projects().timeSeries().list() の中の引数は実際のコードの抜粋なので参考程度にしてください。これはmonitoring.projects.timeSeries.listのコールとなります。

https://developers.google.com/apis-explorer/#search/monitoring.projects.timeseries.list/m/monitoring/v3/monitoring.projects.timeSeries.list

コード解説

credentials = GoogleCredentials.get_application_default() 特に触れなくていいいと思います、
service = discovery.build('monitoring', 'v3', credentials=credentials)これも問題無いでしょう、
req = service.projects().timeSeries().list(...がなんとも気持ち悪いコードだと思います(AWS脳には)。なんでわざわざメソッドになるの？ということですが、ここが Client APIの肝です。IPythonなどのREPLを使えばわかりますが、
service.projects(). まで打って 補完しても候補が出てきません。メソッドなので当たり前といえばそうですが、service.projects() を評価して初めて timeSeries リソース(クラス)が存在することが分かりのです。試しに().のチェーンをやめて、1つずつ変数に込めて見て下さい。
つまり、動的にAPIコールのためのクラスを生成しているのです。

また、メソッドの引数(APIパラメータと引数の名前マップ) を確認したいなら

 .__DOC__

を参照すればわかります。IPythonなら ? でも見えます。

Google API Client Library概要 再び

薄い実装・薄い実装

やり玉にAWSを上げると、AWSのSDKは非常にぶ厚い実装です。上記で述べた認証は勿論、各種サービス毎に、1API毎に細かくclass-methodを実装し、各サービスを網羅しています。

それに対して Google の API Client は API Clientのソースコード自体に、各サービスが持っている APIを細かく実装するということは行っておらず、classやresourceをダイナミックに取得・生成することにより、ものすごくコンパクトな実装になっています。

1.認証についてはどちらも同じ
2.API操作部分については、 AWSが泥臭く全サービス毎に実装しているのに対して、Googleは API clientの中で自動生成している

優劣は一旦置いておいて、
AWS SDK は AWS CLI とほぼ同じ領域をカバーする実装であるのに対し、
gcloudコマンド と Google API Client は 全くカバーする範囲が異なります。

gcloud に近い実装としては、 API Client ではなくGoogle Cloud Client Libraryというものが対応しています。

GoogleCloudPlatform/google-cloud-python
google-cloud-python - Google Cloud Client Library for Python
GitHub

github.com

ただしこちらはまだ開発中であるためか、GCE等のサービスには対応していなかったりします。とりあえずAWS SDKに近いのはこちらで、AWS脳のひとはすんなり入れると思います。

薄い実装の利点

APIを作る側(この場合はGoogle)にとってはとてもメリットが大きいです。ここでもAWS SDKと比較しますが、APIの数だけSDKのclass-methodとして実装しているので、APIの仕様ドキュメントは勿論、AWS SDKでもほぼ同じ内容のドキュメントを用意、さらに各種言語毎に作成することになり、かなりのリソースを割くことになります。無論、潜在的なバグも多く含むことになります。
対して、API Clientのような実装の場合、各APIのドキュメントはありますが、API Client側にひとつひとつの対応class-methodのドキュメントを用意する必要がありません。出来ないといったほうが正しいかもしれません。APIs Explorer を使えばOAuth2 で実際に打てるので、四の五の言わずに打って試せ！そしてそれをコードにしろ！ というスタンスかもしれません。

また、API本体に仕様変更があっても、API Client側の実装はまず変更不要となるはずです。(使う側は堪ったもんではないですが)

この考え方・実装は、自分がAPIの提供側となった時、とても参考になると思う。

薄い実装の欠点

一言で言うと取っ付きにくい
私個人の感覚ですが、AWS SDKを使ったことがある人で、APIなんて curlさえあれば呼べると分かっていない人(つまりSDKなんて必須でないことをわかっている人以外)、SDKとは丁寧なドキュメントがあるのが正しいと思っている人は、まずそう感じると思います。それをGoogle自身も感じているため Google Cloud Client Library を作っているのだと思います。私も、取っ付きにくいと感じました。

また、根本的な話ですが、GCPは結構頻繁にAPIを弄ります。破壊的な変更は v1,v2 などと旧バージョンを残した上で、エンドポイントが変わる(増える)ことがほとんどですが、パラメータが増える等の対応があった場合、確かに API Client自体は影響受けないですが、API使う側の実装は当然変更となります。ただし、この点は 厚い実装でも同じですし、厚い実装と違って新機能のためにわざわざ API Clientのバージョンを上げる必要が無い点は利点に述べた通りです。

まとめ

  • Google API Client Library は主に認証の面倒を見てくれる
  • Google API Client Library の API を呼ぶ部分の実装はかなり 薄い
  • AWS SDK のような 厚い実装が良いなら Google Cloud Client Library を待つ？

自分がAPIを提供する側だったら、この薄い実装の方がいいなとは思いました。最近は自動生成とかできますけどね。。

元記事はこちら

「Google API Client Library 入門」