Sviluppo di funzioni locali

Cloud Run Functions supporta diversi metodi per eseguire le funzioni al di fuori dell'ambiente di deployment di destinazione. Questo è particolarmente utile per lo sviluppo iterativo e per le situazioni in cui vuoi testare la funzione prima del deployment.

La possibilità di eseguire le funzioni senza eseguirne il deployment può semplificare i test locali, la conformità alle limitazioni relative alla localizzazione dei dati e i deployment multi-cloud:

• Limitazioni alla localizzazione dei dati: testa la funzione localmente senza accedere ai dati di produzione per evitare di violare le regole di localizzazione dei dati della tua organizzazione.

• Deployment multi-cloud: i deployment di funzioni multi-cloud rappresentano un metodo collaudato per ridurre il rischio di tempo di inattività in ambienti in cui l'affidabilità è critica. Il deployment di funzioni in ambienti diversi da Cloud Run Functions riduce il rischio di tempo di inattività non pianificato per la tua applicazione.

Sviluppare funzioni localmente utilizzando il framework di Functions

Puoi sviluppare e testare le funzioni localmente utilizzando il framework di Functions. Lo sviluppo di una funzione in locale può aiutarti a testare il codice senza dover ricompilare il container della funzione. In questo modo puoi risparmiare tempo e semplificare il test della tua funzione.

Cloud Run utilizza le librerie open source del framework di Functions per aggregare le funzioni di cui è stato eseguito il deployment in un'applicazione HTTP persistente.

Il framework di Functions può essere eseguito anche su qualsiasi altra piattaforma che supporti il linguaggio stesso, inclusi il computer locale, i server on-premise e Compute Engine.

Installa le dipendenze

Nella directory della funzione, installa la libreria del framework di Functions per il tuo linguaggio:

Node.js

Nota: questa libreria viene inclusa automaticamente durante il deployment della funzione se non la specifichi nelle dipendenze della funzione.

npm install --save-dev @google-cloud/functions-framework

Python

Nota: questa libreria viene inclusa automaticamente durante il deployment della funzione se non la specifichi nelle dipendenze della funzione.

pip3 install functions-framework

Go

Nota: questa libreria viene inclusa automaticamente durante il deployment della funzione se non la specifichi nelle dipendenze della funzione.

go install github.com/GoogleCloudPlatform/functions-framework-go/funcframework

Java

Nota: questa libreria viene inclusa automaticamente durante il deployment della funzione se non la specifichi nelle dipendenze della funzione.

Maven

Se utilizzi Maven, aggiungi quanto segue al file pom.xml:

<dependency>
  <groupId>com.google.cloud.functions</groupId>
  <artifactId>functions-framework-api</artifactId>
  <version>1.1.0</version>
  <scope>provided</scope>
</dependency>

Gradle

Se utilizzi Gradle, aggiungi quanto segue al tuo file build.gradle:

dependencies {
  // Every function needs this dependency to get the Functions Framework API.
  compileOnly 'com.google.cloud.functions:functions-framework-api:1.1.0'

  // To run function locally using Functions Framework's local invoker
  invoker 'com.google.cloud.functions.invoker:java-function-invoker:1.3.1'
}

Per saperne di più, consulta Libreria del framework di Functions per Java.

C#

I comandi riportati di seguito utilizzano i template .NET per creare un nuovo codebase della funzione .NET con la libreria del framework di Functions per.NET come dipendenza:

# HTTP functions
dotnet new gcf-http

# CloudEvent functions
dotnet new gcf-event

Ruby

In Ruby, il framework di Functions deve essere aggiunto alle dipendenze della funzione per poter eseguire il deployment in Cloud Run:

bundle add functions_framework

PHP

Nota: questa libreria viene inclusa automaticamente durante il deployment della funzione se non la specifichi nelle dipendenze della funzione.

composer require google/cloud-functions-framework

Configura il framework di Functions

Prima di eseguire una funzione utilizzando il framework di Functions, devi specificare sia il tipo che il nome della funzione che vuoi eseguire. Puoi specificare questi attributi come flag dell'interfaccia a riga di comando (CLI) o come variabili di ambiente.

Tipi di funzioni supportati

Functions Framework supporta entrambi i tipi di funzioni supportati da Cloud Run Functions. Tutti i runtime dei linguaggi supportano i tipi di firma http e cloudevent.

Tipo di funzione	Tipo di firma	Descrizione	Runtime supportati
Funzioni attivate da HTTP	http	Funzioni che ricevono e rispondono a richieste HTTP.	Tutti i runtime
Funzioni basate su eventi	cloudevent	Formato evento standard del settore.	Tutti i runtime

