Tutorial su Cloud Storage (1ª generazione.)

Questo semplice tutorial mostra come scrivere, eseguire il deployment e attivare una funzione Cloud Run basata su eventi con un trigger Cloud Storage per rispondere agli eventi Cloud Storage.

Se cerchi esempi di codice per utilizzare Cloud Storage, visita il browser di esempi di Google Cloud.

Obiettivi

• Scrivere ed eseguire il deployment di una funzione Cloud Run basata sugli eventi.
• Attiva la funzione caricando un file in Cloud Storage.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

• Cloud Run functions
• Cloud Storage

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

Prima di iniziare

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Functions, Cloud Build, Cloud Storage, and Eventarc APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Functions, Cloud Build, Cloud Storage, and Eventarc APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Se hai già installato gcloud CLI, aggiornala eseguendo il seguente comando:

gcloud components update

1. Prepara l'ambiente di sviluppo:

   Node.js

   Vai alla guida alla configurazione di Node.js

   Python

   Vai alla guida alla configurazione di Python

   Vai

   Vai alla Guida alla configurazione di Go

   Java

   Vai alla guida alla configurazione di Java

   Ruby

   Vai alla Guida alla configurazione di Ruby

Preparazione della richiesta

1. Crea un bucket Cloud Storage per caricare un file di test, dove YOUR_TRIGGER_BUCKET_NAME è un nome di bucket univoco a livello globale:

   gcloud storage buckets create gs://YOUR_TRIGGER_BUCKET_NAME

2. Clona il repository dell'app di esempio sulla tua macchina locale:

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   In alternativa, puoi scaricare il campione come file ZIP ed estrarlo.

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

   In alternativa, puoi scaricare il campione come file ZIP ed estrarlo.

   Vai

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

   In alternativa, puoi scaricare il campione come file ZIP ed estrarlo.

   Java

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

   In alternativa, puoi scaricare il campione come file ZIP ed estrarlo.

   Ruby

   git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git

   In alternativa, puoi scaricare il campione come file ZIP ed estrarlo.

3. Passa alla directory che contiene il codice campione delle funzioni Cloud Run:

   Node.js

   cd nodejs-docs-samples/functions/helloworld/

   Python

   cd python-docs-samples/functions/helloworld/

   Vai

   cd golang-samples/functions/helloworld/

   Java

   cd java-docs-samples/functions/helloworld/hello-gcs/

   Ruby

   cd ruby-docs-samples/functions/helloworld/storage/

Eseguire il deployment e attivare la funzione

Le funzioni Cloud Storage si basano sulle notifiche Pub/Sub di Cloud Storage e supportano tipi di eventi simili:

• finalize

• elimina

• archive

• aggiornamento dei metadati

Le sezioni seguenti descrivono come eseguire il deployment e attivare una funzione per ciascuno di questi tipi di eventi.

Finalizzazione oggetto

Gli eventi di finalizzazione dell'oggetto vengono attivati quando una "scrittura" di un oggetto Cloud Storage viene finalizzata correttamente. In particolare, la creazione di un nuovo oggetto o la sovrascrittura di un oggetto esistente attiva questo evento. Le operazioni di aggiornamento dell'archivio e dei metadati vengono ignorate da questo trigger.

Finalizzazione oggetto: esecuzione del deployment della funzione

Dai un'occhiata alla funzione di esempio, che gestisce gli eventi Cloud Storage:

Node.js

/**
 * Generic background Cloud Function to be triggered by Cloud Storage.
 * This sample works for all Cloud Storage CRUD operations.
 *
 * @param {object} file The Cloud Storage file metadata.
 * @param {object} context The event metadata.
 */
exports.helloGCS = (file, context) => {
  console.log(`  Event: ${context.eventId}`);
  console.log(`  Event Type: ${context.eventType}`);
  console.log(`  Bucket: ${file.bucket}`);
  console.log(`  File: ${file.name}`);
  console.log(`  Metageneration: ${file.metageneration}`);
  console.log(`  Created: ${file.timeCreated}`);
  console.log(`  Updated: ${file.updated}`);
};

Python

