Google 広告との統合

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

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 Access Google APIs を使用して新しいトークンを生成します。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 広告ヘルプセンターの データの更新速度について の記事をご覧ください。

Managed Service for Apache Airflow 接続の権限

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

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

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

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

取り込みに関する設定

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

ソースから元テーブル

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

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

パラメータ 説明
load_frequency このエンティティの DAG が Google 広告からデータを取得するために実行される頻度。使用可能な値の詳細については、Airflow のドキュメントをご覧ください。
api_name API リソース名（例: customer）。
table_name 取得したデータが保存される元データセットのテーブル（customer など）。
schema_file src/table_schema ディレクトリ内のスキーマ ファイル。API レスポンス フィールドを宛先テーブルの列名にマッピングします。
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 オブジェクト（テーブル、ビュー、関数、ストアド プロシージャ）の生成方法を制御します。

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

次のステップ