שימוש בחבילות 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, יוצרים סוד.