Tutorial do Cloud Storage (1.ª geração)


Este tutorial simples demonstra como escrever, implementar e acionar uma função do Cloud Run baseada em eventos com um acionador do Cloud Storage para responder a eventos do Cloud Storage.

Se procura exemplos de código para usar o Cloud Storage, aceda ao navegador de exemplos do Google Cloud.

Objetivos

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

  • Cloud Run functions
  • Cloud Storage

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Antes de começar

  1. 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.
  2. 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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

  5. Install the Google Cloud CLI.

  6. Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

  7. Para inicializar a CLI gcloud, execute o seguinte comando:

    gcloud init
  8. 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

  9. Verify that billing is enabled for your Google Cloud project.

  10. 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

  11. Install the Google Cloud CLI.

  12. Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

  13. Para inicializar a CLI gcloud, execute o seguinte comando:

    gcloud init
  14. Se já tiver a CLI gcloud instalada, atualize-a executando o seguinte comando:

    gcloud components update
  15. Prepare o ambiente de programação:
  16. A preparar a aplicação

    1. Crie um contentor do Cloud Storage para carregar um ficheiro de teste, onde YOUR_TRIGGER_BUCKET_NAME é um nome de contentor exclusivo a nível global:

      gcloud storage buckets create gs://YOUR_TRIGGER_BUCKET_NAME
    2. Clone o repositório da app de exemplo para a sua máquina local:

      Node.js

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

      Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

      Python

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

      Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

      Go

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

      Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

      Java

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

      Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

      Ruby

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

      Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

    3. Altere para o diretório que contém o código de exemplo das funções do Cloud Run:

      Node.js

      cd nodejs-docs-samples/functions/helloworld/

      Python

      cd python-docs-samples/functions/helloworld/

      Go

      cd golang-samples/functions/helloworld/

      Java

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

      Ruby

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

    Implementar e acionar a função

    As funções do Cloud Storage baseiam-se em notificações do Pub/Sub do Cloud Storage e suportam tipos de eventos semelhantes:

    As secções seguintes descrevem como implementar e acionar uma função para cada um destes tipos de eventos.

    Objeto finalizado

    Os eventos de finalização de objetos são acionados quando uma "escrita" de um objeto do Cloud Storage é finalizada com êxito. Em particular, isto significa que a criação de um novo objeto ou a substituição de um objeto existente aciona este evento. As operações de arquivo e atualização de metadados são ignoradas por este acionador.

    Object Finalize: implementar a função

    Veja a função de exemplo, que processa eventos do 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

    Para implementar a função, execute o seguinte comando no diretório onde o código de exemplo está localizado:

    Node.js

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão suportada do Node.js para executar a sua função.

    Python

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Python suportada para executar a sua função.

    Go

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Go suportada para executar a sua função.

    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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão Java suportada para executar a sua função.

    Ruby

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Ruby suportada para executar a sua função.

    em que YOUR_TRIGGER_BUCKET_NAME é o nome do contentor do Cloud Storage que aciona a função.

    Object Finalize: acionar a função

    Para acionar a função:

    1. Crie um ficheiro gcf-test.txt vazio no diretório onde se encontra o código de exemplo.

    2. Carregue o ficheiro para o Cloud Storage para acionar a função:

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

      onde YOUR_TRIGGER_BUCKET_NAME é o nome do seu contentor do Cloud Storage onde vai carregar um ficheiro de teste.

    3. Verifique os registos para se certificar de que as execuções foram concluídas:

      gcloud functions logs read --limit 50
      

    Eliminação de objeto

    Os eventos de eliminação de objetos são acionados quando um objeto é eliminado temporariamente. Isto acontece quando um objeto é substituído ou eliminado num contentor sem a versão de objetos ativada. A eliminação de um objeto especificando o respetivo número de geração também resulta na eliminação temporária do objeto.

    Eliminação de objetos: implementação da função

    Usando o mesmo exemplo de código que no exemplo de finalização, implemente a função com a eliminação de objetos como evento acionador. Execute o seguinte comando no diretório onde o exemplo de código está localizado:

    Node.js

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão suportada do Node.js para executar a sua função.

    Python

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Python suportada para executar a sua função.

    Go

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Go suportada para executar a sua função.

    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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão Java suportada para executar a sua função.

    Ruby

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Ruby suportada para executar a sua função.

    em que YOUR_TRIGGER_BUCKET_NAME é o nome do contentor do Cloud Storage que aciona a função.

    Eliminação de objetos: acionamento da função

    Para acionar a função:

    1. Crie um ficheiro gcf-test.txt vazio no diretório onde se encontra o código de exemplo.

    2. Certifique-se de que o seu contentor não tem controlo de versões:

      gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --no-versioning
    3. Carregue o ficheiro para o Cloud Storage:

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

      onde YOUR_TRIGGER_BUCKET_NAME é o nome do seu contentor do Cloud Storage onde vai carregar um ficheiro de teste. Neste ponto, a função ainda não deve ser executada.

    4. Elimine o ficheiro para acionar a função:

      gcloud storage rm gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt
    5. Verifique os registos para se certificar de que as execuções foram concluídas:

      gcloud functions logs read --limit 50
      

    Tenha em atenção que a função pode demorar algum tempo a terminar a execução.

    Arquivo de objetos

    Os eventos de arquivo de objetos são acionados quando uma versão ativa de um objeto se torna uma versão não atual. Isto acontece quando um objeto é substituído ou eliminado num contentor com a versão de objetos ativada.

    Arquivo de objetos: implementar a função

    Usando o mesmo exemplo de código que no exemplo de finalização, implemente a função com o arquivo de objetos como o evento de acionador. Execute o seguinte comando no diretório onde o exemplo de código está localizado:

    Node.js

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão suportada do Node.js para executar a sua função.

    Python

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Python suportada para executar a sua função.

    Go

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Go suportada para executar a sua função.

    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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão Java suportada para executar a sua função.

    Ruby

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Ruby suportada para executar a sua função.

    em que YOUR_TRIGGER_BUCKET_NAME é o nome do contentor do Cloud Storage que aciona a função.

    Arquivo de objetos: acionar a função

    Para acionar a função:

    1. Crie um ficheiro gcf-test.txt vazio no diretório onde se encontra o código de exemplo.

    2. Certifique-se de que o seu contentor tem a gestão de versões ativada:

      gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --versioning
    3. Carregue o ficheiro para o Cloud Storage:

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

      onde YOUR_TRIGGER_BUCKET_NAME é o nome do seu contentor do Cloud Storage onde vai carregar um ficheiro de teste. Neste ponto, a função ainda não deve ser executada.

    4. Arquive o ficheiro para acionar a função:

      gcloud storage rm gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt
    5. Monitorize os registos para se certificar de que as execuções foram concluídas:

      gcloud functions logs read --limit 50
      

    Atualização dos metadados do objeto

    Os eventos de atualização de metadados são acionados quando os metadados do objeto existente são atualizados.

    Atualização dos metadados do objeto: implementação da função

    Usando o mesmo exemplo de código que no exemplo de finalização, implemente a função com a atualização de metadados como o evento de acionamento. Execute o seguinte comando no diretório onde o exemplo de código está localizado:

    Node.js

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão suportada do Node.js para executar a sua função.

    Python

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Python suportada para executar a sua função.

    Go

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Go suportada para executar a sua função.

    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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão Java suportada para executar a sua função.

    Ruby

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

    Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Ruby suportada para executar a sua função.

    em que YOUR_TRIGGER_BUCKET_NAME é o nome do contentor do Cloud Storage que aciona a função.

    Atualização de metadados de objetos: acionar a função

    Para acionar a função:

    1. Crie um ficheiro gcf-test.txt vazio no diretório onde se encontra o código de exemplo.

    2. Certifique-se de que o seu contentor não tem controlo de versões:

      gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --no-versioning
    3. Carregue o ficheiro para o Cloud Storage:

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

      onde YOUR_TRIGGER_BUCKET_NAME é o nome do seu contentor do Cloud Storage onde vai carregar um ficheiro de teste. Neste ponto, a função ainda não deve ser executada.

    4. Atualize os metadados do ficheiro:

      gcloud storage objects update gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt --content-type=text/plain
    5. Monitorize os registos para se certificar de que as execuções foram concluídas:

      gcloud functions logs read --limit 50
      

    Limpar

    Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

    Eliminar o projeto

    A forma mais fácil de eliminar a faturação é eliminar o projeto que criou para o tutorial.

    Para eliminar o projeto:

    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.

    A eliminar a função

    A eliminação de funções do Cloud Run não remove recursos armazenados no Cloud Storage.

    Para eliminar a função que criou neste tutorial, execute o seguinte comando:

    Node.js

    gcloud functions delete helloGCS 

    Python

    gcloud functions delete hello_gcs 

    Go

    gcloud functions delete HelloGCS 

    Java

    gcloud functions delete java-gcs-function 

    Ruby

    gcloud functions delete hello_gcs 

    Também pode eliminar funções do Cloud Run a partir da Google Cloud consola.

    O que se segue?