User Deletion API - 承認

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

リクエストの承認

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

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

認証プロトコルについて

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

OAuth 2.0 を使用したリクエストの承認

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

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

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

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

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

範囲 意味
https://www.googleapis.com/auth/analytics.user.deletion User Deletion 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 番目のトークンが無効になる、といった具合です。