Specifica le dipendenze in Python (1ª gen.)

Esistono due modi per specificare le dipendenze per le funzioni Cloud Run scritte in Python: utilizzando il file requirements.txt del gestore di pacchetti pip o includendo le dipendenze locali nel pacchetto della funzione.

La specifica delle dipendenze mediante lo standard Pipfile/Pipfile.lock non è supportata. Il tuo progetto non deve includere questi file.

Specifica le dipendenze con pip

Le dipendenze in Python vengono gestite con pip e sono espresse in un file di metadati denominato requirements.txt. Questo file deve trovarsi nella stessa directory del file main.py che contiene il codice della funzione.

Quando esegui o riesegui il deployment della funzione, Cloud Run Functions utilizza pip per scaricare e installare l'ultima versione delle dipendenze dichiarate nel file requirements.txt. Il file requirements.txt contiene una riga per pacchetto. Ogni riga contiene il nome del pacchetto e, facoltativamente, la versione richiesta. Per maggiori dettagli, consulta il relativo requirements.txtriferimento.

Per evitare che la build sia interessata dalle modifiche alla versione delle dipendenze, ti consigliamo di bloccare i pacchetti di dipendenze su una versione specifica.

Ecco un esempio di file requirements.txt:

functions-framework
requests==2.20.0
numpy

Il framework di Functions è una dipendenza obbligatoria per tutte le funzioni. Sebbene Cloud Run Functions lo installi per tuo conto al momento della creazione della funzione, ti consigliamo di includerlo come dipendenza esplicita per maggiore chiarezza.

Se la tua funzione si basa su dipendenze private, ti consigliamo di eseguire il mirroring di functions-framework nel tuo registro privato. Includi il functions-framework sottoposto a mirroring come dipendenza della tua funzione per evitare di installare il pacchetto dalla rete internet pubblica.

Crea un pacchetto di dipendenze locali

Puoi anche creare pacchetti delle dipendenze ed eseguirne il deployment insieme alla funzione. Questo approccio è utile se la dipendenza non è disponibile tramite il gestore di pacchetti pip o se l'accesso a internet dell'ambiente Cloud Run Functions è limitato.

Nota: puoi comunque utilizzare un file requirements.txt per specificare dipendenze aggiuntive che non hai incluso nel pacchetto insieme alla funzione.

Ad esempio, puoi utilizzare una struttura di directory come la seguente:

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

Puoi quindi importare il codice come di consueto da localpackage utilizzando l'istruzione import.

# Code in main.py
from localpackage import script

Tieni presente che con questo approccio non viene eseguito alcun file setup.py. I pacchetti con questi file possono comunque essere raggruppati in bundle, ma potrebbero non essere eseguiti correttamente in Cloud Run Functions.

Dipendenze di vendoring

Le dipendenze di vendoring sono dipendenze la cui origine è inclusa direttamente nel pacchetto di codice sorgente e ricompilata insieme al tuo codice. Utilizza la variabile di ambiente di build GOOGLE_VENDOR_PIP_DEPENDENCIES per creare dipendenze pip di vendoring ed evitare di installarle durante il deployment.

Crea dipendenze di vendoring

1. Assicurati che python3 sia installato nel tuo sistema di sviluppo.

2. Dichiara le dipendenze dell'applicazione in un file requirements.txt nella directory root dell'albero di sviluppo.

3. Dichiara il framework di Functions come requisito includendo functions-framework in una riga separata nel file requirements.txt.

4. Scarica le dipendenze della funzione nella directory locale. La procedura da eseguire varia a seconda che la dipendenza sia un file wheel Python (*.whl) o un file tar (*.tar.gz).

   1. Se la dipendenza è un file wheel Python (*.whl), scaricalo nella directory root dell'albero di sviluppo con questo comando pip:

      python3 -m pip download -r requirements.txt --only-binary=:all: \
         -d DIRECTORY \
         --python-version PYTHON_RUNTIME_VERSION \
         --platform manylinux2014_x86_64 \
         --implementation cp
      

      Sostituisci:

      • DIRECTORY: il nome della directory locale in cui eseguire il download.
      • PYTHON_RUNTIME_VERSION: la versione di Python da utilizzare per i controlli di compatibilità. Ad esempio, 311 per Python 3.11.
        Questa versione deve corrispondere a uno dei runtime Python supportati

      La struttura di directory risultante dovrebbe essere simile alla seguente:

      myfunction/
      ├── main.py
      └── requirements.txt
      └── DIRECTORY
         ├── dependency1.whl
         └── dependency2.whl
      

   2. Se la dipendenza è un file tar (*.tar.gz):

      1. Se la dipendenza è scritta in Python, utilizza pip per scaricarla:

         python3 -m pip download -r requirements.txt \
            -d DIRECTORY
         

      2. Se una dipendenza è costituita da codice scritto in C o C++, devi scaricarla e compilarla separatamente.

