שילוב עם Meta

בדף הזה מוסבר על ההגדרות הנדרשות כדי להביא נתונים מ-מטא (פייסבוק ו-אינסטגרם Ads) כמקור נתונים של עומס העבודה השיווקי של Cortex Framework Data Foundation.

מטא היא חברת טכנולוגיה שבבעלותה כמה פלטפורמות פופולריות באינטרנט. המסגרת של Cortex משלבת נתונים של מודעות מאינסטגרם ומפייסבוק כדי לנתח אותם, משלבת אותם עם מקורות נתונים אחרים ומשתמשת ב-AI כדי לקבל תובנות מעמיקות יותר ולבצע אופטימיזציה של אסטרטגיית השיווק.

בתרשים הבא מתואר איך נתוני שיווק של Meta זמינים דרך עומס העבודה השיווקי של Cortex Framework Data Foundation:

מקור המטא-נתונים

איור 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 פריסת סקריפטים של CDC עבור Meta true ליצור סקריפטים לעיבוד CDC של Meta כדי להריץ אותם כ-DAG ב-Managed Airflow.
marketing.Meta.datasets.cdc מערך נתונים של CDC עבור Meta מערך נתונים של CDC עבור Meta.
marketing.Meta.datasets.raw מערך נתונים גולמי ל-Meta קבוצת נתונים גולמית למטא.
marketing.Meta.datasets.reporting מערך נתונים לדיווח ב-Meta "REPORTING_Meta" מערך נתונים לדיווח עבור Meta.

מודל נתונים

בקטע הזה מתואר מודל הנתונים של Meta באמצעות דיאגרמת קשר בין ישויות (ERD).

תרשים קשרים בין ישויות של מטא

איור 2. ‫Meta: Entity Relationship Diagram.

תצוגות בסיסיות

אלה האובייקטים הכחולים ב-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 כדי לאחזר מאפיינים ומדדים של דיווח. התבניות הנוכחיות משתמשות בגרסה v25.0.

מערכת Meta מטילה מגבלת קצב דינמית כששולחים שאילתות ל-Marketing API. כשמגיעים למגבלת הקצב, יכול להיות שגרפים מכווני מחזור (DAG) של הטמעת נתונים ממקור לנתונים גולמיים לא יושלמו בהצלחה. במקרים כאלה, אפשר לראות הודעות שגיאה רלוונטיות ביומן, וההפעלה הבאה של ה-DAGs תטען באופן רטרואקטיבי את הנתונים החסרים.

ל-Meta Marketing API יש שתי רמות גישה: בסיסית ורגילה. התוכנית הרגילה מציעה מכסה גבוהה בהרבה, ומומלצת אם אתם מתכננים להשתמש בתכונה 'העברה ממקור לנתונים גולמיים' באופן נרחב. פרטים נוספים על המגבלות האלה ועל האופן שבו אפשר להשיג רמת גישה גבוהה יותר זמינים במסמכי התיעוד של Meta.

אם יש לכם גישה לרמה רגילה, אתם יכולים להקטין את הערך של ההגדרה next_request_delay_sec ב-src/Meta/src/raw/pipelines/config.ini כדי לקצר את זמני הטעינה.

גישה ל-API וטוקן גישה

כדי להעביר נתונים ממטא ל-Cortex Framework, צריך לבצע את השלבים הבאים ב-Meta Business Manager וב-Developer Console.

  1. מזהים אפליקציה לשימוש. אתם יכולים ליצור אפליקציה חדשה שמקושרת לחשבון העסקי. חשוב לוודא שהאפליקציה היא מסוג Business.
  2. הגדרת הרשאות שניתנות לאפליקציה כדי ליצור טוקנים באמצעות האפליקציה, צריך להיות מוקצים לה בתור אדמינים. לעיון במאמרי העזרה בנושא תפקידים באפליקציות חשוב להקצות לאפליקציה נכסים רלוונטיים (חשבונות).

  3. יוצרים אסימון גישה. כדי לגשת ל-Meta Marketing API, צריך אסימוני גישה, והם תמיד משויכים לאפליקציה ולמשתמש. אפשר ליצור את האסימון באמצעות משתמש מערכת או באמצעות פרטי הכניסה שלכם.

    1. יוצרים משתמש מערכת עם הרשאות אדמין.
    2. יצירת טוקן. חשוב לרשום את הטוקנים מיד אחרי שהם נוצרים, כי אי אפשר לאחזר אותם אחרי שיוצאים מהדף.
    3. מעניקים לטוקן את ההרשאות ads_read ו-business_management כדי לגשת לאובייקטים הנתמכים.

  4. כדי להפעיל את Secret Manager ב-Managed Airflow, פועלים לפי ההוראות בתיעוד של Managed Airflow. לאחר מכן יוצרים סוד בשם cortex_meta_access_token ומאחסנים את האסימון שיצרתם בשלב הקודם כתוכן.

