メインコンテンツまでスキップ
に最終更新

Meta Ads 取り込みコネクタリファレンス

備考

ベータ版

この機能はベータ版です。ワークスペース管理者は、 プレビュー ページからこの機能へのアクセスを制御できます。「Databricks プレビューの管理」を参照してください。

このページには、 Databricks LakeFlow Connectの Meta Ads 取り込みコネクタに関するリファレンス マテリアルが含まれています。

自動データ変換​

Databricks は、次のように Meta Ads データ型を Delta 互換データ型に変換します。

メタ広告タイプ

Delta型

string

String

int

Integer

long

Long

float

Float

double

Double

boolean

Boolean

datetime

タイムスタンプ

日付

Date

list

Array

map

Map

enum

String

メタ広告タイプ

Delta型

string

String

int

Integer

long

Long

float

Float

double

Double

boolean

Boolean

datetime

タイムスタンプ

日付

Date

list

Array

map

Map

enum

String

サポートされているオブジェクト​

Meta Ads コネクタは、次のオブジェクトの取り込みをサポートしています。

オブジェクト

説明

広告

キャンペーン内の個別の広告

広告セット

共通のターゲティング、予算、スケジュール設定で広告をグループ化した広告セット

キャンペーン

広告セットを含む最上位のキャンペーン オブジェクト

広告画像

広告で使用される画像アセット

広告インサイト

広告、広告セット、キャンペーン、またはアカウントのパフォーマンス メトリクスおよびアナリティクス データ

広告クリエイティブ

広告で使用されるクリエイティブ要素（画像、動画、テキスト）

カスタムオーディエンス

ターゲティングのためのカスタムオーディエンス定義

広告動画

広告で使用される動画アセット

カスタムコンバージョン

カスタムコンバージョンイベント定義

作成済みレポート（21 テーブル）

レポートごとに固定構成の既成の ad_insights バリアント。

custom_report

ユーザー定義の知見レポートレポートを custom_report_options で構成し、出力を destination_table で命名してください。

オブジェクト

説明

広告

キャンペーン内の個別の広告

広告セット

共通のターゲティング、予算、スケジュール設定で広告をグループ化した広告セット

キャンペーン

広告セットを含む最上位のキャンペーン オブジェクト

広告画像

広告で使用される画像アセット

広告インサイト

広告、広告セット、キャンペーン、またはアカウントのパフォーマンス メトリクスおよびアナリティクス データ

広告クリエイティブ

広告で使用されるクリエイティブ要素（画像、動画、テキスト）

カスタムオーディエンス

ターゲティングのためのカスタムオーディエンス定義

広告動画

広告で使用される動画アセット

カスタムコンバージョン

カスタムコンバージョンイベント定義

作成済みレポート（21 テーブル）

レポートごとに固定構成の既成の ad_insights バリアント。

custom_report

ユーザー定義の知見レポートレポートを custom_report_options で構成し、出力を destination_table で命名してください。

ad_insights構成オプション​

ad_insightsオブジェクトは、パフォーマンス データを分析するための追加の構成オプションをサポートしています。

開始日​

過去のad_insightsデータを取り込む開始日を設定してください。APIデータを約36か月間しか保持しないため、 start_date過去36か月以内である必要があります。 設定されていない場合、コネクタはデフォルトで現在の日付の36ヶ月前になります。

粒度レベル​

パフォーマンス メトリクスを取得するレベルを指定します。

  • account: アカウントレベルのメトリクス
  • campaign: キャンペーンレベルのメトリクス
  • adset: 広告セットレベルのメトリクス
  • ad: 広告レベルのメトリクス (自信)

内訳ディメンション​

パフォーマンス データをセグメント化するための内訳ディメンションを構成します。

  • age: 年齢層
  • gender： 性別
  • country： 国
  • region: 地理的地域
  • dma: 指定市場エリア（米国のみ）
  • device_platform: デバイス プラットフォーム (モバイル、デスクトップなど)
  • placement: 広告掲載場所
  • publisher_platform: パブリッシャープラットフォーム（Facebook、Audience Networkなど）
  • impression_device: インプレッションのデバイスタイプ

アクションの内訳ディメンション​

