שימוש בחבילות 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 Editor (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

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

בקטע הזה מוסבר איך לאמת חבילת 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. בשדה ערך סודי, מזינים אסימון אימות אחד או יותר בפורמט הבא:

   {
     "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
   }
   

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

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

2. נותנים לחשבון השירות המותאם אישית גישה לסוד.

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

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

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

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

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

   מעבר אל Dataform

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

3. בדף המאגר, לוחצים על הגדרות > הגדרת חבילות NPM פרטיות.

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. בשדה Add a file path (הוספת נתיב קובץ), מזינים את הערך .npmrc.

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

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

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

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

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

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

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

   מעבר אל Dataform

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

3. בחלונית קבצים, בוחרים את הקובץ .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, list secrets (רשימת סודות) ובוחרים את הסוד שבו מאוחסנים אסימוני אימות של חבילות 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 זמינה ב-dataform-package-base ב-GitHub.

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

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

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

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

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

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

   2. בשדה Add a file path (הוספת נתיב קובץ), מזינים את הערך 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 זמין במאמר בנושא שימוש חוזר בקוד בכמה מאגרי מידע באמצעות חבילות.
• כדי ללמוד איך לכתוב משתנים ופונקציות ב-JavaScript שאפשר להשתמש בהם מחדש ב-Dataform, אפשר לעיין במאמר שימוש חוזר במשתנים ובפונקציות באמצעות קובצי include ב-Dataform.