5. Esegui il deployment della funzione e delle relative dipendenze di vendoring:

   gcloud functions deploy FUNCTION_NAME \
     --runtime PYTHON_RUNTIME_NAME \
     --set-build-env-vars GOOGLE_VENDOR_PIP_DEPENDENCIES=DIRECTORY
   

   Sostituisci:

   • FUNCTION_NAME: il nome della funzione Cloud Run Functions di cui stai eseguendo il deployment
   • PYTHON_RUNTIME_NAME: il nome di uno dei runtime Python supportati in cui eseguire la funzione di cui è stato eseguito il deployment, ad esempio python311. Deve essere la stessa versione del runtime Python che hai utilizzato nel tuo ambiente di sviluppo locale.
   • DIRECTORY:il nome della directory contenente le dipendenze di vendoring

Per saperne di più sull'utilizzo dei buildpack, consulta Crea una funzione con i buildpack.

Utilizza dipendenze private

Dipendenze private di Artifact Registry

Un repository Python di Artifact Registry può ospitare le dipendenze private della tua funzione Python. Quando esegui il deployment in Cloud Run Functions, il processo di compilazione genera automaticamente le credenziali di Artifact Registry per il service account Cloud Build. Devi solo includere l'URL di Artifact Registry nel tuo file requirements.txt senza generare credenziali aggiuntive. Ad esempio:

--index-url REPOSITORY_URL
sampleapp
Flask==0.10.1
google-cloud-storage

Se la tua build richiede più repository, utilizza un repository virtuale Artifact Registry per controllare in modo sicuro l'ordine in cui pip esegue la ricerca nei repository.

Dipendenze private di altri repository

Le dipendenze vengono installate in un ambiente Cloud Build che non fornisce l'accesso alle chiavi SSH. I pacchetti ospitati in repository che richiedono l'autenticazione basata su SSH devono essere sottoposti a vendoring e caricati insieme al codice del progetto, come descritto nella sezione precedente.

Puoi utilizzare il comando pip install con il flag -t DIRECTORY per copiare le dipendenze private in una directory locale prima di eseguire il deployment dell'app, come segue:

1. Copia la dipendenza in una directory locale:

   pip install -t DIRECTORY DEPENDENCY

2. Aggiungi un file __init__.py vuoto nella directory DIRECTORY per trasformarlo in un modulo.

3. Esegui l'importazione da questo modulo per utilizzare la dipendenza:

   import DIRECTORY.DEPENDENCY

Pacchetti preinstallati

I seguenti pacchetti Python vengono installati automaticamente insieme alla tua funzione durante il deployment. Se utilizzi uno di questi pacchetti nel codice della funzione, ti consigliamo di includere le seguenti versioni nel file requirements.txt:

Python 3.7

aiohttp==3.8.1
aiosignal==1.2.0
async-timeout==4.0.2
attrs==21.4.0
cachetools==4.2.4
certifi==2021.10.8
chardet==4.0.0
charset-normalizer==2.0.10
click==8.0.3
Flask==2.0.2
frozenlist==1.2.0
google-api-core==2.3.2
google-api-python-client==2.34.0
google-auth==2.3.3
google-auth-httplib2==0.1.0
google-cloud-core==2.2.1
google-cloud-trace==1.5.1
googleapis-common-protos==1.54.0
grpcio==1.43.0
grpcio-status==1.43.0
httplib2==0.20.2
idna==3.3
itsdangerous==2.0.1
Jinja2==3.1.6
MarkupSafe==2.0.1
multidict==5.2.0
opencensus==0.8.0
opencensus-context==0.1.2
packaging==21.3
proto-plus==1.19.8
protobuf==3.19.1
pyasn1==0.4.8
pyasn1-modules==0.2.8
pyparsing==3.0.6
pytz==2021.3
PyYAML==6.0
requests==2.27.1
rsa==4.8
setuptools==60.3.1
six==1.16.0
uritemplate==4.1.1
urllib3==1.26.7
Werkzeug==2.0.2
wrapt==1.13.3
yarl==1.7.2

Python 3.8 e versioni successive

anyio==4.5.2
blinker==1.8.2
click==8.1.8
cloudevents==1.11.0
deprecation==2.1.0
exceptiongroup==1.3.0
Flask==3.0.3
functions-framework==3.9.1
gunicorn==23.0.0
h11==0.16.0
idna==3.10
importlib_metadata==8.5.0
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==2.1.5
packaging==25.0
sniffio==1.3.1
# Install starlette 0.44.0 for Python 3.8
starlette==0.44.0; python_version == '3.8'
# Install starlette 0.49.1 for Python versions greater than 3.8
starlette==0.49.1; python_version > '3.8'
typing_extensions==4.13.2
uvicorn==0.33.0
uvicorn-worker==0.2.0
watchdog==4.0.2
Werkzeug==3.0.6
zipp==3.20.2

Nota: indipendentemente dal contenuto del file requirements.txt, i seguenti pacchetti vengono sempre bloccati su una versione specifica:

* `pip` (latest version)
* `setuptools` (latest version)
* `wheel` (determined by product requirements)

Inoltre, il runtime Python include una serie di pacchetti di sistema nell'ambiente di esecuzione. Se la tua funzione utilizza una dipendenza che richiede un pacchetto di sistema non elencato, puoi richiedere un pacchetto.