コンバージョン アクションを分析するには、アクション内訳ディメンションを設定します。

  • action_type: コンバージョンアクションの種類
  • action_destination: コンバージョンアクションの目的地
  • action_carousel_card_id: カルーセルカード識別子
  • action_carousel_card_name: カルーセルカード名
  • action_video_sound: ビデオサウンド設定
  • action_video_type: ビデオの種類

時間増分​

ad_insightsデータの集計期間を設定します。

  • all_days: 全時間範囲をカバーする単一のバケット (知見API )。
  • monthly：1暦月につき1つのバケツ。
  • 日数を整数で文字列として指定します（例：日単位の場合は"1" 、週単位の場合は"7" ）。

当該API時間単位の時間増分をサポートしていません。

行動報告の時間です​

アクション統計を報告する際に使用するタイムスタンプを設定します。

  • impressionコンバージョンは、コンバージョンを引き起こしたインプレッションの日付で報告されます。
  • conversion変換は、変換が発生した日付に報告されます。
  • mixedクリックコンバージョンはインプレッション時間を使用し、ビュースルーコンバージョンはコンバージョン時間を使用します。
  • lifetime: エンティティの生涯変換。

アトリビューションウィンドウ​

アクションの帰属期間を設定します。

  • 1d_click、 7d_click ：クリックスルーアトリビューションウィンドウ
  • 1d_view: 表示アトリビューションウィンドウ
  • 7d_view、28d_view：ビュースルー属性ウィンドウ。Meta により非推奨となり、コネクタではサポートされなくなりました。

複数の値を指定できます（例： ["7d_click", "1d_view"] ）。action_attribution_windowsが設定されていない場合、コネクタはメタ広告アカウントの確実なアトリビューション設定を使用します。 値のリストについては、 Meta の知見APIリファレンスを参照してください。

ルックバック期間​

各同期でコネクタがデータを再取り込みする期間（日数）を設定します。ルックバック期間は、ad_insights、custom_report、および事前構築済みレポートに適用されます。設定されていない場合、defaultは7日です。

  • 時間範囲の再取り込み ：最初の同期以降、コネクタは[last_sync_cursor - <N> days, today]データを取得するため、遅れて到着した変換がキャプチャされます。custom_insights_lookback_windowが設定されていない場合、コネクタはデフォルトで過去7日間のデータを再取り込みします。
  • 帰属フォールバック : custom_insights_lookback_window明示的に設定し 、 action_attribution_windowsを設定していない場合、コネクタは<N>d_click,1d_view帰属ウィンドウとして共有APIにも渡します。 ルックバックとは独立してアトリビューションを制御するには、 action_attribution_windowsを設定します。

作成済みのレポート​

事前構築済みレポートは、すぐに使用できる ad_insights バリアントです。各事前構築済みレポートは、固定されたレベル、内訳、およびアクション内訳の組み合わせで Meta /insights を呼び出すため、構成は不要です。ad_insights とは異なり、事前構築済みレポートは構成できません。

事前構築済みレポートを取り込むには、source_tableをレポート名に設定します。connector_optionsはオプションです。事前構築済みレポートは、何も設定しない場合（デフォルトを使用）、実行されますが、日付範囲を制御するために、meta_ads_optionsでstart_dateを設定できます。

利用可能なあらかじめ用意されたレポート​

各プリビルドレポートは、固定のMeta /insightsリクエストにマッピングされます。

レポート（source_table）

カテゴリー

レベル

内訳

アクションの内訳

メトリクスセット

basic_ad_report

ベーシック

ad

—

action_type

コアメトリクス

basic_ad_set_report

ベーシック

adset

—

action_type

コアメトリクス

basic_campaign_report

ベーシック

campaign

—

action_type

コアメトリクス

basic_all_levels_report

ベーシック

ad

—

action_type

コアメトリクス（広告、広告セット、キャンペーン名）

delivery_device_report

配信

ad

device_platform

action_type

コアメトリクス

delivery_platform_report

配信

ad

publisher_platform

action_type

コアメトリクス

delivery_platform_and_device_report

配信

ad

publisher_platform, device_platform

action_type

コアメトリクス

delivery_purchase_roas_report

配信

ad

—

action_type

コンバージョン / ROAS

demographics_age_report

人口統計

ad

age

action_type

コアメトリクス

demographics_gender_report

人口統計

ad

gender

action_type

コアメトリクス

demographics_age_and_gender_report

人口統計

ad

age, gender

action_type

コアメトリクス

demographics_country_report

人口統計

ad

country

