Meta との統合

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

Meta は、複数の人気オンライン プラットフォームを所有するテクノロジー企業です。Cortex Framework は、Instagram と Facebook の広告データを統合して分析し、他のデータソースと組み合わせて、AI を使用してより深い分析情報を取得し、マーケティング戦略を最適化します。

次の図は、Cortex Framework Data Foundation のマーケティング ワークロードを通じて Meta のマーケティング データを利用できる仕組みを示しています。

メタデータ ソース

図 1. Meta マーケティング データソース。

構成ファイル

config.json ファイルは、さまざまなワークロードからデータを転送するためにデータソースに接続するために必要な設定を構成します。このファイルには、Meta の次のパラメータが含まれています。

   "marketing": {
        "deployMeta": true,
        "Meta": {
            "deployCDC": true,
            "datasets": {
                "cdc": "",
                "raw": "",
                "reporting": "REPORTING_Meta"
            }
        }
    }

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

パラメータ 意味 デフォルト値 説明
marketing.deployMeta Deploy Meta true Meta のデータソースのデプロイを実行します。
marketing.Meta.deployCDC Meta 用の CDC スクリプトをデプロイする true Cloud Composer で DAG として実行する Meta CDC 処理スクリプトを生成します。
marketing.Meta.datasets.cdc Meta の CDC データセット Meta の CDC データセット。
marketing.Meta.datasets.raw Meta の元データセット Meta の未加工のデータセット。
marketing.Meta.datasets.reporting Meta のレポート用データセット "REPORTING_Meta" Meta のレポート用データセット。

データモデル

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

Meta のエンティティ関係図

図 2. Meta: エンティティ関係図。

ベースビュー

これらは ERD の青いオブジェクトであり、複雑なデータ構造を解凍するための最小限の変換を含む CDC テーブルのビューです。src/marketing/src/Meta/src/reporting/ddls のスクリプトをご覧ください。

レポートビュー

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

API 接続

Meta 用 Cortex Framework の取り込みテンプレートは、Meta Marketing API を使用してレポート属性と指標を取得します。現在のテンプレートでは バージョン v25.0 が使用されています。

Meta は、Marketing API のクエリ時に動的なレート制限を適用します。レート制限に達すると、Source to Raw 変換 DAG が正常に完了しないことがあります。このような場合、ログに関連するエラー メッセージが表示され、DAG の次の実行で欠落しているデータが遡及的に読み込まれます。

Meta Marketing API には、ベーシックとスタンダードの 2 つのアクセスレベルがあります。スタンダード ティアでは上限が大幅に引き上げられているため、Source to Raw データの取り込みを広範囲にわたって使用する場合は、スタンダード ティアをおすすめします。これらの上限と、より高いアクセス階層を取得する方法について詳しくは、Meta のドキュメントをご覧ください。

スタンダード ティアにアクセスできる場合は、読み込み時間を短縮するために、src/Meta/src/raw/pipelines/config.ini の next_request_delay_sec 設定の値を小さくすることができます。

API アクセスとアクセス トークン

Meta から Cortex Framework にデータを正常に取り込むには、Meta Business Manager と Developer Console で次の手順を行う必要があります。

  1. 使用するアプリを特定します。ビジネス アカウントに接続されている新しいアプリを作成できます。アプリが Business タイプであることを確認します。
  2. アプリの権限を設定します。アプリでトークンを作成するには、アプリの管理者として割り当てられている必要があります。アプリのロールに関するドキュメントをご覧ください。関連するアセット（アカウント）をアプリに割り当てます。

  3. アクセス トークンを作成します。Meta Marketing API にアクセスするにはアクセス トークンが必要です。アクセス トークンは常にアプリとユーザーに関連付けられています。トークンは、システム ユーザーまたは独自のログインを使用して作成できます。

    1. 管理者システム ユーザーを作成します。
    2. トークンを生成します。トークンは、ページを離れると再度取得できなくなるため、生成されたらすぐにメモしてください。
    3. サポートされているオブジェクトにアクセスするには、トークンに ads_read 権限と business_management 権限を付与します。

  4. Cloud Composer のドキュメントに沿って、Cloud Composer で Secret Manager を有効にします。次に、cortex_meta_access_token という名前のシークレットを作成し、前の手順で生成したトークンをコンテンツとして保存します。

データの更新頻度と遅延

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

Meta Marketing API を使用すると、ほとんどのデータ（コンバージョンを除く）はほぼリアルタイムで利用できますが、イベントから 28 日後まで調整される可能性があります。

