與 Meta 整合

本頁說明如何設定，將 Meta (Facebook 和 Instagram Ads) 的資料做為 Cortex Framework Data Foundation 行銷工作負載的資料來源。

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 部署 Meta true 執行 Meta 資料來源的部署作業。
marketing.Meta.deployCDC 為 Meta 部署 CDC 指令碼 true 產生 Meta CDC 處理指令碼，在 Cloud Composer 中以 DAG 形式執行。
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：中繼資料：實體關係圖。

基本檢視畫面

這些是 ERD 中的藍色物件，也是 CDC 資料表的檢視區塊，可透過最少的轉換來解壓縮複雜的資料結構。請參閱src/marketing/src/Meta/src/reporting/ddls中的指令碼。

報表資料檢視

這些是 ERD 中的綠色物件，也是包含匯總指標的報表檢視畫面。請參閱src/marketing/src/Meta/src/reporting/ddls中的指令碼。

API 連線

Cortex Framework for Meta 中的擷取範本會使用 Meta Marketing API 擷取報表屬性和指標。目前的範本使用版本 v21.0。

查詢 Marketing API 時，Meta 會強制執行動態速率限制。達到速率限制後，來源至原始資料擷取 DAG 可能無法順利完成。在這種情況下，您可以在記錄中看到相關錯誤訊息，且 DAG 的下一次執行作業會追溯載入任何遺漏的資料。

Meta Marketing API 提供兩種存取層級，分別是「基本」和「標準」。標準層級的限制高出許多，如果您打算大量使用「來源到原始資料」擷取功能，建議採用這個層級。如要進一步瞭解這些限制，以及如何取得較高的存取層級，請參閱 Meta 的說明文件。

如果您有標準層級存取權，可以降低 src/Meta/src/raw/pipelines/config.ini 中的 next_request_delay_sec 設定值，加快載入速度。

API 存取權和存取權杖

如要順利將 Meta 的資料匯入 Cortex Framework，請在 Meta Business Manager 和開發人員控制台中完成下列步驟。

  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 原始資料集
meta_cdc_bq 針對原始資料集 > CDC 資料集移轉
meta_reporting_bq 如為 CDC 資料集 > 報表資料集轉移

Cloud Composer 服務帳戶權限

將 Dataflow 權限授予 Cloud Composer 中使用的服務帳戶 (如 meta_raw_dataflow 連線中設定)。請參閱 Dataflow 說明文件中的操作說明。服務帳戶也需要 Secret Manager Secret Accessor 權限。詳情請參閱存取權控管說明文件。

要求參數

目錄 src/Meta/config/request_parameters 包含從 Meta Marketing API 擷取的每個實體的 API 要求規格檔案。每個要求檔案都包含要從 Meta Marketing API 擷取的欄位清單，每列一個欄位。詳情請參閱 Meta Marketing API 參考資料。

內容攝入設定

透過 src/Meta/config/ingestion_settings.yaml 檔案中的設定，控制 Source to Raw 和 Raw to CDC 資料管道。本節說明各個資料管道的參數。

來源到原始資料表

這個部分包含的項目可控管 API 擷取的實體和方式。每個項目都對應一個 Meta Marketing API 實體。根據這項設定，Cortex Framework 會建立 Airflow DAG，執行 Dataflow 管道，使用 Meta Marketing API 擷取資料。

檔案 src/Meta/src/raw/pipelines/config.ini 可控管 Cloud Composer DAG 的部分行為，以及 Meta Marketing API 的使用方式。檔案中會說明各項參數。

下列參數可控制每個項目的 Source to Raw 設定：

參數 說明
base_table 儲存擷取資料的原始資料集中的資料表 (例如 customer)。
load_frequency DAG 執行頻率，用於從 Meta 擷取資料。如要進一步瞭解可能的值，請參閱 Airflow 說明文件。
object_endpoint API 端點路徑 (例如 campaigns，適用於 /{account_id}/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 資料表

本節說明控制資料從原始資料表移至 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 節中說明如何將每個 BigQuery 原始資料表正確轉換為 CDC 資料表。

每個結構定義檔案都包含三個資料欄：

  • SourceField：這個實體原始資料表的欄位名稱。
  • TargetField：這個實體的 CDC 資料表中的資料欄名稱。
  • DataType：每個 CDC 資料表欄位的資料類型。

報表設定

您可以使用報表設定檔 (src/Meta/config/reporting_settings.yaml)，設定及控管 Cortex 如何為 Meta 最終報表層產生資料。這個檔案會控管報表層 BigQuery 物件 (資料表、檢視區塊、函式或預存程序) 的產生方式。

詳情請參閱「自訂報表設定檔」。

後續步驟