การจัดการทรัพยากร Dependency

เลือกภาษา: Node.js Python

ฟังก์ชัน Cloud Functions สามารถใช้โมดูลภายนอกและการอ้างอิงภายในได้ วิธีระบุและจัดการการอ้างอิงจะขึ้นอยู่กับภาษาที่ใช้รันไทม์

Node.js

ฟังก์ชันสามารถใช้โมดูล Node.js ภายนอก รวมถึงข้อมูลภายในได้ ระบบจะจัดการการอ้างอิงใน Node.js ด้วย npm และแสดงในการอ้างอิงในไฟล์ข้อมูลเมตาที่ชื่อว่า package.json รันไทม์ Node.js ของ Cloud Functions รองรับการติดตั้งโดยใช้ npm, yarn หรือ pnpm

หากต้องการระบุการอ้างอิงสำหรับฟังก์ชัน ให้เพิ่มการอ้างอิงลงในไฟล์ package.json

ในตัวอย่างนี้ ทรัพยากร Dependency จะแสดงอยู่ในไฟล์ package.json ดังนี้

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

จากนั้นจะมีการนำเข้าทรัพยากร Dependency ในฟังก์ชันดังนี้

JavaScript

const onRequest = require("firebase-functions/https");
const escapeHtml = require("escape-html");

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

TypeScript

import { onRequest } from "firebase-functions/https";
import * as escapeHtml from "escape-html";

// Return a greeting with the input HTML-escaped.
export let hello = 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 มากขึ้น คุณอาจพบว่าตัวเองใช้การติดตั้งทั้ง 2 แบบร่วมกัน

npm install uuid @types/uuid

ทรัพยากร Dependency ประเภทควรเป็นชนิดเดียวกับทรัพยากร Dependency ไลบรารี ตัวอย่างเช่น คุณไม่ควรบันทึก uuid เป็นทรัพยากร Dependency ปกติและ @types/uuid เป็น ทรัพยากร Dependency การพัฒนาหรือทรัพยากร Dependency เพียร์

การโหลดโมดูล Node.js

ใช้ require() ฟังก์ชันของ Node.js เพื่อโหลดโมดูล Node.js ที่คุณติดตั้งไว้ นอกจากนี้ คุณยังใช้ฟังก์ชัน require() เพื่อนำเข้าไฟล์ภายในที่คุณทำให้ใช้งานได้พร้อมกับฟังก์ชันได้ด้วย

หากคุณเขียนฟังก์ชันใน TypeScript ให้ใช้คำสั่ง import ในลักษณะเดียวกันเพื่อโหลดโมดูล Node.js ที่คุณติดตั้งไว้

การใช้โมดูลส่วนตัว

คุณสามารถใช้ โมดูล npm ส่วนตัว ได้โดยระบุการตั้งค่าสำหรับการตรวจสอบสิทธิ์กับ รีจิสทรีในไฟล์ .npmrc ในไดเรกทอรีของฟังก์ชัน หากคุณใช้ Yarn v2 ขึ้นไปเป็นตัวจัดการแพ็กเกจ ไฟล์นี้จะมีชื่อว่า .yarnrc.yml

โมดูลส่วนตัวจาก Artifact Registry

ที่เก็บแพ็กเกจ Node.js ของ Artifact Registry สามารถโฮสต์โมดูลส่วนตัวสำหรับฟังก์ชันได้ เมื่อคุณทำให้ฟังก์ชัน Google Cloud Functions ใช้งานได้ กระบวนการบิลด์จะสร้างข้อมูลเข้าสู่ระบบ 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 v2 ขึ้นไป คุณเพียงต้องระบุที่เก็บ 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

Python

คุณระบุการอ้างอิงสำหรับ Cloud Functions ที่เขียนด้วย Python ได้ 2 วิธี ได้แก่ การใช้ไฟล์ pip ของตัวจัดการแพ็กเกจ requirements.txt หรือการแพ็กการอ้างอิงภายในพร้อมกับฟังก์ชัน

ระบบไม่รองรับการระบุการอ้างอิงโดยใช้มาตรฐาน Pipfile/Pipfile.lock โปรเจ็กต์ไม่ควรรวมไฟล์เหล่านี้

การระบุการอ้างอิงด้วย pip

ระบบจะจัดการการอ้างอิงใน Python ด้วย pip และแสดงในการอ้างอิงในไฟล์ข้อมูลเมตา ที่ชื่อว่า requirements.txt ไฟล์นี้ต้องอยู่ในไดเรกทอรีเดียวกับไฟล์ main.py ที่มีโค้ดฟังก์ชัน

เมื่อคุณทำให้ฟังก์ชันใช้งานได้หรือทำให้ใช้งานได้อีกครั้ง Cloud Functions จะใช้ pip เพื่อดาวน์โหลดและติดตั้งการอ้างอิงเวอร์ชันล่าสุดตามที่ประกาศไว้ในไฟล์ requirements.txt ไฟล์ requirements.txt มี 1 บรรทัดต่อแพ็กเกจ แต่ละบรรทัดจะมีชื่อแพ็กเกจและเวอร์ชันที่ขอ (ไม่บังคับ) ดูรายละเอียดเพิ่มเติมได้ที่ ข้อมูลอ้างอิงrequirements.txt

หากต้องการป้องกันไม่ให้บิลด์ได้รับผลกระทบจากการเปลี่ยนแปลงเวอร์ชันของทรัพยากร Dependency ให้พิจารณาตรึงแพ็กเกจทรัพยากร Dependency ไว้ที่เวอร์ชันที่เฉพาะเจาะจง

ตัวอย่างไฟล์ requirements.txt มีลักษณะดังนี้

functions-framework
requests==2.20.0
numpy

การแพ็กการอ้างอิงภายใน

นอกจากนี้ คุณยังแพ็กและทำให้การอ้างอิงใช้งานได้พร้อมกับฟังก์ชันได้ด้วย วิธีนี้มีประโยชน์หากทรัพยากร Dependency ไม่พร้อมใช้งานผ่านเครื่องมือจัดการแพ็กเกจ pip หรือหากการเข้าถึงอินเทอร์เน็ตของสภาพแวดล้อม Cloud Functions ถูกจำกัด

ตัวอย่างเช่น คุณอาจใช้โครงสร้างไดเรกทอรีดังต่อไปนี้

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

จากนั้นคุณสามารถนำเข้าโค้ดตามปกติจาก localpackage โดยใช้คำสั่ง import ต่อไปนี้

# Code in main.py
from localpackage import script

โปรดทราบว่าวิธีนี้จะ ไม่ เรียกใช้ไฟล์ setup.py คุณยังคงรวมแพ็กเกจที่มี ไฟล์เหล่านั้นได้ แต่แพ็กเกจอาจทำงานไม่ถูกต้องใน Cloud Functions