GoogleタグマネージャーをAPIで操作｜Tag Manager API v2で変数・トリガー・タグを設定する方法

Google Tag Manager（GTM）の変数・トリガー・タグは、 Tag Manager API v2 でコードから操作できます。作成・更新からワークスペース管理、バージョン作成、公開までREST APIで完結します。

本記事では、APIでできること、管理画面・JSONインポートとの使い分け、サービスアカウントの権限設定、Node.jsの実装例、クォータと公開まわりの運用の注意点を整理します。

01.結論：GTMはAPIでフル操作できる

Tag Manager API v2 で、GTMの管理画面でできる設定作業のほぼすべてを実行できます。 デベロッパーガイド のとおり、アカウント・コンテナ・ワークスペースの管理、タグ・トリガー・変数のCRUD（作成・取得・更新・削除）、バージョン作成、公開までAPIが揃っています。

APIがあることでGTMをプログラムから操作できるため、Claude CodeなどのAIエージェントに設定作業を頼めるようになります。一度きりの設定でも、依頼するだけで済むのは楽です。

02.Tag Manager API v2 でできること

Tag Manager API v2 は、エンドポイントhttps://tagmanager.googleapis.comに対してaccounts/{アカウントID}/containers/{コンテナID}/workspaces/{ワークスペースID}/...という階層のパスでアクセスするREST APIです。GTMの管理画面と同じ構造（アカウント > コンテナ > ワークスペース > 各エンティティ）がそのままリソースになっています。主なリソースと操作は次のとおりです（詳細は RESTリファレンスを参照）。

「変数とトリガーを作り、タグを作って、バージョンを作成・公開する」という一連の設定作業を、すべてHTTPリクエストで表現できます。クライアントライブラリもPython・Node.js・Javaなど主要言語に用意されています。

03.管理画面・JSONインポート・APIの使い分け

GTMの設定を変更する手段は3つあり、それぞれ得意な場面が違います。

Googleの ヘルプ記事「コンテナのエクスポートとインポート」 によると、コンテナ全体をJSONで書き出し、編集して別のコンテナに取り込めます。既存サイトと同じタグ構成を新しいサイトに立ち上げるような「まとまった引っ越し」は、APIを書くまでもなくこの機能で足ります。APIが活きるのは、設定変更が繰り返し発生する場合と、作業者がプログラム（AIエージェントを含む）の場合です。

なお、管理画面での基本操作や、タグ・トリガー・変数といったGTM自体の基礎は、別記事で体系的に解説しています。

04.セットアップ：サービスアカウントにGTMの権限を渡す

初回セットアップの手順

認証はOAuth 2.0です。自動化には、プログラム専用のGoogleアカウントであるサービスアカウントを使います。初回だけ次の設定を人間が行います。

1. Google Cloud コンソールでプロジェクトを用意し、Tag Manager API を有効化します。
2. サービスアカウントを作成し、認証用のキー（JSON）を発行します。
3. GTMの管理画面（管理 > ユーザー管理）で、サービスアカウントのメールアドレスを通常のユーザーと同じように追加し、コンテナ権限を付与します。
4. スクリプトの実行環境に、キーのパスや内容を環境変数として設定します。

サービスアカウントは「...iam.gserviceaccount.comで終わるメールアドレスのユーザー」としてGTMに招待でき、特別な連携設定なしで人間と同じ権限管理に乗ります。

OAuthスコープとGTMユーザー権限の二段構え

APIで何ができるかは、OAuthスコープ（アプリケーションに何を許可するか）とGTMのユーザー権限（そのアカウントに何を許可するか）の両方で決まります。主なスコープは 認可のドキュメント で次のように定義されています。

一方、GTM側のコンテナ権限は、 ヘルプ記事「ユーザーと権限の管理」 によると「読み取り」「編集」「承認」「公開」の4段階です。「編集」はワークスペースの編集まで、「承認」はバージョン作成まで、公開には「公開」が必要です。公開だけ人間が承認する形にしたい場合は、サービスアカウントへの付与を「承認」までにし、スコープからもtagmanager.publishを外せば、公開操作を二重に防げます。

サービスアカウントを追加できない場合の代替策

