R + Google API 系パッケージのプロジェクトテンプレートと認可フローのまとめ

前の記事 では Docker + RStudio Server プロジェクトの GitHub テンプレート terashim/rstudio-docker-project-template を紹介しました。 このテンプレートから派生して、Google API 系パッケージを使った R プロジェクトのテンプレートを作成しました:

terashim/rstudio-docker-google-project-template

API を使うには認可が必要になりますが、その際 サービスアカウント を作成して利用するのがおすすめです。 Google Cloud Console でサービスアカウントを作成して鍵ファイルをダウンロードし、 .env ファイルの変数 SERVICE_ACCOUNT_KEY_JSON にその保存先パスを指定すれば使い始めることができるようになります。

このテンプレートの使い方についてより詳しくはリポジトリ内の README や サンプルコード をご覧ください。

以下、この記事では Google API の利用における認可の仕組みや R パッケージの開発状況について整理します。

Google はさまざまなサービスをプログラムから利用できるようにするための API を提供しています。 Google ドライブ や Google スプレッドシート は広く利用されているかと思います。BigQuery を使って分析を行っている方も多いかもしれません。 いずれのサービスも API を通してプログラムから呼び出すことができます。

これらの API を R から利用するため、さまざまなパッケージが開発されています。

この表を見ればお分かりのように、 Jennifer Bryan 氏 と Mark Edmondson 氏 がこれらのパッケージ開発を牽引しています。

さまざまな API がありますが、いずれも最初に認可が必要になる点が共通しています。

このとき、主に２種類の認可フロー

• サービスアカウント による認可
• 通常の Google ユーザーアカウントによる認可

のどちらかが利用されます。

このテンプレート は初期設定として

• サービスアカウントを作成してそのJSON鍵ファイルをダウンロードし、保存先パスを .env ファイルの変数 SERVICE_ACCOUNT_KEY_JSON で指定する
• OAuth 2.0 クライアントを作成してそのJSONファイルをダウンロードし、保存先パスを .env ファイルの変数 OAUTH2_CLIENT_JSON で指定する

のどちらかを行えばその認可フローが利用可能になるよう設計しました。

R で API を利用してデータ処理や分析、可視化等のタスクを行う場合、多くのケースではサービスアカウントを使うのがおすすめです。

サービスアカウントや OAuth 2.0 クライアントを作成する具体的な操作手順についてはこの記事では触れません。詳しくは Google の公式ドキュメントや gargle パッケージのドキュメントに書かれていますのでそちらをご覧ください:

• サービス アカウントの作成と管理  |  Cloud IAM のドキュメント  |  Google Cloud
• サービス アカウントキーの作成と管理  |  Cloud IAM のドキュメント  |  Google Cloud
• サーバー間での本番環境アプリケーションの認証の設定  |  Google Cloud
• エンドユーザーとして認証する  |  Google Cloud
• How to get your own API credentials • gargle

gargle は Jennifer Bryan 氏らによって開発されたパッケージで、Google API を利用する際のさまざまな認可フローを統一的に扱うためのものです。 ユーザーが gargle パッケージを直接使うことは少なく、主にパッケージ開発者向けのパッケージという位置づけになっています。

同氏作のパッケージである googledrive, googlesheets4 などはこれをベースにしています。

googleComputeEngineR, googleAnalyticsR, searchConsoleR など主に Mark Edmondson 氏の開発したパッケージ群では、 その認可フロー部分が googleAuthR パッケージによって実装されています。

googleAuthR はバージョン 1.0.0 で gargle パッケージをベースにした実装となりました。

したがって、現在では主要な Google API 系パッケージはすべて認可フローに gargle を利用している状況となっています。

プログラムが Google API を通して何か操作を行うためには、まず最初に認可を行う必要があります。この認可機構は OAuth 2.0 の標準に基づいて実装されています。

上述の通り、主に通常の Google ユーザーアカウントによる認可とサービスアカウントによる認可の２種類が利用されています。

この認可方式ではプログラム、ユーザー、Google の３者間でのやりとりが発生します。

まず、プログラムの開発者はあらかじめ OAuth 2.0 クライアントを作成しておきます。

認可フローが開始すると以下のようなステップを進みます:

• プログラムはユーザーのブラウザで Google 同意画面を開かせる。
• ユーザーはブラウザの Google 同意画面でプログラムによる操作を承認する。
• Google はプログラムが待機しているURLに認証コードを付けてブラウザを遷移させる。
• 認証コードを受け取ったプログラムはそれを使って Google からアクセストークンを取得する。

途中でユーザーによるブラウザ操作が発生するので、Rではインタラクティブモードでのみこの認可フローが利用可能です。 Rのスクリプトをバッチモードで動かしたい場合はサービスアカウントによる認可フローを利用することになります。