action_type

コアメトリクス

demographics_region_report

人口統計

ad

region

action_type

コアメトリクス

demographics_dma_region_report

人口統計

ad

comscore_market

action_type

コアメトリクス

action_canvas_component_report

操作

ad

—

action_type

コンバージョン / ROAS

action_carousel_card_report

操作

ad

—

action_carousel_card_id, action_carousel_card_name

コンバージョン / ROAS

action_conversion_device_report

操作

ad

device_platform

action_type

コンバージョン / ROAS

action_product_id_report

操作

ad

product_id

action_type

コンバージョン / ROAS

action_reactions_report

操作

ad

—

action_reaction

actions, action_values

action_video_sound_report

操作

ad

—

action_video_sound

動画エンゲージメント

action_video_view_type_report

操作

ad

—

action_video_type

動画エンゲージメント

レポート（source_table）

カテゴリー

レベル

内訳

アクションの内訳

メトリクスセット

basic_ad_report

ベーシック

ad

—

action_type

コアメトリクス

basic_ad_set_report

ベーシック

adset

—

action_type

コアメトリクス

basic_campaign_report

ベーシック

campaign

—

action_type

コアメトリクス

basic_all_levels_report

ベーシック

ad

—

action_type

コアメトリクス（広告、広告セット、キャンペーン名）

delivery_device_report

配信

ad

device_platform

action_type

コアメトリクス

delivery_platform_report

配信

ad

publisher_platform

action_type

コアメトリクス

delivery_platform_and_device_report

配信

ad

publisher_platform, device_platform

action_type

コアメトリクス

delivery_purchase_roas_report

配信

ad

—

action_type

コンバージョン / ROAS

demographics_age_report

人口統計

ad

age

action_type

コアメトリクス

demographics_gender_report

人口統計

ad

gender

action_type

コアメトリクス

demographics_age_and_gender_report

人口統計

ad

age, gender

action_type

コアメトリクス

demographics_country_report

人口統計

ad

country

action_type

コアメトリクス

demographics_region_report

人口統計

ad

region

action_type

コアメトリクス

demographics_dma_region_report

人口統計

ad

comscore_market

action_type

コアメトリクス

action_canvas_component_report

操作

ad

—

action_type

コンバージョン / ROAS

action_carousel_card_report

操作

ad

—

action_carousel_card_id, action_carousel_card_name

コンバージョン / ROAS

action_conversion_device_report

操作

ad

device_platform

action_type

コンバージョン / ROAS

action_product_id_report

操作

ad

product_id

action_type

コンバージョン / ROAS

action_reactions_report

操作

ad

—

action_reaction

actions, action_values

action_video_sound_report

操作

ad

—

action_video_sound

動画エンゲージメント

action_video_view_type_report

操作

ad

—

action_video_type

動画エンゲージメント

各事前構築済みレポートは3つのメトリクスセットのいずれかを使用し、これらは出力に含まれる列を決定します。

メトリクスセット

列

コアメトリクス

reach、impressions、frequency、spend、cpm、cpc、cost_per_inline_link_click、ctr、inline_link_click_ctr、inline_link_clicks、actions、cost_per_action_type（array）

コンバージョン / ROAS

inline_link_clicks、outbound_clicks、website_purchase_roas、mobile_app_purchase_roas（配列）

動画エンゲージメント

video_thruplay_watched_actions、video_30_sec_watched_actions、video_p25_watched_actions、video_p50_watched_actions、video_p75_watched_actions、video_p100_watched_actions、video_avg_time_watched_actions（配列）

メトリクスセット

列

コアメトリクス

reach、impressions、frequency、spend、cpm、cpc、cost_per_inline_link_click、ctr、inline_link_click_ctr、inline_link_clicks、actions、cost_per_action_type（array）

コンバージョン / ROAS

inline_link_clicks、outbound_clicks、website_purchase_roas、mobile_app_purchase_roas（配列）

動画エンゲージメント

video_thruplay_watched_actions、video_30_sec_watched_actions、video_p25_watched_actions、video_p50_watched_actions、video_p75_watched_actions、video_p100_watched_actions、video_avg_time_watched_actions（配列）

出力列​

すべての事前構築済みレポート行には、date_start、date_stop、account_id、レポートのエンティティと階層列（例：ad_id、adset_id、campaign_id、および該当する場合は名前）、内訳列（例：age、device_platform）、派生したbreakdown_hash、および主キーinsight_idが含まれます。メトリクス列は、レポートのメトリクスセットによって異なります。アクション列とROAS列はarray<string>型です。