GTMのユーザー管理（招待状の送信）でサービスアカウントのメールアドレスを入力すると、送信前のバリデーションで拒否されることがあります。この場合、まず試す価値があるのがAPIの user_permissions.create でユーザーを追加する方法です。管理画面のバリデーションだけが原因で、API経由なら同じアドレスを問題なく追加できるケースがあるためです（OAuthスコープ tagmanager.manage.users と、GTMアカウントの管理者権限が必要です）。

await tagmanager.accounts.user_permissions.create({
  parent: "accounts/1234567890",
  requestBody: {
    emailAddress: "サービスアカウントのメールアドレス",
    accountAccess: { permission: "user" },
    containerAccess: [{ containerId: "12345678", permission: "publish" }],
  },
});

API経由でも拒否される場合は、組織のユーザーポリシーで追加できるアカウントのドメインが制限されているケースです。このときは、GTMの権限をすでに持っている本人のGoogleアカウントでOAuth認証する手もあります。GTM側の設定変更が一切不要で、本人の権限（公開まで持っていれば公開も）をそのまま使えます。ただし、実装には次の2点の注意があります。

• gcloud CLI 標準のクライアントIDで Tag Manager のスコープを要求すると、Googleが「このアプリはブロックされます」と認可を拒否することがあります。Google Cloud コンソールで自前のOAuthクライアント（デスクトップアプリ型）を作成し、組織内のアカウントだけが使うなら同意画面の対象を「内部」にすると、審査なしで必要なスコープを要求できます。
• 取得したリフレッシュトークンは、gcloud のアプリケーションデフォルト認証情報（ADC）とは別の専用ファイルに保存するのが安全です。ADCの置き場所を共有すると、他のプロジェクトの認証と上書きし合う事故が起きやすくなります。

無人実行（CIなど）が必要になった段階で、組織ポリシーを確認のうえサービスアカウント方式を再検討する、という順番で十分です。

05.実装例：変数・トリガー・タグの作成からバージョン作成まで

実装例はNode.js（公式の googleapis パッケージ）で、題材は弊社のサイトで実際に使っている計測です。ページ側はツールの操作時にdataLayerへカスタムイベントを積んでおり、GA4に届けるには「データレイヤー変数 → カスタムイベントトリガー → GA4イベントタグ」の3点をGTM側に作ります。なお、コード例は説明のためにパラメータを tool と action の2つに絞り、エラー処理も省いた簡略版です。運用時は実際のイベント仕様に合わせて変数を増やし、try/catch とクォータ超過（403）時のリトライを足してください。

window.dataLayer.push({
  event: "tool_action",      // イベント名
  tool: "json-formatter",    // どのツールか
  action: "copy",            // どの操作か
});

認証クライアントの準備

サービスアカウントのキーを使って認証クライアントを作ります。この例のスコープは、設定変更とバージョン作成までです。

import { google } from "googleapis";

const auth = new google.auth.GoogleAuth({
  keyFile: process.env.GTM_SA_KEY_FILE, // サービスアカウントのキー（JSON）
  scopes: [
    "https://www.googleapis.com/auth/tagmanager.edit.containers",
    "https://www.googleapis.com/auth/tagmanager.edit.containerversions",
  ],
});

const tagmanager = google.tagmanager({ version: "v2", auth });

// 操作対象のワークスペースのパス
const parent =
  "accounts/1234567890/containers/12345678/workspaces/12";

アカウントID・コンテナIDは、GTM管理画面のURLか、APIのaccounts.list→containers.listで確認できます。GTM-XXXXXXX形式の公開IDとは別の数値IDです。

データレイヤー変数の作成

dataLayerのtoolとactionをタグから参照するための変数を作ります。type はv（データレイヤー変数）です。

for (const key of ["tool", "action"]) {
  await tagmanager.accounts.containers.workspaces.variables.create({
    parent,
    requestBody: {
      name: `DLV - ${key}`,
      type: "v", // データレイヤー変数
      parameter: [
        { type: "template", key: "name", value: key },
        { type: "integer", key: "dataLayerVersion", value: "2" },
      ],
    },
  });
}

カスタムイベントトリガーの作成

event: "tool_action"が積まれたときに発火するトリガーです。type はcustomEventで、イベント名の一致条件をcustomEventFilterに書きます。

const { data: trigger } =
  await tagmanager.accounts.containers.workspaces.triggers.create({
    parent,
    requestBody: {
      name: "CE - tool_action",
      type: "customEvent",
      customEventFilter: [
        {
          type: "equals",
          parameter: [
            { type: "template", key: "arg0", value: "{{_event}}" },
            { type: "template", key: "arg1", value: "tool_action" },
          ],
        },
      ],
    },
  });

