טעינת נתונים מ-Salesforce ל-BigQuery

כדי לתזמן העברות נתונים חוזרות מ-Salesforce Sales Cloud ל-BigQuery, צריך ליצור הגדרת העברה שבה מציינים אילו אובייקטים של נתונים רוצים להעביר ובאיזו תדירות לתזמן את העברת הנתונים. אפשר ליצור הגדרות העברה באמצעות המסוף Google Cloud , כלי שורת הפקודה bq או שירות העברת נתונים ל-BigQuery. אחרי שמגדירים את ההעברה, שירות העברת הנתונים ל-BigQuery מעביר את הנתונים העדכניים לטבלה ב-BigQuery לפי לוח הזמנים שצוין.

במאמר מבוא להעברות נתונים מ-Salesforce מוסבר איך פועלת העברה מ-Salesforce.

מגבלות

העברות נתונים מ-Salesforce כפופות למגבלות הבאות:

  • המחבר של Salesforce תומך רק בהעברות מ-Salesforce Sales Cloud.
  • המחבר של Salesforce תומך רק בשדות שנכללים ב-Salesforce Bulk API V1 בגרסה 64.0. יכול להיות שחלק מהשדות שנכללו בגרסאות קודמות של Salesforce Bulk API לא נתמכים. מידע נוסף על השינויים האלה במחבר של Salesforce זמין במאמר Salesforce Bulk API.

  • המחבר של Salesforce משתמש ב-Salesforce Bulk API V1 כדי להתחבר לנקודת הקצה של Salesforce Sales Cloud ולאחזר נתונים.

    • המחבר של Salesforce תומך רק ב-Salesforce Bulk API V1 כדי להתחבר למכונה של Salesforce, ותומך רק בהעברת ישויות שנתמכות על ידי Salesforce Bulk API. מידע נוסף על הישויות הנתמכות זמין במאמר הישות לא נתמכת על ידי Bulk API.

  • המחבר של Salesforce לא תומך בהעברה של האובייקטים הבאים, שיש בהם שדות בינאריים.

    • Attachment
    • ContentVersion
    • Document
    • StaticResource
    • Scontrol
    • EmailCapture
    • MailMergeTemplate

  • מרווח הזמן המינימלי בין העברות נתונים חוזרות הוא 15 דקות. מרווח הזמן שמוגדר כברירת מחדל להעברה חוזרת הוא 24 שעות.

  • בגלל מגבלות העיבוד של Salesforce, תזמון של יותר מדי העברות נתונים בבת אחת עלול לגרום לעיכובים או לכשלים. מומלץ להגביל את העברות הנתונים מ-Salesforce באופן הבא:

    • לא יותר מ-10 נכסים לכל הגדרת העברה.
    • בכל הגדרות ההעברה, לא מומלץ להפעיל יותר מ-10 העברות בו-זמנית.

  • הגדרת העברה אחת יכולה לתמוך רק בהפעלה אחת של העברת נתונים בכל זמן נתון. אם העברת נתונים שנייה מתוזמנת לפעול לפני שההעברה הראשונה מסתיימת, רק העברת הנתונים הראשונה תושלם, וכל העברת נתונים אחרת שחופפת להעברה הראשונה תבוטל.

    • כדי למנוע דילוג על העברות בהגדרת העברה אחת, מומלץ להגדיל את משך הזמן בין העברות נתונים גדולות על ידי הגדרת תדירות החזרה.

  • אם אתם משתמשים בחיבורי רשת להעברת נתונים, אתם צריכים להגדיר תרגום כתובות רשת (NAT) ציבורי עם כתובת IP סטטית. מידע נוסף זמין במאמר הגדרת רשימת היתרים של כתובות IP להעברות מ-Salesforce.

  • אם חיבור הרשת נוצר בפרויקט ב- Google Cloud ששונה מהפרויקט ב- Google Cloud שבו נוצרה העברת הנתונים, צריך לתת את ההרשאות compute.networkAttachments.get ו-compute.networkAttachments.update לסוכן השירות ששייך לפרויקט ב- Google Cloud שבו נוצרה העברת הנתונים.

  • אם מחבר הרשת שהגדרתם והמכונה הווירטואלית (VM) נמצאים באזורים שונים, יכול להיות שהנתונים יועברו בין אזורים כשתעבירו נתונים מ-Salesforce.

מגבלות על העברות מצטברות

