データ インポート - デベロッパー ガイド

このドキュメントでは、Management API を使ってデータを Google アナリティクス アカウントにインポートする方法に関して、開発者の方向けに高度なコンセプトを説明します。

はじめに

Management API のデータ インポート機能により、Google アナリティクス アカウントのインポート データをアップロード、一覧表示、削除、取得できます。データ インポート機能のメリットの詳細については、データ インポートについてをご覧ください。

Management API には、データ インポート機能を有効にする以下の 2 つのリソースがあります。

• カスタム データソース リソース（管理画面でいうデータセット）。アップロードしたファイルのコンテナとして機能します。カスタム データソースのコレクションは、Google アナリティクスのプロパティに関連付けられるすべてのデータソースを表します。
• アップロードしたファイルを表すアップロード リソース。アップロード リソースのコレクションは、カスタム データソース / データセットにアップロードしたすべてのファイルを表します。

準備

Google アナリティクス API はすべて同じ方法でアクセスできます。Management API を使用する前に、以下のドキュメントをご覧ください。

• クライアント ライブラリのページ。API の操作に対応したプログラミング言語ごとのクライアント ライブラリ一覧を確認します。API で利用できるプログラミング言語ごとのクライアント ライブラリがまとめられています。
• リファレンス ガイド。クライアント ライブラリを使わずにデータにアクセスする API インターフェースについて確認します。

各クライアント ライブラリは、すべての Management API データにアクセスするための 1 つの Analytics サービス オブジェクトを提供します。サービス オブシェクトを作成する方法は次のとおりです。

1. Google Developers Console でアプリケーションを登録します。
2. Google アナリティクス データへのアクセスを承認します。
3. Analytics サービス オブジェクトを作成します。

上記の手順を完了していない場合は、まず Google アナリティクス API についてのチュートリアルをご覧ください。このチュートリアルでは、Google アナリティクス API アプリケーションを作成する基本的な手順を詳しく説明しています。この手順を完了すると、Google アナリティクス API を実際の作業に活用する方法を理解することができます。

使用例

データ インポート機能を使用して、ビジネスデータを Google アナリティクスのデータに統合できます。たとえば、次のデータを使用できます。

• ヒットデータのインポート
• 払い戻しデータ
• 拡張データのインポート
• ユーザーデータ
• キャンペーン データ
• 地域データ
• コンテンツ データ
• 商品データ
• 概要データのインポート
• 費用データ

ヒットデータのインポート

払い戻しデータ

一部または全額が払い戻された e コマース トランザクションを Google アナリティクスにアップロードできます。そうすることで、Google アナリティクスの e コマース レポートのデータと処理された払い戻し額を、簡単かつ自動的に照合できます。

払い戻しデータを Google アナリティクスにインポートする方法については、払い戻しデータのインポート例をご覧ください。

拡張データのインポート

ユーザーデータ

個人を特定できないユーザーデータを外部の CRM ツールからアップロードすると、最も貴重なユーザー セグメントに関する AdWords のリマーケティング リストを作成できます。

ユーザーデータを Google アナリティクスにインポートして AdWords のリマーケティング リストを作成する方法については、ユーザーデータをインポートして AdWords リマーケティング リストを作成するをご覧ください。

キャンペーン データ

キャンペーン データを Google アナリティクスにインポートすると、自社のキャンペーンの掲載結果の分析をカスタマイズできます。

キャンペーン データを Google アナリティクスにインポートする方法については、Management API を使用したキャンペーン データのインポートをご覧ください。

地域データ

地域 ID と地域とのマッピングをインポートできるため、Google アナリティクス データのレポートをカスタム地域別に作成できます。たとえば、米国では東部、中部、西部の州グループで処理し、ヨーロッパでは北部、中部、南部の国グループで処理することができます。データをインポートする際は、キーとして ga:regionId、ga:cityId、ga:countryIsoCode、ga:subContinentCode を使用できます。市区町村 ID と国 ID の一覧は、地域ターゲティング表に記載されています。ISO 国コードと亜大陸コードの一覧は、ISO-3166-1 alpha-2 表および UN M.49 表にそれぞれ記載されています。

地域データのインポートについて詳しくは、地域データのインポート例をご覧ください。

コンテンツ データ

作成者やトピックなど、コンテンツ関連のメタデータをアップロードすると、Google アナリティクスを活用して、ウェブサイトで公開されている記事の詳細な分析を実行できます。

コンテンツ データを Google アナリティクスにインポートする方法については、コンテンツ データのインポート例をご覧ください。

商品データ

商品データを Google アナリティクスにインポートすると、ページビューやイベントなどのヒットと一緒に送信する必要のある e コマース データを簡略化し、削減することができます。インポートした商品データには、商品 ID か SKU を 1 つ結合させることができます。そうすることで、レポートに商品のディメンションや指標などのデータを入力できます。

商品データを Google アナリティクスにインポートする方法については、Management API を使用した商品データのインポートをご覧ください。

概要データのインポート

費用データ

