google-ads

Google Ads

Google Ads API（https://googleads.googleapis.com/v23/）を使用して Google Ads アカウントを操作するためのツールです。読み取りでは検索エンドポイントに対して GAQL（Google Ads Query Language）でクエリを記述し、書き込みではリソースごとの mutate エンドポイントを使用します。アカウントの移動、読み取りとレポート、キャンペーン／予算／コンバージョン トラッキングの管理に対応する13個のツールを提供します。Google Ads のアカウントは階層構造になっており、マネージャー（MCC）アカウントから、その配下のクライアントアカウントを操作できます。ほとんどのツールでは、操作対象アカウントの customerId と、マネージャーを経由して操作対象アカウントにアクセスする場合はオプションの loginCustomerId（マネージャーアカウント）が必要です。

Google Ads 用の独立した非公式コネクターです。Google Ads との提携、承認、後援を受けていません。「Google Ads」はそのサービスを識別する目的でのみ使用している、所有者の商標です。

使用する場面

• 操作するアカウントを特定する — 接続からアクセスできるアカウントを一覧表示し、マネージャー経由でアクセスする場合は、その配下のクライアントアカウントを一覧表示します。
• キャンペーン、広告グループ、広告を読み取る — ステータスや予算とともに一覧表示するか、構造化された読み取りでは対応できない内容について任意の GAQL クエリを実行します。
• パフォーマンスレポートを作成する — リソース、測定する指標、期間を選択します。
• キャンペーンと予算を管理する — キャンペーンを一時停止、有効化、または削除するか、1日の予算を作成または調整します。
• コンバージョン トラッキングを設定する — コンバージョン アクション（オフライン コンバージョンの UPLOAD_CLICKS アクションを含む）を一覧表示または作成します。

セットアップ

これは agentskills.io のスキルです。

コネクターをまだスキルとしてインストールしていない場合は、まず npx skills add zapier/connectors --skill google-ads（または、お使いのハーネス独自のスキルインストール手段）でインストールしてから、ここに進んでください。スキルをインストールすると、これらのファイルがコピーされます。依存関係はコピーされません。CLI、ローカル MCP サーバー、または zapier-sdk の認証コマンドを実行する前に、ここで一度 npm install --omit=dev を実行してください。公開パッケージを依存関係として自分のプロジェクトにインポートしますか？その場合は npm install ですべての依存関係が解決されます。詳しくは references/use-as-sdk.md をご覧ください。

代わりにリポジトリのソースを確認したい場合（references/ の閲覧、このコネクターのテスト実行、改変など）は、範囲を指定した git clone について README.md をご覧ください。

コネクターの実行には Node.js 22.18+ が必要です。実行方法に合ったリファレンスを選び、ほかの作業を始める前に読み込んでください。

使用環境	読み込むリファレンス
MCP 対応クライアント — ツールがすでに読み込まれている（例：mcp__google-ads__<tool>）か、ローカルサーバーを自分で登録できる（またはユーザーに案内できる）環境	references/use-as-mcp.md
ターミナル／サブプロセスへのアクセス（node を実行できる）	references/use-as-cli.md
自分のコードのみを使い、このパッケージを依存関係としてインポートする環境	references/use-as-sdk.md
ツール、ターミナル、パッケージのインポート手段がなく、Google Ads API を直接呼び出す独自コードを作成する環境（例：コード実行サンドボックス）	references/use-as-recipe.md

スクリプト

すべてのスクリプトで、接続 google-ads を使用します。顧客アカウントを対象とするスクリプトでは、運用アカウントの customerId（数字のみ）と、任意の loginCustomerId（マネージャー経由でアクセスする場合のマネージャーアカウント）を指定します。

スクリプト	スクリプト名	接続	説明
scripts/listAccessibleCustomers.ts	listAccessibleCustomers	google-ads	接続から直接アクセスできるアカウントを一覧表示します（アカウント解決のエントリーポイントです）。
scripts/listCustomerClients.ts	listCustomerClients	google-ads	マネージャーアカウント配下のクライアント（運用）アカウントを一覧表示します。
scripts/search.ts	search	google-ads	任意の GAQL クエリを実行します。読み取り操作をすべて網羅しています。
scripts/listSearchableFields.ts	listSearchableFields	google-ads	リソースで選択・フィルタリング・並べ替え可能なフィールドを一覧表示します（search クエリを組み立てます）。
scripts/listCampaigns.ts	listCampaigns	google-ads	ステータス、チャネルタイプ、予算、日付とともにキャンペーンを一覧表示します。
scripts/listAdGroups.ts	listAdGroups	google-ads	広告グループを一覧表示します。必要に応じて、特定のキャンペーンに絞り込めます。
scripts/listAds.ts	listAds	google-ads	広告を一覧表示します。必要に応じて、特定の広告グループに絞り込めます。
scripts/listConversionActions.ts	listConversionActions	google-ads	アカウントに設定されているコンバージョンアクションを一覧表示します。
scripts/getReport.ts	getReport	google-ads	パフォーマンスレポートを作成します。リソース、指標、セグメントを日付範囲で指定します。
scripts/setCampaignStatus.ts	setCampaignStatus	google-ads	キャンペーンを一時停止、有効化、または削除します。
scripts/createCampaignBudget.ts	createCampaignBudget	google-ads	1 日あたりのキャンペーン予算を作成します（金額はマイクロ単位）。
scripts/updateCampaignBudget.ts	updateCampaignBudget	google-ads	既存の予算の金額、名前、または配信方法を更新します。
scripts/createConversionAction.ts	createConversionAction	google-ads	コンバージョンアクションを作成します（オフラインのトラッキングには UPLOAD_CLICKS などを使用します）。