העברות מצטברות מ-Salesforce כפופות למגבלות הבאות:

  • אפשר לבחור רק TIMESTAMP עמודות כעמודות של סימני מים.
  • הטמעה מצטברת נתמכת רק בנכסים עם עמודות סימן מים תקינות.
  • הערכים בעמודת סימן המים חייבים להיות בסדר עולה מונוטוני.
  • העברות מצטברות לא יכולות לסנכרן פעולות מחיקה בטבלת המקור.
  • הגדרת העברה אחת יכולה לתמוך רק בהטמעה מצטברת או בהטמעה מלאה.
  • אי אפשר לעדכן אובייקטים ברשימה asset אחרי ההפעלה הראשונה של הטמעה מצטברת.
  • אי אפשר לשנות את מצב הכתיבה בהגדרות ההעברה אחרי ההפעלה הראשונה של הטמעת הנתונים המצטברים.
  • אי אפשר לשנות את עמודת סימן המים או את המפתח הראשי אחרי ההפעלה הראשונה של הטמעת הנתונים המצטברים.
  • טבלת היעד ב-BigQuery מסודרת באשכולות באמצעות המפתח הראשי שסופק, והיא כפופה למגבלות של טבלאות מסודרות באשכולות.
  • כשמעדכנים הגדרת העברה קיימת למצב הטמעה מצטברת בפעם הראשונה, העברת הנתונים הראשונה אחרי העדכון מעבירה את כל הנתונים הזמינים ממקור הנתונים. בכל העברת נתונים מצטברת שתתבצע לאחר מכן, יועברו רק השורות החדשות והמעודכנות ממקור הנתונים.

במאמר העברות מלאות או מצטברות מוסבר איך פועלות העברות מצטברות.

לפני שמתחילים

בקטעים הבאים מתוארים השלבים שצריך לבצע לפני שיוצרים העברת נתונים מ-Salesforce.

יצירת אפליקציה מקושרת של Salesforce

צריך ליצור אפליקציה מקושרת של Salesforce עם ההגדרות הנדרשות הבאות:

  • מגדירים את המידע הבסיסי באפליקציה המקושרת. השדות Connected App Name ו-Contact Email נדרשים להעברה מ-Salesforce.
  • מפעילים את הגדרות ה-OAuth עם ההגדרות הבאות:
    • מסמנים את התיבה Enable OAuth Settings.
    • בשדה Callback URL, מזינים את הכתובת הבאה:
      • בסביבת ייצור, מזינים https://login.salesforce.com/services/oauth2/token.
      • לסביבת ארגז חול, מזינים את הערך https://test.salesforce.com/services/oauth2/token.
    • מוודאים שהתיבה Issue JSON Web Token (JWT)-based טוקני גישה for named users לא מסומנת.
  • בקטע Selected OAuth Scopes, בוחרים באפשרות Manage user data via APIs (api).
  • בוחרים באפשרות Enable Client Credentials Flow ולוחצים על OK בהודעה שמופיעה.

אחרי שמגדירים את האפליקציה המקושרת עם ההגדרות הנדרשות, לוחצים על Save. המערכת תפנה אתכם לדף הפרטים של האפליקציה המקושרת החדשה שיצרתם.

אחרי שיוצרים את האפליקציה המקושרת, צריך גם להגדיר את תהליך פרטי הכניסה של הלקוח:

  1. לוחצים על הגדרה.
  2. בסרגל החיפוש, מחפשים את אפליקציות מקושרות.
  3. לוחצים על ניהול אפליקציות > אפליקציות מקושרות. אם אתם משתמשים ב-Salesforce Lightning Experience, לוחצים על Manage Connected Apps (ניהול אפליקציות מקושרות).
  4. באפליקציה המקושרת שיצרתם, לוחצים על Edit (עריכה).
  5. הדף פרטי האפליקציה מופיע. בקטע Client Credentials Flow, מזינים את שם המשתמש בשדה Run As. אתם יכולים להשתמש בכלי החיפוש בשדה הזה כדי לוודא שבחרתם את המשתמש הנכון.
  6. לוחצים על Save.

המידע הנדרש מ-Salesforce

כדי ליצור העברת נתונים מ-Salesforce, צריך את הפרטים הבאים מ-Salesforce:

שם הפרמטר תיאור
myDomain הדומיין שלי ב-Salesforce.
clientId טוקן צרכן של האפליקציה המקושרת של Salesforce.
clientSecret

סוד הלקוח ב-OAuth או סוד הצרכן של האפליקציה המקושרת ב-Salesforce.

כדי לקבל את הערכים של myDomain, clientID ו-clientSecret, בוחרים באחת מהאפשרויות הבאות:

Salesforce Classic

אחזור פרטים של myDomain