def hello_gcs(event, context):
    """Background Cloud Function to be triggered by Cloud Storage.
       This generic function logs relevant data when a file is changed,
       and works for all Cloud Storage CRUD operations.
    Args:
        event (dict):  The dictionary with data specific to this type of event.
                       The `data` field contains a description of the event in
                       the Cloud Storage `object` format described here:
                       https://cloud.google.com/storage/docs/json_api/v1/objects#resource
        context (google.cloud.functions.Context): Metadata of triggering event.
    Returns:
        None; the output is written to Cloud Logging
    """

    print(f"Event ID: {context.event_id}")
    print(f"Event type: {context.event_type}")
    print("Bucket: {}".format(event["bucket"]))
    print("File: {}".format(event["name"]))
    print("Metageneration: {}".format(event["metageneration"]))
    print("Created: {}".format(event["timeCreated"]))
    print("Updated: {}".format(event["updated"]))

Go

// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"context"
	"fmt"
	"log"
	"time"

	"cloud.google.com/go/functions/metadata"
)

// GCSEvent is the payload of a GCS event.
type GCSEvent struct {
	Kind                    string                 `json:"kind"`
	ID                      string                 `json:"id"`
	SelfLink                string                 `json:"selfLink"`
	Name                    string                 `json:"name"`
	Bucket                  string                 `json:"bucket"`
	Generation              string                 `json:"generation"`
	Metageneration          string                 `json:"metageneration"`
	ContentType             string                 `json:"contentType"`
	TimeCreated             time.Time              `json:"timeCreated"`
	Updated                 time.Time              `json:"updated"`
	TemporaryHold           bool                   `json:"temporaryHold"`
	EventBasedHold          bool                   `json:"eventBasedHold"`
	RetentionExpirationTime time.Time              `json:"retentionExpirationTime"`
	StorageClass            string                 `json:"storageClass"`
	TimeStorageClassUpdated time.Time              `json:"timeStorageClassUpdated"`
	Size                    string                 `json:"size"`
	MD5Hash                 string                 `json:"md5Hash"`
	MediaLink               string                 `json:"mediaLink"`
	ContentEncoding         string                 `json:"contentEncoding"`
	ContentDisposition      string                 `json:"contentDisposition"`
	CacheControl            string                 `json:"cacheControl"`
	Metadata                map[string]interface{} `json:"metadata"`
	CRC32C                  string                 `json:"crc32c"`
	ComponentCount          int                    `json:"componentCount"`
	Etag                    string                 `json:"etag"`
	CustomerEncryption      struct {
		EncryptionAlgorithm string `json:"encryptionAlgorithm"`
		KeySha256           string `json:"keySha256"`
	}
	KMSKeyName    string `json:"kmsKeyName"`
	ResourceState string `json:"resourceState"`
}

// HelloGCS consumes a(ny) GCS event.
func HelloGCS(ctx context.Context, e GCSEvent) error {
	meta, err := metadata.FromContext(ctx)
	if err != nil {
		return fmt.Errorf("metadata.FromContext: %w", err)
	}
	log.Printf("Event ID: %v\n", meta.EventID)
	log.Printf("Event type: %v\n", meta.EventType)
	log.Printf("Bucket: %v\n", e.Bucket)
	log.Printf("File: %v\n", e.Name)
	log.Printf("Metageneration: %v\n", e.Metageneration)
	log.Printf("Created: %v\n", e.TimeCreated)
	log.Printf("Updated: %v\n", e.Updated)
	return nil
}

Java

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import functions.eventpojos.GcsEvent;
import java.util.logging.Logger;

/**
 * Example Cloud Storage-triggered function.
 * This function can process any event from Cloud Storage.
 */
public class HelloGcs implements BackgroundFunction<GcsEvent> {
  private static final Logger logger = Logger.getLogger(HelloGcs.class.getName());

  @Override
  public void accept(GcsEvent event, Context context) {
    logger.info("Event: " + context.eventId());
    logger.info("Event Type: " + context.eventType());
    logger.info("Bucket: " + event.getBucket());
    logger.info("File: " + event.getName());
    logger.info("Metageneration: " + event.getMetageneration());
    logger.info("Created: " + event.getTimeCreated());
    logger.info("Updated: " + event.getUpdated());
  }
}