Specifica la funzione da eseguire

Prima di eseguire una funzione con il framework di Functions, devi specificare quale funzione all'interno del codice deve essere eseguita. Per la maggior parte dei linguaggi, puoi farlo specificando il nome del metodo della funzione di destinazione come mostrato nelle tabelle riportate di seguito. Tieni presente che esistono eccezioni a questa regola per i runtime Java e .NET.

Istruzioni per linguaggio

Consulta la tabella seguente per un elenco delle opzioni di configurazione supportate da ciascun linguaggio.

Node.js

Argomento dell'interfaccia a riga di comando	Variabile di ambiente	Descrizione
--port	PORT	La porta su cui rimanere in ascolto delle richieste. (Valore predefinito: 8080)
--target	FUNCTION_TARGET	Il nome della funzione con export da richiamare. (Valore predefinito: function)
--signature-type	FUNCTION_SIGNATURE_TYPE	Il tipo di firma utilizzato dalla funzione. Può essere http (valore predefinito) o cloudevent.

Python

Argomento dell'interfaccia a riga di comando	Variabile di ambiente	Descrizione
--port	PORT	La porta su cui rimanere in ascolto delle richieste. (Valore predefinito: 8080)
--target	FUNCTION_TARGET	Il nome della funzione con export da richiamare. (Valore predefinito: function)
--signature-type	FUNCTION_SIGNATURE_TYPE	Il tipo di firma utilizzato dalla funzione. Può essere http (valore predefinito) o cloudevent.

Go

Variabile di ambiente	Descrizione
PORT	La porta su cui rimanere in ascolto delle richieste. (Valore predefinito: 8080)

Nota: il framework di Functions per Go rileva automaticamente il tipo di firma della funzione.

Java

Nome argomento	Variabile di ambiente	Descrizione
run.port	PORT	La porta su cui rimanere in ascolto delle richieste. (Valore predefinito: 8080)
run.functionTarget	FUNCTION_TARGET	Il nome della funzione con export da richiamare. (Valore predefinito: function)

Nota: il framework di Functions per Java rileva automaticamente il tipo di firma della funzione.

C#

Argomento dell'interfaccia a riga di comando	Variabile di ambiente	Descrizione
--port	PORT	La porta su cui rimanere in ascolto delle richieste. (Valore predefinito: 8080)
--target (o unico argomento)	FUNCTION_TARGET	Il classname della funzione da richiamare. (Valore predefinito: function)

Nota: il framework di Functions per .NET rileva automaticamente il tipo di firma della funzione.

Ruby

Argomento dell'interfaccia a riga di comando	Variabile di ambiente	Descrizione
--port	PORT	La porta su cui rimanere in ascolto delle richieste. (Valore predefinito: 8080)
--target	FUNCTION_TARGET	Il nome della funzione con export da richiamare. (Valore predefinito: function)

PHP

Variabile di ambiente	Descrizione
FUNCTION_TARGET	Il nome della funzione da richiamare. (Valore predefinito: function)
FUNCTION_SIGNATURE_TYPE	Il tipo di firma utilizzato dalla funzione. Può essere http (valore predefinito) o cloudevent.

Segui queste istruzioni per configurare ed eseguire il framework di Functions:

Node.js

Il framework di Functions per Node.js ti consente di specificare il nome e il tipo di firma della funzione come argomenti della riga di comando o variabili di ambiente.

Nota: gli argomenti della riga di comando hanno la precedenza sulle variabili di ambiente quando viene eseguito il framework di Functions per Node.js.

Puoi anche specificare questi valori nel file di build package.json aggiungendo uno script start con gli argomenti dell'interfaccia a riga di comando richiesti, come mostrato nell'esempio seguente.

"scripts": {
"start": "npx functions-framework --target=YOUR_FUNCTION_NAME [--signature-type=YOUR_SIGNATURE_TYPE]"
}

Lo stesso risultato si può ottenere con le variabili di ambiente:

"scripts": {
"start": "FUNCTION_TARGET=YOUR_FUNCTION_NAME FUNCTION_SIGNATURE_TYPE=YOUR_SIGNATURE_TYPE npx functions-framework"
}

Sostituisci YOUR_FUNCTION_NAME con il nome del metodo della funzione e YOUR_SIGNATURE_TYPE (se applicabile) con il tipo di firma della funzione, come mostrato in Tipi di funzioni supportati.

Python