כדי למצוא את myDomain, מבצעים את הפעולות הבאות:

  1. נכנסים לפלטפורמת Salesforce.
  2. לוחצים על הגדרה.
  3. בשורת החיפוש, מחפשים את My Domain (הדומיין שלי).
  4. בתוצאות החיפוש, לוחצים על Domain Management (ניהול דומיינים) > My Domain (הדומיין שלי).

בקטע My Domain Details, הערך של myDomain מופיע בתור הקידומת של Current My Domain URL. לדוגמה, אם כתובת ה-URL של "הדומיין שלי" היא example.my.salesforce.com, הערך של myDomain שצריך להשתמש בו הוא example.

אחזור פרטים של ClientId ושל ClientSecret

כדי למצוא את הערכים של ClientId ו-ClientSecret, מבצעים את הפעולות הבאות:

  1. נכנסים לפלטפורמת Salesforce.
  2. לוחצים על הגדרה.
  3. בשורת החיפוש, מחפשים את המילה אפליקציות.
  4. בקטע Build בתוצאות החיפוש, לוחצים על Create > Apps.
  5. לוחצים על שם האפליקציה המקושרת.
  6. בדף הפרטים של Connected Apps, לוחצים על Manage Consumer Details.
  7. מאמתים את הזהות באמצעות אחת מהשיטות הרשומות. אפשר לצפות בדף הפרטים של הצרכן במשך עד חמש דקות לפני שמוצגת בקשה לאמת את הזהות שוב.
  8. בדף Consumer Details (פרטי הצרכן), הערך של Consumer Key (טוקן הצרכן) הוא הערך של ClientId. הערך של Customer Secret הוא הערך של ClientSecret.

Salesforce Lightning Experience

אחזור פרטים של myDomain

כדי למצוא את myDomain, מבצעים את הפעולות הבאות:

  1. נכנסים לפלטפורמת Salesforce.

  2. לוחצים על הגדרה.

    פותחים את דף ההגדרה בפלטפורמת Salesforce.

  3. בשורת החיפוש, מחפשים את My Domain (הדומיין שלי).

  4. בתוצאות החיפוש, לוחצים על Company Settings (הגדרות החברה) > My Domain (הדומיין שלי).

בקטע My Domain Details, הערך של myDomain מופיע בתור הקידומת של Current My Domain URL. לדוגמה, אם כתובת ה-URL של "הדומיין שלי" היא example.my.salesforce.com, הערך של myDomain שצריך להשתמש בו הוא example.

אחזור פרטים של ClientId ושל ClientSecret

  1. נכנסים לפלטפורמת Salesforce.
  2. לוחצים על הגדרה.
  3. בשורת החיפוש, מחפשים את המילה אפליקציות.
  4. בתוצאות החיפוש, לוחצים על אפליקציות > מנהל האפליקציות.
  5. מוצאים אפליקציה מקושרת ולוחצים על הצגה.
  6. לוחצים על ניהול פרטי הצרכן.
  7. מאמתים את הזהות באמצעות אחת מהשיטות הרשומות. אפשר לצפות בדף הפרטים של הצרכן במשך עד חמש דקות לפני שמוצגת בקשה לאמת את הזהות שוב.
  8. בדף Consumer Details (פרטי הצרכן), הערך של Consumer Key (טוקן הצרכן) הוא הערך של ClientId. הערך של Customer Secret הוא הערך של ClientSecret.

הגדרת רשימת היתרים של כתובות IP להעברות מ-Salesforce

כדי להוסיף כתובות IP ספציפיות לרשימת ההיתרים להעברת נתונים, צריך להגדיר את הסביבה של Google Cloud ואת החשבון ב-Salesforce. כך Salesforce מקבלת רק חיבורים מכתובת IP סטטית מהימנה. השלב הזה נדרש אם אתם משתמשים בחיבורי רשת בהעברות הנתונים.

כדי לעשות את זה, קודם צריך להגדיר את הרשת ב- Google Cloud לשימוש בכתובת IP סטטית:

  1. הגדרת תרגום כתובת רשת (NAT) ציבורית עם כתובת IP סטטית ברשת של הענן הווירטואלי הפרטי (VPC). צריך להגדיר את CloudNAT באותו אזור שבו נמצא מערך הנתונים של היעד להעברת הנתונים.
  2. מגדירים חיבור לרשת באותה רשת VPC. המשאב הזה משמש את שירות העברת הנתונים ל-BigQuery כדי לגשת לשירותים פרטיים.

בשלב הבא, צריך להגדיר את טווחי כתובות ה-IP המהימנות ב-Salesforce. כשמוסיפים את טווח כתובות ה-IP, משתמשים בכתובת ה-IP הסטטית מ-NAT הציבורי שלGoogle Cloud גם לכתובת ה-IP בתחילת הטווח וגם לכתובת ה-IP בסוף הטווח.

