このガイドでは、アプリケーションが User Deletion API へのリクエストを承認する方法について説明します。
リクエストの承認
ユーザーが Google アナリティクスのウェブサイトで自分のアカウント情報を確認するには、最初に Google アカウントにログインする必要があります。同様に、ユーザーが初めてアプリケーションにアクセスする際には、自身のデータにアクセスできるようアプリケーションを承認する必要があります。
アプリケーションからアナリティクス API に送信するすべてのリクエストには、認証トークンを含める必要があります。このトークンは Google でアプリケーションを識別するためにも使用されます。
認証プロトコルについて
リクエストを承認するために、アプリケーションは OAuth 2.0 を使用する必要があります。これ以外の認証プロトコルには対応していません。アプリケーションで「Google でログイン」を使用している場合、承認手続きの一部が自動化されます。
OAuth 2.0 を使用したリクエストの承認
アナリティクス API へのすべてのリクエストは、認証済みのユーザーによって承認される必要があります。
OAuth 2.0 の承認プロセス（「フロー」）の詳細は、開発対象のアプリケーションの種類によって若干異なりますが、次の一般的なプロセスはすべての種類のアプリケーションに当てはまります。
- アプリケーションの作成時に、Google API Console を使用してアプリケーションを登録します。すると、後で必要になるクライアント ID やクライアント シークレットなどの情報が Google から提供されます。
- Google API コンソールでアナリティクス API を有効にします（API が API コンソールに表示されない場合は、この手順をスキップしてください）。
- アプリケーションでユーザーデータにアクセスする必要がある場合は、特定のアクセスのスコープを Google にリクエストします。
- データをリクエストするアプリケーションの承認を求める Google の同意画面がユーザーに表示されます。
- ユーザーが承認すると、有効期間の短いアクセス トークンがアプリケーションに付与されます。
- アプリケーションは、リクエストにそのアクセス トークンを付与してユーザーデータをリクエストします。
- 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 アナリティクス データにアクセスするためにアプリケーションと直接やり取りする場合に最適です。サーバー側の機能を使わずに済みますが、レポートの自動作成、オフライン作成、スケジュールに基づく作成には向いていません。
例:
- Analytics Query Explorer などのブラウザベースのレポートツール。
インストール済みアプリケーション
このフローは、パッケージとして配布され、ユーザーによってインストールされたアプリケーションを対象としています。このフローでは、アプリケーションまたはユーザーがブラウザにアクセスして認証フローを完了する必要があります。
例:
- パソコン（Windows または Mac）のデスクトップ ウィジェット。
- コンテンツ マネジメント システムのプラグイン - ウェブサーバーまたはクライアント側と比較してこのフローが優れているのは、1 つの API Console プロジェクトをアプリケーションに使用できる点です。これにより、レポートの統合とユーザーによるインストールが容易になります。
サービス アカウント
サービス アカウントは、ご自身のアカウントの Google アナリティクス データに自動的、オフラインで、またはスケジュールどおりにアクセスする場合に便利です。たとえば、ご自身の Google アナリティクス データのライブ ダッシュボードを作成し、他のユーザーと共有することもできます。
アナリティクス API を使用するには、まずセットアップ ツールを使用して Google API Console でプロジェクトを作成し、API を有効にする必要があります。
新しいサービス アカウントを設定するには、以下の手順に従ってください。
- [認証情報を作成] > [サービス アカウント キー] をクリックします。
- サービス アカウントの公開鍵と秘密鍵を標準 P12 ファイルとしてダウンロードするか、Google API クライアント ライブラリで読み込むことのできる JSON ファイルとしてダウンロードするかを選択します。
新しい公開鍵と秘密鍵のペアが生成され、パソコンにダウンロードされます。 この鍵は再発行できませんので、大切に保管してください。
トラブルシューティング
次のような場合は承認に失敗します。
access_tokenが期限切れになっている場合や、API で間違ったスコープを使用している場合は、401ステータス コードが返されます。承認されたユーザーがビュー（プロフィール）にアクセスできない場合は、
403ステータス コードが返されます。正しいユーザーで認証されており、選択したビュー（プロファイル）が実際に存在することを確認します。
OAuth 2.0 Playground
このツールを使用すると、ウェブ インターフェースから承認フロー全体を実行できます。このツールでは、承認済みのクエリを実行するために必要なすべての HTTP リクエスト ヘッダーも表示されます。ご自身のアプリケーションで承認を得ることができない場合は、OAuth 2.0 Playground 経由で承認を試みてください。その後、Playground からの HTTP ヘッダーおよびリクエストとアプリケーションの送信内容を Google アナリティクスで比較することができます。これにより、リクエストの形式が正しいかどうかを簡単に確認できます。
無効な承認
更新トークンを使用しようとすると、次のエラーが返されます。invalid_grant
- サーバーのクロックが ネットワーク タイム プロトコル（NTP）と同期していない。
- 更新トークンの制限を超えている。
アプリケーションは 1 つの Google アナリティクス アカウントにアクセスする場合でも、複数の更新トークンをリクエストできます。
たとえば、複数のマシンにアプリケーションをインストールし、そのすべてで同じ Google アナリティクス アカウントにアクセスする場合、マシンごとに個別のトークンが必要になります。更新トークンの数が制限を超えると、古いトークンは無効になります。アプリケーションで無効な更新トークンが使用されると、invalid_grant エラーが返されます。
OAuth 2.0 クライアントと Google アナリティクス アカウントの固有のペアごとに、25 個の更新トークンが上限となります。同じクライアント/アカウントのペアでアプリケーションが更新トークンのリクエストを繰り返した場合、26 回目のトークンの発行時点で最初に発行された更新トークンが無効になります。27 回目のリフレッシュ トークン リクエストでは、2 回目に発行されたトークンが無効になります。