Cloud Composer 接続の権限

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

接続名 目的
meta_raw_dataflow Meta Marketing API > BigQuery Raw Dataset の場合
meta_cdc_bq [Raw dataset] > [CDC dataset transfer]
meta_reporting_bq CDC データセット > レポート データセットの転送

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

Cloud Composer で使用されるサービス アカウント（meta_raw_dataflow 接続で構成されている）に Dataflow 権限を付与します。Dataflow のドキュメントの手順をご覧ください。サービス アカウントには Secret Manager Secret Accessor 権限も必要です。詳細については、アクセス制御のドキュメントをご覧ください。

リクエスト パラメータ

ディレクトリ src/Meta/config/request_parameters には、Meta Marketing API から抽出された各エンティティの API リクエスト仕様ファイルが含まれています。各リクエスト ファイルには、Meta Marketing API から取得するフィールドのリストが 1 行に 1 つずつ含まれています。詳しくは、Meta Marketing API リファレンスをご覧ください。

取り込み設定

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

ソースから元テーブル

このセクションには、API によって取得されるエンティティとその方法を制御するエントリがあります。各エントリは 1 つの Meta Marketing API エンティティに対応しています。この構成に基づいて、Cortex Framework は Dataflow パイプラインを実行して Meta Marketing API を使用してデータを取得する Airflow DAG を作成します。

ファイル src/Meta/src/raw/pipelines/config.ini は、Cloud Composer DAG の一部の動作と、Meta Marketing API の使用方法を制御します。各パラメータの説明は、ファイルで確認してください。

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

パラメータ 説明
base_table 取得したデータが保存される Raw データセット内のテーブル（例: customer）。
load_frequency この DAG が Meta からデータを取得するために実行される頻度。取り得る値の詳細については、Airflow のドキュメントをご覧ください。
object_endpoint API エンドポイント パス（例: /{account_id}/campaigns エンドポイントの campaigns）。
entity_type テーブルのタイプ（fact、dimension、addaccount) のいずれかである必要があります）。
object_id_column このテーブルの一意のレコードを形成する列（カンマ区切り）。entity_type が fact の場合にのみ必須です。
breakdowns 省略可: 分析情報エンドポイントのブレークダウン列（カンマ区切り）。entity_type が fact の場合にのみ適用されます。
action_breakdowns 省略可: 分析情報エンドポイントのアクションの内訳列（カンマ区切り）。entity_type が fact の場合にのみ適用されます。
partition_details 省略可: パフォーマンスを考慮してこのテーブルをパーティショニングする場合。詳細については、テーブル パーティションをご覧ください。
cluster_details 省略可: パフォーマンスを考慮してこのテーブルをクラスタ化する場合。詳細については、クラスタ設定をご覧ください。

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

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

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

パラメータ 説明
base_table 元データが複製されたテーブル。CDC データセット内の同じ名前のテーブルには、CDC 変換後の元データが保存されます（例: campaign_insights）。
row_identifiers このテーブルの一意のレコードを形成する列（カンマ区切り）。
load_frequency このエンティティの DAG が CDC テーブルにデータを入力するために実行される頻度。取り得る値の詳細については、Airflow のドキュメントをご覧ください。
partition_details 省略可: パフォーマンス上の理由からこのテーブルをパーティショニングする場合。詳細については、テーブル パーティションをご覧ください。
cluster_details 省略可: パフォーマンスを考慮してこのテーブルをクラスタ化する場合。詳細については、クラスタ設定をご覧ください。

CDC テーブルのスキーマ

Meta の場合、すべてのフィールドは未加工レイヤに文字列形式で保存されます。CDC レイヤでは、プリミティブ型は関連するビジネス データ型に変換され、すべての複合型は BigQuery JSON 形式で保存されます。

この変換を有効にするため、ディレクトリ src/Meta/config/table_schema には、raw_to_cdc_tables セクションで指定された各エンティティのスキーマ ファイルが 1 つずつ含まれています。このファイルでは、各 BigQuery 生テーブルを CDC テーブルに適切に変換する方法について説明します。

各スキーマ ファイルには次の 3 つの列が含まれています。

  • SourceField: このエンティティの未加工テーブルのフィールド名。
  • TargetField: このエンティティの cdc テーブルの列名。
  • DataType: 各 cdc テーブル フィールドのデータ型。

レポート設定

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

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

次のステップ