Data Connector for Google Analytics Reporting 徹底解説 その４
前回まで
4. Data Connector for Google Analytics Reporting
4-1. Data Connector とは
「Data Connector」はトレジャーデータが提供するデータ収集ツールの一つで，ストリーミング型収集ツール：「Fluentd」と双対をなすバルク型の収集ツールです。
Data Connector は様々なデータソースをインプットとしており，トレジャーデータアカウントにエクスポートするデータ収集ツールですが，その最大の特徴はインプットデータソースを「プラグイン」という YAML 形式の設定ファイルで記述することによって汎用性の高いツールとなっている点です。以下は存在するプラグイン（インプットデータベース）のリストです。これらは設定ファイルの内容以外では同様の Data Connector コマンドを利用してトレジャーデータに格納することができます。
- Data Connector for Amazon S3
- Data Connector for Amazon Redshift
- Data Connector for Google Cloud Storage
- Data Connector for Google Analytics reporting
- Data Connector for Microsoft Azure Blob Storage
- Data Connector for FTP
- Data Connector for MySQL
- Data Connector for PostgreSQL
- Data Connector for MongoDB
- Data Connector for Salesforce
- Data Connector for Marketo
- ...
過去のブログで「Amazon S3」と「MySQL」プラグインについてご紹介していますのでこちらもご参照ください！
4-2. Data Connector for Google Analytics Reporting
4-2-1. plugin テンプレートの準備
Data Connector では plugin と呼ばれる YAML 形式の設定ファイルでインプットデータ情報を記述します。「in:」以下のインデントでインプット先の情報，「out:」以下のインデントでエクスポート先の情報を記述します。「out:」の方はトレジャーデータアカウントとなるので詳細な記述は必要ありません。
「in:」以下のインデントの情報を記述していきましょう。
今回は，第2章で紹介したトレジャーデータの「Main TD Data」View を指定するプラグインをテンプレートとしてご紹介します：
- 「type」は google analytics となりますが，Amazon S3，MySQL といった他のあらゆる Data Connector ファミリーでも，この type の値を書き換える（必要ならば接続情報などを追記）だけです。
- 「json_key_content」は第 1 章で Service Account を作成した際に作成された json ファイルの内容そのままになっています。
- 「view_id」：第 2 章で特定した，GA 内の一つの View になっています。
- 「start_date」：データの取得期間のスタートを "YYYY-MM-DD" フォーマットで指定します。(default: 7 days ago)
- 「end_date」：データの取得期間のエンドを "YYYY-MM-DD" フォーマットで指定します。(default: 1 day ago)
- 「time_series」：TD にインポートする際の「time」カラムのためのタイムスタンプを取得するために存在します。ここに指定できるのは「date」または「dateHour」です。time_series で1つディメンジョンを消費することになるので，以下の dimensions で設定できるディメンジョン数は6個までです。
- 「dimension」「metrics」：GA から取得する Dimension カラム，Metric カラムを記述します。
- 「out:」に唯一記述された，「mode: append」は既存のテーブルに追記するオプションです。置き換える場合は「mode:replace」とします。
4-2-2. preview コマンドの実行
まずは td コマンドが v0.11.9 以上であることを確認します。実際に少しデータを取得してみましょう。Data Connector の挙動を確認するための preview コマンドは，インプットデータソースの少しのデータを取得します。
↑ ここで取得できたテーブルの項目「date_hour」,「browser」,「visits」,「pageviews」はいずれもプラグインの後半に記述されていた項目でした。この結果から類推されるように，プラグイン内の「time_series」でトレジャーデータテーブル内で「time」カラムと見なす項目を指しています。これに利用できるのは「ga:date」と「ga:dateHour」の2つに限定されることに注意して下さい。
他にどんな項目が取得できるかというと，実は非常に多くの項目があります。
↑ Google Reporting API V4 ガイド内における「Dimensions & Metrics Explorer」が取得可能な項目の一覧です。Data Connector のプラグインでは，ここに記述のあるものを dimensions および measures に設定すれば，GA 上で集計されたデータを取得できるというわけです！わくわくしてきましたね。
例えば追加の項目として， dimensions に "ga:keyword"を，metrics に "ga:organicSearches"を追加して preview してみましょう。
4-2-3. issue コマンドの実行
さて，本章の最後にトレジャーデータアカウントのテーブルとしてインポートするコマンドをご紹介します。preview コマンドで検証が完了したら， issue コマンドによってデータを取得してトレジャーデータにバルクロードするジョブを実行させます。
connector:issue コマンド一つでGAのデータをトレジャーデータにバルクロードできます。まずは db名およびtable名の存在を確認しましょう。tableは --auto-create-table オプションで存在していなければ自動作成できます。time カラムはトレジャーデータの中では重要な項目ですが、ここに設定ファイル内で time_series 項目に指定したカラムを指定します。
↑ issue コマンドで実行したジョブは，Web 管理画面からも参照することができます。Running のままでジョブが進行しない時は，ジョブ詳細画面に推移してログメッセージを読みましょう。例えば上限以上の dimension や metric を設定していれば、エラー＆リトライを繰り返している事が判明します。こういったマイナーエラーは issue コマンドの前に preview コマンドで試行することで無くすことができます。
設定ファイルを書き換えた際は preview → issue コマンドの順序を守りましょう。
↑ 今回の issue コマンドによって，978件のレコードが master_td_data_82405714 table に追加されました。これは設定ファイル内で，output のモードを「append」にしていたからです。「replace」にするとテーブルが置き換えられることになります。
4-3. Connector UI ( Web UI ) から Data Connector を利用する
4-2. では，Data Connector をコマンドラインから実行していましたが，トレジャーデータの最新のWeb管理コンソールでは，コマンドラインを用いずとも，Connector UI 上から，様々なデータソースからのインポートが可能になっています。
↑ 既に多くの Data Source が，Connector UI に記載されています。この画面を「Source Catalog」と呼びます。
4-3-1. GA コネクションの追加
↑ リストの中から「Google Analytics」を選択します。
↑ 始めに，3-3. で得た View ID と，2-2-2. で得た Service Account の Privacy Key の情報を記入します。
※ Private Key は一番外側の括弧：{ … } まで入れてください。
↑ コネクション名を設定して，GA 向けのコネクションが生成されました。
↑ 管理コンソールでは，あらゆるデータソースとの接続情報を「My Connection」にて管理しています。今回 GA 様に作ったコネクションも，「My Connection」に追加された事がわかります。
4-3-2. Transfer: Dimensions, Metcis の追加
次に先ほど作成した GA コネクションで「NEW TRANSFER」ボタンを押します。
現れた Transfer ダイアログから Dimensions，Metrics を設定することができます。Dimension は Time Series の値も含めて7個まで，Metrics は10個まで指定できます。
4-3-3. Transfer: Preview
指定した Dimension, Metric での preview 結果10件を確認します。問題なければ次に進みます。
ここで，データの取得期間はデフォルトで
- 「start_date」：7日前
- 「end_date」：1日前
ですが，任意の取得期間を設定したい場合には「NEXT」に進む前に「ADVANCES SETTING」ボタンを押します。
4-3-4. Transfer: to
データ転送先の database名 / table名 を選択肢，「Append（追記）」か「Replace（置換）」を選択します。Partition key seed はトレジャーデータの中で「time」カラムとして扱われる重要な項目です。GA コネクターの場合は time_series 項で指定した date か dateHour となりますのでそちらを選ぶようにしてください。
4-3-5. Transfer: When
最後に実行タイミングを設定します。一回だけのの実行なら「Once now」を，特定のインターバルでの実行なら「Repeat...」を選択します。
4-3-6. Transfer: Start
「START TRANSFERT」を押すと，「My Input Transfer」 画面に遷移し，実行された Transger のログを見ることができます。先ほど実行した transfer をクリックすると，データ転送先の Table に飛ぶことができます。
データがインポートされた事が確認できました。
Data Connector for Google Analytics Reporting 徹底解説 その３
前回まで
3. Google Analytics 上での設定
3-1. ログイン
次に GA にログインします。
3-2. Google APIs のサービスアカウントIDの接続許可
「Admin」→「User Management」より，このGAにアクセス許可のあるユーザーを登録します。先ほど作成したサービスアカウントID（今回の例では treasure-data@ga-to-td.iam.gserviceaccount.com ）に「Read & Analyze」以上の権限を付与します。
これでサービスアカウント ID からのAPI を通じてのデータ取得が許可されました。次に GA のどのレポートを取得するのか， View ID を指定します。
3-3. データ取得する View の特定
GA からのレポートデータの取得には，まず取得対象の「View ID」を特定する必要があります。
↑ 今回は，「Treasure Data」> 「Main Site Data」>「TD Japanese Site」の View を例にして進めて行きます。※以後表示している指標値は全てダミー値です
↑ 「TD Japanese Site」（値はダミーです）の Reporing Overview です。このサイトのあらゆる GA Report で使われている 項目（KPI）を Data Connector でデータとして取得することができます。
3-4. View ID の取得
「TD Japanese Site」の View ID を取得するために，Admin メニューに入ります。
↑ GA の概念では，
Account:「Treasure Data」> Property:「Main Site Data」> View:「TD Japanese Site」
という階層を持っており，View ID とは一番下の階層に与えられるユニークな ID です。「View Settings」をクリックします。
↑ View ID はView Settings内のBasic Setting内で確認することができます。今回取得対象となっている View ID は「82405714」となります。
3-5. 終わりに
Data Connector で取得したい GA Report の View ID を得ることができましたね。前章で GA 用のサービスアカウントを設定しましたが，Data Connector コマンドを通じて、このアカウントがこの View ID におけるあらゆるデータ項目を取得して，かつTreasure Data Serviceに格納することになります。次章で紹介する「Data Connector for Google Analytics Reporting」は，この一連の試みを Data Connector という一つの枠組み内で完結することができる、大変に便利なインポートプラグインです。
Data Connector for Google Analytics Reporting 徹底解説 その２
前回まで
2. Google APIs 上での設定
2-1. ログイン
↑ 適切な Google アカウントで Google APIs にログインします。「適切なアカウント」とは，取得したい Google Analytics に API を通じてアクセスすることが許されているアカウントを意味します。
2-2. プロジェクトの作成
2-2-1. Project 新規作成
↑ Projects ボタンから「Create project」を選択し，Data Connector で利用するためのプロジェクトを作成します。
↑ 今回は「GA to TD」というプロジェクト名を与えています。
2-2-2. Service Account の新規作成
以下，「GA to TD」プロジェクト下で設定を進めて行きます。
↑ まずは「Service Account」を新規作成します。このアカウントは後ほど GA への API によるアクセスを許可するアカウントとして利用されます。この「Service」アカウントは，特定のプロジェクト内で作成されるアカウントであり，Google APIs にログインした一般の Google アカウントとは異なる概念のものです。
↑ 今回は「treasure-data」というサービスアカウントを作成します。オプションの選択肢はどちらも指定しておきます。「Create」ボタンを押すと，本サービスアカウントにおける認証情報が JSON ファイル（今回の例では GA to TD-18f4c65b19b3.json という名前）としてダウンロードされます。
↑ このJSONファイルの private key 情報は後の Embulk の設定ファイル内でごそっと利用するので大切に保管するようにしてください。
↑ また，同時に「treasure-data@ga-to-td.iam.gserviceaccount.com」というサービスアカウントIDが作成されます。後の GA の管理画面で，この ID に API アクセス許可の権限を与えることになります。
2-3. 使用する Analytics API を有効にする
2-3-1. API の検索
↑ 次にこのプロジェクトで使用する API を有効にしていきます。今回は GA に関係する2つのAPIを登録します。
「Library」の検索バーから
- Analytics API
- Analytics Reporting API V4
を検索し，この2つを有効にします。
2-3-2. API の有効化
↑ それぞれの API リンクに入ってこの API を「Enable」にします。
↑ API を有効にすると，「Dashboard」メニューから，登録された APIを一覧で参照することができ，かつ API のモニタリングがその時点から開始されます。
2-4. 終わりに
Google APIs で設定する項目について紹介しました。次にこの作成したサービスアカウントIDで，取得対象のGoogle Analytics のデータにアクセスできるように，権限を追加していきます。
