Scrivere funzioni

Questa pagina fornisce un'introduzione alla scrittura di funzioni con il framework Functions.

Quando scrivi il codice sorgente delle funzioni per Cloud Run, devi utilizzare il Functions Framework, una libreria open source per la scrittura di funzioni Cloud Run. Con il framework Functions, puoi scrivere funzioni leggere che vengono eseguite in Cloud Run e in altri ambienti, tra cui la tua macchina di sviluppo locale e gli ambienti basati su Knative.

Il framework Functions ti consente di:

  • Richiama una funzione in risposta a una richiesta.
  • Esegui automaticamente il unmarshalling degli eventi conformi alla specifica CloudEvents, una specifica standard di settore per descrivere i dati sugli eventi in un modo comune.
  • Avvia un server di sviluppo locale per test rapidi.

Scrivere funzioni con il framework Functions

Il framework Functions fornisce un'interfaccia per la creazione di servizi modulari. Per usare il framework Functions nel codice sorgente, specifica quanto segue:

Entry point della funzione

Il codice sorgente deve definire un punto di contatto per la funzione, ovvero il codice specifico che viene eseguito quando viene invocata la funzione Cloud Run. Specifichi questo punto di ingresso quando esegui il deployment della funzione.

La definizione del punto di contatto dipende dal runtime del linguaggio che utilizzi. Per alcuni linguaggi, l'entry point è una funzione, mentre per altri è una classe.

Tipo di firma

Quando scrivi il codice sorgente di una funzione con il framework Functions, devi specificare uno dei due tipi di firma:

  • Funzioni HTTP: una funzione che registra una funzione di gestore HTTP. Per ulteriori informazioni, consulta Scrivere funzioni HTTP.
  • Funzioni CloudEvents (chiamate anche funzioni basate su eventi): una funzione che registra una funzione di gestore CloudEvents. Per ulteriori informazioni, consulta Scrivere funzioni CloudEvents.

Utilizza una funzione HTTP quando devi che la funzione abbia un endpoint URL e risponda alle richieste HTTP, ad esempio per gli webhook. Utilizza una funzione CloudEvents quando la funzione deve essere attivata direttamente in risposta a eventi all'interno del tuo progettoGoogle Cloud , ad esempio messaggi in un argomento Pub/Sub o modifiche in un bucket Cloud Storage.

Struttura della directory di origine

Il framework Functions è supportato in diversi linguaggi di programmazione. Il runtime del linguaggio scelto e il tipo di funzione che vuoi scrivere determinano la struttura del codice e l'implementazione della funzione.

Affinché Cloud Run possa trovare la definizione della funzione, ogni runtime del linguaggio ha requisiti per la strutturazione del codice sorgente.

Node.js

La struttura di directory di base per le funzioni Node.js è la seguente:

.
├── index.js
└── package.json

Per impostazione predefinita, Cloud Run tenta di caricare il codice sorgente da un file chiamato index.js nella directory principale della funzione. Per specificare un file di origine principale diverso, utilizza il campo main nel file package.json.

Il file package.json deve includere anche il Functions Framework per Node.js come dipendenza:

{
  "main": "index.js",
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}

Il codice nel file principale deve definire il punto di ingresso della funzione e può importare altro codice e moduli Node.js. Il file principale può anche definire più entry point di funzione che possono essere implementati separatamente.

Per ulteriori dettagli, consulta la panoramica del runtime Node.js e il Functions Framework per Node.js.

Python

La struttura di directory di base per le funzioni Python è la seguente:

.
├── main.py
└── requirements.txt

Cloud Run carica il codice sorgente da un file denominato main.py nella directory principale della funzione. Devi assegnare il nome main.py al file principale.

Il file requirements.txt deve includere il Functions Framework per Python come dipendenza:

functions-framework==3.*

Il codice nel file main.py deve definire il punto di ingresso della funzione e può importare altro codice e dipendenze esterne come di consueto. Il file main.py può anche definire più punti di accesso alle funzioni che possono essere implementati separatamente.

Per ulteriori dettagli, consulta la panoramica del runtime Python e il Functions Framework per Python.

Vai

La struttura di directory di base per le funzioni Go è la seguente:

.
├── myfunction.go
└── go.mod

La funzione deve trovarsi in un pacchetto Go nella directory principale del progetto. Il pacchetto e i relativi file di origine possono avere qualsiasi nome, tranne che la funzione non può essere in package main. Se hai bisogno di un pacchetto main, ad esempio per i test locali, puoi crearne uno in una sottodirectory:

