このドキュメントでは、Tag Manager API にリクエストを送信する際、アプリケーションがどのように承認を得るのか説明します。
リクエストの承認
ユーザーが Google サイトで自分のアカウント情報を確認するには、最初に Google アカウントにログインする必要があります。同様に、ユーザーが初めてアプリケーションにアクセスする際には、自身のデータにアクセスできるようアプリケーションを承認する必要があります。
アプリケーションから Tag Manager API に送信するリクエストには、必ず承認トークンが含まれている必要があります。このトークンは Google でアプリケーションを識別するためにも使用されます。
認証プロトコルについて
リクエストを承認するために、アプリケーションは OAuth 2.0 を使用する必要があります。これ以外の認証プロトコルには対応していません。アプリケーションで「Google でログイン」を使用している場合、承認手続きの一部が自動化されます。
OAuth 2.0 を使用したリクエストの承認
Tag Manager API に対するリクエストはすべて、認証済みのユーザーから承認を受ける必要があります。
OAuth 2.0 の承認プロセス（「フロー」）の詳細は開発するアプリケーションの種類によって若干異なりますが、次の一般的なプロセスはすべての種類のアプリケーションに当てはまります。
- アプリケーションの作成時に、Google API Console を使用してアプリケーションを登録します。登録すると、後で必要になるクライアント ID やクライアント シークレットなどの情報が Google から提供されます。
- Google API Console で Tag Manager API を有効にします（Tag Manager API が API Console に表示されない場合は、この手順をスキップしてください）。
- アプリケーションでユーザーデータにアクセスする必要がある場合は、特定のアクセスのスコープを Google にリクエストします。
- データをリクエストするアプリケーションの承認を求める Google の同意画面がユーザーに表示されます。
- ユーザーが承認すると、有効期間の短いアクセス トークンがアプリケーションに付与されます。
- アプリケーションは、リクエストにそのアクセス トークンを付与してユーザーデータをリクエストします。
- Google がそのリクエストとトークンが有効であると判断すると、リクエストされたデータが返されます。
プロセスによっては、更新トークンを使用して新しいアクセス トークンを取得するなど、追加の手順が必要になる場合もあります。各種アプリケーションのフローについて詳しくは、Google の OAuth 2.0 ドキュメントをご覧ください。
以下は、Tag Manager API の OAuth 2.0 のスコープに関する情報です。
| スコープ | 意味 |
|---|---|
https://www.googleapis.com/auth/tagmanager.readonly |
Google タグ マネージャーのコンテナの表示。 |
https://www.googleapis.com/auth/tagmanager.edit.containers |
Google タグ マネージャーのコンテナの管理。 |
https://www.googleapis.com/auth/tagmanager.delete.containers |
Google タグ マネージャーのコンテナの削除。 |
https://www.googleapis.com/auth/tagmanager.edit.containerversions |
Google タグ マネージャーのコンテナ バージョンの管理。 |
https://www.googleapis.com/auth/tagmanager.publish |
Google タグ マネージャーのコンテナの公開。 |
https://www.googleapis.com/auth/tagmanager.manage.users |
Google タグ マネージャーのデータのユーザー権限の管理。 |
https://www.googleapis.com/auth/tagmanager.manage.accounts |
Google タグ マネージャー アカウントの管理。 |
OAuth 2.0 を使用してアクセスをリクエストする場合、アプリケーションを登録したときに Google から提供された情報（クライアント ID やクライアント シークレットなど）に加えて、スコープ情報が必要になります。
はじめに
Tag Manager API を使用するには、最初に設定ツールを使用して Google API Console でプロジェクトを作成し、API を有効にして認証情報を作成する必要があります。
新しいサービス アカウントを設定するには、以下の手順に従ってください。
- [認証情報を作成] > [サービス アカウント キー] をクリックします。
- サービス アカウントの公開鍵と秘密鍵を標準 P12 ファイルとしてダウンロードするか、Google API クライアント ライブラリで読み込むことのできる JSON ファイルとしてダウンロードするかを選択します。
新しい公開鍵と秘密鍵のペアが生成され、パソコンにダウンロードされます。 この鍵は再発行できませんので、大切に保管してください。
OAuth 2.0 の一般的フロー
以下のガイドラインでは、特定の OAuth 2.0 フローでの一般的な使用例を紹介します。
ウェブサーバー
このフローは、ユーザーの Google タグ マネージャー アカウントに自動的、オフラインで、またはスケジュールどおりにアクセスする場合に適しています。
- サーバーからタグ マネージャーの情報を自動的に更新する。
クライアント側
Google タグ マネージャー アカウントにアクセスするアプリケーションと、ユーザーがブラウザで直接やり取りする場合に最適です。 サーバー側の機能を使わずに済みますが、レポートの自動作成、オフライン作成、スケジュールに基づく作成には向いていません。
- カスタマイズされたブラウザベースの設定ツール。
インストール済みアプリ
パッケージとして配布され、ユーザーによってインストールされたアプリケーションでは、 アプリケーションまたはユーザーがブラウザにアクセスして認証フローを完了する必要があります。
- パソコン（Windows または Mac）のデスクトップ ウィジェット。
- コンテンツ管理システム用のプラグイン。ウェブサーバーまたはクライアント側と比較してこのフローが優れているのは、1 つの API Console プロジェクトをアプリケーションに使用できる点です。これにより、ユーザーによるインストールが容易になります。
サービス アカウント
ご自身の Google タグ マネージャー アカウントに自動的、オフラインで、またはスケジュールどおりにアクセスする場合に適しています。たとえば、ご自身の Google タグ マネージャー アカウントを監視するカスタムツールを作成し、それを他のユーザーと共有することもできます。
トラブルシューティング
access_token が期限切れになっているか、特定の API 呼び出しでスコープが間違っていた場合は、レスポンスで 401 ステータス コードが返されます。
承認されたユーザーが Google タグ マネージャー アカウントやコンテナにアクセスできない場合は、レスポンスで 403 ステータス コードが返されます。適切なユーザーから承認を得たうえで、タグ マネージャー アカウントやコンテナにアクセスする権限が付与されていることを確認してください。
OAuth 2.0 Playground
OAuth 2.0 Playground は、管理画面から承認フローを最後まで実行できるツールです。このツールでは、承認済みのクエリを実行するために必要なすべての HTTP リクエスト ヘッダーも表示されます。ご自身のアプリケーションで承認を得ることができない場合は、OAuth 2.0 Playground 経由で承認を試みてください。その後、Playground からの HTTP ヘッダーおよびリクエストとアプリケーションの送信内容を比較することができます。 これにより、リクエストの形式が正しいかどうかを簡単に確認できます。
無効な承認
更新トークンを使おうとして invalid_grant エラーが返ってきた場合は、次のいずれかまたは両方が原因として考えられます。
- サーバーのクロックが NTP と同期していない。
- 更新トークンの制限を超えている。
アプリケーションは 1 つの Google タグ マネージャー アカウントにアクセスする場合でも、複数の更新トークンをリクエストできます。これは、複数のマシンにアプリケーションをインストールし、そのすべてで同じ Google タグ マネージャー アカウントにアクセスする場合などに便利です。この場合、アプリケーションをインストールするごとに更新トークンが必要になります。 更新トークンの数が制限を超えると、古いトークンは無効になります。アプリケーションで無効な更新トークンが使用されると、invalid_grantエラーが返されます。Client-ID とアカウントの組み合わせごとに、最大 25 個の更新トークンを取得できます（この制限は変更される可能性があります）。 同じ Client-ID とアカウントの組み合わせでアプリケーションが更新トークンのリクエストを繰り返した場合、26 回目のトークンの発行時点で最初に発行されたトークンが無効になります。27 回目になると、2 回目に発行されたトークンが無効になります。