טיפול ביחסי תלות


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

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

בדוגמה הזו, יחסי התלות מפורטים בקובץ package.json:

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

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

JavaScriptTypeScript
const escapeHtml = require('escape-html');

// Return a greeting with the input HTML-escaped.
exports.hello = functions.https.onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

import * as escapeHtml from 'escape-html';

// Return a greeting with the input HTML-escaped.
export let hello = functions.https.onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
}

הוספת מודולים מקומיים של Node.js

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

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

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

שלבים נוספים ל-TypeScript

TypeScript עוזרת הכי הרבה כשמשתמשים בספריות שיש בהן פרטי טיפוס. כך, TypeScript יכול לזהות שגיאות תחביר והעורכים יכולים להציע הצעות טובות יותר להשלמה אוטומטית. ספריות מסוימות, כמו firebase-admin ו-firebase-functions, כוללות הגדרות של TypeScript.

בספריות רבות אין הגדרה משלהם של TypeScript. הפרויקט DefinitelyTyped מספק הגדרות שמנוהלות על ידי הקהילה לספריות הצמתים הפופולריות ביותר. ההגדרות האלה מתפרסמות על ידי DefinitelyTyped באותו שם חבילה ב-NPM, אבל בתוך הארגון ‎@types. לדוגמה, אפשר להתקין את פרטי הסוג של הספרייה uuid באמצעות הפקודה הבאה:

npm install @types/uuid

ככל שתתמקצעו ב-TypeScript, יכול להיות שתשתמשו בשתי ההתקנות:

npm install uuid @types/uuid

יחסי התלות בין הסוגים צריכים להיות מאותו סוג כמו יחסי התלות בספרייה. לדוגמה, לא מומלץ לשמור את uuid כיחסי תלות רגילים ואת @types/uuid כיחסי תלות לצורכי פיתוח או כיחסי תלות בין חבילות.

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

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

אם אתם כותבים פונקציות ב-TypeScript, תוכלו להשתמש בהצהרה import באותו אופן כדי לטעון כל מודול של Node.js שהותקן.

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

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

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

מאגר חבילות Node.js ב-Artifact Registry יכול לארח מודולים פרטיים של הפונקציה. כשפורסים פונקציה של Google Cloud Functions, תהליך ה-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 ולדלג על ההתקנה שלהם במהלך הפריסה, משתמשים במשתנה הסביבה ל-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 Functions שמפרסים
    • RUNTIME_NAME: השם של סביבת זמן הריצה של Node.js שבה תפעל הפונקציה הפרוסה. זו צריכה להיות אותה גרסת Node.js שבה השתמשתם בסביבת הפיתוח המקומית

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

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