אחרי שמגדירים את טווחי ה-IP, אפשר לציין את כתובת ה-IP הסטטית כשמגדירים את ההעברה, על ידי בחירת חיבור הרשת בשדה Network attachment.

דרישות מוקדמות ל-BigQuery

התפקידים הנדרשים ב-BigQuery

כדי לקבל את ההרשאות שדרושות ליצירת העברת נתונים בשירות העברת הנתונים ל-BigQuery, בקשו מהאדמין להקצות לכם את התפקיד אדמין ב-BigQuery (roles/bigquery.admin) ב-IAM בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

ההרשאות הנדרשות

כדי ליצור העברת נתונים באמצעות שירות העברת הנתונים ל-BigQuery, צריך את ההרשאות הבאות:

  • הרשאות לשירות העברת נתונים ל-BigQuery:
    • bigquery.transfers.update
    • bigquery.transfers.get
  • הרשאות ב-BigQuery:
    • bigquery.datasets.get
    • bigquery.datasets.getIamPolicy
    • bigquery.datasets.update
    • bigquery.datasets.setIamPolicy
    • bigquery.jobs.create

יכול להיות שתקבלו את ההרשאות האלה באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.

מידע נוסף זמין במאמר מתן גישה ל-bigquery.admin.

הגדרת העברת נתונים מ-Salesforce

כדי להוסיף נתונים מ-Salesforce ל-BigQuery, צריך להגדיר העברה באחת מהאפשרויות הבאות:

המסוף

  1. נכנסים לדף Data transfers במסוף Google Cloud .

    מעבר אל "העברות נתונים"

  2. ‫ Create transfer.

  3. בקטע Source type, בשדה Source בוחרים באפשרות Salesforce.

  4. בקטע פרטי מקור הנתונים, מבצעים את הפעולות הבאות:

    • בשדה Network attachment, בוחרים חיבור לרשת מהרשימה. כדי להשתמש במחבר רשת בהעברת הנתונים הזו, צריך להגדיר את ה-NAT הציבורי ואת רשימת ההיתרים של כתובות ה-IP.
    • בקטע My Domain, מזינים את My Domain ב-Salesforce.
    • בשדה Client ID, מזינים את טוקן הצרכן של האפליקציה המקושרת של Salesforce.
    • בשדה Client secret, מזינים את סוד הלקוח של האפליקציה המקושרת ב-Salesforce.
    • בקטע סוג ההטמעה, בוחרים באפשרות מלאה או מצטברת.
      • אם בחרתם באפשרות Incremental בשדה Write mode, בחרו באפשרות Append או Upsert. למידע נוסף על מצבי הכתיבה השונים, קראו את המאמר העברות מלאות או מצטברות.
    • בקטע Salesforce objects to transfer, לוחצים על Browse:
      • בוחרים את האובייקטים שרוצים להעביר למערך הנתונים של היעד ב-BigQuery. אפשר גם להזין ידנית בשדה הזה אובייקטים שרוצים לכלול בהעברת הנתונים.
      • אם בחרתם באפשרות Append כמצב הכתיבה המצטברת, אתם צריכים לבחור עמודה שתשמש כעמודת סימן המים.
      • אם בחרתם באפשרות עדכון או הוספה (upsert) כמצב הכתיבה המצטברת, אתם צריכים לבחור עמודה שתשמש כעמודת סימן המים, ואז לבחור עמודה אחת או יותר שתשמש כמפתח הראשי.

  5. בקטע Destination settings, בשדה Dataset בוחרים את מערך הנתונים שיצרתם כדי לאחסן את הנתונים.

  6. בקטע Transfer config name, בשדה השם המוצג, מזינים שם להעברת הנתונים.

  7. בקטע אפשרויות תזמון:

    • ברשימה Repeat frequency, בוחרים אפשרות כדי לציין את תדירות ההפעלה של העברת הנתונים. כדי להגדיר תדירות חזרה מותאמת אישית, לוחצים על בהתאמה אישית. אם בוחרים באפשרות On-demand, ההעברה תתבצע כשמפעילים אותה ידנית.
    • אם רלוונטי, בוחרים באפשרות Start now או באפשרות Start at set time, ומציינים תאריך התחלה וזמן ריצה.

  8. אופציונלי: בקטע Notification options, מבצעים את הפעולות הבאות:

    • כדי להפעיל התראות באימייל, לוחצים על המתג התראות באימייל. כשמפעילים את האפשרות הזו, האדמין של ההעברה מקבל התראה באימייל כשהרצת ההעברה נכשלת.
    • כדי להפעיל התראות על הפעלת העברות ב-Pub/Sub להעברה הזו, לוחצים על המתג Pub/Sub notifications. אפשר לבחור את שם הנושא או ללחוץ על Create a topic כדי ליצור נושא.

  9. לוחצים על Save.

