rubyのGoogleアナリティクスAPI用ラッパーライブラリ「garb」が面白い


Googleのサイトにruby用のGoogleアナリティクスAPIラッパーは「garb」と「Gattica」の2種類が紹介されています。

そのうちの「Garb」を使ってみたら、案外面白かったので紹介します。

https://github.com/vigetlabs/garb

*ここに記載されているrubyのコードは基本的にruby1.9系のものを利用しています

 

簡単な使い方

Garbのgithubのページには、READMEやWikiなどがあるのですが、結構不親切な感じになっているので、まず簡単な使い方を紹介します。

インストール

インストールは、たぶん下記コマンドでできます

gem install garb

実行時に色んなエラーが出てくる場合は、githubからGemfileを持ってきて、

bundle install

とすれば、必要なgemファイルがインストールされると思います。

 

ログイン

OAuthを使ったログインもできますが、通常はシングルユーザーログインで十分だと思います。
こんな感じで簡単にログインできます。

Garb::Session.login('sample@gmail.com', 'password')

 

プロファイルを選択する

エクスポートしたいデータが入っているプロファイルを選択します。

Web Property ID (UA-XXXXXX-Xってやつ)だけで簡単に選択できます。

profile = Garb::Management::Profile.all.detect {|p| p.web_property_id == 'UA-XXXXXXX-X'}

1つのWeb Property IDで複数のレポート(テーブル)を作成した場合は、最初に表示されるものが選択されてしまいます。

そのような場合、個別のレポートID(table ID)で指定することもできます。

profile = Garb::Management::Profile.all.detect {|p| p.table_id == 'ga:xxxxxxxxx'}

table_idはData Feed Query Explorerで調べると楽です。

http://code.google.com/intl/ja/apis/analytics/docs/gdata/gdataExplorer.html

こんな感じのコードでtable_idを出すこともできます。

profile.each do |x|
    puts "UA Account: #{x.web_property_id}ttitle: #{x.title}ttable_id: #{x.table_id}"
end

 

必要なデータを定義する

次に、どのディメンションとメトリクスを使うのかを定義します。

定義方法は簡単です。
「metrics」のところに、使いたいメトリクスを並べて、
「dimensions」のところに、使いたいディメンションを並べるだけです。
ページごとのセッション数、PVが知りたい場合、次のようなコードになります。

class Upvs
    extend Garb::Model

    metrics :unique_pageviews, :pageviews
    dimensions :page_path
end

利用できるディメンションとメトリクスの種類は Data Export APIのページを参考にしましょう。

http://code.google.com/intl/ja/apis/analytics/docs/gdata/dimsmets/dimsmets.html

ただ、少し注意が必要です。
ga:visitsやga:pageviewsなどは、そのまま単純に「ga:」を削除して、
:visitsや:pageviewsにすればOKです。
しかし、ga:unique_pageviewsやga:pagePathなどの大文字が含まれている場合は、
大文字を「アンダースコア+小文字」にする必要があります。
ga:pagePathの場合は、「:page_path」となります。
めんどうな人は、active_supportを利用して、

str = ga:pagePath
str.underscore.gsub(/^ga:/,"")

みたいな形で、変換させてあげれば良いと思います。

 

データを取り出す

データを取り出す方法も簡単です。
とりあえず取るという場合は、これで十分です。

res = profile.upvs
res.each do |x|
    puts "#{x.page_path},#{x.unique_pageviews},#{x.pageviews}}"
end

これだけで、ページ別のPVとセッション数が取れます。
コード中にある「profile」は上で指定したレポートのプロファイルです。
「upvs」というのは、上で作ったClass「Upvs」のUを小文字にしたものです。
「profile.upvs」とするだけで、Googleアナリティクスのサーバーからデータを引っ張ってくることができます。

ちなみに、「Upvs.results(profile)」でも同様のデータを出すことが可能です。
あとは、rubyらしくeachでイテレーションをかけて、フォーマットを整えて吐き出せば完了です。

 

フィルター・期間・ソートの設定

このままじゃ、使い物にデータなので、期間を指定したり、フィルターを掛けたりしましょう。
これらの設定は、「profile.upvs」の引数で指定します。

res = profile.upvs(
    :filters => {:page_path.eql => '/'},
    :limit => 1000,
    :offset => 1001,
    :sort => :unique_pageviews.desc,
    :start_date => Time.parse("2011-11-01"),
    :end_date => Time.parse("2011-11-02")
)

