cotomu

広告・計測API連携

Google Ads・GA4を、AIエージェントへつなぐ

cotomuは、Google Ads、Meta Ads、GA4、GTM、Search Consoleをpromotion単位へ接続します。MCP、CLI、REST APIから認可済みのデータを読み、レポート生成や社内workflowへ渡せます。

現在の連携先を送って相談する対応範囲を見る

利用できるservice、機能、更新頻度、OAuth scopeは契約・接続状態・各APIの提供条件により異なります。

SOURCE

Google Ads / Meta Ads
GA4 / GTM / Search Console

接続済みの広告・計測account

SCOPE

tenant
→ promotion
→ DataSourceAccount

READONLY / READ_WRITE

RESPONSE

CLI JSON
MCP tool response
REST response

認可範囲のquery結果

対応範囲

serviceごとに、readとwriteを分けて確認する

「連携できる」という一語では、分析だけか、設定変更まで含むかが分かりません。主要serviceのPublic API経路を、query、write、対象scopeに分けます。

servicereadwrite対象scope
Google AdsGAQL、検索語句、改善候補、simulationChange Plan接続済み広告アカウント
Meta AdsGraph nodeとfieldsのquery（MCP / REST）Change Plan接続済み広告アカウント
Google Analytics 4Admin API / Data APIのreport queryChange Plan認可済みproperty
Google Tag Managercontainer、workspace、tag等のqueryChange Plan認可済みcontainerとOAuth scope
Google Search Console検索performance、sitemap対象外認可済みsite（read-only）

上表はPublic API経路の整理です。cotomuの分析画面を含む全機能一覧ではありません。writeの対応operationと必要scopeはserviceごとに異なります。

広告レポート自動化

自動化するのは、まず取得と受け渡し

query responseを自社workflowへ渡せば、媒体ごとの転記を減らす構成を作れます。一方、指標定義、集計条件、コメント、共有前の確認は別の判断です。

  1. 01

    INPUT

    接続先と期間を決める

    promotionとDataSourceAccountを選び、queryの期間・指標・dimensionを固定します。

  2. 02

    QUERY

    認可済みデータを取得する

    CLI、MCP、REST APIのいずれかでresponseを受け取ります。

  3. 03

    HANDOFF

    既存workflowへ渡す

    JSONを集計、BI、spreadsheet、レポート下書きの処理へ渡します。

  4. 04

    REVIEW

    定義と共有内容を確認する

    運用担当者が集計条件と説明を確認し、変更が必要な場合だけChange Planへ分けます。

実行入口

利用者とworkflowに合わせて、入口を選ぶ

CLI
script、CI、定期実行するworkflow
cotomu google-ads query <PROMO_ID> <DSA_ID> --gaql …

OAuth login後にJSONで受け取り、retryやidempotency keyを扱えます。Meta Adsの透過readはCLI未対応です。

MCP
人がAI toolから対話的にquery
execute_ga4_query / execute_facebook_ads_query

自然文からtoolを選ぶ入口です。認証後もpromotionとDataSourceAccountの範囲は変わりません。

REST API
社内tool、独自UI、既存data pipeline
POST /api/v1/promotions/{id}/data_source_accounts/{dsa}/ga4/queries

OpenAPIで定義したendpointへ接続します。API key permissionとpromotion whitelistを設定できます。

READONLY

分析とレポート作成は、読み取りだけで始める

READONLYのAPI keyはquery系操作に限定できます。promotion whitelistと接続accountのscopeを組み合わせ、必要な案件だけをAIエージェントやCIへ渡します。

READ_WRITE / CHANGE PLAN

変更はresponseと切り離し、planへ積む

raw mutateの直接実行はchange_plan_requiredで拒否されます。対応するwriteはreasonとoperationをChange Planへ記録し、preview後に明示的にapplyします。

権限設計と変更確認のガイドを読む

導入時に決めること

accountを接続する前に、対象と出力先をそろえる

  1. 01

    対象をpromotionへ分ける

    client、brand、事業など、別accountへ越境させない業務単位を決めます。

  2. 02

    DataSourceAccountを接続する

    Google Ads、Meta Ads、GA4等のうち、必要なaccountとOAuth scopeを確認します。

  3. 03

    入口と出力先を選ぶ

    CLI、MCP、REST APIと、JSON、BI、spreadsheet等へ渡すworkflowを決めます。

  4. 04

    readから結果を照合する

    READONLYで同じ期間・指標を再現できるか確認し、必要な操作だけwriteへ広げます。

FAQ

API連携を決める前の確認

CLI・MCP・REST APIは同じデータへ接続しますか？

はい。いずれもcotomu Public APIを利用し、tenant、promotion、DataSourceAccountで認可範囲を限定します。ただし、入口ごとに提供commandやtoolの差があり、Meta Adsの透過readはCLIではなくMCPまたはREST APIを使います。

広告レポートを自動化できますか？

認可済みの広告・計測データをqueryし、JSON responseを自社の集計、BI、spreadsheet、レポート生成workflowへ渡せます。出力項目、更新頻度、共有方法、最終確認は要件により異なり、cotomuへの接続だけで完成レポートの定期配信まで一律に有効になるわけではありません。

読み取り専用で始められますか？

はい。分析やレポート作成だけに使う場合はREADONLYのAPI keyから始められます。promotion whitelistと接続済みDataSourceAccountも組み合わせ、必要な案件とアカウントだけへ範囲を限定します。

広告や計測設定の変更は直接実行されますか？

raw mutate endpointへの直接実行はchange_plan_requiredで拒否されます。対応するwriteはREAD_WRITE権限でChange Planへreasonとoperationを積み、preview後にapplyします。担当者確認はAPIが強制する承認状態ではないため、外部の運用手順として定めます。

NEXT STEP

現在の連携先と、データを渡したいworkflowを送る

使用中の広告媒体・計測service、レポートや社内toolの出力先、読み取りだけか変更も必要かを伺い、接続範囲を整理します。

現在の連携先を送って相談する