Google Analytics の API を用いて簡単にデータを取得できる gem を作りました

追記

2018/04/13 14:35:00 ごろに v1.1.1 をリリースしました。このバージョンで引数の指定方法が変わっています（キーワード引数に変更）。以下の説明では最新のものに修正していますが、旧版をお使いの方はご注意下さい。

きっかけ

Ruby を用いて Google Analytics のデータを API で取得する場合、Legato という gem を使うのが一般的かと思います*1。

しかしながらこの Legato は私のような初心者が使うのには難しい点が多くありました。そこで、簡単な設定ファイルを書くだけでデータを取得できる Legato のラッパーとなる gem を作りました。

simple_ga_reporting

simple_ga_reporting というのがその gem になります。ソースコードは以下の場所にあります。

gem としても公開済みです。

simple_ga_reporting | RubyGems.org | your community gem host

使い方

使い方を説明します。README に網羅してはいますが*2、改めてここでも説明します。

使い方の大まかな流れ

使うための大まかな流れは以下のとおりです。

1. API を用いるために private_key と client_email を取得する（Google Cloud Platform上）
2. Google Analytics の API を有効にする（Google Cloud Platform上）
3. Google Analytics のユーザアカウントに client_email のユーザを登録する（Google Analytics上）
4. 設定ファイルを3つ作成する
   • 4-1. private_key と client_email を記載した設定ファイルを作成する あるいは この2つをメソッドの引数で設定する（必須）
   • 4-2. 取得したいデータの条件を記載した設定ファイルを作成する（必須）
   • 4-3. データをフィルタリングする場合はフィルタの設定ファイルを作成する（任意）
5. データを取得するためのアプリケーションを書く
6. アプリケーションを実行してデータを取得する

使い方の詳細

詳しい使い方を一つ一つ順を追って説明していきます。

1. API を用いるために private_key と client_email を取得する（Google Cloud Platform上）

private_key と client_email を取得します。少々長くなりますので、別の記事にまとめました。

2. Google Analytics の API を有効にする（Google Cloud Platform上）

Google Cloud Platform で サービス アカウント を取得した後に利用したい API を有効にしなければいけません。

メニューから「API とサービス」→「ライブラリ」とたどります。すると API を検索することができますので、「Analytics」と入力して絞り込みます。

「それっぽい」結果がいくつか出てきますが、Analytics API を選びます。Google Analytics Reporting APIではないです*3。Analytics API を選択後、有効化しましょう。

Google Analytics のユーザアカウントに client_email のユーザを登録する（Google Analytics上）

「1.」で取得できた client_email ã‚’ Google Analytics のユーザとして登録します。

まず Google Analytics の管理画面に行きます。

https://analytics.google.com/

一番右の「ビュー」の列から「ユーザー管理者」を選択します。「ユーザー管理者」のリンクが存在しない場合は操作しているアカウントに権限がありませんので、権限があるアカウントでログインをし直しましょう。

「ユーザ管理者」の画面に遷移すると、右上に「+」マークが見えます。このマークをクリックして新規ユーザーの登録を行います。

登録するユーザのメールアドレスは client_email のアドレスになります。付与する権限は「表示と分析」で十分です。

4. 設定ファイルを3つ作成する

設定ファイルを作成していきます。

4-1. private_key と client_email を記載した設定ファイルを作成する あるいは メソッドの引数で設定する（必須）

Google Analytics へのアクセスを API 経由で行うために private_key と client_email を記載した設定ファイルを作成します。デフォルトの保存場所は config/key_and_email.yml です。

設定ファイルのフォーマットは YAML です。private_key と client_email をキーに持ち、値は「1.」で取得した値となります（下記参照）。

private_key: "-----BEGIN PRIVATE KEY-----\nMIIEここに長い文字列が入るEqw==\n-----END PRIVATE KEY-----\n"
client_email: "[email protected]"

※v1.3.0 にて、上記のファイルを用いずに SimpleGaReports.filtered_results(private_key: 'FOO', client_email: 'BAR') のような形で引数として設定することもできるようになりました

4-2. 「取得したいデータの条件」を記載した設定ファイルを作成する（必須）

Google Analytics で「取得したいデータの条件」を記した設定ファイルを作成します。ファイルのフォーマットは YAML です。デフォルトの保存場所は config/ga_reporting_config.yml です。このファイルを複数作ることで複数のデータ取得条件を使い分けることができます。

実際のファイルの例を示しましょう。

profile_name: my_profile_name
start_date: 2018-04-01
end_date: 2018-04-05
metrics:
  - users
  - pageviews
dimensions:
  - pagePath
  - pageTitle
