שימוש בחבילות JavaScript

במאמר הזה מוסבר איך:

• התקנת חבילת JavaScript במאגר של Dataform
• אימות של חבילת NPM פרטית כדי לאפשר את ההתקנה שלה במאגר.
• ליצור חבילת JavaScript בהתאמה אישית שאפשר להשתמש בה כדי לפתח תהליכי עבודה.

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

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

   כניסה ל-Dataform

2. מבצעים אחת מהפעולות הבאות או את שתיהן:

   1. כדי להתקין חבילה במאגר או לאמת חבילת NPM פרטית כדי לאפשר את ההתקנה שלה, פועלים לפי השלבים הבאים:
      1. בוחרים מאגר או יוצרים מאגר.
      2. בוחרים או יוצרים סביבת עבודה לפיתוח.
      3. אופציונלי: כדי להתקין חבילה פרטית, מאמתים את החבילה הפרטית.
      4. אם המאגר לא מכיל קובץ package.json, צריך ליצור קובץ package.json ולהעביר את חבילת הליבה של Dataform.
   2. כדי ליצור חבילה:
      1. יוצרים מאגר Dataform שמיועד לחבילה. שם המאגר צריך להיות זהה לשם החבילה.
      2. מקשרים את המאגר למאגר Git של צד שלישי שיארח את החבילה.
      3. יוצרים ומפעילים סביבת עבודה במאגר של Dataform.

3. מוודאים שיש לכם את ההרשאות הנדרשות כדי לבצע את המשימות שמפורטות במסמך הזה.

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לביצוע המשימות שמפורטות במאמר הזה, בקשו מהאדמין להקצות לכם את התפקידים הבאים ב-IAM:

• עריכה ב-Dataform (roles/dataform.editor) בסביבות עבודה ובמאגרים
• אדמין ב-Dataform (roles/dataform.admin) במאגרים

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

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

התקנת חבילה

בקטע הזה מוסבר איך להתקין חבילת JavaScript ולייבא אותה לקובץ JavaScript ולקובץ SQLX, כדי שתוכלו להשתמש בחבילה לפיתוח תהליכי עבודה ב-Dataform.

כדי להשתמש בחבילה ב-Dataform, צריך להתקין אותה במאגר.

אפשר להתקין את סוגי החבילות הבאים ב-Dataform:

• חבילות NPM ציבוריות שפורסמו
• חבילות NPM ציבוריות שלא פורסמו
• חבילות NPM פרטיות מאומתות

לאחר מכן, כדי להשתמש בחבילה בקובץ JavaScript או SQLX, צריך לייבא את התוכן שנבחר מהחבילה לקובץ. אפשר גם לייבא חבילה שלמה לקובץ JavaScript או SQLX במקום את התוכן שנבחר.

כדי למנוע בעיות בהתקנת חבילות בסביבת הייצור, מומלץ לבצע את הפעולות הבאות:

• מציינים במפורש את גרסת החבילה ב-package.json, לדוגמה 3.0.0. אל תשתמשו באפשרויות אחרות של dependencies ב-package.json, למשל >version.

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

הוספת חבילה כתלות

כדי להתקין חבילה במאגר של Dataform, צריך להוסיף אותה כתלות בקובץ package.json:

1. בסביבת העבודה, בחלונית Files, בוחרים באפשרות package.json.