Ruby

require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # This function supports all Cloud Storage events.
  # The `event` parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  payload = event.data

  logger.info "Event: #{event.id}"
  logger.info "Event Type: #{event.type}"
  logger.info "Bucket: #{payload['bucket']}"
  logger.info "File: #{payload['name']}"
  logger.info "Metageneration: #{payload['metageneration']}"
  logger.info "Created: #{payload['timeCreated']}"
  logger.info "Updated: #{payload['updated']}"
end

Per eseguire il deployment della funzione, esegui questo comando nella directory in cui si trova il codice campione:

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs20 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Node.js supportata per eseguire la funzione.

Python

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Python supportata per eseguire la funzione.

Vai

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Go supportata per eseguire la funzione.

Java

gcloud functions deploy java-gcs-function \
--entry-point functions.HelloGcs \
--runtime java17 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Utilizza il flag --runtime per specificare l'ID runtime di una versione Java supportata per eseguire la funzione.

Ruby

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Ruby supportata per eseguire la funzione.

dove YOUR_TRIGGER_BUCKET_NAME è il nome del bucket Cloud Storage che attiva la funzione.

Finalizzazione dell'oggetto: attivazione della funzione

Per attivare la funzione:

1. Crea un file gcf-test.txt vuoto nella directory in cui si trova il codice campione.

2. Carica il file su Cloud Storage per attivare la funzione:

   gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME

   dove YOUR_TRIGGER_BUCKET_NAME è il nome del bucket Cloud Storage in cui caricherai un file di test.

3. Controlla i log per assicurarti che le esecuzioni siano state completate:

   gcloud functions logs read --limit 50
   

Eliminazione oggetto

Gli eventi di eliminazione dell'oggetto vengono attivati quando un oggetto viene eliminato temporaneamente. Ciò si verifica quando un oggetto viene sovrascritto o eliminato in un bucket senza che sia abilitato il controllo delle versioni degli oggetti. L'eliminazione di un oggetto specificando il numero di generazione comporta anche l'eliminazione temporanea dell'oggetto.

Eliminazione oggetto: deployment della funzione

Utilizzando lo stesso codice campione dell'esempio di finalizzazione, esegui il deployment della funzione con l'eliminazione dell'oggetto come evento trigger. Esegui questo comando nella directory in cui si trova ilcodice campioneo:

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs20 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Node.js supportata per eseguire la funzione.

Python

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Python supportata per eseguire la funzione.

Vai

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Go supportata per eseguire la funzione.

Java

gcloud functions deploy java-gcs-function \
--entry-point functions.HelloGcs \
--runtime java17 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Utilizza il flag --runtime per specificare l'ID runtime di una versione Java supportata per eseguire la funzione.

Ruby

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Ruby supportata per eseguire la funzione.

dove YOUR_TRIGGER_BUCKET_NAME è il nome del bucket Cloud Storage che attiva la funzione.

Eliminazione oggetto: attivazione della funzione

Per attivare la funzione:

1. Crea un file gcf-test.txt vuoto nella directory in cui si trova il codice campione.

2. Assicurati che il bucket non sia sottoposto al controllo delle versioni:

   gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --no-versioning

3. Carica il file su Cloud Storage:

   gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME

   dove YOUR_TRIGGER_BUCKET_NAME è il nome del bucket Cloud Storage in cui caricherai un file di test. A questo punto la funzione non dovrebbe ancora essere eseguita.

4. Elimina il file per attivare la funzione:

   gcloud storage rm gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt

5. Controlla i log per assicurarti che le esecuzioni siano state completate:

   gcloud functions logs read --limit 50
   

Tieni presente che l'esecuzione della funzione potrebbe richiedere del tempo.

Archiviazione oggetto

Gli eventi di archiviazione degli oggetti vengono attivati quando una versione live di un oggetto diventa una versione non corrente. Ciò si verifica quando un oggetto viene sovrascritto o eliminato in un bucket con il controllo delle versioni degli oggetti abilitato.

Archiviazione oggetti: deployment della funzione

