このページは Cloud Translation API によって翻訳されました。

Google Analytics Data API のクォータの管理

Minhaz Kazi（Google アナリティクスデベロッパーアドボケイト） - 2023 年 2 月

Google Analytics Data API を使ったアプリケーションを開発する際は、API のクォータや制限の仕組みを理解しましょう。アプリケーションの設計が優れていれば、ユーザーがクォータを使い切ってしまう可能性は下がります。的確なベストプラクティスの活用は、API に対するクエリのパフォーマンス向上にもつながり、アプリケーション内のレポートやダッシュボードの動作速度アップ、ユーザーエクスペリエンスの改善につながります。この記事では、Google Analytics Data API のクォータシステムについて説明し、実装時のベストプラクティスを紹介します。

Google Analytics Data API のクォータシステム

Google アナリティクスは何百万人ものデベロッパーやユーザーに利用されているため、システムが処理するデータの量を許容範囲内に抑えつつシステムリソースを公平に配分できるよう、API リクエストにクォータが設定されています。Google アナリティクス 4 プロパティの Data API では、API クォータの管理にトークンバケットシステムを採用しています。この概念を理解するには、所定の数までトークンが入るバケツ（バケット）を想像するといいでしょう。API リクエストを実行すると、まずバケツの中身が確認されます。トークンの残量が足りなければ、リクエストは失敗します。十分な数のトークンが残っていればリクエストは実行され、バケツ内のトークンがリクエストの複雑さに応じた数だけ消費されます。バケツ内のトークンは、決まったタイミングで上限まで補充されます。

クォータは 3 つのカテゴリに分かれており、使用する Data API メソッドの種類に応じたカテゴリのトークンが消費されます。

リアルタイム（runRealtimeReport 用）
ファネル（runFunnelReport 用）
コア（他のすべてのメソッド用）

また、Data API の各メソッドがクォータトークンを確認するバケットも何種類か存在します。

同一プロパティで 1 日あたり
同一プロパティで 1 時間あたり
同一プロジェクト・同一プロパティで 1 時間あたり
プロパティあたりの同時リクエスト数
同一プロジェクト・同一プロパティで 1 時間あたりのサーバーエラー数

プロパティに対する Data API リクエストが届くたびに、上記 5 種類のバケットが確認されます。トークン残量の足りないバケットがひとつでもあれば、リクエストはその場で失敗となり、429 エラーが発生します。残量不足のバケットがひとつもなければ、「プロパティあたりの同時リクエスト数」バケットのトークンを 1 個消費して API リクエストが実行されます。実行が完了すると、最初の 3 つのバケットのそれぞれから、リクエストの複雑さに応じた数のトークンが消費されます。また、この時点で「プロパティあたりの同時リクエスト数」バケットにトークンが 1 個補充されます。

「同一プロジェクト・同一プロパティで 1 時間あたり」クォータには、アプリケーションの一部のユーザーによるクォータ消耗が他のユーザーに影響することを防ぐ役割があります。ここで言う「プロジェクト」とは、アプリケーションの GCP プロジェクトを指します。「同一プロパティで 1 時間あたり」クォータは通常、「同一プロジェクト・同一プロパティで 1 時間あたり」クォータの 4 倍に設定されています。よってエンドユーザーの視点では、同一プロパティに 4 つの異なるプロジェクトからアクセスが発生しない限り、「同一プロパティで 1 時間あたり」クォータを使い切ってしまうことはありません。プロジェクトとプロパティの両方のレベルでクォータを適用することにより、クォータによる制約の対象は単一のプロパティに限定され、同じアプリケーションによる他のプロパティへのアクセスには影響しない仕組みとなっています。

「同一プロジェクト・同一プロパティで 1 時間あたりのサーバーエラー数」クォータにおけるサーバーエラーとは、コード 500 または 503 の API レスポンスを指します。アプリケーションが同一プロパティへのアクセス中に発生させるエラーの数が多すぎると、「同一プロジェクト・同一プロパティで 1 時間あたりのサーバーエラー数」クォータを使い切る可能性があります。