スクリプトを呼び出す前に、入力仕様を確認してください。フィールド名、大文字と小文字の区別、型を推測してはいけません。 スクリプトで --help を実行します（./scripts/<name>.ts --help または node cli.js run <name> --help）。inputSchema を JSON Schema として表示し、接続フラグとリゾルバーを一覧表示します。ペイロードを推測すると ZodError が発生し、余計な往復が生じます。

曖昧さの解消と拒否

• 金額の単位はマイクロです。 予算、入札単価、レポートの費用指標（*_micros）は、通貨額の1,000,000倍です（例：$50.00 → 50000000）。唯一の例外は、コンバージョン アクションのデフォルト値で、通常の通貨額です。cost_micros が5,000,000だからといって、「$5,000,000」と報告しないでください。
• 名前ではなくIDで操作してください。 書き込み操作（setCampaignStatus、updateCampaignBudget）にはIDを指定します。まず listCampaigns / search で名前からIDを特定してください。同じ名前のキャンペーンが2つある場合は、識別に使えるフィールド（ID、ステータス、チャネルタイプ）を含めて一覧表示し、どちらを操作するか確認してください。黙って一方を選ぶことは決してしないでください。
• 未対応の操作は代替せず、断ってください。 このコネクターでは、オフライン コンバージョンのアップロードや、カスタマー マッチ オーディエンスへのメンバー追加には対応していません（Googleは新しいAPI連携を、別のData Manager APIに誘導しています）。また、キャンペーン全体の作成や、キーワード、ターゲティング、広告クリエイティブの管理にも対応していません。依頼された場合は、別のツールで代用して成功したと報告せず、未対応であることを伝えてください。createConversionAction で設定できるのはコンバージョン アクション であり、コンバージョンをアップロードすることはできません。

認証

すべてのシェイプでは、認証情報そのものではなく、1つの接続 セレクター（[<resolver>:]<value> 形式の文字列）を渡して認証します。すべてのコネクターで zapier:<connection-id> を使用できます（Zapier管理の認証。Zapierの認証、再試行、ガバナンスのレイヤーを経由します）。コネクターによっては、直接トークン用のリゾルバーも1つ以上使用できます（名前と数はコネクターによって異なるため、推測せず、このコネクター独自のリゾルバーを確認してください）。<resolver>: のプレフィックスは省略可能です。プレフィックスのない値は、その値を受け付ける最初のリゾルバーに渡されます。UUID形式の値は、必ず zapier: によって受け付けられます。各スクリプトには、必要な接続と、各接続で受け付けるリゾルバーが記載されています。接続を渡す正確な構文と、このコネクターのリゾルバー一覧の確認方法はシェイプごとに異なります。上記で読み込んだリファレンスを参照してください。

すでに設定済みのものを先に確認しますか？そのために環境変数の値を出力しないでください。env または env | grep <name> は名前と値の両方を表示するため、値が設定されている場合、使用中の認証情報がログに漏れるおそれがあります。名前だけを確認する（env | cut -d= -f1 | grep -i <name>）か、既知の名前を直接テストしてください（[ -n "$VAR_NAME" ]）。

まだ接続がありませんか？接続方法を1つ選び、そのリファレンスに記載された手順に従って取得してください。接続IDやトークンをユーザーがすでに覚えているかのように、ただ尋ねることは決してしないでください。

	読み込むもの
認証情報を直接渡す	references/use-without-zapier.md
Zapier接続経由で渡す	references/use-with-zapier.md

出力形式

すべてのスクリプトは { data, meta } エンベロープを返します。

• data — スクリプトの結果（outputSchema が宣言する形式です。スクリプトの正確なスキーマを確認する方法については、上で読み込んだリファレンスを参照してください）。
• meta.outputDataValidation — data の検証結果です。
  • { skipped: false, droppedPaths: null } — 検証済みで、削除されたものはありません。
  • { skipped: false, droppedPaths: [...], instruction } — 検証済みですが、該当するパスが data から削除されました。これらは、スクリプトが API から返したフィールドのうち、outputSchema で宣言されていないものです。これらが必要な場合は、出力検証をスキップして再実行してください。
  • { skipped: true } — 検証はバイパスされ、data は未検証のスクリプト出力です。

削除されたフィールドの読み取り／skipOutputDataValidation。 生の未検証結果を受け取るには、出力検証を無効にします（正確な構文は shape によって異なります。上で読み込んだリファレンスを参照してください）。入力検証は常に行われます。

結果の絞り込み／filterOutputData。 大きな結果から必要なフィールドだけを取り出すには、data を後処理する jq 式を渡します（正確な構文は shape によって異なります）。jq は { data, meta } エンベロープではなく data のみを対象とするため、data をルートとして記述してください（スクリプトの --help または shape に相当するオプションを実行すると、出力スキーマを確認できます）。変換後の値が data を置き換え、meta は保持されます。結果は出力スキーマに対して再検証されません。

リファレンス

該当する領域で作業する前に、対応するリファレンスファイルを読み込んでください。

リファレンス	対象	読み込むタイミング
references/google-ads-api-gotchas.md	認証ヘッダー、アカウント階層、GAQL、マイクロ単位、ミューテーションの意味、エラー、レート制限、コンバージョントラッキング、バージョン管理。	GAQL クエリを作成する前、金額フィールド（マイクロ単位）を扱うとき、キャンペーンのステータスを設定するとき、または Google Ads API のエラーを解釈するとき。