ユーザー権限 - デベロッパー ガイド

このドキュメントでは、Management API を使用して Google アナリティクス アカウントのプロパティとビュー（旧プロファイル）のユーザー権限を表示、管理するための重要な概念について説明します。

はじめに

Management API のユーザー権限を使用すると、Google アナリティクスのアカウントでユーザーを一覧表示、作成、編集、削除することができます。これは、Google アナリティクスへの新しいユーザーの追加、Google アナリティクスから一連のユーザーを削除したりするのを自動化する場合に便利です。

準備

Google アナリティクス API はすべて同じ方法でアクセスできます。Management API を使用する前に、以下の準備をしてください。

  • API を扱うプログラミング言語固有のクライアント ライブラリのリストについてクライアント ライブラリ ページで確認します。
  • API インターフェースと、クライアント ライブラリを使わずにデータにアクセスする方法についてリファレンス ガイドで確認します。

各クライアント ライブラリは、すべての Management API データにアクセスするための 1 つの Analytics サービス オブジェクトを提供します。このサービス オブジェクトを作成するには、通常、次の手順に従います。

  1. Google Developers Console でアプリケーションを登録します。
  2. Google アナリティクス データへのアクセスを承認します。
  3. Analytics サービス オブジェクトを作成します。

上記の手順を完了していない場合は、まず Google アナリティクス API についてのチュートリアルをご覧ください。このチュートリアルでは、Google アナリティクス API アプリケーションを作成する基本的な手順を詳しく説明しています。この手順を完了すると、Google アナリティクス API を実際の作業に活用する方法を理解することができます。

コンセプト

アカウントの階層構造

Google アナリティクスのアカウントは階層構造になっていて、単一の認証済みユーザーに複数のアカウントを割り当てることができます。また、各アカウントには複数のプロパティを、各プロパティには複数のビュー（旧プロファイル）を割り当てることができます。

最上位レベルに 1 つのアカウント、2 番目のレベルにはそのアカウントに結合されている 2 つのウェブ プロパティがあります。3 番目のレベルでは、1 つのプロファイルが左側のウェブ プロパティに、2 つのプロパティが右側のウェブ プロパティに結合されています。ユーザーと権限は、それぞれ 3 レベルあります。
図 1: アカウントの階層構造

権限レベル

Google アカウントによって表されるユーザーには、Google アナリティクスのアカウント、プロパティ、ビューへのアクセスをさまざまなレベルで許可することができます。

アクセスのレベルは次のとおりです。

  • MANAGE_USERS
  • EDIT
  • COLLABORATE
  • READ_AND_ANALYZE

アクセスの各レベルについて詳しくは、ユーザー権限をご覧ください。

権限の継承

あるアカウントに対する EDIT 権限がユーザーに許可されると、このアカウントのすべてのプロファイルとプロパティにもこの権限が継承されます。同様に、あるプロパティに対する COLLABORATE 権限がユーザーに許可されると、このプロパティのすべてのプロファイルにもこの権限が継承されます。

権限の操作

API では、local と effective の 2 種類の権限が公開されています。local 権限は、実際のアカウント、プロパティ、ビューに適用されます。設定できるのは local 権限のみです。effective 権限は、親リソースから継承される権限を表します。

認証済みユーザーの権限の取得

現在認証されているユーザーの権限情報を取得するには、list や get の操作をアカウント、ウェブ プロパティ、または ビューのリソースに対して実行します。

これらの操作を実行するには、ユーザーが次のスコープのいずれかを承認する必要があります。

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics

ユーザー権限の管理

次のリソースは、Google アナリティクスのアカウント、プロパティ、ビューのユーザー権限を表示、管理するために使用できます。

これらの操作を実行できるのは、MANAGE_USERS レベルの権限を持ち、次のスコープを承認しているユーザーのみです。

  • https://www.googleapis.com/auth/analytics.manage.users スコープ。

アカウント ユーザー リンクの制限事項

API には、ユーザーあたりのアカウントは 100 個までという上限があります。

  • 既に 100 個以上のアカウントを持つユーザーで insert メソッドを呼び出そうとすると、エラーが返されます。
  • 一般的な制限事項については、制限と割り当てをご覧ください。

使用例

Management API のユーザー権限を使用すると、次のような使用例を解決できます。

アカウントのすべてのユーザーを一覧表示する

accountUserLinks リソースの list メソッドを実行するだけで、アカウントのすべてのユーザー（そのアカウントの任意のプロパティやビューに対する権限を持つすべてのユーザーを含む）を一覧表示することができます。