どのクォータのトークンも、所定のタイミングで上限まで回復します。最新のクォータ情報は、Google Analytics Data API のクォータについての記事でご確認ください。たとえば、「コア」カテゴリのメソッドの「同一プロジェクト・同一プロパティで 1 時間あたり」バケットには、クォータトークンが 1,250 個割り当てられます。仮にアプリケーションの平均的なリクエスト 1 回でクォータトークンを 10 個消費する場合、通常のアナリティクスプロパティでは「コア」カテゴリのリクエストを 1 時間あたり 125 回まで実行可能です。アナリティクス 360 プロパティであれば、上限は 10 倍になります（「コア」リクエスト 1,250 回まで）。クォータトークンの上限値が大きいことは、アナリティクス 360 の大きなメリットのひとつです。

最初の 3 つのバケットのトークン消費量はリクエストの複雑さに応じて変化するため、使用されるトークンの正確な数をリクエスト実行前に予測するのは困難です。一般に、次の条件に当てはまるとリクエストの複雑さが増し、トークン消費量が増えます。

リクエストするディメンションの数が多い
クエリ対象の期間が長い
基数が大きいディメンションを含む
クエリ対象のプロパティのイベント数が多い

よって、たとえ同内容のクエリでも、対象とするプロパティが違えばトークンの消費量が大きく異なる可能性があります。含まれるディメンションの基数やトラフィック量はプロパティによって異なるためです。一方、トラフィック量にも構成にも大きな差がないプロパティ同士であれば、トークン消費量も近くなることを期待できます。プランニングやアプリ設計の段階で顧客のトークン消費量を予想する際の目安にしましょう。

クォータ使用状況のモニタリング

クォータの使用状況を把握し、その情報をエンドユーザーに伝えるには、API リクエストボディに "returnPropertyQuota": true を追加します。これにより、API レスポンスとともに PropertyQuota オブジェクトが返されます。PropertyQuota オブジェクトには、5 種類のバケットのトークンの消費量と残量が格納されています。以下はリクエストのボディとレスポンスの例です。

リクエスト

{
  "dimensions": [
    {
      "name": "medium"
    }
  ],
  "metrics": [
    {
      "name": "activeUsers"
    }
  ],
  "dateRanges": [
    {
      "startDate": "yesterday",
      "endDate": "yesterday"
    }
  ],
  "returnPropertyQuota": true
}

レスポンス

{
  "dimensionHeaders": [
    {
      "name": "medium"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  ...
  
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 24997
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 4997
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 1247
    }
  },
  
  "kind": "analyticsData#runReport",
  ...
}

このように、Data API リクエストが成功するたびに、そのリクエストが消費したクォータと、該当プロパティのクォータの残量を確認することができます。取得した情報を、アプリケーションのインターフェースを通してユーザーに伝えることも可能です。

クォータの管理

Data API を最大限に活用していただけるよう、クォータ管理のベストプラクティスをご紹介します。なお、プロパティをアナリティクス 360 にアップグレードすれば、API を通してアクセス可能なデータの量そのものを増やすことができます。

ベストプラクティス

アプリケーションのクォータ消費量を抑える方法は、大きく分けて 2 つあります。

送信する API リクエストの数を減らす
送信する API リクエストの複雑さを軽減する

この 2 つの原則を念頭に、次のような運用の工夫が考えられます。

