Core Reporting API - 承認

このドキュメントでは、Core Reporting API にリクエストを送信するために、アプリケーションが承認を取得する方法を説明します。

リクエストの承認

ユーザーが Google アナリティクス ウェブサイトで自身のアカウント情報を表示するには、まず Google アカウントを使ってログインします。同様に、ユーザーは初めてアプリケーションにアクセスする際、自身のデータへのアクセスをアプリケーションに対して承認する必要があります。

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

承認プロトコルについて

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

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

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

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

  1. アプリケーションを作成したら、Google Developers Console を使用して登録します。すると、後で必要になるクライアント ID やクライアント シークレットなどの情報が Google から提供されます。
  2. Google Developers Console でアナリティクス API を有効にします(API が Developers Console に表示されない場合は、この手順をスキップしてください)。
  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 つの Developers Console プロジェクトをアプリケーションに使用できる点です。これによって、一元的にレポートを管理でき、インストールがシンプルになります。

サービス アカウント

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

Google アナリティクス向けにサービス アカウントを設定するために、以下の手順を実行します。

アナリティクス API を利用するには、まず Google Developers Console で新しいプロジェクトを作成するか、既存のプロジェクトを選択して API を有効にする必要があります。前述のリンクをクリックすると、画面の指示に従ってアナリティクス API を自動的に有効にすることができます。

また、次の手順に従い、Developers Console にアクセスして、自身でアナリティクス API を有効にすることもできます。

  1. [認証情報] ページを開きます。

いずれの場合も、最後に [認証情報] ページが表示され、ここでプロジェクトの認証情報を作成することができます。

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

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

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

トラブルシューティング

認証の過程で問題が発生し、401 または 403 ステータス コードを受信した場合の解決方法は次のとおりです。

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

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

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

OAuth 1.0 Playground。これは OAuth 2.0 Playground と同じツールですが、以前のバージョンの OAuth 向けです。

無効な承認

リフレッシュ トークンを使おうとして invalid_grant エラー レスポンスを受け取った場合、エラーの原因として以下の理由が考えられます。

  1. サーバーのクロックが NTP と同期していない。
  2. リフレッシュ トークンの制限を超えている。
    アプリケーションは、1 つの Google アナリティクス アカウントにアクセスするために複数のリフレッシュ トークンをリクエストすることができます。たとえば、ユーザーが 1 つのアプリケーションを複数のコンピュータにインストールして、同じ Google アナリティクス アカウントにアクセスする場合にこれが役立ちます。この場合、アプリケーションをインストールするごとにリフレッシュ トークンが必要になります。リフレッシュ トークンの数が制限を超えると、古いトークンが無効になります。アプリケーションが無効になったリフレッシュ トークンを使おうとすると、invalid_grant エラー レスポンスが返されます。OAuth 2.0 クライアントと Google アナリティクス アカウントの固有なペアごとの制限は、25 リフレッシュ トークンです(この制限は変更される場合があります)。アプリケーションが、同じクライアント / アカウントのペア向けにリフレッシュ トークンをリクエストし続けると、26 番目のトークンが発行されたときに、前に発行された最初のリフレッシュ トークンが無効になります。さらに、27 番目にリクエストされたリフレッシュ トークンによって、前に発行された 2 番目のトークンが無効になる、といった具合です。