2. מוסיפים את החבילה לבלוק dependencies:

   1. מוסיפים חבילת NPM ציבורית שפורסמה בפורמט הבא:

      "PACKAGE-NAME": "PACKAGE-VERSION"
      

      מחליפים את מה שכתוב בשדות הבאים:

      • ‫PACKAGE-NAME בשם החבילה.
      • ‫PACKAGE-VERSION עם הגרסה העדכנית של חבילת ה-NPM הציבורית שפורסמה. כדי למנוע בעיות בהתקנת החבילה, צריך לציין את הגרסה באופן מפורש, לדוגמה, 3.0.0.

   2. מוסיפים חבילת NPM ציבורית שלא פורסמה בפורמט הבא:

      "PACKAGE-NAME": "PACKAGE-URL"
      

      מחליפים את מה שכתוב בשדות הבאים:

      • ‫PACKAGE-NAME בשם החבילה.
      • ‫PACKAGE-URL בכתובת ה-URL של tar.gz במאגר החבילות של הצד השלישי, לדוגמה https://github.com/user/sample-package-repository/archive/master.tar.gz.

   3. מוסיפים חבילת NPM פרטית מאומתת בפורמט הבא:

      "REGISTRY-SCOPE/PACKAGE-NAME": "PACKAGE-URL"
      

      מחליפים את מה שכתוב בשדות הבאים:

      • ‫REGISTRY-SCOPE בשם החבילה. הערך של REGISTRY-SCOPE צריך להתאים להיקף המרשם שמוגדר בקובץ .npmrc במאגר.
      • ‫PACKAGE-NAME בשם החבילה.
      • ‫PACKAGE-URL בכתובת ה-URL של tar.gz במאגר החבילות, לדוגמה: https://github.com/user/sample-package-repository/archive/master.tar.gz.

3. לוחצים על Install packages (התקנת חבילות).

4. שומרים ודוחפים את השינויים.

בדוגמת הקוד הבאה מוצגת חבילת Slowly changing dimensions הציבורית בקוד פתוח שנוספה לקובץ .package.json:

 ```json
 {
   "name": "repository-name",
   "dependencies": {
     "@dataform/core": "2.0.3",
     "dataform-scd": "https://github.com/dataform-co/dataform-scd/archive/0.3.tar.gz"
   }
 }
 ```

ייבוא פונקציה או קבוע של חבילה לקובץ JavaScript ב-Dataform

כדי להשתמש בפונקציה או בקבוע מחבילה בתוך קובץ JavaScript ב-Dataform, קודם צריך לייבא אותם לקובץ.

כדי לייבא פונקציה או קבוע מחבילה לקובץ JavaScript, פועלים לפי השלבים הבאים:

1. בחלונית Files בסביבת העבודה, בוחרים קובץ .js שבו רוצים להשתמש בחבילה.

2. בקובץ, מייבאים פונקציה או קבוע בפורמט הבא:

   const { EXPORT-NAME } = require("PACKAGE-NAME");
   

   1. מחליפים את EXPORT-NAME בשם של הפונקציה או הקבוע שרוצים להשתמש בהם, שהוצהרו ב-module.exports בקובץ החבילה index.js.
   2. מחליפים את PACKAGE-NAME בשם החבילה שבה רוצים להשתמש.

3. שומרים ודוחפים את השינויים.

בדוגמת הקוד הבאה מוצגת הפונקציה getDomain מהחבילה postoffice, שיובאה ונעשה בה שימוש בקובץ JavaScript:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const { getDomain } = require("postoffice");
getDomain();

ייבוא של חבילה שלמה לקובץ JavaScript ב-Dataform

כדי לייבא את כל החבילה לקובץ JavaScript במקום לייבא פונקציות או קבועים נבחרים לקובץ JavaScript, פועלים לפי השלבים הבאים:

1. בחלונית Files בסביבת העבודה, בוחרים קובץ .js שבו רוצים להשתמש בחבילה.

2. בקובץ, מייבאים את החבילה בפורמט הבא:

   const CONSTANT-NAME = require("PACKAGE-NAME");
   

   1. מחליפים את CONSTANT-NAME בשם של הקבוע.
   2. מחליפים את PACKAGE-NAME בשם החבילה שבה רוצים להשתמש.

3. שומרים ודוחפים את השינויים.

דוגמת הקוד הבאה מציגה את הפונקציה getDomain מהחבילה המיובאת postoffice שמשמשת בקובץ JavaScript:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const postoffice = require("postoffice");
postoffice.getDomain();

ייבוא פונקציה או קבוע של חבילה לקובץ SQLX ב-Dataform

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

כדי לייבא פונקציה או קבוע מחבילה לקובץ SQLX:

1. בסביבת העבודה, בחלונית Files, בוחרים קובץ .sqlx שבו רוצים להשתמש בחבילה.

2. בקובץ, מזינים את הבלוק הבא של js:

   js {
     const { EXPORT-NAME } = require("PACKAGE-NAME");
   }
   

   1. מחליפים את EXPORT-NAME בשם של הפונקציה או הקבוע שרוצים להשתמש בהם, שהוצהרו ב-module.exports בקובץ החבילה index.js.
   2. מחליפים את PACKAGE-NAME בשם החבילה שבה רוצים להשתמש.

3. שומרים ודוחפים את השינויים.

בדוגמת הקוד הבאה מוצגת הפונקציה getDomain מהחבילה postoffice, שיובאה בבלוק js ומשמשת בהצהרה SELECT בקובץ SQLX:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const { getDomain } = require("postoffice");
}

SELECT ${getDomain("email")} as test

ייבוא של חבילה שלמה לקובץ SQLX ב-Dataform

כדי לייבא את כל החבילה לקובץ SQLX במקום לייבא פונקציות או קבועים נבחרים לקובץ JavaScript, פועלים לפי השלבים הבאים:

1. בסביבת העבודה, בחלונית Files, בוחרים קובץ .sqlx שבו רוצים להשתמש בחבילה.

2. בקובץ, מייבאים את החבילה בפורמט הבא:

   js {
     const CONSTANT-NAME = require("PACKAGE-NAME");
   }
   

   1. מחליפים את CONSTANT-NAME בשם של הקבוע.
   2. מחליפים את PACKAGE-NAME בשם החבילה שבה רוצים להשתמש.

3. שומרים ודוחפים את השינויים.

בדוגמת הקוד הבאה מוצגת החבילה postoffice שיובאה בבלוק js, והפונקציה getDomain שלה שמשמשת בהצהרה SELECT בקובץ SQLX:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const postoffice = require("postoffice");
}

SELECT ${postoffice.getDomain("email")} as test

אימות של חבילה פרטית

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

בקטע הזה מוסבר איך לאמת חבילת NPM פרטית ב-Dataform כדי לאפשר את ההתקנה שלה במאגר Dataform.

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

אימות החבילה הפרטית הראשונה במאגר Dataform

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

1. יוצרים סוד ב-Secret Manager שמוקדש לאחסון אסימוני אימות של חבילות NPM פרטיות במאגר של Dataform.

   1. מוסיפים לסוד את אסימון האימות של החבילה, שהתקבל מהמרשם של NPM.

   אתם צריכים לאחסן את כל אסימוני האימות של חבילות ה-NPM הפרטיות במאגר שלכם בסוד אחד. צריך ליצור סוד ייעודי אחד לכל מאגר Dataform. הסוד חייב להיות בפורמט JSON.

2. מעלים את הסוד למאגר של Dataform.

3. יוצרים קובץ .npmrc ומוסיפים לקובץ את אסימון האימות של החבילה.

   אסימון האימות בקובץ .npmrc חייב להיות זהה לאסימון האימות בסוד שהועלה.

אחרי שמאמתים את חבילת ה-NPM הפרטית, אפשר להתקין את החבילה במאגר של Dataform.

יצירת סוד לאימות של חבילות פרטיות

כדי לאמת חבילות NPM פרטיות במאגר Dataform, צריך ליצור סוד ב-Secret Manager ולהגדיר אסימוני אימות לכל החבילות הפרטיות שרוצים להתקין במאגר Dataform בתוך הסוד. מגדירים טוקן אימות אחד לכל חבילת NPM פרטית, ומאחסנים את כל טוקני האימות בסוד אחד לכל מאגר. הסוד חייב להיות בפורמט JSON.

כדי ליצור סוד עם אסימוני אימות לחבילות NPM פרטיות:

1. ב-Secret Manager, יוצרים סוד.

   1. בשדה Secret value, מזינים אסימון אימות אחד או יותר בפורמט הבא:

   {
     "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
   }
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫AUTHENTICATION_TOKEN_NAME: שם ייחודי לאסימון שמזהה את החבילה שהוא מאמת.
   • ‫TOKEN_VALUE: הערך של אסימון האימות, שהתקבל מהמרשם של NPM.