sort:
  - -pageviews
  - -users
filters:
  - chrome_or_fx
  - happy_page
limit: 20

上記の設定ファイルにより取得されるデータは次のとおりです。

• 「my_profile_name」というビュー名（プロファイル名）のデータで、
• 取得データの日付の範囲は 2018-04-01 〜 2018-04-05 で、
• 指標（メトリクス）は users と pageviews で、
• ディメンションは pagePath と pageTitle で、
• 結果の並び順は「pageviews で降順ソートしたものを users で降順ソートしたもの」で、
• フィルターとして chrome_or_fx と happy_page というものを用いて、
• 表示件数の最大数を 20 とする

この設定ファイルで指定できるキーは Legato で定義されているキーになります。具体的には以下のとおりです。

• profile_name
• start_date
• end_date
• metrics
• dimensions
• sort
• filters
• limit
• sampling_level

キーの詳細は 公式ドキュメント をご覧ください（非常に詳しいです）。

それぞれのキーについて以下で説明をします。

profile_name（必須）

データ取得の対象とする「プロファイル名（ビュー名）」です。「プロファイルID（ビューID）」ではなく、「プロファイル名（ビュー名）」を指定して下さい*4。

start_date（必須）

データを取得する開始日です。書式としては以下のものが認められています。

• 2018-04-01
• today または yesterday
• 14daysAgo
  • 1日前の場合も 1daysAgo と複数形になります

end_date（必須）

データを取得する終了日です。書式は start_date と同一です。

metrics（必須）

日本語で「指標」と呼ばれるものです。このキーに取り得る値については公式ドキュメントを参照しましょう（非常に詳しく、便利です）。

以下のブログも大変に参考になります。

deimensions（任意）

日本語で「ディメンション」と呼ばれるものです。このキーに取り得る値については公式ドキュメントを参照しましょう（非常に詳しく、便利です）。

以下のブログも大変に参考になります。

sort（任意）

取得されたデータをソート（並び替え）する際に指定します。指定された値の列でソートされます。値の前に - 記号が付与された場合は「降順」、何も記号がない場合は「昇順」となります*5。

filters（任意）

取得されたデータにフィルターをかける場合に指定します。値として指定する文字列は「適用するフィルタメソッド名」になります。重ねがけも可能です（順不同）。

このキーを用いる場合には別途フィルターファイルを作成することが必要です。フィルターファイルの作成方法は「3-3.」にて説明します。

limit（任意）

取得するデータの行数の上限値を指定します。デフォルトでは 100 です。

sampling_level（任意）

取得するデータの「精度」を指定します。デフォルトで HIGHER_PRECISION に設定しています。他に FASTER と DEFAULT があります。精度が高いほど処理時間がかかるのですが、私がこれまでに試した範囲では、この値が異なることによる実行速度の差は感じられませんでした。

4-3. データをフィルタリングする場合はフィルタの設定ファイルを作成する（任意）

取得結果にフィルターをかける場合にはフィルターファイルを書くことが必要です。フォーマットは Ruby のモジュールです。

具体例で説明した方が分かりやすいと思いますので、以下に示します。

module Filters
  def chrome_or_fx
    filter :chrome_or_fx, &lambda { contains(:browser, 'Chrome|Firefox') }
  end

  def happy_page
    filter :happy_page, &lambda { contains(:pagePath, '\A.*happy.*\z') }
  end
end

上記のフィルターファイルを説明します。

• モジュール名は Filters となっており、これは固定です
• モジュールの中にメソッドを用いてフィルターを指定します
  • メソッド名は任意ですが、フィルター名と同一にした方が分かりやすいとは思います
• フィルター作成の際には「フィルターメソッド名」と「フィルターの内容」を指定します
  • 「フィルターメソッド名」はシンボルで指定します
    • 上記で言えば :chrome_or_fx と :happy_page です
  • 「フィルターの内容」はブロックオブジェクトで指定します
    • 上記で言えば &lambda のブロック引数の部分です
    • contains などの演算子に何を取れるかは Legato のドキュメント を参照して下さい
    • AND条件 ã‚„ OR条件 は与える正規表現で指定できます
      • フィルタを「重ねがけ」しても AND条件 を作れます

4. データを取得するためのアプリケーションを書く

設定ファイルが用意できたらいよいよデータを取得するためのアプリケーションを書きます。こちらもサンプルコードを見てみます。

注意点として、「設定ファイル名のパスを指定する場合は、先頭に『./（ドットスラッシュ）』を必ず付与してください」*6。

require 'simple_ga_reporting'