Google API 系のパッケージでは、パッケージ開発者があらかじめ OAuth 2.0 クライアントを作成してパッケージに埋め込んでいることが多いようです。 しかし、この OAuth 2.0 クライアントはパッケージ利用者の間で共有されるので、API呼び出し回数の割り当て制限も共有されます。 よって、そのパッケージを利用している他の誰かが API を多数回呼び出すと回数制限に達してしまって使えなくなってしまう可能性があります。 そのため、パッケージにデフォルトの OAuth 2.0 クライアント埋め込まれている場合でも、それは練習やデモの用途のみに利用するものとし、なるべく自分で OAuth 2.0 クライアント を作成して使うことが推奨されています。

Mark Edmondson 氏による googleAuthR パッケージやそれを利用したパッケージ群（googleAnalyticsR, searchConsoleR, など）では、 環境変数 GAR_CLIENT_JSON に OAuth 2.0 クライアントのJSONファイルパスを設定してあればそれを使用するようになっています。 その他 googlesheets4 などのパッケージでは、httr::oauth_app 関数の引数で OAuth 2.0 クライアント情報を指定して使う形になっているようです。

参考:

• Google authentication types for R • googleAuthR
• Edit and view auth configuration — gs4_auth_configure • googlesheets4

サービスアカウント はマシン間での認証を行うために Google が用意している仕組みで、いわばロボット用の Google アカウントのようなものです。 サービスアカウントによる認可フローではユーザーによるブラウザ画面上での操作が発生しないので、サーバ上で動作する自動バッチ処理等に利用することができます。

サービスアカウントを作成すると、 [email protected] のようなメールアドレスが発行されます。 例えばそのメールアドレスに対して Google ドライブ上のファイルへのアクセス権限を与えれば、Google Drive API を通してそのファイルにアクセスすることができるようになります。 サービスアカウントで BigQuery の操作などを行いたい場合には、Cloud IAM による権限付与 が必要になります。

サービスアカウントを利用するには、以下の手順を踏みます:

• サービスアカウントを作成する。
• サービスアカウントに対して必要な権限を与える。
• サービスアカウント鍵ファイルを作成してダウンロードする。
• 環境変数や関数の引数などでサービスアカウント鍵ファイルの保存場所をプログラムに伝える。

具体的な操作手順や各 API の利用にあたって必要となる権限については Google のドキュメントやパッケージのヘルプ等を参照してください。

gargle パッケージでは、 環境変数 GOOGLE_APPLICATION_CREDENTIALS にサービスアカウント鍵のファイルパスが指定されていればそれを利用するようになっています。 googleAuthR パッケージもバージョン 1.0.0 以降は gargle パッケージをベースにした実装となっているので、 いまやほとんどのユースケースでは環境変数 GOOGLE_APPLICATION_CREDENTIALS を指定すればサービスアカウントによる認可の設定が完了します。

このテンプレート では、 .env ファイルの変数 SERVICE_ACCOUNT_KEY_JSON でサービスアカウント鍵ファイルのパスを指定すれば、 そのファイルが Docker コンテナ内の /home/rstudio/secrets/service_account_key.json にマウントされるようになっています。 そして、環境変数 GOOGLE_APPLICATION_CREDENTIALS にそのマウントされたファイルパスを設定しています。

サービスアカウントによる認可フローはインタラクティブな操作が不要なので、Rのバッチモードでも利用できます。 慣れていないと初期設定が多少面倒に感じるかもしれませんが、実際にはそれほど難しいものではありません。 また、同意画面での操作が要らなくなるのでインタラクティブモードでコードを実行する場合も作業が楽になります。 可能ならばなるべく通常のユーザーアカウントによる認可よりもこちらを利用することをお勧めします。

最後に RStudio Server で通常の Google ユーザーアカウントによる認可フローを利用する際の注意点について触れておきます。

認可フローが開始すると、gargle はブラウザで同意画面を開くとともにローカルサーバを起動し、ブラウザが同意画面から http://localhost:1410 のURLにリダイレクトされてくるのを待機します。

RStudio デスクトップ版ではなく RStudio Server を利用している場合、デフォルト設定のままではブラウザが同意画面からこのURL http://localhost:1410 にリダイレクトされてきても認証コードを受け取ることができず、認可フローが完了しません。

この認可フローを機能させるためには、まずローカルホストの 1410 からサーバ（コンテナ）のポート 1410 へとトラフィックを転送することが必要です。 加えて、ローカルサーバの起動に使われる httr パッケージはデフォルトでポート転送されたアクセスを許可していないので、環境変数 HTTR_LOCALHOST=0.0.0.0 を設定することでこれを許可する必要があります。

このテンプレート ではあらかじめ Dockerfile と .Renvirion ファイルでこの対応を行っています。

Docker + RStudio Server 環境で Google API を利用したプロジェクトのテンプレートリポジトリを作成しました。 また OAuth 2.0 の仕組み、それに基づいた Google API における認可フロー、それを利用するための R パッケージについて整理しました。このテンプレートや記事が何かのお役に立てば幸いです。

今後は R + Google API の具体的な活用例についてもご紹介できればと思っています。