2. נותנים לסוכן השירות של Dataform גישה לסוד.

   המזהה של סוכן השירות של Dataform הוא בפורמט הבא:

   service-PROJECT_NUMBER@gcp-sa-dataform.
   

   1. כשנותנים גישה, חשוב לוודא שנותנים לסוכן השירות של Dataform את התפקיד roles/secretmanager.secretAccessor.

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

העלאת הסוד לאימות של חבילות פרטיות למאגר Dataform

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

כדי להעלות את הסוד עם אסימוני האימות של חבילות NPM פרטיות למאגר Dataform, פועלים לפי השלבים הבאים:

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

   כניסה ל-Dataform

2. בוחרים את המאגר שבו רוצים להתקין חבילות NPM פרטיות.

3. בדף המאגר, לוחצים על Settings > Configure private NPM packages.

4. בחלונית Add NPM package secret token, בתפריט Secret, בוחרים את הסוד שמכיל אסימוני אימות לחבילות NPM פרטיות.

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

יצירת קובץ .npmrc לאימות של חבילות פרטיות

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

כדי ליצור קובץ .npmrc ברמה העליונה במאגר:

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

   כניסה ל-Dataform

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

3. בחלונית Files, לוחצים על More ואז על Create file.

4. בחלונית Create new file:

   1. בשדה הוספת נתיב לקובץ, מזינים .npmrc.

   2. לוחצים על יצירת קובץ.

הוספת אסימון אימות לקובץ .npmrc במאגר של Dataform

כדי לאמת חבילת NPM פרטית במאגר של Dataform שכבר מכיל סוד עם אסימוני אימות של חבילות וקובץ .npmrc, צריך להוסיף את אסימון האימות של החבילה הפרטית לקובץ .npmrc במאגר.

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

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

כדי להוסיף אסימון אימות לקובץ .npmrc במאגר של Dataform:

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

   כניסה ל-Dataform

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

3. בחלונית Files, בוחרים את הקובץ .npmrc.

4. בקובץ .npmrc, מגדירים את היקף המרשם של NPM ואת אסימון האימות של החבילה הפרטית בפורמט הבא:

   @REGISTRY-SCOPE:registry=NPM-REGISTRY-URL
   NPM-REGISTRY-URL:_authToken=$AUTHENTICATION-TOKEN
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫REGISTRY-SCOPE: היקף המרשם של NPM שעליו רוצים להחיל את אסימון האימות.
   • ‫NPM-REGISTRY-URL: כתובת ה-URL של המרשם של NPM, לדוגמה https://npm.pkg.github.com.
   • ‫AUTHENTICATION-TOKEN: אסימון האימות של חבילת ה-NPM הפרטית. אסימון האימות בקובץ .npmrc צריך להיות זהה לאסימון האימות בסוד שהועלה. אסימון האימות מסופק כמשתנה סביבה בקובץ .npmrc, לכן חשוב להוסיף את הסוגריים המסולסלים הפותחים ${ והסוגרים }.

   אפשר להזין כמה אסימוני אימות.

דוגמת הקוד הבאה מראה אסימון אימות של חבילת NPM פרטית שנוספה לקובץ .npmrc במאגר של Dataform:

@company:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${AUTHENTICATION_TOKEN}

אימות של חבילה פרטית נוספת במאגר Dataform

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

1. ב-Secret Manager, מציגים את רשימת הסודות ובוחרים את הסוד שבו מאוחסנים אסימוני האימות של חבילות NPM פרטיות במאגר.

2. מוסיפים גרסה חדשה לסוד.

   כברירת מחדל, Dataform משתמש בגרסה העדכנית של הסוד.

   1. מוסיפים את אסימון האימות של החבילה הפרטית לערך הסודי בפורמט הבא:

   {
     "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
   }
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫AUTHENTICATION_TOKEN_NAME: שם ייחודי לאסימון שמזהה את החבילה שהוא מאמת.
   • ‫TOKEN_VALUE: הערך של אסימון האימות, שהתקבל מהמרשם של NPM.

   אפשר להוסיף כמה אסימוני אימות בבת אחת.