Utilizzando lo stesso codice campione dell'esempio di finalizzazione, esegui il deployment della funzione con l'archiviazione degli oggetti come evento trigger. Esegui questo comando nella directory in cui si trova ilcodice campioneo:

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs20 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Node.js supportata per eseguire la funzione.

Python

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Python supportata per eseguire la funzione.

Vai

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Go supportata per eseguire la funzione.

Java

gcloud functions deploy java-gcs-function \
--entry-point functions.HelloGcs \
--runtime java17 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Utilizza il flag --runtime per specificare l'ID runtime di una versione Java supportata per eseguire la funzione.

Ruby

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Ruby supportata per eseguire la funzione.

dove YOUR_TRIGGER_BUCKET_NAME è il nome del bucket Cloud Storage che attiva la funzione.

Archive oggetti: attivazione della funzione

Per attivare la funzione:

1. Crea un file gcf-test.txt vuoto nella directory in cui si trova il codice campione.

2. Assicurati che il controllo delle versioni sia attivato per il bucket:

   gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --versioning

3. Carica il file su Cloud Storage:

   gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME

   dove YOUR_TRIGGER_BUCKET_NAME è il nome del bucket Cloud Storage in cui caricherai un file di test. A questo punto la funzione non dovrebbe ancora essere eseguita.

4. Archivia il file per attivare la funzione:

   gcloud storage rm gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt

5. Controlla i log per assicurarti che le esecuzioni siano state completate:

   gcloud functions logs read --limit 50
   

Aggiornamento metadati oggetto

Gli eventi di aggiornamento dei metadati vengono attivati quando i metadati dell'oggetto esistente vengono aggiornati.

Aggiornamento dei metadati degli oggetti: deployment della funzione

Utilizzando lo stesso codice campione dell'esempio di finalizzazione, esegui il deployment della funzione con l'aggiornamento dei metadati come evento trigger. Esegui questo comando nella directory in cui si trova ilcodice campioneo:

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs20 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Node.js supportata per eseguire la funzione.

Python

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Python supportata per eseguire la funzione.

Vai

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Go supportata per eseguire la funzione.

Java

gcloud functions deploy java-gcs-function \
--entry-point functions.HelloGcs \
--runtime java17 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Utilizza il flag --runtime per specificare l'ID runtime di una versione Java supportata per eseguire la funzione.

Ruby

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Ruby supportata per eseguire la funzione.

dove YOUR_TRIGGER_BUCKET_NAME è il nome del bucket Cloud Storage che attiva la funzione.

Aggiornamento dei metadati degli oggetti: attivazione della funzione

Per attivare la funzione:

1. Crea un file gcf-test.txt vuoto nella directory in cui si trova il codice campione.

2. Assicurati che il bucket non sia sottoposto al controllo delle versioni:

   gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --no-versioning

3. Carica il file su Cloud Storage:

   gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME

   dove YOUR_TRIGGER_BUCKET_NAME è il nome del bucket Cloud Storage in cui caricherai un file di test. A questo punto la funzione non dovrebbe ancora essere eseguita.

4. Aggiorna i metadati del file:

   gcloud storage objects update gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt --content-type=text/plain

5. Controlla i log per assicurarti che le esecuzioni siano state completate:

   gcloud functions logs read --limit 50
   

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione è eliminare il progetto creato per il tutorial.

Per eliminare il progetto:

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Eliminazione della funzione

L'eliminazione delle funzioni Cloud Run non rimuove le risorse archiviate in Cloud Storage.

Per eliminare la funzione creata in questo tutorial, esegui questo comando:

Node.js

gcloud functions delete helloGCS 

Python

gcloud functions delete hello_gcs 

Vai

gcloud functions delete HelloGCS 

Java

gcloud functions delete java-gcs-function 

Ruby

gcloud functions delete hello_gcs 

Puoi anche eliminare le funzioni Cloud Run dalla consoleGoogle Cloud .

Passaggi successivi

• Scopri come eseguire l'OCR sulle immagini caricate in un bucket.
• Scopri come tradurre file di testo utilizzando le funzioni Cloud Run.