Obsługa zależności

Wybierz język: Node.js Python

Funkcja w Cloud Functions może korzystać z modułów zewnętrznych i zależności lokalnych. Sposób określania zależności i zarządzania nimi zależy od języka środowiska wykonawczego.

Node.js

Funkcja może korzystać z zewnętrznych modułów Node.js oraz danych lokalnych. Zależności w Node.js są zarządzane za pomocą npm i wyrażane w pliku metadanych o nazwie package.json. Środowiska wykonawcze Cloud Functions Node.js obsługują instalację za pomocą npm, yarn, lub pnpm.

Aby określić zależność funkcji, dodaj ją do pliku package.json.

W tym przykładzie zależność jest wymieniona w pliku package.json:

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

Zależność jest następnie importowana w funkcji:

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")}!`);
});

Dołączanie lokalnych modułów Node.js

Możesz też dołączyć lokalne moduły Node.js jako część funkcji. Aby to zrobić, zadeklaruj moduł w package.json za pomocą file: prefiksu. W tym przykładzie mymodule odnosi się do nazwy modułu, a mymoduledir to katalog zawierający moduł:

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

Kod tego modułu lokalnego powinien być przechowywany w innym miejscu niż folder node_modules w katalogu głównym funkcji.

Dodatkowe czynności w przypadku TypeScript

TypeScript jest najbardziej przydatny, gdy używasz bibliotek zawierających informacje o typach. Dzięki temu TypeScript może wykrywać błędy składniowe, a edytory mogą wyświetlać lepsze sugestie autouzupełniania. Niektóre biblioteki, takie jak firebase-admin i firebase-functions, zawierają definicje TypeScript.

Wiele bibliotek nie zawiera własnych definicji TypeScript. Projekt DefinitelyTyped zawiera definicje najpopularniejszych bibliotek Node.js utrzymywane przez społeczność. Projekt DefinitelyTyped publikuje te definicje pod tą samą nazwą pakietu NPM, ale w organizacji „@types”. Na przykład informacje o typach biblioteki uuid możesz zainstalować za pomocą tego polecenia:

npm install @types/uuid

Gdy lepiej poznasz TypeScript, możesz połączyć obie instalacje:

npm install uuid @types/uuid

Zależności typu powinny być tego samego rodzaju co zależność biblioteki. Na przykład nie należy zapisywać uuid jako zwykłej zależności, a @types/uuid jako zależności deweloperskiej lub zależności równorzędnej.

Wczytywanie modułów Node.js

Aby wczytać dowolny zainstalowany moduł Node.js, użyj funkcji Node.js require(). Możesz też użyć funkcji require() do importowania plików lokalnych, które wdrażasz razem z funkcją.

Jeśli piszesz funkcje w TypeScript, użyj import w ten sam sposób, aby wczytać dowolny zainstalowany moduł Node.js.

Używanie modułów prywatnych

Możesz używać prywatnego modułu npm, podając ustawienia uwierzytelniania w rejestrze w pliku .npmrc w katalogu funkcji. Jeśli używasz Yarn w wersji 2 lub nowszej jako menedżera pakietów, ten plik ma nazwę .yarnrc.yml.

Moduły prywatne z Artifact Registry

Repozytorium pakietów Node.js w Artifact Registry może hostować moduły prywatne dla Twojej funkcji. Gdy wdrażasz funkcję Google Cloud Functions function, proces kompilacji automatycznie generuje dane uwierzytelniające Artifact Registry dla konta usługi Cloud Build. Nie musisz generować dodatkowych danych uwierzytelniających – wystarczy, że dodasz repozytorium Artifact Registry do pliku .npmrc. Przykład:

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

To podejście działa też w przypadku menedżera pakietów Yarn w wersji 1. Jeśli używasz Yarn w wersji 2 lub nowszej, wystarczy, że dodasz repozytorium Artifact Registry do pliku .yarnrc.yml bez dodatkowych danych uwierzytelniających. Przykład:

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

Moduły prywatne z innych repozytoriów

W dokumentacji npm znajdziesz informacje o tym, jak utworzyć niestandardowe tokeny dostępu tylko do odczytu. Nie zalecamy używania pliku .npmrc utworzonego w katalogu domowym, ponieważ zawiera on token z uprawnieniami do odczytu i zapisu. Uprawnienia do zapisu nie są wymagane podczas wdrażania i mogą stanowić zagrożenie dla bezpieczeństwa.

Jeśli nie używasz repozytoriów prywatnych, nie dołączaj pliku .npmrc, ponieważ może to wydłużyć czas wdrażania funkcji.

Format pliku

Jeśli używasz pliku .npmrc do ustawienia niestandardowego tokena uwierzytelniającego, powinien on zawierać wiersz pokazany poniżej.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Zastąp:

  • REGISTRY_DOMAIN: nazwa domeny prywatnego rejestru npm. Jeśli repozytorium jest hostowane w npmjs.org, ustaw to pole na registry.npmjs.org.

  • AUTH_TOKEN: token autoryzacji dla rejestru npm. Może to być dosłowna wartość tekstowa tokena lub ciąg tekstowy ${NPM_TOKEN}, który npm zastępuje rzeczywistą wartością tokena ze środowiska.

    Zmienną środowiskową $NPM_TOKEN możesz ustawić za pomocą argumentu --set-build-env-vars w poleceniu gcloud functions deploy. Więcej informacji o tokenie uwierzytelniającym npm znajdziesz w samouczku NPM dotyczącym modułów prywatnych.

Python

Zależności dla Cloud Functions napisanych w Pythonie możesz określić na 2 sposoby: za pomocą pliku pip menedżera pakietów' requirements.txt lub przez spakowanie zależności lokalnych razem z funkcją.

Określanie zależności za pomocą standardu Pipfile/Pipfile.lock nie jest obsługiwane. Projekt nie powinien zawierać tych plików.

Określanie zależności za pomocą pip

Zależności w Pythonie są zarządzane za pomocą pip i wyrażane w pliku metadanych o nazwie requirements.txt. Ten plik musi znajdować się w tym samym katalogu co plik main.py zawierający kod funkcji.

Gdy wdrażasz lub ponownie wdrażasz funkcję, Cloud Functions używa pip do pobierania i instalowania najnowszej wersji zależności zadeklarowanych w pliku requirements.txt. Plik requirements.txt zawiera 1 wiersz na pakiet. Każdy wiersz zawiera nazwę pakietu i opcjonalnie żądaną wersję. Więcej informacji znajdziesz w dokumentacji requirements.txt referencyjnej.

Aby zapobiec wpływowi zmian wersji zależności na kompilację, rozważ przypięcie pakietów zależności do określonej wersji.

Oto przykład pliku requirements.txt:

functions-framework
requests==2.20.0
numpy

Pakowanie zależności lokalnych

Możesz też spakować i wdrożyć zależności razem z funkcją. To podejście jest przydatne, jeśli zależność nie jest dostępna za pomocą menedżera pakietów pip lub jeśli dostęp do internetu w środowisku Cloud Functions jest ograniczony.

Możesz na przykład użyć takiej struktury katalogów:

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

Następnie możesz zaimportować kod jak zwykle z localpackage za pomocą tej instrukcji import.

# Code in main.py
from localpackage import script

Pamiętaj, że to podejście nie spowoduje uruchomienia żadnych plików setup.py. Pakiety z tymi plikami można nadal łączyć, ale mogą one nie działać prawidłowo w Cloud Functions.