ציון יחסי תלות ב-Node.js

מותר להשתמש בפונקציה במודולים חיצוניים של Node.js וגם בנתונים מקומיים. תלויות ב-Node.js מנוהלות באמצעות npm ומופיעות בקובץ מטא-נתונים בשם package.json. סביבות זמן הריצה של Node.js ב-Cloud Run functions תומכות בהתקנה באמצעות npm,‏ yarn או pnpm.

כדי לציין תלות בפונקציה, מוסיפים אותה לקובץ package.json.

בדוגמה הזו, תלות מופיעה בקובץ package.json:

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

לאחר מכן, התלות מיובאת בפונקציה:

const functions = require('@google-cloud/functions-framework');
const escapeHtml = require('escape-html');

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

‫Functions Framework הוא תלות חובה לכל הפונקציות. למרות שפונקציות Cloud Run מתקינות אותו בשמכם כשהפונקציה נוצרת, מומלץ לכלול אותו כתלות מפורשת כדי שהקוד יהיה ברור.

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

שימוש ב-npm כדי להתקין מודולים של Node.js באופן מקומי

הדרך הקלה ביותר להתקין מודול Node.js באופן מקומי היא להשתמש בפקודה npm install בתיקייה שמכילה את הפונקציה. לדוגמה, הפקודה הבאה מוסיפה את המודול uuid:

npm install uuid

הפעולה הזו משלבת שני שלבים:

  1. הגרסה האחרונה של המודול מסומנת כתלות בקובץ package.json. חשוב מאוד: פונקציות Cloud Run מתקינות רק מודולים שמוצהרים בקובץ package.json.
  2. המודול יורד לספרייה node_modules. כך תוכלו להשתמש במודול כשאתם מפתחים באופן מקומי.

אם npm לא מותקן במחשב, מורידים את npm.

הגדרת יחסי תלות בהתקנות

אפשר להתקין יחסי תלות של סביבת הייצור עבור NPM,‏ Yarn או Pnpm:

NPM

כשפורסים את הפונקציה, Cloud Run functions מתקין את התלויות שמוצהרות בקובץ package.json באמצעות הפקודה npm install:

npm install --production

חוטי סריגה

בסביבת זמן הריצה Node.js 8 ומעלה, אם קיים קובץ yarn.lock, פונקציות Cloud Run משתמשות במקום זאת בפקודה yarn install:

yarn install --production

Pnpm

בסביבת זמן הריצה Node.js 8 ומעלה, אם קיים קובץ pnpm-lock.yaml, פונקציות Cloud Run משתמשות במקום זאת בפקודה pnpm install:

pnpm install

ביצוע שלבי build בהתאמה אישית במהלך הפריסה

אחרי הפריסה, אפשר לבצע שלב בנייה מותאם אישית במהלך תהליך build של הפונקציה על ידי הוספת סקריפט gcp-build לקובץ package.json.

כשמריצים את הסקריפט הזה, התלויות בשדות dependencies ו-devDependencies בקובץ package.json זמינות. אחרי שמריצים את שלב הבנייה המותאם אישית, פונקציות Cloud Run מסירות את התיקייה node_modules ויוצרות אותה מחדש, ומתקינות רק את יחסי התלות של הסביבה הפרודקטיבית שהוגדרו בשדה dependencies בקובץ package.json.

אם אין סקריפט gcp-build ב-package.json, פונקציות Cloud Run מתקינות רק תלות בייצור.

שימוש בחבילות מערכת

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

כולל מודולים מקומיים של Node.js

אפשר גם לכלול מודולים מקומיים של Node.js כחלק מהפונקציה. כדי לעשות את זה, צריך להצהיר על המודול ב-package.json באמצעות הקידומת file:. בדוגמה הבאה, mymodule הוא שם המודול ו-mymoduledir הוא הספרייה שמכילה את המודול:

{
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}

הקוד של המודול המקומי הזה צריך להיות מאוחסן במקום אחר ולא בתיקייה node_modules בתיקיית השורש של הפונקציה.

טעינת מודולים של Node.js

משתמשים בפונקציה Node.js‏ require() כדי לטעון כל מודול Node.js שהתקנתם. אפשר גם להשתמש בפונקציה require() כדי לייבא קבצים מקומיים שאתם פורסים לצד הפונקציה.