Il framework di Functions per Python ti consente di specificare il nome e il tipo di firma della funzione come argomenti della riga di comando o variabili di ambiente. Gli argomenti della riga di comando devono essere specificati quando esegui il framework.

Nota: gli argomenti della riga di comando hanno la precedenza sulle variabili di ambiente quando viene eseguito il framework di Functions per Python.

Go

Il framework di Functions per Go utilizza funcframework.RegisterHTTPFunctionContext per specificare tipo di firma e destinazione della funzione.

Java

Il framework di Functions per Java accetta i dati di configurazione da tre diverse origini, nel seguente ordine di priorità (dalla più specifica alla meno specifica):

• Argomenti della riga di comando
• File di build
• Variabili di ambiente

Argomenti della riga di comando

Maven

Puoi specificare la funzione che vuoi eseguire aggiungendo il seguente flag dell'interfaccia a riga di comando (CLI) ai comandi mvn:

-Drun.functionTarget=YOUR_FUNCTION_NAME

Puoi anche specificare la porta di destinazione aggiungendo il seguente flag dell'interfaccia a riga di comando in modo simile:

-Drun.port=12345

Gradle

I flag dell'interfaccia a riga di comando di Gradle sono quasi identici a quelli di Maven. L'unica modifica apportata da Gradle è la sostituzione di -D iniziale in ogni flag con -P, come mostrato nell'esempio seguente:

# Maven version

-Drun.functionTarget=...

# Gradle version

-Prun.functionTarget=...

File di build

Puoi anche specificare la funzione che vuoi eseguire nel file di build del progetto. Sebbene Maven e Gradle abbiano flag dell'interfaccia a riga di comando simili, le clausole dei file di build differiscono in modo significativo.

Maven

I file di build di Maven sono denominati pom.xml. Aggiungi la seguente clausola a questo file per specificare una funzione di destinazione:

<plugin>
  <groupId>com.google.cloud.functions</groupId>
  <artifactId>function-maven-plugin</artifactId>
  <version>0.11.0</version>
  <configuration>
    <functionTarget>functions.HelloWorld</functionTarget>
  </configuration>
</plugin>

Sostituisci <functionTarget> con il nome classe della tua funzione. Ad esempio, una funzione nel pacchetto functions con nome classe HelloCloudFunctions avrà un nome classe functions.HelloCloudFunctions. Questo è relativo al file di build principale, pom.xml o build.gradle.

Gradle

I file di build di Gradle sono denominati build.gradle. Aggiungi la seguente clausola a questo file per specificare una funzione di destinazione:

// Register a "runFunction" task to run the function locally
tasks.register("runFunction", JavaExec) {
  main = 'com.google.cloud.functions.invoker.runner.Invoker'
  classpath(configurations.invoker)
  inputs.files(configurations.runtimeClasspath, sourceSets.main.output)
  args(
    '--target', project.findProperty('run.functionTarget') ?: '',
    '--port', project.findProperty('run.port') ?: 8080
  )
  doFirst {
    args('--classpath', files(configurations.runtimeClasspath, sourceSets.main.output).asPath)
  }
}

C#

Se crei il progetto utilizzando dotnet new e uno dei modelli specificati in precedenza, il framework di Functions per .NET rileverà automaticamente la funzione.

Se il progetto contiene più funzioni, consulta la sezione Esecuzione del framework per informazioni su come eseguire una funzione specifica.

Ruby

Il framework di Functions per Ruby ti consente di specificare il nome e il tipo di firma della funzione come argomenti della riga di comando o variabili di ambiente. Gli argomenti della riga di comando devono essere specificati quando esegui il framework.

Nota: gli argomenti della riga di comando hanno la precedenza sulle variabili di ambiente quando viene eseguito il framework di Functions per Ruby.

PHP

Il framework di Functions per PHP ti consente di specificare variabili di ambiente come argomenti della riga di comando.

Puoi anche specificare questi valori nel file di build composer.json aggiungendo uno script start, come mostrato nell'esempio seguente.

"scripts": {
 "start": [
     "Composer\\Config::disableProcessTimeout",
     "FUNCTION_TARGET=YOUR_FUNCTION_NAME php -S localhost:${PORT:-8080} vendor/bin/router.php"
].
}

