Google 広告との統合

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

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

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

Google 広告のデータソース

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

構成ファイル

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 Managed Airflow で DAG として実行する Google 広告 CDC 処理スクリプトを生成します。
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 広告のエンティティ関係図

図 2. Google 広告: エンティティ リレーションシップ図。

ベースビュー

これらは ERD の青いオブジェクトであり、一部の列名エイリアス以外の変換がない CDC テーブルのビューです。src/marketing/src/GoogleAds/src/reporting/ddls のスクリプトをご覧ください。

レポートビュー

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

API 接続

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

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

API 接続の詳細については、Google Ads 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 を使用して Secret を作成します。

    • Google Cloud コンソールで、[Secret Manager] をクリックします。
    • 次の形式を使用して cortex-framework-google-ads-yaml という Secret を作成し、設定に応じて値を変更します。
    {"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 広告ヘルプセンターのデータの更新速度についての記事をご覧ください。

Managed Service for Apache Airflow 接続の権限

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

接続名 目的
googleads_raw_dataflow Google Ads API > BigQuery Raw Dataset。
googleads_cdc_bq 元データセット > CDC データセットの転送。
googleads_reporting_bq CDC データセット > レポート データセットの転送。

Managed Airflow サービス アカウントの権限

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

取り込み設定

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

ソースから元テーブル

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

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

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

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

このセクションでは、生テーブルから CDC テーブルにデータを移動する方法を制御するエントリについて説明します。各エントリは、未加工のテーブルに対応しています（未加工のテーブルは、前述のように Google Ads 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 省略可: パフォーマンスを考慮してこのテーブルをクラスタ化する場合。詳細については、クラスタの設定をご覧ください。

レポート設定

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

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

次のステップ