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

כדי לתזמן העברות נתונים חוזרות מ-Salesforce Sales Cloud ל-BigQuery, צריך ליצור הגדרת העברה שבה מציינים אילו אובייקטים של נתונים רוצים להעביר ובאיזו תדירות לתזמן את העברת הנתונים. אפשר ליצור הגדרות העברה באמצעות מסוף Google Cloud , כלי שורת הפקודה bq או BigQuery Data Transfer Service API. אחרי שמגדירים את ההעברה, שירות העברת הנתונים ל-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.

• אם מחבר הרשת שהגדרתם והמכונה הווירטואלית (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 access tokens 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 של My Domain היא 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. לוחצים על הגדרה.

   

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

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

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

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

1. נכנסים לפלטפורמת Salesforce.
2. לוחצים על הגדרה.
3. בשורת החיפוש, מחפשים את המילה אפליקציות.
4. בתוצאות החיפוש, לוחצים על Apps (אפליקציות) > App Manager (מנהל האפליקציות).
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 ברמת הפרופיל או בכל קריאה ל-API. מידע נוסף זמין במאמר הגבלת כתובות ה-IP להתחברות בפרופילים.

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

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

• מוודאים שביצעתם את כל הפעולות הנדרשות כדי להפעיל את שירות העברת הנתונים ל-BigQuery.
• יוצרים מערך נתונים ב-BigQuery כדי לאחסן את הנתונים.
• אם אתם מתכוונים להגדיר התראות על הפעלת העברות ב-Pub/Sub, ודאו שיש לכם את ההרשאה pubsub.topics.setIamPolicy לניהול זהויות והרשאות גישה (IAM). אם אתם מגדירים רק התראות באימייל, אתם לא צריכים הרשאות Pub/Sub. למידע נוסף, קראו את המאמר התראות על הפעלות של שירות העברת הנתונים ל-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. בקטע Data source details:

   • בשדה 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, בוחרים אפשרות כדי לציין את התדירות שבה העברת הנתונים הזו תפעל. כדי להגדיר תדירות חזרה מותאמת אישית, לוחצים על בהתאמה אישית. אם בוחרים באפשרות על פי דרישה, ההעברה תתבצע כשמפעילים אותה ידנית.
   • אם רלוונטי, בוחרים באפשרות Start now או באפשרות Start at set time, ומציינים תאריך התחלה וזמן ריצה.

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

   • כדי להפעיל התראות באימייל, לוחצים על המתג התראות באימייל. כשמפעילים את האפשרות הזו, האדמין של ההעברה מקבל התראה באימייל כשהרצת ההעברה נכשלת.
   • כדי להפעיל התראות על הפעלת העברות ב-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":"[e-mail]",
        "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.

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

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