構築済みレポートの動作​

  • 各行はinsight_idによって一意に識別されます。コネクタは、date_stopをカーソルとして使用してデータを増分的に同期します。
  • レポート構成（level、breakdowns、action_breakdowns、time_increment（毎日）、アトリビューション期間（7d_click、1d_view）、action_report_time（mixed））は、レポートごとに固定されており、meta_ads_options を使用して上書きすることはできません。
  • meta_ads_options で start_date（default：今日の36か月前）と custom_insights_lookback_window（default：7日）を任意で設定できます。

custom_report構成オプション​

custom_report カスタムレベル、ブレークダウン、アクションブレークダウンの組み合わせで独自のad_insights形式レポートを定義し、それを指定したテーブルに取り込むことができます。事前構築済みレポートがニーズに合わず、/insights の設定を完全に制御したい場合に使用します。

カスタムレポートを取り込むには、source_tableをcustom_reportに設定し、destination_tableの名前を選択して、connector_options.meta_ads_options.custom_report_optionsの下でレポートを設定します。複数のcustom_reportオブジェクトを1つのパイプラインに、それぞれ異なるdestination_tableを指定して追加できます。

オブジェクト構造：

JSON
{
  "table": {
    "source_schema": "<meta-ads-account-id>",
    "source_table": "custom_report",
    "destination_catalog": "<catalog>",
    "destination_schema": "<schema>",
    "destination_table": "<your-report-name>",
    "connector_options": {
      "meta_ads_options": {
        "start_date": "<YYYY-MM-DD>",
        "custom_insights_lookback_window": 7,
        "custom_report_options": {
          "level": "ad",
          "breakdowns": ["country"],
          "action_breakdowns": ["action_type"],
          "time_increment": "1",
          "action_report_time": "mixed",
          "action_attribution_windows": ["7d_click", "1d_view"]
        }
      }
    }
  }
}

custom_report_options​

各オプションは、対応する ad_insights オプションを反映します：

オプション

説明

level

粒度：account、campaign、adset、またはad。

breakdowns

すべてのメトリクスを区分するディメンション（たとえば、["country", "age"]）。

action_breakdowns

アクション/コンバージョンメトリクスをセグメント化するディメンション (例: ["action_type"])。

time_increment

集計期間: all_days、monthly、または文字列としての整数日数 (例: 日次の場合は"1")。

action_report_time

アクションがカウントされる場合：impression、conversion、mixed、またはlifetime。

action_attribution_windows

アクションの属性ウィンドウ（例：["7d_click", "1d_view"]）。

オプション

説明

level

粒度：account、campaign、adset、またはad。

breakdowns

すべてのメトリクスを区分するディメンション（たとえば、["country", "age"]）。

action_breakdowns

アクション/コンバージョンメトリクスをセグメント化するディメンション (例: ["action_type"])。

time_increment

集計期間: all_days、monthly、または文字列としての整数日数 (例: 日次の場合は"1")。

action_report_time

アクションがカウントされる場合：impression、conversion、mixed、またはlifetime。

action_attribution_windows

アクションの属性ウィンドウ（例：["7d_click", "1d_view"]）。

共有 meta_ads_options​

オプション

説明

未設定時のdefault

start_date

取り込みの最も早い日付、YYYY-MM-DD。

現在の日付から36か月前

custom_insights_lookback_window

後続の各同期で再取り込みする日数（遅延コンバージョンをキャプチャします）。

7日

オプション

説明

未設定時のdefault

start_date

取り込みの最も早い日付、YYYY-MM-DD。

現在の日付から36か月前

custom_insights_lookback_window

後続の各同期で再取り込みする日数（遅延コンバージョンをキャプチャします）。

7日

複数のカスタム レポートを1 つのパイプラインで共存させるには、テーブル オブジェクトでdestination_tableを設定する必要があります。

各行はinsight_idによって一意に識別されます。コネクタは、date_stopをカーソルとして使用してデータを増分的に同期します。

APIバージョン​

Meta Ads コネクタは Meta マーケティングAPI (Graph API ) を使用します。 Databricksは、コネクタを最新の安定版APIバージョンに常に更新しています。

このページの見出し