res.each do |x|
    puts "#{x.page_path},#{x.unique_pageviews},#{x.pageviews}}"
end

フィルターは、:filters => {フィルター}のようにして記述します。

上の例では、”/”とURLが一致したデータのみ抽出としています。

フィルターで利用できるオペレーターは以下の通りです。

【メトリクス用】
eql => ‘==’(完全一致),
not_eql => ‘!=’(完全不一致),
gt => ‘>’(大なり),
gte => ‘>=’(大なりイコール),
lt => ‘ ‘ ‘==’(完全一致),

【ディメンション用】
does_not_match => ‘!=’(完全不一致),
contains => ‘=~’(正規表現一致),
does_not_contain => ‘!~’(正規表現不一致),
substring => ‘=@’(文字列が含まれる),
not_substring => ‘!@(文字列が含まれない)’

次に期間の設定です。
期間はrubyの日付オブジェクトで指定します。
Timeクラスをrequireして、

require 'time'
Time.parse("2011-11-01")

のようなやり方が簡単です。後述しますが、active_supportを使うとより便利になります。

次に、ソートです。
ディメンション・メトリクスのどれかを基にデータを並び替えることができます。
昇順の場合は、並べ替えをしたい指標を:sortの項目に入れればOKです。
:sort => :unique_pageviews
降順の場合は、指標のあとに、.descを付けてください。
:sort => :unique_pageviews.desc
でユニークページビューの値が大きい順に並び替えられてデータが出てきます。

最後にリミットとオフセットです。
リミットとは、一回のリクエストで取得するデータの数です。API経由の場合は、1回あたり1,000件までと制限されています(確か)。
オフセットはデータを取得するときの始める位置です。「100」と指定すると100番目からのデータを取得します。
最初からデータを取りたい場合は、オフセットの項目を指定しないか、「nil」を指定しておきます。
設定の仕方は簡単で、

:limit => 1000,
:offset => 1001

こんな感じで指定すれば、OKです。
これで必要なデータを取得できる準備ができました。

ここまでのコードをまとめておくと、こんな感じになります。

require 'garb'

Garb::Session.login('sample@gmail.com', 'password')
profile = Garb::Management::Profile.all.detect {|p| p.web_property_id == 'UA-XXXXXXXX-1'}

class Upvs
    extend Garb::Model

    metrics :unique_pageviews, :pageviews
    dimensions :page_path
end

res = profile.upvs(
    :filters => {:page_path.eql => '/'},
    :limit => 1000,
    :sort => :unique_pageviews.desc,
    :start_date => Time.parse("2011-11-01"),
    :end_date => Time.parse("2011-11-30")
)

res.each do |x|
    puts "#{x.page_path},#{x.unique_pageviews},#{x.pageviews}"
end

これだけのコードで、”/”のセッション数とPV数を取得することができちゃいます。

 

 

ちょっと応用編

ここまでわかれば、後はrubyの知識を駆使して、色んなことができます。
Garb使ってみて気づいた、ちょっとしたTipsを書いておきます。
 

1000件以上のデータを取る

API経由でデータを引っ張ってくることで、特に嬉しいことは、大量のデータをぼーっとしている間に取得することが出来る点です。
API経由だと、1回のリクエストでの取得件数が1000件と制限されているはずですが、何度かに分けてデータをリクエストすれば問題ありません。

具体的には、データを取得する時の設定を関数化して、offset値を引数にして、イテレータで回してしまうのがいいでしょう。
データの総数は、返り値のres.total_resultsで取得することができます。
(ちなみに、データがサンプリングされているかどうかは、res.sampledで取得することができます)

あとは、rubyらしく、timesのイテレータを使って、関数にバシバシ設定値を入れてあげて、リクエストを送れば、全部のデータを抽出されます。

↓こんな感じのコードで、簡単に1,000件以上のデータが取得できます。

require 'garb'

Garb::Session.login('sample@gmail.com', 'password')
profile = Garb::Management::Profile.all.detect {|p| p.web_property_id == 'UA-XXXXXXXX-1'}

class Upvs
    extend Garb::Model

    metrics :unique_pageviews, :pageviews
    dimensions :page_path
end

