ניהול פקודות מאקרו, העדפות וארגומנטים של זמן ריצה

בדף הזה מוסבר איך מגדירים העדפות, פקודות מאקרו וארגומנטים של זמן ריצה בצינורות של Cloud Data Fusion.

מונחי מפתח

פקודות מאקרו

פקודות מאקרו הן placeholders בהגדרות של תוסף Cloud Data Fusion. הם מיוצגים על ידי משתנים שמוקפים ב-${ }, כמו ${input_file_path}. הוראות מאקרו מוסיפות גמישות לצינורות העיבוד, כי הן מאפשרות להשתמש בערכי placeholder שמוחלפים בערכים בפועל בזמן הריצה. ההגדרה הזו מאפשרת הגדרה דינמית של פרמטרים, כמו נתיבי קבצים ושמות טבלאות.

העדפות

העדפות הן הגדרות מוגדרות מראש שחלות ברמות שונות ב-Cloud Data Fusion, כולל המערכת עצמה, מרחבי שמות, אפליקציות (שכוללות צינורות) ותוכניות נפרדות בתוך צינורות. בהעדפות אפשר להגדיר ערכי ברירת מחדל להגדרות נפוצות. אפשר להעביר את הגדרות ברירת המחדל לצינורות עיבוד נתונים ולתוכניות ברמות נמוכות יותר, וכך לצמצם את כמות משימות ההגדרה שחוזרות על עצמן.

ארגומנטים של זמן ריצה

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

הגדרת פקודות מאקרו

כדי להשתמש בפקודת מאקרו לערך של מאפיין של תוסף:

1. ב-Cloud Data Fusion Studio, עוברים לצומת של הפלאגין ולוחצים על Properties (מאפיינים).
2. עוברים לשדה שבו רוצים להשתמש במאקרו ולוחצים על M לצד השדה.
3. מזינים מקש לקיצור הדרך של המאקרו. לדוגמה, בשדה Format במאפייני הפלאגין של מקור הקובץ, מזינים את המפתח הבא: ${format.type}.

הערה: הסמל M שמופיע ליד שדה מאפיין של פלאגין הוא מתג שמאפשר להפעיל פקודות מאקרו. לוחצים עליו שוב כדי לאפס את ערך ברירת המחדל של מאפיין התוסף.

הגדרת ערכי מאקרו

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

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

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

• קודם כל, מערכת Cloud Data Fusion בודקת אם צינור הנתונים כולל תוסף להגדרת ארגומנט:
  • אם יש לו פונקציה להגדרת ארגומנטים, Cloud Data Fusion משתמש בערכים של פקודות מאקרו ממנו.
  • אם אין פונקציה להגדרת ארגומנטים, או אם יש פקודות מאקרו שלא הוקצו בפונקציה להגדרת ארגומנטים, Cloud Data Fusion ישתמש במקום זאת בערכים בארגומנטים של זמן הריצה של הצינור.
• ארגומנטים של זמן ריצה מקבלים בירושה פקודות מאקרו מהעדפות האפליקציה.
• העדפות האפליקציה מקבלות בירושה פקודות מאקרו מהעדפות של מרחב שמות
• העדפות מרחב השמות מקבלות בירושה פקודות מאקרו מהעדפות המערכת.

דוגמאות

שימוש נפוץ בפקודות מאקרו הוא בשדות של נתיבים. במקום להשתמש בנתיבים שמוגדרים ברמת הקוד, אפשר להשתמש בנתיבים דינמיים. לדוגמה, בתוסף מקור של Cloud Storage, אפשר להחליף את ערך הנתיב בכמה פקודות מאקרו. הערך הבא מחלק את האלמנטים של ה-bucket, התיקייה והקובץ: gs://${bucket.name}/${folder}/${file.name}.

בדוגמה הבאה מוצג טעינת נתונים מקטגוריה שהיא סטטית ומקובץ עם שם שהוא לא סטטי. כדי לעשות זאת, צריך להזין את שם הקטגוריה ולהשתמש בפקודת מאקרו לשם הקובץ: gs://<BUCKET_NAME>/${folder}/${file.name}.

מידע נוסף זמין במאמר בנושא פקודות מאקרו ופונקציות מאקרו.

הגדרת העדפות

בקטע הבא מתוארת היררכיית ההעדפות, שבה ההעדפות מוגדרות, עוברות בירושה או משתנות.

הגדרת העדפות המערכת

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

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

כדי להגדיר את העדפות המערכת, פועלים לפי השלבים הבאים:

1. ב-Cloud Data Fusion Studio, לוחצים על System admin > Configuration (ניהול מערכת > הגדרה).
2. לוחצים על העדפות המערכת > עריכת העדפות המערכת.
3. בתיבת הדו-שיח העדפות, מזינים העדפות חדשות או עורכים העדפות קיימות.
4. לוחצים על Save & Close (שמירה וסגירה). ההעדפות האלה זמינות בכל מרחבי השמות, האפליקציות וצינורות הנתונים.

הגדרת העדפות למרחב שמות

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

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

כדי להגדיר העדפות של מרחב שמות:

1. ב-Cloud Data Fusion Studio, לוחצים על System admin (ניהול מערכת) > Configuration (הגדרה).
2. לוחצים על Namespaces (מרחבי שמות) ובוחרים מרחב שמות כדי לפתוח את דף ההגדרות שלו.
3. כדי לערוך את ההעדפות שהועברו בירושה או להוסיף העדפות חדשות, עוברים אל הכרטיסייה 'העדפות' ולוחצים על עריכה. תיבת הדו-שיח העדפות נפתחת. אפשר להזין העדפה חדשה או לבטל את ההעדפות שהוגדרו במערכת. לוחצים על Add ומזינים את המקש ואת הערך החדש של המאקרו.
4. לוחצים על Save & Close (שמירה וסגירה). העדפת מרחב השמות נוצרת עם הערך החדש, שמקבל עדיפות על פני העדפת המערכת.

הגדרת העדפות לאפליקציות

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

1. ב-Cloud Data Fusion Studio, לוחצים על ואז על התפריט Namespace כדי לבחור את מרחב השמות שרוצים להוסיף לו העדפות של אפליקציות.
2. לוחצים על מרכז הבקרה.
3. לוחצים על סמל מפתח הברגים הגדרת העדפות. תוצג רשימה של כל ההעדפות שהועברו בירושה.
4. כדי לערוך את ההעדפות שהועברו בירושה או להוסיף העדפות חדשות, עוברים אל הכרטיסייה 'העדפות' ולוחצים על עריכה. תיבת הדו-שיח העדפות נפתחת. אפשר להזין העדפה חדשה או לבטל את ההעדפות שהוגדרו במערכת. לוחצים על Add ומזינים את המקש ואת הערך החדש של המאקרו.
5. לוחצים על Save & Close (שמירה וסגירה). העדפת האפליקציה נוצרת עם הערך החדש, שמבטל את ההעדפות של המערכת או של מרחב השמות. כשמריצים את צינור הנתונים שנפרס, העדפות האפליקציה מופיעות כארגומנטים של זמן הריצה, שאפשר לערוך אותם.

הגדרת ארגומנטים של זמן ריצה

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

ארגומנטים של זמן ריצה לתצוגה מקדימה של נתונים

כדי להגדיר את הערכים של כל פקודת מאקרו בצינור כשמציגים תצוגה מקדימה של נתונים ב-Cloud Data Fusion Studio, לוחצים על רשימה > הגדרה.

ארגומנטים של זמן ריצה להפעלת צינורות עיבוד נתונים שנפרסו

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

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

הגדרת העדפות של צינור עיבוד הנתונים

כדי להגדיר העדפות לצינור:

1. ב-Cloud Data Fusion Studio, לוחצים על List > Deployed (רשימה > פריסה) ובוחרים צינור פריסה כדי להציג אותו.
2. במרחב העבודה של צינור הנתונים, לוחצים על התפריט הנפתח שליד הפעלה. תיפתח תיבת הדו-שיח Runtime arguments (ארגומנטים של זמן ריצה).
3. בתיבת הדו-שיח Runtime arguments שמופיעה, מציינים את הערך של כל מאקרו בצינור.

סקירה כללית של העדפות, פקודות מאקרו וארגומנטים של זמן ריצה

אפשר להגדיר העדפות ברמות הבאות:

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

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

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

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

• פיתוח צינור עיבוד נתונים. הטמעת פקודות מאקרו במקומות שבהם נדרשים ערכים דינמיים למאפייני התוסף.
• אופציונלי: הגדרת העדפות. אפשר להגדיר ערכי ברירת מחדל לפקודות המאקרו בהעדפות ברמות שונות.
• פריסה והפעלה של צינור עיבוד נתונים. כשמריצים צינור לעיבוד נתונים, קורים הדברים הבאים:
  • העדפות ברמה הרלוונטית, כמו העדפות מערכת או העדפות מרחב שמות, מוחלות.
  • כל ארגומנט שמועבר בזמן הריצה מבטל את הערכים שמוקצים לפקודות המאקרו בהעדפות.
  • ‫Cloud Data Fusion מחליף את פקודות המאקרו בערכים שלהן מתוך הארגומנטים של זמן הריצה (או ההעדפות, אם לא סופק ארגומנט של זמן הריצה).

דוגמה

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

1. מגדירים את המאקרו. במאפיינים של יעד הנתונים, משתמשים בפקודת המאקרו הבאה בשדה Table name: ${output_table}.
2. מגדירים את ההעדפה. בהעדפות האפליקציה, מגדירים העדפה ל-${output_table} עם ערך ברירת המחדל הבא: data_staging.
3. מגדירים את ארגומנט זמן הריצה. כשמריצים את צינור עיבוד הנתונים, צריך לספק ארגומנט של זמן ריצה – לדוגמה, output_table=final_analytics_data.

במהלך ההפעלה של צינור עיבוד הנתונים, המאקרו ${output_table}, מוחלף ב-final_analytics_data.

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

• איך מפעילים צינורות עיבוד נתונים