Google 広告との連携

このページでは、Cortex Framework Data Foundation のマーケティング ワークロードのデータソースとして Google 広告からデータを取得するために必要な構成について説明します。

Google 広告は、さまざまな Google サービスに商品やサービスを宣伝できるオンライン広告プラットフォームです。Cortex Framework は、Google 広告のデータを他のマーケティング チャネルと統合し、包括的に分析して、AI を活用してキャンペーンの成果を高めます。

次の図は、Cortex Framework Data Foundation のマーケティング ワークロードで Google 広告データを利用できるようにする方法を示しています。

Google 広告のデータソース

図 1Google 広告のデータソース。

構成ファイル

config.json ファイルでは、Google 広告を含む任意のデータソースからデータを転送するために必要な設定を構成します。このファイルには、Google 広告の次のパラメータが含まれています。

  "marketing": {
          "deployGoogleAds": true,
          "GoogleAds": {
              "deployCDC": true,
              "lookbackDays": 180,
              "datasets": {
                  "cdc": "",
                  "raw": "",
                  "reporting": "REPORTING_GoogleAds"
                    }
                  }
                 }

次の表に、Google 広告の各マーケティング パラメータの値を示します。

パラメータ 意味 デフォルト値 説明
marketing.deployGoogleAds Google 広告を導入する true Google 広告データソースのデプロイを実行します。
marketing.GoogleAds.deployCDC Google 広告用 CDC をデプロイする true Google 広告の CDC 処理スクリプトを生成して、Cloud Composer で DAG として実行します。
marketing.GoogleAds.lookbackDays Google 広告のルックバック期間 180 Google Ads API からデータの取得を開始する日数。
marketing.GoogleAds.datasets.cdc Google 広告の CDC データセット Google 広告の CDC データセット。
marketing.GoogleAds.datasets.raw Google 広告の元データセット Google 広告の元データセット。
marketing.GoogleAds.datasets.reporting Google 広告のレポート データセット "REPORTING_GoogleAds" Google 広告のレポート データセット。

データモデル

このセクションでは、エンティティ関係図（ERD）を使用して Google 広告データモデルについて説明します。

Google 広告のエンティティ関係図

図 2Google 広告: エンティティ関係図

ベースビュー

これらは ERD の青色のオブジェクトであり、CDC テーブルのビューで、一部の列名エイリアス以外の変換はありません。スクリプトは src/marketing/src/GoogleAds/src/reporting/ddls にあります。

レポートビュー

これらは ERD の緑色のオブジェクトであり、集計指標を含むレポートビューです。スクリプトは src/marketing/src/GoogleAds/src/reporting/ddls にあります。

API 接続

Cortex Framework 取り込みテンプレートは、Google 広告 API を使用して、Google 広告からレポート属性と指標を取得します。現在の Cortex Framework テンプレートでは、Google Ads API バージョン 17.1 が使用されています。Google Ads API の制限事項を検討してください。

  • 1 日あたりの基本アクセス オペレーション: 15,000（有効な next_page_token を含むページ分けリクエストはカウントされません）。
  • 最大ページサイズ: ページあたり 10,000 行。
  • 推奨されるデフォルト パラメータ: ページサイズは 1 ページあたり 10,000 行です。

API 接続の詳細については、Google 広告 API のドキュメントをご覧ください。

アカウント認証

アカウント認証を設定する手順は次のとおりです。

  1. Google Cloud コンソールで、ナビゲーション メニュー > [API とサービス] > [認証情報] > [認証情報を作成] をクリックします。

  2. 次の特性を持つ OAuth クライアント ID 認証情報を作成します。詳細については、OAuth 2.0 を使用した Google API へのアクセスをご覧ください。

    Application type: "Web Application"
Name: CHOSEN_NAME #(For example,"Cortex Authentication Client").
Authorized redirect URIs: http://127.0.0.1

    CHOSEN_NAME は、OAuth クライアント ID 認証情報アカウントに選択した名前に置き換えます。

  3. 認証情報を構成したら、Client ID と Client secret を保存します。後で必要になります。

  4. OAuth 2.0 を使用して Google API にアクセスする方法で新しいトークンを生成します。Cortex Data Foundation は、トークンの生成に使用された認証情報にアクセスできるすべてのお客様（アカウント）からデータを自動的に検出して取り込みます。

  5. Secret Manager を使用してシークレットを作成します。

    • Google Cloud コンソールで、[Secret Manager] をクリックします。
    • 次の形式を使用して cortex-framework-google-ads-yaml というシークレットを作成し、設定に応じて値を変更します。
    {"developer_token": "DEVELOPER_TOKEN_VALUE", "refresh_token": "REFRESH_TOKEN_VALUE", "client_id": "CLIENT_ID_VALUE", "client_secret": "CLIENT_SECRET_VALUE", "use_proto_plus": False}