SimpleGaReports.configure(report_config: './bar/my_ga_reporting_config.yml', filters: './foobar/filters.rb', start_date:
'2daysAgo', limit: 100)
results = SimpleGaReports.filtered_results(key_and_email: './foo/my_key_and_email.yml')

results.each do |result|
  puts '==================================='
  puts result['pagePath']
  puts result['pageTitle']
  puts result['pageviews']
  puts result['users']
end

上記のコードを追いかけていきます。

• 1行目は gem ã‚’ require しています。実行するまでには gem をインストールしておきましょう
• 3行目で「データの取得条件の設定ファイル」と「フィルタ設定ファイル」を読み込んで設定を確定させています
  • SimpleGaReports.configure は固定のクラスメソッドです
  • 引数は次のとおりです
    • 第一引数には report_config をキーとして「データの取得条件の設定ファイル」の場所を指定します（省略時はデフォルトの場所）
    • 第二引数には filters をキーとして「フィルタ設定ファイル」の場所を指定します（指定は任意です）
    • 第三引数以降には「データの取得条件の設定ファイル」の設定項目で上書きしたい項目を個別に指定できます（指定は任意です）
• 4行目のメソッド実行により結果が取得できます
  • SimpleGaReports.filtered_results は固定のクラスメソッドです
  • 引数には key_and_email をキーとして「private_key と client_email を記載した設定ファイル」の場所を値に指定します（省略時はデフォルトの場所）
  • 戻り値は Legato::Query です
    • 詳細は Legato のドキュメント を参考にして下さい
• 6行目 〜 12行目 で具体的なデータを取り出しています
  • eachメソッドでバラしたオブジェクトに対してキーを指定することで値を取り出しています
  • キーに指定できる文字列は（もちろん）設定ファイルに記載した文字列です

5. アプリケーションを実行してデータを取得する

「4.」のコードを、例えば my_sample_app.rb と保存して実行すれば以下の結果が得られます。gem のインストールは予め済ませておいて下さい*7。

各種設定ファイルの内容は「4-1. 〜 4-3.」の内容を用いたものとします。

$ ruby ./my_sample_app.rb
===================================
/i_am_happy.html
I am HAPPY!
10000
1000
===================================
/happy/index.html
HAPPY TOP
9000
900
===================================
/path/to/happy.html
Are You Happy?
8000
800
===================================
/happy.php
HAPPY CHECK!
7000
700
===================================
......

Rails で使う場合

Ruby on Rails で用いる場合に特別なことは必要ありません。Gemfile に追加して $ bundle install すればよいだけです。設定ファイルの位置はデフォルトから変更したほうがスマートになりそうです。

TODO

• 「取得したいデータの条件を記載した設定ファイル」の中に記載する「プロファイル」（ビュー）の指定は、現在は「プロファイル名（ビュー名）」でしか指定できません
  • プロファイルID（ビューID）でも指定できるようにする
• クエリパラメータ中の以下の3つについては設定がまだできていない
  • offset
  • quota_user
  • segment_id
    • ただし「セグメント」の内容は実質的にはフィルタをかけた場合と同一であるので、フィルタを用いればセグメントと同等の処理は実現できます
      • コードベースで管理できることも考えると、そちらの方が良いように思えます

公式ドキュメント一覧

• Core Reporting API - Reference Guide
  • https://developers.google.com/analytics/devguides/reporting/core/v3/reference
• Dimensions & Metrics Explorer
  • https://developers.google.com/analytics/devguides/reporting/core/dimsmets
• Query Explorer
  • https://ga-dev-tools.appspot.com/query-explorer/
• API Rate Limits
  • https://developers.google.com/analytics/devguides/reporting/core/v3/limits-quotas

参考書籍

Google Analytics の用語の意味や基本的な操作方法、実務に使う際の具体的な考え方などについては「わかばちゃんと学ぶ Googleアナリティクス」が大変に分かりやすいです。

著者の湊川あいさんは「わかばちゃんと学ぶ Git使い方入門」の著作でも有名です。いずれの著作においても読者の視点を大切にした内容になっていて、自己満足に終わっていない*8ところが素晴らしいと思います。

余談

gem を作るために費やした時間より、ドキュメント（この記事も）を書くために費やした時間の方が長かったですね……。

*1:Legato の前身として Garb という gem があります

*2:書くのにめちゃくちゃ時間がかかった……

*3:この理由については詳しく調べていないです

*4:ここは修正したい

*5:プラス記号をつけるとエラーになるので注意して下さい

*6:イケてない仕様ではあるので、そのうち直します

*7:$ gem install simple_ga_reporting または Gemfile に gem 'simple_ga_reporting' と記載の上で $ bundle install

*8:削ぎ落とすところは削ぎ落とす