Sostituisci YOUR_FUNCTION_NAME con il nome della funzione e YOUR_SIGNATURE_TYPE (se applicabile; non è incluso nell'esempio mostrato qui).

Esegui la funzione

Utilizza questo comando per eseguire la funzione con il framework di Functions. Per impostazione predefinita, la funzione sarà accessibile su localhost:8080, a meno che tu non specifichi esplicitamente un valore PORT.

Node.js

npm start

Python

Tramite argomenti della riga di comando:

functions-framework --target=YOUR_FUNCTION_NAME

Tramite variabili di ambiente:

FUNCTION_TARGET=YOUR_FUNCTION_NAME functions-framework

Sostituisci YOUR_FUNCTION_NAME con il nome del metodo della funzione.

Go

Per prima cosa, crea un file cmd/main.go come descritto nel sito del framework di Functions per Go.

cd cmd
go build
./cmd

Tramite variabili di ambiente:

cd cmd
go build
PORT=8080 ./cmd

Java

Maven

Utilizza questo comando per eseguire una funzione specificata in pom.xml:

mvn function:run

Utilizza questo comando per eseguire una funzione specificata in un argomento della riga di comando:

mvn function:run -Drun.functionTarget=YOUR_FUNCTION_NAME

Utilizza questo comando per eseguire una funzione specificata come variabile di ambiente:

FUNCTION_TARGET=YOUR_FUNCTION_NAME mvn function:run

Sostituisci YOUR_FUNCTION_NAME con il nome della classe della funzione.

Gradle

Utilizza questo comando per eseguire una funzione specificata in build.gradle:

./gradlew runFunction

Utilizza questo comando per eseguire una funzione specificata in un argomento della riga di comando:

./gradlew runFunction -Prun.functionTarget=YOUR_FUNCTION_NAME

Utilizza questo comando per eseguire una funzione specificata come variabile di ambiente:

FUNCTION_TARGET=YOUR_FUNCTION_NAME ./gradlew runFunction

Sostituisci YOUR_FUNCTION_NAME con il nome della classe della funzione.

C#

Utilizza questo comando per eseguire la funzione quando è presente esattamente una funzione nel progetto .NET attuale. Tieni presente che questa è la struttura predefinita per i progetti creati dai modelli.

dotnet run

Nota: il runtime .NET rileva le funzioni cercando le classi che implementano una delle interfacce del framework di Functions (IHttpFunction o ICloudEventFunction).

Se il progetto .NET contiene più funzioni, utilizza questo comando per eseguire una funzione specifica. Sostituisci YOUR_FUNCTION_CLASSNAME con il nome classe della tua funzione, incluso lo spazio dei nomi.

dotnet run YOUR_FUNCTION_CLASSNAME

Se vuoi eseguire più funzioni contemporaneamente, devi eseguire più istanze del framework di Functions. Per evitare conflitti tra le istanze del framework in esecuzione, ogni istanza deve utilizzare un valore PORT diverso. Il comando seguente mostra come eseguire una funzione con un valore PORT di 8080.

Tramite argomenti della riga di comando:

dotnet run --target YOUR_FUNCTION_CLASSNAME --port 8080

Tramite variabili di ambiente:

FUNCTION_TARGET=YOUR_FUNCTION_CLASSNAME PORT=8080 dotnet run

Ruby

Tramite argomenti della riga di comando:

bundle exec functions-framework-ruby --target YOUR_FUNCTION_NAME

Tramite variabili di ambiente:

FUNCTION_TARGET=YOUR_FUNCTION_NAME bundle exec functions-framework-ruby

Sostituisci YOUR_FUNCTION_NAME con il nome del metodo della funzione.

PHP

export FUNCTION_TARGET=YOUR_FUNCTION_NAME
php -S localhost:8080 vendor/bin/router.php

Sostituisci YOUR_FUNCTION_NAME con il nome della funzione.

Chiama la funzione in esecuzione in locale

Gli esercizi di questa sezione presuppongono che tu abbia configurato una funzione eseguita localmente su localhost utilizzando il framework di Functions.

Nota: curl è incluso per impostazione predefinita in alcuni sistemi operativi, ma non in tutti (non è incluso in Windows). Consulta le istruzioni su come installare curl sul tuo computer. In alternativa, puoi utilizzare anche altri strumenti di test HTTP come Postman per testare le tue funzioni.

Puoi attivare le funzioni eseguite localmente inviando loro richieste HTTP instradate tramite un processo di gestione locale.

Funzioni HTTP

Quando testi la funzione HTTP dall'ambiente di sviluppo, in genere rimane in ascolto delle richieste su localhost:8080. Questa interfaccia è accessibile solo dalla macchina o dalla VM su cui è in esecuzione la funzione; le richieste inviate da qualsiasi altro sistema non possono raggiungerla. Per questo motivo, devi inviare la richiesta HTTP dallo stesso sistema su cui viene eseguita la funzione. Negli esempi seguenti, se la tua funzione è in ascolto su una porta diversa da 8080, sostituisci 8080 nell'esempio con il numero di porta della tua funzione.

Test delle funzioni HTTP con Cloud Shell

Se utilizzi Cloud Shell per creare e testare la funzione, avviala localmente nella finestra del terminale Cloud Shell, quindi invia la richiesta di trigger HTTP da un browser o da un'istanza curl come segue:

Browser

Fai clic sull'icona sulla barra degli strumenti di Cloud Shell e scegli porta 8080 o Cambia porta per selezionare una porta diversa. Si apre una finestra del browser sul sistema corretto e viene inviata una richiesta GET alla porta indicata.

Curl

Per controllare il formato della richiesta HTTP o per visualizzare la risposta non formattata, utilizza curl:

1. Fai clic sull'icona + nella barra dei menu di Cloud Shell per aprire una nuova finestra del terminale nello stesso sistema in cui viene eseguita la funzione.

2. All'interno di questa finestra, esegui il comando curl per attivare la funzione. Ad esempio:

   curl localhost:8080
   

Test delle funzioni HTTP sul computer server locale

Se stai creando ed eseguendo la funzione sul tuo computer locale, prima avvia la funzione localmente, poi invia la richiesta di attivazione HTTP da un browser o da un'istanza curl come segue:

Browser

Apri una nuova finestra o scheda del browser e digita http://localhost:8080 nella barra degli indirizzi del browser. Si apre una finestra del browser su localhost:8080 sul computer server locale per attivare la funzione.

Curl

Apri una nuova finestra del terminale sul computer locale, quindi esegui il comando curl in quella finestra per attivare la funzione. Ad esempio:

 curl localhost:8080

Esegue il comando curl specificato per attivare la funzione e visualizza la risposta non formattata.

Funzioni basate su eventi

Puoi inviare eventi di esempio alle funzioni basate su eventi utilizzando curl. Le seguenti richieste curl mostrano come inviare eventi di esempio Pub/Sub e Cloud Storage a una funzione basata su eventi in esecuzione su localhost:8080.

Pub/Sub

curl localhost:8080 \
  -X POST \
  -H "Content-Type: application/json" \
  -H "ce-id: 123451234512345" \
  -H "ce-specversion: 1.0" \
  -H "ce-time: 2020-01-02T12:34:56.789Z" \
  -H "ce-type: google.cloud.pubsub.topic.v1.messagePublished" \
  -H "ce-source: //pubsub.googleapis.com/projects/MY-PROJECT/topics/MY-TOPIC" \
  -d '{
        "message": {
          "data": "d29ybGQ=",
          "attributes": {
             "attr1":"attr1-value"
          }
        },
        "subscription": "projects/MY-PROJECT/subscriptions/MY-SUB"
      }'
    