GA4イベントタグの作成

イベントをGA4に送るタグです。type はgaaweで、イベントパラメータはeventSettingsTableキーに parameter / parameterValue の組で渡します（現行の管理画面で作ったタグと同じ形式）。値はデータレイヤー変数を{{DLV - tool}}の形で参照し、発火条件には作成したトリガーのIDを渡します。

if (!trigger.triggerId) {
  throw new Error("トリガー作成のレスポンスに triggerId がありません");
}

await tagmanager.accounts.containers.workspaces.tags.create({
  parent,
  requestBody: {
    name: "GA4 - tool_action",
    type: "gaawe", // GA4イベントタグ
    parameter: [
      { type: "template", key: "eventName", value: "tool_action" },
      {
        type: "template",
        key: "measurementIdOverride",
        value: "G-XXXXXXXXXX",
      },
      {
        type: "list",
        key: "eventSettingsTable",
        list: [
          {
            type: "map",
            map: [
              { type: "template", key: "parameter", value: "tool" },
              {
                type: "template",
                key: "parameterValue",
                value: "{{DLV - tool}}",
              },
            ],
          },
          {
            type: "map",
            map: [
              { type: "template", key: "parameter", value: "action" },
              {
                type: "template",
                key: "parameterValue",
                value: "{{DLV - action}}",
              },
            ],
          },
        ],
      },
    ],
    firingTriggerId: [trigger.triggerId],
  },
});

バージョン作成と公開

ワークスペースに積んだ変更は、create_versionでコンテナバージョンにまとめます。このメソッドはバージョン作成と同時にワークスペースを削除します。続けてversions.publishを呼べば公開まで自動化できます。慎重に運用したい場合は、公開だけ人間が承認する形にしておくと安心です（運用の注意点で触れます）。

const { data } =
  await tagmanager.accounts.containers.workspaces.create_version({
    path: parent,
    requestBody: {
      name: "tool events v1",
      notes: "無料ツールの計測イベント（tool_action / tool_cta_click）を追加",
    },
  });

// タグ定義の誤りはHTTPエラーではなく compilerError フラグで返る
if (data.compilerError) {
  throw new Error("コンパイルエラー。ワークスペースを確認してください");
}

// 公開には tagmanager.publish スコープとGTMの「公開」権限が必要
await tagmanager.accounts.containers.versions.publish({
  path: data.containerVersion.path,
});

バージョン作成と公開のレスポンスにはcompilerErrorというフラグがあり、タグ定義に誤りがあってもHTTPエラーにはなりません。フラグを確認せずに成功扱いにすると、壊れた定義に気づかないまま作業を終えてしまうので、上の例のように両方のレスポンスで確認してください。

06.運用の注意点：クォータと公開の扱い

注意点は2つあります。1つ目はクォータです。 公式の「制限と割り当て」 によると、デフォルトはプロジェクトあたり1日10,000リクエスト・毎秒0.25クエリ（毎分15リクエスト相当）で、超えると403エラーが返ります（2026年6月時点。引き上げの申請は可能です）。タグ数本の同期なら問題ありませんが、一括操作にはリクエスト間隔の調整とリトライが必要です。

2つ目は公開の扱いです。計測タグは誤って公開してもサイトの表示は壊れませんが、誤配信の間に集計されたデータは信頼できなくなり、後から取り戻せません。誤配信が不安なら、公開だけ人間が承認する形にして、GTMプレビューとGA4のDebugViewでイベントの着弾を確認してから公開するとよいでしょう。

なお、計測データの信頼性はbot流入でも損なわれます。bot前提の計測設計は、別記事「GA4の数値がbotで汚染される原因と対策」で整理しています。

07.よくある質問（FAQ）

08.まとめ

GTMは Tag Manager API v2 で、変数・トリガー・タグの作成からバージョン作成・公開までフル操作できます。APIがあることでGTMをプログラムから操作でき、Claude CodeなどのAIエージェントに設定作業を頼めるようになります。

セットアップは、Tag Manager API の有効化、サービスアカウントの作成、GTMへのユーザー追加の3点だけです。クォータの低さにだけ注意して、まずは検証用コンテナで試してみてください。