Google 以外の有料キャンペーンの費用データをアップロードすると、Google アナリティクス プラットフォームを活用して、投資収益分析を実行し、すべてのオンライン広告とマーケティング投資のキャンペーンの掲載結果を比較することができます。

費用データを Google アナリティクスにインポートする方法については、Management API を使用した費用データのインポートをご覧ください。

コンセプト

処理ステータス

ファイルをアップロードしてから、アップロードが検証、処理されるまでは、アップロードのステータスが PENDING になります。処理が正常に終了すると、ステータスは COMPLETED に変わります。

処理中にエラーが発生し、アップロードに失敗した場合は、アップロードのステータスが FAILED になります。エラーリストを見れば、ファイルの問題点を特定できます。検証に失敗したアップロードのレスポンスの例を次に示します。

{
  id: "YU4DersR_ORzyzXC_AoWw",
  kind: "analytics#upload",
  accountId: "12345",
  customDataSourceId: "poaU7EPcR4WGU-dkNghYKQ",
  status: "FAILED",
  errors:
  [
    "Invalid cell data 12.99 at row 1 column 6. expected data type LONG.",
    "Invalid cell data 12.99 at row 2 column 6. expected data type LONG.",
    "Invalid cell data 23.81 at row 3 column 6. expected data type LONG.",
    "Invalid cell data 199.99 at row 4 column 6. expected data type LONG."
  ]
}

費用データの合計と上書き

費用データのカスタム データソース / データセットを作成する場合、既存の行と一致するキー（日付、参照元、メディアなど）を含むデータ行がアップロードしたファイルに含まれているときの処理方法を指定できます。処理方法は次のいずれかです。

• 合計（デフォルト） - 新しいデータを一致する過去のデータに追加し、指標を合計します。
• 上書き - 新しいデータで一致する過去のデータを上書きします。

カスタム データソース / データセットでどのタイプが設定されているかを調べるには、カスタム データソースの list メソッドを使用して、importBehavior プロパティが OVERWRITE と SUMMATION のどちらに設定されているかを確認します。

行レベルでの費用データの合計と上書き

ga:importBehavior 列をヘッダーに追加すると、アップロードするファイルごとに、カスタム データソース / データセットの動作を上書きすることもできます。ga:importBehaviour の値は、行単位で SUMMATION か OVERWRITE に設定できます。

たとえば、以下のファイルは、Facebook / CPC と Yahoo / CPC の前の費用データを上書きしますが、Bing / CPC の行は、特定の日付と参照元 / メディアの組み合わせに基づき、既存の費用データに追加されます。

ga:date,ga:source, ga:medium,ga:adCost,ga:importBehavior
20140604,facebook,cpc,12.23,OVERWRITE
20140604,bing,cpc,3.23,SUMMATION
20140604,yahoo,cpc,11.23,OVERWRITE

データ インポートの形式と制限事項

Google アナリティクスにデータをアップロードするには、適切な形式の CSV ファイルに含める必要があります。このセクションでは、すべてのタイプのデータ インポートへアップロードできるように、守る必要のある制限事項について説明します。

下記の制限事項のいずれかに違反したり解析エラーが発生したりすると、アップロード リクエストは失敗し、エラー メッセージが返されます。無効なアップロードの低減に役立つ情報として、1 個の API レスポンスにつき最大 10 個のエラーが返されます。

ファイルの制限事項

• エンコード: UTF-8
• ファイル サイズの上限: 1 GB

ヘッダーの制限事項

• 最初の行は列ヘッダーと見なされます（列ヘッダーは必須です）。
• 特定の列に含まれるディメンションと指標を指定する必要があります。　

行の制限事項

• 1 行につき 1 MB のサイズの上限があります。

セルの形式

• セルには最大 2048 文字（半角）の値を指定できます。
• セルの値の前後にあるスペースは削除されます。
• セル内でカンマを使用する場合は、そのセルの値全体を二重引用符で囲む必要があります。たとえば「source1,"medium,ether",group1,100」と指定すると、2 番目のセルの値は「medium,ether」になります。
• セル内で二重引用符を使用する場合は、そのセルの値全体を二重引用符で囲んだうえで、エスケープ文字としてもう 1 つ二重引用符を追加します。たとえば「source1,"medium""ether",group1,100」と指定すると、2 番目のセルの値は「medium"ether」になります。

サンプルコード

upload リソースを使用すると、認証済みユーザーがインポート済みのデータをアップロード、一覧表示、取得、削除することができます。customDataSource リソースを使用すると、認証済みユーザーがカスタム データソースを一覧表示することができます。これらのメソッドを使用するには、準備セクションで説明するとおりに、Analytics サービス オブジェクトを作成する必要があります。

アップロード リソースを扱う方法を示すサンプルコードについては、以下のメソッド リファレンスをご覧ください。

アップロード

• list - ユーザーがアクセスできるアップロードのリストを表示します。
• get - ユーザーがアクセスできるアップロードを取得します。
• deleteUploadData - 以前のアップロードに関連付けられているデータを削除します。
• uploadData - データをカスタム データソースにアップロードします。

カスタム データソース / データセット

• list - ユーザーがアクセスできるカスタム データソースを一覧表示します。