Nota: i valori data degli eventi Pub/Sub hanno valori data con codifica base64. Le funzioni che devono accedere al valore data del messaggio Pub/Sub originale devono eseguire questa decodifica. In questo esempio, la codifica base64 della parola world restituisce d29ybGQ=.

Cloud Storage

curl localhost:8080 \
  -X POST \
  -H "Content-Type: application/json" \
  -H "ce-id: 123451234512345" \
  -H "ce-specversion: 1.0" \
  -H "ce-time: 2020-01-02T12:34:56.789Z" \
  -H "ce-type: google.cloud.storage.object.v1.finalized" \
  -H "ce-source: //storage.googleapis.com/projects/_/buckets/MY-BUCKET-NAME" \
  -H "ce-subject: objects/MY_FILE.txt" \
  -d '{
        "bucket": "MY_BUCKET",
        "contentType": "text/plain",
        "kind": "storage#object",
        "md5Hash": "...",
        "metageneration": "1",
        "name": "MY_FILE.txt",
        "size": "352",
        "storageClass": "MULTI_REGIONAL",
        "timeCreated": "2020-04-23T07:38:57.230Z",
        "timeStorageClassUpdated": "2020-04-23T07:38:57.230Z",
        "updated": "2020-04-23T07:38:57.230Z"
      }'
    

Nota: la sezione inferiore dell'esempio precedente contiene gli attributi di uso comune di un evento Oggetto Cloud Storage. Consulta il Riferimento per gli oggetti Cloud Storage per un elenco completo delle proprietà degli oggetti Cloud Storage.

Passaggi successivi

• Scopri come eseguire il deployment di funzioni Cloud Run.