デベロッパーガイド

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

はじめに

Real Time Reporting API を使用して、プロパティで実行中のアクティビティについてレポートすることができます。リアルタイムデータにアクセスするには、ビュー（プロファイル）と 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 サービスオブジェクトを提供します。サービスオブジェクトを作成するには、次の手順に従います。

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

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

Real Time Reporting API の使用

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

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

Real Time Reporting API に対するクエリ

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

Real Time Reporting API リファレンスでは、Real Time Reporting API の get メソッドで使用できるすべてのクエリパラメータの一覧を確認できます。
標準クエリパラメータリファレンスでは、すべてのメソッドとリソースで使用できるクエリパラメータの一覧を参照できます。
ディメンションと指標のリファレンスページでは、Google アナリティクスから取得できるデータの一覧を参照できます。

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

API レスポンスの処理

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

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

サンプルコード

リアルタイムデータ: get ページの例のセクションでは、Realtime Reporting API へのクエリと API レスポンスの処理を行うためのサンプルコードがさまざまなプログラミング言語で提供されています。

クエリの制限

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

次のディメンションフィルタを使用したクエリに rt:activeUsers 指標が含まれている場合、AND 演算子と等価マッチタイプ（==）のみがサポートされます。
- rt:goalId
- rt:eventAction
- rt:eventCategory
- rt:eventLabel
rt:activeUsers 指標はサイトで現在アクティブであるユーザーの数のみを取得するため、rt:activeUsers では rt:minutesAgo を使用しないでください。つまり、rt:activeUsers は rt:minutesAgo が 0 であることを示します。
指標フィルタはサポートされていません。
fields パラメータはサポートされていません。

割り当て管理

制限と割り当てで説明されているように、Realtime 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 秒です。ビュー（旧プロファイル）の 1 日あたりのリクエストの合計数が 1 日の上限である 4,000 回未満になるように、各ダッシュボードの更新間隔を 65 秒（86,400 ÷ 1,333）より長くする必要があります。