עדכניות הנתונים והעיכובים

באופן כללי, רמת העדכניות של הנתונים במקורות הנתונים של Cortex Framework מוגבלת על ידי מה שמאפשר החיבור במעלה הזרם, וגם על ידי התדירות של הפעלת ה-DAG. משנים את תדירות ההפעלה של ה-DAG בהתאם לתדירות של מקור הנתונים, למגבלות המשאבים ולצרכים העסקיים.

ב-Meta Marketing API, רוב הנתונים (לא כולל המרות) זמינים כמעט בזמן אמת, אבל יכול להיות שיתבצעו בהם שינויים עד 28 ימים אחרי האירוע.

הרשאות לחיבורים ב-Managed Service for Apache Airflow

יוצרים את החיבורים הבאים ב-Managed Airflow. פרטים נוספים זמינים במאמר בנושא ניהול חיבורים ב-Airflow.

שם החיבור מטרה
meta_raw_dataflow ‫Meta Marketing API > מערך נתונים גולמי של BigQuery
meta_cdc_bq למערך נתונים גולמי > העברת מערך נתונים של CDC
meta_reporting_bq למערך נתונים של CDC > העברת מערך נתונים של דיווח

הרשאות של חשבון שירות ב-Managed Airflow

נותנים הרשאות Dataflow לחשבון השירות שבו נעשה שימוש ב-Managed Airflow (כפי שהוגדר בחיבור meta_raw_dataflow). הוראות מפורטות זמינות במסמכי התיעוד של Dataflow. לחשבון השירות נדרשת גם ההרשאה Secret Manager Secret Accessor. פרטים נוספים זמינים במאמר בנושא בקרת גישה.

פרמטרים של בקשה

הספרייה src/Meta/config/request_parameters מכילה קובץ מפרט של בקשת API לכל ישות שמחולצת מ-Meta Marketing API. כל קובץ בקשה מכיל רשימה של שדות לאחזור מ-Meta Marketing API, שדה אחד בכל שורה. מידע נוסף זמין במאמר Meta Marketing API Reference.

הגדרות הטמעה

שליטה בצינורות הנתונים של Source to Raw ו-Raw to CDC דרך ההגדרות בקובץ src/Meta/config/ingestion_settings.yaml. בקטע הזה מתוארים הפרמטרים של כל צינור נתונים.

מקור לטבלאות גולמיות

בקטע הזה יש רשומות שקובעות אילו ישויות יאוחזרו על ידי ממשקי API ואיך. כל רשומה תואמת לישות אחת ב-Meta Marketing API. על סמך ההגדרה הזו, Cortex Framework יוצר DAG של Airflow שמריץ צינורות עיבוד נתונים של Dataflow כדי לאחזר נתונים באמצעות Meta Marketing APIs.

קובץ src/Meta/src/raw/pipelines/config.ini שולט בחלק מההתנהגויות של Managed Airflow DAG ובאופן השימוש ב-Meta Marketing APIs. בכל קובץ יש תיאורים של כל פרמטר.

הפרמטרים הבאים שולטים בהגדרות של 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 אופציונלי: אם רוצים שהטבלה הזו תהיה מקובצת כדי לשפר את הביצועים. מידע נוסף מופיע במאמר בנושא הגדרות אשכול.

טבלאות Raw לטבלאות 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, סוגים פרימיטיביים מומרים לסוגים רלוונטיים של נתונים עסקיים, וכל הסוגים המורכבים מאוחסנים בפורמט JSON של BigQuery.

כדי להפעיל את ההמרה הזו, בספרייה src/Meta/config/table_schema יש קובץ סכימה אחד לכל ישות שצוינה בקטע raw_to_cdc_tables שמסביר איך לתרגם נכון כל טבלה גולמית ב-BigQuery לטבלת CDC.

כל קובץ סכימה מכיל שלוש עמודות:

  • ‫SourceField: שם השדה של הטבלה הגולמית של הישות הזו.
  • ‫TargetField: שם העמודה בטבלת ה-CDC של הישות הזו.
  • ‫DataType: סוג הנתונים של כל שדה בטבלת ה-CDC.

הגדרות דיווח

אתם יכולים להגדיר ולשלוט באופן שבו Cortex יוצר נתונים בשכבת הדיווח הסופית של Meta באמצעות קובץ הגדרות הדיווח (src/Meta/config/reporting_settings.yaml). הקובץ הזה קובע איך נוצרים אובייקטים של BigQuery בשכבת הדיווח (טבלאות, תצוגות, פונקציות או פרוצדורות מאוחסנות).

מידע נוסף זמין במאמר בנושא התאמה אישית של קובץ הגדרות הדיווח.

מה השלב הבא?