次のように置き換えます。

  • DEVELOPER_TOKEN_VALUE は、Google 広告アカウントで利用可能なデベロッパー トークン値に置き換えます。
  • REFRESH_TOKEN_VALUE は、手順 4 で取得した更新トークンの値に置き換えます。
  • CLIENT_ID_VALUE は、ステップ 2 の OAuth 設定で取得したクライアント ID の値に置き換えます。
  • CLIENT_SECRET_VALUE は、ステップ 2 の OAuth 設定で取得したクライアント シークレットの値に置き換えます。

データの更新頻度と遅延

一般に、Cortex Framework データソースのデータの更新頻度は、アップストリーム接続で許可される内容と DAG 実行の頻度によって制限されます。アップストリームの頻度、リソースの制約、ビジネスニーズに合わせて DAG の実行頻度を調整します。

Google Ads API を使用して取得したデータは、一般提供で 3 時間以上のレイテンシがあります。コンバージョンや無効なトラフィックの検出により、後で調整される場合があります。詳しくは、Google 広告ヘルプセンターのデータの更新頻度についての記事をご覧ください。

Cloud Composer 接続の権限

Cloud Composer で次の接続を作成します。詳細については、Airflow 接続を管理するドキュメントをご覧ください。

接続名 目的
googleads_raw_dataflow Google Ads API の場合は、[BigQuery Raw Dataset] を選択します。
googleads_cdc_bq 元データセット > CDC データセットの転送の場合。
googleads_reporting_bq CDC データセットの場合は、[レポート データセットの転送] に移動します。

Cloud Composer サービス アカウントの権限

Cloud Composer で使用されるサービス アカウントに Dataflow 権限を付与します（googleads_raw_dataflow 接続で構成されているように）。Dataflow のドキュメントの手順をご覧ください。

取り込み設定

Source to Raw データ パイプラインと Raw to CDC データ パイプラインは、ファイル src/GoogleAds/config/ingestion_settings.yaml の設定で制御します。このセクションでは、各データ パイプラインのパラメータについて説明します。

ソースから未加工テーブル

このセクションでは、API によって取得されるエンティティとその方法について説明します。各エントリは 1 つの Google 広告エンティティに対応しています。この構成に基づいて、Cortex は Dataflow パイプラインを実行し、Google Ads API を使用してデータを取得する Airflow DAG を作成します。

次のパラメータは、各エントリの Source to Raw の設定を制御します。

パラメータ 説明
load_frequency このエンティティの DAG が Google 広告からデータを取得するために実行される頻度。使用可能な値の詳細については、Airflow のドキュメントをご覧ください。
api_name API リソース名（customer など）。
table_name フェッチされたデータが保存されている元データセット内のテーブル（例: customer）。
schema_file API レスポンス フィールドを宛先テーブルの列名にマッピングする src/table_schema ディレクトリ内のスキーマ ファイル。
key このテーブルの一意のレコードを形成する列（カンマ区切り）。
is_metrics_table 特定のエントリが（Google Ads API で）指標エンティティのものかどうかを示します。このようなテーブルは集約された性質があるため、システムでは若干異なる方法で処理されます。
partition_details 省略可: パフォーマンスを考慮してこのテーブルをパーティショニングする場合。詳細については、テーブル パーティションをご覧ください。
cluster_details 省略可: パフォーマンスを考慮してこのテーブルをクラスタリングする場合。詳細については、クラスタ設定をご覧ください。

元のテーブルから CDC テーブル

このセクションでは、元のテーブルから CDC テーブルにデータが移動される方法を制御するエントリについて説明します。各エントリは元のテーブルに対応しています（これは、前述のように Google 広告 API エンティティに対応しています）。

次のパラメータは、各エントリの Raw to CDC の設定を制御します。

パラメータ 説明
table_name CDC 変換後の元データが保存される CDC データセット内のテーブル（customer など）。
raw_table 元データが複製されたテーブル。
key このテーブルの一意のレコードを形成する列（カンマ区切り）。
load_frequency このエンティティの DAG が実行され、CDC テーブルにデータが入力される頻度。使用可能な値の詳細については、Airflow のドキュメントをご覧ください。
schema_file src/table_schema ディレクトリにあるスキーマ ファイル。未加工の列を CDC 列にマッピングし、CDC 列のデータ型を指定します。これは、前のセクションで参照したスキーマ ファイルと同じです。
partition_details 省略可: パフォーマンスを考慮してこのテーブルをパーティショニングする場合。詳細については、テーブル パーティションをご覧ください。
cluster_details 省略可: パフォーマンスを考慮してこのテーブルをクラスタリングする場合。詳細については、クラスタ設定をご覧ください。

レポート設定

Cortex Framework が Google 広告の最終レポートレイヤ用にデータを生成する方法は、レポート設定ファイル src/GoogleAds/config/reporting_settings.yaml を使用して構成、制御できます。このファイルは、レポートレイヤの BigQuery オブジェクト（テーブル、ビュー、関数、ストアド プロシージャ）の生成方法を制御します。

詳細については、レポート設定ファイルのカスタマイズをご覧ください。

次のステップ