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

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

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

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

כדי לציין תלות בפונקציה, מוסיפים אותה לקובץ 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')}!`);
});

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

הדרך הקלה ביותר להתקין מודול Node.js באופן מקומי היא להשתמש בפקודה npm install בתיקייה שמכילה את הפונקציה של Cloud Run. לדוגמה, הפקודה הבאה מוסיפה את המודול 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 בנושא מודולים פרטיים.

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

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

דרישות מוקדמות להעתקת יחסי תלות

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

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

        npm install

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

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

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

      gcloud run deploy SERVICE \
    --source . \
    --function FUNCTION_ENTRY_POINT \
    --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true

    מחליפים את:

    • ‫SERVICE: השם של פונקציית Cloud Run שפורסתם
    • ‫FUNCTION_ENTRY_POINT: עם נקודת הכניסה לפונקציה בקוד המקור.

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