3. ב-Dataform, מוסיפים את אסימון האימות לקובץ .npmrc במאגר.

אחרי שמאמתים את חבילת ה-NPM הפרטית, אפשר להתקין את החבילה במאגר של Dataform.

יצירת חבילה

בקטע הזה מוסבר איך ליצור חבילת JavaScript בהתאמה אישית, שבה תוכלו להשתמש כדי לפתח תהליכי עבודה ב-Dataform.

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

לאחר מכן, צריך ליצור קובץ index.js ברמה העליונה ולהוסיף לקובץ את תוכן החבילה שניתן לייצא, כמו פונקציות וקבועים. דוגמה לחבילה שנוצרה ב-Dataform זמינה ב-GitHub, בכתובת dataform-package-base.

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

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

כדי ליצור חבילה משלכם עם קוד JavaScript שאפשר להשתמש בו שוב ב-Dataform, פועלים לפי השלבים הבאים בסביבת העבודה:

1. בחלונית קבצים, לוחצים על אפשרויות נוספות.

2. לוחצים על יצירת קובץ.

   1. בחלונית Create new file:

   2. בשדה הוספת נתיב לקובץ, מזינים index.js.

   3. לוחצים על יצירת קובץ.

3. בקובץ index.js, מזינים את קוד ה-JavaScript שרוצים שהחבילה תייצא.

   1. יוצרים קבועים בפורמט הבא:

      const CONSTANT_NAME = CONSTANT_VALUE;
      module.exports = { CONSTANT_NAME };
      

      מחליפים את מה שכתוב בשדות הבאים:

      • ‫CONSTANT_NAME: שם הקבוע
      • ‫CONSTANT_VALUE: הערך של הקבוע

   2. יוצרים פונקציות בפורמט הבא:

      function FUNCTION_NAME(PARAMETERS) { FUNCTION_BODY }
      
      module.exports = { FUNCTION_NAME }
      

      מחליפים את מה שכתוב בשדות הבאים:

      • ‫FUNCTION_NAME: שם הפונקציה.
      • ‫PARAMETERS: הפרמטרים של הפונקציה.
      • ‫FUNCTION_BODY: הקוד שרוצים שהפונקציה תריץ.

4. אופציונלי: לוחצים על עיצוב.

5. אופציונלי: בספרייה definitions, מוסיפים את הקוד של החבילה שלא תיוצא.

6. שומרים ודוחפים את השינויים.

בדוגמת הקוד הבאה של החבילה מוצג הקובץ index.js של החבילה postoffice שמייצאת את הפונקציה getDomain:

// filename index.js
// package name postoffice

const GENERIC_DOMAINS = "('samplemail.com','samplemail.co.uk','examplemailbox.com'";

function getDomain(email) {
  let cleanEmail = `trim(${email})`
  const domain = `substr(${cleanEmail}, strpos(${cleanEmail}, '@') + 1)`;
  return `case
            when ${domain} in ${common.GENERIC_DOMAINS} then ${cleanEmail}
            when ${domain} = "othermailbox.com" then "other.com"
            when ${domain} = "mailbox.com" then "mailbox.global"
            when ${domain} = "support.postman.com" then "postman.com"
            else ${domain}
          end`;
}

module.exports = { getDomain }

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

• במאמר ניהול חבילת הליבה של Dataform מוסבר איך לנהל את חבילת הליבה הנדרשת של Dataform.
• מידע נוסף על חבילות ב-Dataform מופיע במאמר שימוש חוזר בקוד בכמה מאגרים באמצעות חבילות.
• במאמר שימוש חוזר במשתנים ובפונקציות עם הכללות ב-Dataform מוסבר איך לכתוב משתנים ופונקציות של JavaScript שאפשר להשתמש בהם שוב ב-Dataform.