שימוש במודולים פרטיים

כדי להשתמש במודול npm פרטי, צריך לספק הגדרות לאימות מול המאגר בקובץ .npmrc בתיקייה של הפונקציה. אם אתם משתמשים ב-Yarn בגרסה 2 ומעלה כמנהל החבילות, שם הקובץ הוא .yarnrc.yml.

מודולים פרטיים מ-Artifact Registry

מאגר חבילות Node.js ב-Artifact Registry יכול לארח מודולים פרטיים של הפונקציה. כשפורסים פונקציית Cloud Run, תהליך ה-build יוצר באופן אוטומטי פרטי כניסה ל-Artifact Registry עבור חשבון השירות של Cloud Build. צריך לכלול רק את מאגר Artifact Registry שב-.npmrc בלי ליצור פרטי כניסה נוספים. לדוגמה:

@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

הגישה הזו רלוונטית גם למנהל החבילות Yarn v1. אם אתם משתמשים ב-Yarn בגרסה 2 ומעלה, אתם צריכים רק לציין את מאגר Artifact Registry ב-.yarnrc.yml בלי פרטי כניסה נוספים. לדוגמה:

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

מודולים פרטיים ממאגרים אחרים

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

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

פורמט קובץ

אם אתם משתמשים בקובץ .npmrc כדי להגדיר אסימון אימות בהתאמה אישית, הוא צריך לכלול את השורה שמוצגת למטה.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

מחליפים את:

  • ‫REGISTRY_DOMAIN: שם הדומיין של מאגר npm פרטי. אם המאגר מתארח ב-npmjs.org, צריך להגדיר את השדה הזה לערך registry.npmjs.org.

  • ‫AUTH_TOKEN: אסימון ההרשאה של מאגר npm. זה יכול להיות ערך הטקסט המילולי של הטוקן או מחרוזת הטקסט ${NPM_TOKEN}, שמוחלפת בערך הטוקן בפועל מהסביבה.npm

    אפשר להגדיר את משתנה הסביבה $NPM_TOKEN באמצעות הארגומנט --set-build-env-vars בפקודה gcloud functions deploy. לפרטים נוספים על אסימון האימות של NPM, אפשר לעיין במדריך של NPM בנושא מודולים פרטיים.

איך בונים פונקציה עם יחסי תלות של ספקים

תלויות מסוג Vendored הן תלויות שקוד המקור שלהן נכלל ישירות בחבילת קוד המקור שלכם ונבנה מחדש לצד הקוד שלכם. כדי ליצור תלויות של Node.js שנכללות בחבילה ולדלג על ההתקנה שלהן במהלך ה-Deployment (פריסה), משתמשים במשתנה הסביבה של סביבת ה-build‏ GOOGLE_VENDOR_NPM_DEPENDENCIES.

דרישות מוקדמות ליחסי תלות של יצירת עותק מקוד של צד שלישי (vendoring)

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

  2. כדי להתקין את יחסי התלות האלה באופן מקומי, מריצים את הפקודה:

        npm install

  3. מסירים את node_modules מהקובץ ‎ .gcloudignore בספריית העבודה.

  4. פורסים את הפונקציה ומוודאים שגרסת Node.js המקומית זהה לגרסה שצוינה במהלך הפריסה.

  5. מפעילים את הפונקציה ואת התלויות שנוספו באמצעות הפקודה הבאה:

      gcloud functions deploy FUNCTION_NAME \
    --runtime RUNTIME_NAME \
    --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true

    מחליפים את:

    • ‫FUNCTION_NAME: השם של הפונקציה ב-Cloud Run Functions שפורסים
    • ‫RUNTIME_NAME: השם של סביבת זמן הריצה של Node.js שבה הפונקציה הפרוסה תפעל. הגרסה הזו צריכה להיות זהה לגרסת Node.js שבה השתמשתם בסביבת הפיתוח המקומית

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

אם מציינים מנוע npm בקובץ package.json, הגרסה שצוינה של npm מורדת בזמן ה-build. כדי למנוע את ההתנהגות הזו, צריך להסיר את השורה הזו מקובץ package.json.