def get_data(profile, offset_val)
    res = profile.upvs(
        :limit => 1000,
        :offset => offset_val,
        :sort => :unique_pageviews.desc,
        :start_date => Time.parse("2011-11-01"),
        :end_date => Time.parse("2011-11-30")
    )

    return res
end

#初回リクエスト
res = get_data(profile, nil)

#全部の件数から繰り返し回数を算出
repeat_times = res.total_results / 1000

#サンプリングの有無を調査
puts "Sampled? => #{res.sampled}"

puts "---we have #{res.total_results} results---"

res.each do |x|
    puts "#{x.page_path},#{x.unique_pageviews},#{x.pageviews}"
end

#2回目以降
if(repeat_times != 0)
    repeat_times.times do |x|
        res = get_data(profile, (x+1)*10)
        puts "---processing #{x+2}th iteration---"

        res.each do |x|
            puts "#{x.page_path},#{x.unique_pageviews},#{x.pageviews}"
        end
    end

end

 

アクティブサポートを有効に使う

Garbは色んなところで、active_supportを利用しているようです。
なので、こちらもactive_supportを利用しちゃいましょう。特に日付の操作が超絶便利です。
(active_support3以降を利用している場合は、active_support/timeをrequireする必要があります)

よく使いそうなところで、先月一ヶ月のデータを取得したいという場合は、こんな感じでできます。

require 'active_support/time'
#先月の初め
start_date = (1.month.ago Time.now).beginning_of_month
#先月の終わり
end_date = (1.month.ago Time.now).end_of_month

これだけで、先月の初めと先月の終わりの日付が取得できちゃいます。

これをフィルター設定のところの期間に、入れて上げれば期間設定せずとも、自動的に先月分のデータを取得できます。

 

設定はYAMLで

アカウントIDやパスワードなどをプログラム内に書いてしまうと、あまり美しくないので、切り出せるところは切り出してしまいましょう。
rubyでは、YAMLという美しい設定ファイルが使えます。人間にもコンピューターにも優しい構文で、さくっと設定ファイルがかけます。

詳しくは、↓を参照してください。

http://jp.rubyist.net/magazine/?0009-YAML

例えば、

date:
 start_date : 2011-11-01
 end_date : 2011-11-01
account:
 mail_address : sample@gmail.com
 pass_word : password
table_id :
 first : ga:xxxxxxxxx
 second : ga:xxxxxxxxx

こんな感じでconf.ymlを作成し、

本文の中で、

require 'yaml'
#read conf file
f = File.open('conf.yml')
conf_str = f.read
conf = YAML.load(conf_str)

こうするだけで、confオブジェクトの中に、設定内容が格納されます。

 

 

Garbはrubyらしくて非常に面白いので、ぜひ使ってみてください。
Googleチャートなどを使って、簡単にブラウザ上でグラフ化することもできます。
(そんなことするんだったら、Googleアナリティクスの画面を見ても同じですが。。。)

 

2012/1/13:自分用備忘録追記

garbは、アドバンスセグメントにも対応しているみたいです。
使い方は、フィルターや日付などを設定する箇所で、
:segment_id => xxxxxx
とするだけです(xxxxxxはセグメントのid。gaid::xxxxxのxxxxx部分)
セグメントIDは、Data Feed Query Explorerで見つけるのが一番楽だと思います。

ダイナミックセグメントのやり方はちょっと見つけられませんでした。
この人が提案しているみたいですけど、まだコードには入っていないみたいです。
https://github.com/stevenwilkin/garb/commit/d7c5b1c5fbde702a1b2f06edcebc44bfa555b0e6

ソースコードをいじっちゃえば、いいんですけどね。

One Comment

  1. Ruby初心者 より:

    記事を拝見し、参考にさせて頂きました。

    自分の環境の問題かもわかりませんが、下記を追加しないとエラーとなってしまう現象があったので、報告だけさせて頂きます。

    # 追加した行
    require ‘rexml/document’

    # 実行環境
    ruby 2.0.0p0 (2013-02-24 revision 39474) [x86_64-linux]
    garb (0.9.1)

    # エラー内容(抜粋)
    /root/.rbenv/versions/2.0.0-p0/lib/ruby/2.0.0/rexml/text.rb:386:in `block in unnormalize’: uninitialized constant REXML::Text::Document (NameError)

    以上です。

Leave a Reply