Real Time Reporting API - 承認

このガイドでは、Real Time Reporting API へのリクエストをアプリケーションが承認する方法を説明します。

リクエストの承認

ユーザーが Google アナリティクス ウェブサイトで自分のアカウント情報を確認するには、最初に Google アカウントにログインする必要があります。同様に、最初にアプリケーションにアクセスする際は、ユーザーデータへのアクセスをアプリケーションに許可する必要があります。

アプリケーションからアナリティクス API に送信するすべてのリクエストには、承認トークンを含める必要があります。このトークンは Google でアプリケーションを識別するためにも使用されます。

承認プロトコルについて

リクエストを承認するために、アプリケーションは OAuth 2.0 を使用する必要があります。これ以外の承認プロトコルには対応していません。アプリケーションで Google+ ログインを使用している場合、承認手続きの一部が自動化されます。

OAuth 2.0 によるリクエストの承認

アナリティクス API へのすべてのリクエストは、認証済みのユーザーによって承認される必要があります。

OAuth 2.0 の承認プロセス(「フロー」)の詳細は、開発対象のアプリケーションの種類によって若干異なりますが、次の一般的なプロセスはすべての種類のアプリケーションに当てはまります。

  1. アプリケーションの作成時、Google API コンソールを使用して、アプリケーションを登録します。すると、後で必要になるクライアント ID やクライアント シークレットなどの情報が Google から提供されます。
  2. Google API コンソールでアナリティクス API を有効にします(API が API コンソールに表示されない場合は、この手順をスキップしてください)。
  3. アプリケーションでユーザー データにアクセスする必要がある場合は、アクセスの範囲を Google にリクエストします。
  4. Google は、ユーザーに承諾画面を表示して、アプリケーションによる一部のデータのリクエストを許可するよう求めます。
  5. ユーザーが許可すると、Google はアプリケーションに短期間有効なアクセス トークンを渡します。
  6. アプリケーションは、そのアクセス トークンを付けてユーザー データをリクエストします。
  7. Google がそのリクエストとトークンが有効であると判断すると、リクエストされたデータが返されます。

フローによっては、追加の手順(リフレッシュ トークンを使用して新しいアクセス トークンを取得するなど)が必要になる場合もあります。さまざまな種類のアプリケーションのフローについて、詳しくは Google の OAuth 2.0 に関するドキュメントをご覧ください。

アナリティクス API で使用される OAuth 2.0 のスコープ情報は次のとおりです。

スコープ 意味
https://www.googleapis.com/auth/analytics.readonly アナリティクス API に対する読み取り専用のアクセス。

OAuth 2.0 を使用してアクセスをリクエストする場合、アプリケーションを登録したときに Google から提供された情報(クライアント ID やクライアント シークレットなど)に加えて、スコープ情報が必要になります。

ヒント: Google API クライアント ライブラリで一部の承認プロセスを処理することもできます。これらのライブラリはさまざまなプログラミング言語で用意されています。詳細については、ライブラリとサンプルのページをご覧ください。

OAuth 2.0 の一般的フロー

次に、特定の OAuth 2.0 フローでの一般的な使用例を紹介します。

ウェブサーバー

このフローは、ユーザーの Google アナリティクス データへの自動アクセス、オフライン アクセス、スケジュール設定されたアクセスに適しています。

例:

  • ユーザーのマイレポートを Google アナリティクスの最新データで自動的に更新する。

クライアント側

ユーザーがアプリケーションを直接操作して、ブラウザ内で Google アナリティクス データにアクセスする場合には、このフローが最適です。サーバー側の機能を使わずに済みますが、自動レポート作成、オフラインでのレポート作成、スケジュール設定されたレポート作成には向いていません。

例:

インストール済みのアプリ

このフローは、パッケージとして配布され、ユーザーによってインストールされたアプリケーション向けのフローです。このフローでは、アプリケーションまたはユーザーがブラウザにアクセスして認証フローを完了する必要があります。

例:

  • コンピュータ(Windows または Mac)のデスクトップ ウィジェット。
  • コンテンツ管理システムのプラグイン - ウェブサーバーまたはクライアント側と 比較してこのフローが優れているのは、1 つの API コンソール プロジェクトをアプリケーションに使用できる点です。これによって、一元的にレポートを管理でき、インストールがシンプルになります。

サービス アカウント

サービス アカウントは、ご自身のアカウントの Google アナリティクス データへの自動アクセス、オフライン アクセス、スケジュール設定されたアクセスに役立ちます。たとえば、Google アナリティクス データのライブ マイレポートを作成して、他のユーザーと共有する場合などに便利です。

アナリティクス API を利用するには、まずセットアップ ツールを使用する 必要が あります。このツールに表示される手順に従い、Google API コンソールでの新しい プロジェクトの作成、API の有効化、認証情報の作成を行うことができます。

新しいサービス アカウントを設定するには、以下の手順に従ってください。

  1. [認証情報を作成] > [サービス アカウント キー] をクリックします。
  2. サービス アカウントの公開キーと秘密キーを標準 P12 ファイルとしてダウンロードするか、 Google API クライアント ライブラリで読み込むことのできる JSON ファイルとしてダウンロード するかを選択します。

新しい公開キーと秘密キーのペアが生成され、コンピュータにダウンロードされます。 このキーは再発行できませんので、大切に保管して ください。

トラブルシューティング

次のような場合は承認に失敗します。

  • access_token の有効期限が切れているか、API に誤ったスコープを使用している場合は、401 ステータス コードが送信されます。

  • 承認済みのユーザーがビュー(旧プロファイル)にアクセスできない場合は、403 ステータス コードが送信されます。正しいユーザーとして承認されていること、選択したビュー(旧プロファイル)があることを確認してください。

OAuth 2.0 Playground

これは、管理画面から承認のフローを最後まで実行できるツールです。このツールでは、承認済みのクエリを実行するために必要なすべての HTTP リクエスト ヘッダーも表示されます。ご自身のアプリケーションで承認を得ることができない場合は、OAuth 2.0 Playground 経由で承認を試みてください。その後、Playground からの HTTP ヘッダーおよびリクエストを、アプリケーションから Google アナリティクスに送信される HTTP ヘッダーおよびリクエストと比較することができます。そうすることで、リクエストの形式が正しいかどうかを簡単に確認することができます。

無効な承認

リフレッシュ トークンを使おうとして invalid_grant エラーが返された場合は、以下の理由が考えられます。

アプリケーションは、1 つの Google アナリティクス アカウントにアクセスするために複数のリフレッシュ トークンをリクエストすることができます。

たとえば、ユーザーが 1 つのアプリケーションを複数のコンピュータにインストールして、同じ Google アナリティクス アカウントにアクセスする場合は、コンピュータごとに別々のトークンが必要になります。 リフレッシュ トークンの数が制限を超えると、古いトークンが無効になります。アプリケーションが無効になったリフレッシュ トークンを使おうとすると、invalid_grant エラー レスポンスが返されます。

OAuth 2.0 クライアントと Google アナリティクス アカウントの固有なペアごとの制限は、25 リフレッシュ トークンです。アプリケーションが、同じクライアント / アカウントのペア向けにリフレッシュ トークンをリクエストし続けると、26 番目のトークンが発行されたときに、前に発行された最初のリフレッシュ トークンが無効になります。さらに、27 番目にリクエストされたリフレッシュ トークンによって、前に発行された 2 番目のトークンが無効になる、といった具合です。