アカウントの階層構造からユーザーを削除する

アカウントの階層構造（アカウント、プロパティ、ビューなど）で表示されているすべてのユーザーを削除します。これを実行するために必要な手順は次のとおりです。

  1. エンティティ レベルごとにすべてのユーザーリンクを取得します。
    アカウントに対する次の 3 つの list リクエストを実行します。
    1. list メソッドを使用してすべての accountUserLinks を一覧表示します。
    2. list メソッドを使用してすべての webpropertyUserLinks を一覧表示します（このとき webpropertyId パラメータを ~all に設定します）。
    3. list メソッドを使用してすべての profileUserLinks を一覧表示します（このとき webpropertyId パラメータと profileId パラメータを ~all に設定します）。
  2. local 権限を持つユーザーを検索して削除します。
    手順 1 で 3 つの list 操作から得られたレスポンスごとに、次のように各 entityUserLink を反復処理します。
    • userRef プロパティがユーザーと一致している、かつ local 権限が設定されていることを条件に、そのリソースで delete メソッドを実行します。

アカウント ユーザー リンク、ウェブ プロパティ ユーザー リンク、ビュー ユーザー リンクのリソースの delete メソッドの詳細については、API リファレンスをご覧ください。

1 人のユーザーを更新する

ユーザー権限は、Management API を使用して更新することもできます。たとえば、ビューの名前や ID がわからない場合に、ユーザーの権限レベルを READ_AND_ANALYZE から EDIT に変更する手順は次のとおりです。

  1. エンティティ レベルごとにすべてのユーザーリンクを取得します。
    アカウントに対する次の 3 つの list リクエストを実行します。
    1. list メソッドを使用してすべての accountUserLinks を一覧表示します。
    2. list メソッドを使用してすべての webpropertyUserLinks を一覧表示します（このとき webpropertyId パラメータを ~all に設定します）。
    3. list メソッドを使用してすべての profileUserLinks を一覧表示します（このとき webpropertyId パラメータと profileId パラメータを ~all に設定します）。
  2. local 権限を持つユーザーを検索して更新します。
    手順 1 で 3 つの list 操作から得られたレスポンスごとに、次のように各 entityUserLink を反復処理します。
    • userRef プロパティがユーザーと一致している、かつ READ_AND_ANALYZE アクセスと共に local 権限が設定されていることを条件に、そのリソースで update メソッドを実行します。

アカウント ユーザー リンク、ウェブ プロパティ ユーザー リンク、ビュー ユーザー リンクのリソースの update メソッドの詳細については、API リファレンスをご覧ください。

1 人のユーザーを追加する

ビューなどのアカウントの階層構造にユーザーを追加するには、次の手順に従ってください。

  1. Management API または管理画面を使って、アカウント、プロパティ、ビューの ID を取得します。
  2. profileUserLinks リソースの insert メソッドを実行してユーザーを追加します。

アカウント ユーザー リンク、ウェブ プロパティ ユーザー リンク、ビュー ユーザー リンクのリソースの insert メソッドの詳細については、API リファレンスをご覧ください。

バッチ処理

ユーザー権限 API 書き込み（delete、insert、update）リクエストをバッチ処理すると、パフォーマンスが向上し、割り当ての面でもメリットがあります。

  • ユーザー権限リクエストをバッチ処理することで、バックエンドの最適化を利用でき、大幅にパフォーマンスが向上します。
  • バッチ処理したユーザー権限 API リクエストは、30 件単位で 1 件の書き込み操作としてカウントされます。
  • 1 件のバッチ リクエストで最大 300 件のユーザー権限 API リクエストを実行でき、ユーザー 1 人あたりの制限 QPS が向上します。

パフォーマンスを最大限向上させるには、次のようにしてください。

  • API リクエストをユーザーごとにグループ化します。
  • バッチ リクエストは 1 つのアカウントに対してのみ行います。複数の Google アナリティクス アカウントでユーザー権限リクエストをバッチ処理すると、エラーが発生し、「バッチ リクエストはすべて同じアカウントで実行してください」というメッセージが出力されます。

バッチ処理の例 - Python

下に示す簡単な Python の例では、リクエストをバッチ処理して、ビューのセットにユーザーのリストを追加する方法を示しています。この例では、承認済みユーザーのアカウントをループ処理して、各アカウントにつき 1 件のバッチ リクエストを作成しています。各バッチ リクエストの中では、対象のユーザーのすべての変更をグループ化しています。