BQ

מזינים את הפקודה bq mk ומציינים את הדגל ליצירת העברה --transfer_config:

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

כאשר:

  • ‫PROJECT_ID (אופציונלי): מזהה הפרויקט ב- Google Cloud . אם לא מציינים פרויקט מסוים באמצעות --project_id, המערכת משתמשת בפרויקט שמוגדר כברירת מחדל.
  • DATA_SOURCE: מקור הנתונים – salesforce.
  • ‫NAME: השם המוצג של הגדרות העברת הנתונים. שם ההעברה יכול להיות כל ערך שמאפשר לכם לזהות את ההעברה אם תצטרכו לשנות אותה בהמשך.
  • DATASET: קבוצת הנתונים של היעד להגדרות ההעברה.

  • ‫PARAMETERS: הפרמטרים של הגדרות ההעברה שנוצרו, בפורמט JSON. לדוגמה: --params='{"param":"param_value"}'. אלה הפרמטרים להעברת נתונים מ-Salesforce:

    • ‫connector.authentication.oauth.clientId: טוקן הצרכן של האפליקציה המקושרת של Salesforce.
    • ‫connector.authentication.oauth.clientSecret: סוד הלקוח ב-OAuth או סוד הצרכן של האפליקציה המקושרת ב-Salesforce.
    • ‫connector.authentication.oauth.myDomain: הדומיין שלי ב-Salesforce. לדוגמה, אם כתובת ה-URL של הדומיין היא example.my.salesforce.com, הערך הוא example.
    • ‫ingestionType: מציינים full או incremental. מידע נוסף זמין במאמר העברות מלאות או מצטברות.
    • ‫writeMode: מציינים WRITE_MODE_APPEND או WRITE_MODE_UPSERT.
    • ‫watermarkColumns: ציון עמודות בטבלה כעמודות של סימני מים. השדה הזה נדרש להעברות מצטברות.
    • ‫primaryKeys: מציינים עמודות בטבלה כמפתחות ראשיים. השדה הזה נדרש להעברות מצטברות.
    • ‫assets: הנתיב לאובייקטים של Salesforce שיועברו ל-BigQuery.

כשמציינים כמה נכסים במהלך העברה מצטברת, הערכים של השדות watermarkColumns ו-primaryKeys תואמים למיקום של הערכים בשדה assets. בדוגמה הבאה, Id תואם לטבלה Account, ו-master_label ו-type תואמים לטבלה CaseHistory.

      "primaryKeys":[['Id'], ['master_label','type']],
      "assets":["Account","CaseHistory"],

הפקודה הבאה יוצרת העברת נתונים מצטברת מ-Salesforce בפרויקט ברירת המחדל, ומשתמשת במצב הכתיבה APPEND.

bq mk
    --transfer_config
    --target_dataset=mydataset
    --data_source=salesforce
    --display_name='My Transfer'
    --params='{"assets": ["Account", "CaseHistory"]
        "connector.authentication.oauth.clientId": "1234567890",
        "connector.authentication.oauth.clientSecret":"ABC12345",
        "connector.authentication.oauth.myDomain":"MyDomainName",
        "connector.authentication.username":"user1@force.com",
        "connector.authentication.password":"abcdef1234",
        "ingestionType":"incremental",
        "writeMode":"WRITE_MODE_UPSERT",
        "watermarkColumns":["SystemModstamp","CreatedDate"]
        "primaryKeys":[['Id'], ['master_label','type']]}'

API

משתמשים ב-method‏ projects.locations.transferConfigs.create ומספקים מופע של המשאב TransferConfig.

כששומרים את הגדרות ההעברה, המחבר של Salesforce מפעיל באופן אוטומטי את הרצת ההעברה בהתאם לאפשרות התזמון שבחרתם. בכל הפעלה של העברה, המחבר של Salesforce מעביר את כל הנתונים הזמינים מ-Salesforce ל-BigQuery.

כדי להפעיל ידנית העברת נתונים מחוץ ללוח הזמנים הרגיל, אפשר להתחיל הרצה של מילוי חוסרים.

פתרון בעיות בהגדרת ההעברה

אם נתקלתם בבעיות בהגדרת העברת הנתונים, עיינו במאמר בעיות בהעברת נתונים מ-Salesforce.

המאמרים הבאים