.
├── myfunction.go
├── go.mod
└── cmd/
  └── main.go

Il file go.mod deve includere il Functions Framework per Go come dipendenza:

module example.com/my-module

require (
  github.com/GoogleCloudPlatform/functions-framework-go v1.5.2
)

Il codice nel pacchetto principale deve definire il punto di contatto della funzione e può importare altro codice dai sottopacchetti e dalle dipendenze come di consueto. Il pacchetto può anche definire più punti di accesso alle funzioni che possono essere di cui è possibile eseguire il deployment separatamente.

Per maggiori dettagli, consulta la panoramica del runtime Go e il Functions Framework per Go.

Java

La struttura di directory di base per le funzioni Java è la seguente:

.
├── pom.xml
└── src/
  └── main/
      └── java/
          └── MyFunction.java

I file di origine Java devono trovarsi nella directory src/main/java/ e possono avere qualsiasi nome. Se i file di origine dichiarano un pacchetto, aggiungi un'altra directory in src/main/java con il nome del pacchetto:

.
├── pom.xml
└── src/
  └── main/
      └── java/
          └── mypackage/
              └── MyFunction.java

Ti consigliamo di inserire i test associati in una sottodirectory src/test/java/.

Il file pom.xml deve includere il Functions Framework per Java come dipendenza:

...
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.0.4</version>
    </dependency>
...

Il codice nei file sorgente deve definire il punto di ingresso della funzione e può importare altro codice e dipendenze esterne come di consueto. I file di origine possono anche definire più punti di accesso alle funzioni che possono essere implementati separatamente.

Per maggiori dettagli, consulta la panoramica del runtime Java e il Functions Framework per Java.

.NET

La struttura di directory di base per le funzioni .NET è la seguente:

.
├── MyFunction.cs
└── MyProject.csproj

Puoi strutturare i tuoi progetti come faresti con qualsiasi altro codice sorgente .NET. I file di origine possono avere qualsiasi nome.

Il file del progetto deve includere il Functions Framework per .NET come dipendenza:

...
    <PackageReference Include="Google.Cloud.Functions.Hosting" Version="1.0.0" />
...

Il codice nei file sorgente deve definire il punto di ingresso della funzione e può importare altro codice e dipendenze esterne come di consueto. I file di origine possono anche definire più punti di accesso alle funzioni che possono essere implementati separatamente.

Per ulteriori dettagli, consulta la panoramica del runtime.NET e il Functions Framework per .NET.

Ruby

La struttura di directory di base per le funzioni Ruby è la seguente:

.
├── app.rb
├── Gemfile
└── Gemfile.lock

Cloud Run carica il codice sorgente da un file denominato app.rb nella directory principale della funzione. Il file principale deve avere il nome app.rb.

Il file Gemfile deve includere il Functions Framework per Ruby come dipendenza:

source "https://rubygems.org"
gem "functions_framework", "~> 1.0"

Il codice nel file app.rb deve definire il punto di ingresso della funzione e può importare altro codice e dipendenze esterne come di consueto. Il file app.rb può anche definire più punti di accesso alle funzioni che possono essere implementati separatamente.

Per ulteriori dettagli, consulta la panoramica del runtime Ruby e il Functions Framework per Ruby.

PHP

La struttura di directory di base per le funzioni PHP è la seguente:

.
├── index.php
└── composer.json

Cloud Run carica il codice sorgente da un file denominato index.php nella directory principale della funzione. Devi assegnare il nome index.php al file principale.

Il file composer.json deve includere il Framework di Functions per PHP come dipendenza:

{
  "require": {
    "google/cloud-functions-framework": "^1.1"
  }
}

Il codice nel file index.php deve definire il punto di ingresso della funzione e può importare altro codice e dipendenze esterne come di consueto. Il file index.php può anche definire più punti di accesso alle funzioni che possono essere implementati separatamente.

Per ulteriori dettagli, consulta la panoramica del runtime PHP e il Functions Framework per PHP.

Se raggruppi più funzioni in un unico progetto, tieni presente che ogni funzione potrebbe finire per condividere lo stesso insieme di dipendenze. Tuttavia, alcune funzioni potrebbero non richiedere tutte le dipendenze.

Se possibile, ti consigliamo di suddividere le basi di codice multifunzione di grandi dimensioni e di inserire ogni funzione nella propria directory di primo livello, come mostrato negli esempi precedenti, con i relativi file di configurazione di progetto e di origine. Questo approccio minimizza il numero di dipendenze richieste per una determinata funzione, il che a sua volta riduce la quantità di memoria necessaria per la funzione.

Passaggi successivi