キャッシュ処理: キャッシュ処理のレイヤーを実装すれば、アプリケーションのユーザビリティとクォータ管理の両面でメリットがあります。Google アナリティクス自体も API リクエストのキャッシュ処理を行っていますが、リクエストを繰り返せばクォータトークンが消費される点は変わりません。アプリケーション側で API レスポンスをキャッシュすることにより、反復的なリクエストの数を劇的に削減できます。たとえば通常のアナリティクスプロパティの当日データなら、キャッシュの有効期限は 4 時間またはそれ以上に設定可能です。Google アナリティクスのデータの更新頻度についての記事もご参照ください。
リクエストのマージ: 複数の API リクエストをひとつにまとめられないか検討しましょう。たとえば、2 日間のデータに対するリクエストを 5 件行った場合のクォータトークン消費量は、10 日間のデータに対するリクエストを 1 件行った場合の 3 倍になる可能性があります。ディメンションが 1 つ異なるだけでそれ以外は同内容のリクエストが複数あれば、単一のリクエストにまとめることを検討しましょう。
リクエスト内容の簡素化: リクエストの内容は、アプリケーションおよびユーザーが必要とする最小限のデータ量に絞りましょう。多数の行 / 列や複雑なフィルタ条件を指定すれば、クォータトークンの消費が多くなります。対象期間を長くするとトークン消費も重くなることが一般的です（例: 期間を 28 日間から 365 日間に変更すると、クォータトークンの消費量は 3 倍になる可能性があります）。可能な限り基数の小さいディメンションを使うことも検討しましょう（例: dateHourMinute ではなく dateHour をリクエスト）。
limit の効果的な利用: API リクエストの limit を変更して返される行の数を減らしても、クォータトークンの節約はあまり期待できません。たとえば、上限（limit）を 1 万行に設定したリクエストを 5 件実行した場合のクォータトークン消費量は、上限 5 万行のリクエストを 1 件実行した場合の 5 倍になる可能性があります。
適切なメソッドカテゴリの使用: 前述のとおり、クォータの上限は 3 種類のメソッドカテゴリに分けて適用されます。用途に応じて適切なメソッドを使用すれば、他のカテゴリのクォータを節約できます。たとえばファネルを作成する場合、「コア」カテゴリのメソッドで取得したデータを使ってアプリケーション側で独自に作成するよりも、runFunnelReport メソッドを使って作成するのがいいでしょう。
デフォルト設定の変更: プラットフォームでレポートの作成やカスタマイズを行うユーザーは、アプリケーションが提示したデフォルト値を変更せず、実行時の設定変更だけで済ませることも想定されます。たとえば、ユーザーが普段参照するのは 28 日間のレポートなのに、アプリケーションのデフォルト期間が 365 日間になっていれば、必要以上のクォータ消費が定期的に発生することになります。デフォルトの期間や選択内容は限定的にしておき、ユーザー自身に用途に応じた設定を選択してもらう運用も検討しましょう。場合によっては、ユーザーが変更できるデフォルト設定の種類を制限することも可能です。
リクエストのキュー処理と遅延読み込み: 「プロパティあたりの同時リクエスト数」トークンの上限を意識しましょう。アプリケーションが同時に送信するリクエストの数を抑える必要があります。アプリケーションに多数の UI 要素があるために API リクエストが嵩んでしまう場合は、UI のページネーション、遅延読み込み、リクエストのキュー処理（再試行は指数関数的バックオフで処理）を検討しましょう。returnPropertyQuota メソッドを使ってアプリケーションの「プロパティあたりの同時リクエスト数」トークンの使用状況を積極的にモニタリングすることも重要です。

ユーザーエクスペリエンスとユーザー期待値の管理

トークンを大量消費する可能性があるクエリを実行しようとしているユーザーには、実行前にその旨フィードバックしましょう。たとえば高基数ディメンションを複数含むクエリや対象期間が長いクエリは、トークンを大量に使用する可能性があります。実行前に警告や確認プロンプトを表示すれば、レポートに対する不必要な変更を控え、クエリのスコープを絞ってもらえることが期待できます。
カスタマイズされたレポートを提供するソリューションの場合は、レポートの各要素のクォータ消費量をユーザーが確認できるようにしましょう。たとえば、各レポート要素のクォータトークン使用量を一覧表示できるデバッグビューを用意します。
クォータ関連のエラーが発生した場合は、エラー内容と必要な対応を具体的にフィードバックしましょう。
Google アナリティクス 360 プロパティにアップグレードすれば、クォータ上限が通常のプロパティの 5～10 倍になり、さらに柔軟な運用が可能です。

デフォルトの上限を超える API クォータの引き上げは、Google アナリティクス 4 の Data API ではご利用いただけません。Google アナリティクス 360 プロパティなら、クォータ上限値は Google アナリティクス 4 プロパティよりも大きくなります。各種ベストプラクティスを採用してもトークン消費がクォータ上限に達してしまうユーザーには、プロパティをアナリティクス 360 にアップグレードすることを検討してもらいましょう。また、Google アナリティクス BigQuery Export を利用してもらうのも一案です。この場合、ユーザーはイベントレベルのデータを BigQuery にエクスポートして、自由に分析を行うことができます。

その他、Data API のクォータについてご質問があれば、Google アナリティクスの Discord サーバーに参加するか、Stack Overflow でご質問ください。Data API 関連で具体的な機能の要望をお持ちの場合は、Issue Tracker で機能リクエストを投稿していただけます。