デベロッパー ガイド

このドキュメントでは、Real Time Reporting API を使用して Google アナリティクス データを取得する方法を説明します。

はじめに

Real Time Reporting API を使用して、プロパティで実行中のアクティビティについて レポートすることができます。リアルタイム データにアクセスするには、 1 つのビュー(旧プロファイル)と 1 つ以上の指標を指定したクエリを作成します。 クエリの調整のために、ディメンションやフィルタなどのクエリ パラメータを追加する こともできます。このクエリが Real Time Reporting API に 送信されると、テーブル形式のデータが返されます。

API を初めて使用する方は、 Real Time Reporting API の仕組みと 提供されるデータについて、Real Time Reporting API の概要で詳細を ご確認ください。

前提条件

Real Time Reporting API を使用して Google アナリティクス データを取得するには、次の条件を満たす必要があります。

  • API で利用可能な すべてのプログラミング言語ごとのクライアント ライブラリの一覧を、 クライアント ライブラリ ページで確認する。
  • (クライアント ライブラリを使用せずに) API のみを使用して Google アナリティクス データを取得する方法を、リファレンス ガイドで確認する。

各クライアント ライブラリは、すべての Real Time Reporting API データにアクセス するための 1 つの Analytics サービス オブジェクトを提供します。サービス オブジェクトを作成するには、次の手順に従います。

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

上記の手順を完了していない場合は、まず Google アナリティクス API についての チュートリアルをご覧ください。 このチュートリアルでは、Google アナリティクス API アプリケーションを作成する 基本的な手順を詳しく説明しています。チュートリアルを読み終えると、API を使用 して Google アナリティクス データを取得する方法がわかります。

Real Time Reporting API の使用

Real Time Reporting API を使用するには、アプリケーションで次の作業を行います。

  1. Real Time Reporting API に対してクエリを実行する。
  2. API レスポンスを処理する。

Real Time Reporting API に対するクエリ

Analytics サービス オブジェクトには、Real Time Reporting API へのクエリを 作成するメソッドが含まれています。API に利用可能なクエリ パラメータとデータに ついての詳細は、以下を参照してください。

クエリの定義が完了したら、execute メソッドを呼び出して、クエリを Google アナリティクス サーバーに送信します。

API レスポンスの処理

Real Time Reporting API へのクエリが正常に完了すると、API はリアルタイム データリソースの一部としてリクエストされたデータを返します。API レスポンスの 構造と形式についての詳細は、Real Time Reporting API リファレンス をご覧ください。

エラーが発生すると、API は特定のステータス コードと、エラーに ついての説明を含むメッセージを返します。すべてのアプリケーションは、 エラーを検出して対応しなければなりません。エラー レスポンスでエラーの 詳細な一覧を確認し、推奨事項を再試行してください。

サンプルコード

リアルタイム データ: get ページののセクションに各種プログラミング言語のサンプルコードが記載されています。これらのコードを使用して、Real Time Reporting API へのクエリの実行と、API レスポンスの処理を行うことができます。

クエリの制限

Real Time API クエリには、以下のような制限があります。

  • 以下のディメンション フィルタを使ったクエリに rt:activeUsers 指標が含まれている場合、 AND 演算子と等値演算子 (==) のみサポートされます。
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    rt:activeUsers 指標は、現在サイトでアクティブなユーザー数 のみを取得するので、rt:activeUsersrt:minutesAgo は 併用しないでください。つまり、 rt:activeUsers は、rt:minutesAgo が 0 であることを 意味します。

  • 指標フィルタはサポートされていません。
  • fields パラメータはサポートされていません。

割り当て管理

制限と割り当てページで 説明されているとおり、 Real Time Reporting API には他の Google アナリティクス API と共有 して使用する 1 日の割り当てがあるため、短い間隔で Real Time Reporting API にポーリングを行っていると、すぐに 1 日の制限に 達してしまいます。制限に達すると、割り当てが更新されるまで他の Google アナリティクス API からのリクエストも停止します。

短時間で割り当てを使い果たす可能性がある実装例を以下に 示します。

  • 毎日ごく短い間隔で 1 つの Google アナリティクス ビュー(旧プロファイル)データに関するクエリを実行する複数のリアルタイムのマイレポートがある。
  • 多数のユーザーが使用するプロパティで、リアルタイム ウィジェットを 実装している。この場合、ユーザーにウィジェットが表示されるたびに、 キャッシュを使用することなく、Google アナリティクスに直接クエリが送信されます。

割り当て使用量を最小限に抑え、効率的に管理するには、次の手順に従います。

  • サーバーサイド キャッシュを実装します。複数のユーザーが、 同じリアルタイム データをリクエストした場合、それぞれのリクエストに対して 直接 Real Time Reporting API にクエリを送信するのではなく、キャッシュされた レスポンスを返す必要があります。この場合、1 日の割り当て制限を超えないように 適切な更新間隔で、定期的に最新のリアルタイム データでキャッシュを更新 します。
  • 追加のディメンションを指定して複数のクエリを 組み合わせ、サーバーまたはクライアント側でレスポンスを解析します。
  • リアルタイム データをリクエストする間隔を増やしてください。

例: 更新の間隔を計算する

リアルタイム データを定期的にリクエストする場合、予想されるリクエストの 頻度を基に適切な更新間隔を設定する必要があります。

たとえば、1 つの Google アナリティクス ビュー(旧プロファイル)の割り当て制限が 1 日あたり 10,000 リクエストだとします。1 つのビュー(旧プロファイル)で、1 日に 6,000 件のクエリを Core Reporting API に送信することが予想される場合、 そのビューでは 4,000 件のリクエスト割り当てが残ります。

Real Time Reporting API を使用して 3 つのリアルタイム マイレポートを実装し、 同じビュー(旧プロファイル)からリアルタイムデータのクエリを終日実行することを決定 したと仮定します。1 つのマイレポートにつき、1 日に約 1,333 クエリ(3 つのマイレポート で 4,000 クエリ)を送信できます。1 日は 86,400 秒あります。 したがって、各マイレポートの更新間隔は、65 秒(86,400 / 1,333)より長くする必要があります。そうすれば、ビュー(旧プロファイル)の 1 日のリクエスト総数が、1 日あたりの制限である 4,000 件を下回ります。