Ler e escrever no Cloud Storage

Este documento descreve como armazenar e obter dados através da biblioteca cliente do Cloud Storage. Pressupõe que concluiu as tarefas descritas em Configuração para o Cloud Storage para ativar um contentor do Cloud Storage e transferir as bibliotecas de cliente. Também pressupõe que sabe como criar uma aplicação do App Engine.

Para ver exemplos de código adicionais, consulte as bibliotecas de cliente do Cloud Storage

Importações necessárias

Use o fragmento de código abaixo para aceder ao Cloud Storage através da biblioteca cliente:

# Imports the Google Cloud client library
from google.cloud import storage

# Instantiates a client
storage_client = storage.Client()

# The name for the new bucket
bucket_name = "my-new-bucket"

# Creates the new bucket
bucket = storage_client.create_bucket(bucket_name)

print(f"Bucket {bucket.name} created.")

Especificar o contentor do Cloud Storage

Antes de realizar quaisquer operações no Cloud Storage, tem de indicar o nome do contentor.

# Imports the Google Cloud client library
from google.cloud import storage

# Instantiates a client
storage_client = storage.Client()

# The name for the new bucket
bucket_name = "my-new-bucket"

# Creates the new bucket
bucket = storage_client.create_bucket(bucket_name)

print(f"Bucket {bucket.name} created.")

A forma mais fácil de especificar um nome do contentor é usar o contentor predefinido para o seu projeto. A chamada para get_default_gcs_bucket_name só é bem-sucedida se tiver criado o recipiente predefinido para o seu projeto.

Escrever no Cloud Storage

O exemplo seguinte mostra como escrever no contentor:

from google.cloud import storage


def write_read(bucket_name, blob_name):
    """Write and read a blob from GCS using file-like IO"""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The ID of your new GCS object
    # blob_name = "storage-object-name"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    # Mode can be specified as wb/rb for bytes mode.
    # See: https://docs.python.org/3/library/io.html
    with blob.open("w") as f:
        f.write("Hello world")

    with blob.open("r") as f:
        print(f.read())

Tenha em conta o seguinte:

  • Na chamada para abrir o ficheiro para escrita, o exemplo especifica determinados cabeçalhos do Cloud Storage que escrevem metadados personalizados para o ficheiro. Estes metadados podem ser obtidos através de cloudstorage.stat(). Pode encontrar a lista de cabeçalhos suportados na referência cloudstorage.open().

  • O cabeçalho x-goog-acl não está definido. Isto significa que a ACL do Cloud Storage predefinida de leitura pública vai ser aplicada ao objeto quando for escrita no contentor.

  • Certifique-se de que invoca a função para fechar o ficheiro depois de terminar a escrita. Se não o fizer, o ficheiro não é escrito no Cloud Storage. Tenha em atenção que, depois de chamar a função do ficheiro Python close(), não pode anexar conteúdo ao ficheiro. Se precisar de modificar um ficheiro, tem de chamar a função do ficheiro Python open() para abrir o ficheiro novamente no modo de escrita, o que faz uma substituição e não uma anexação.

Ler a partir do Cloud Storage

O exemplo seguinte mostra como ler um ficheiro completo do contentor:

from google.cloud import storage


def write_read(bucket_name, blob_name):
    """Write and read a blob from GCS using file-like IO"""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The ID of your new GCS object
    # blob_name = "storage-object-name"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    # Mode can be specified as wb/rb for bytes mode.
    # See: https://docs.python.org/3/library/io.html
    with blob.open("w") as f:
        f.write("Hello world")

    with blob.open("r") as f:
        print(f.read())

Em ambos os exemplos, o argumento blob_name que transmite a cloudstorage.open() é o caminho para o seu ficheiro no formato YOUR_BUCKET_NAME/PATH_IN_GCS. Tenha em atenção que a predefinição para cloudstorage.open() é o modo de leitura. Não precisa de especificar um modo quando abre um ficheiro para o ler.

Listar conteúdos de contentores

O código de exemplo mostra como paginar um contentor com conteúdo do tipo blob :

from google.cloud import storage


def list_blobs(bucket_name):
    """Lists all the blobs in the bucket."""
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()

    # Note: Client.list_blobs requires at least package version 1.17.0.
    blobs = storage_client.list_blobs(bucket_name)

    # Note: The call returns a response only when the iterator is consumed.
    for blob in blobs:
        print(blob.name)

Tenha em atenção que o nome do ficheiro completo é apresentado como uma string sem delimitadores de diretório. Se quiser apresentar o ficheiro com a respetiva hierarquia de diretórios mais reconhecível, defina o parâmetro delimiter para o delimitador de diretórios que quer usar.

Eliminar ficheiros no Cloud Storage

O código abaixo demonstra como eliminar um ficheiro do Cloud Storage através do método cloudstorage.delete() (importado como gcs).

from google.cloud import storage


def delete_blob(bucket_name, blob_name):
    """Deletes a blob from the bucket."""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)
    generation_match_precondition = None

    # Optional: set a generation-match precondition to avoid potential race conditions
    # and data corruptions. The request to delete is aborted if the object's
    # generation number does not match your precondition.
    blob.reload()  # Fetch blob metadata to use in generation_match_precondition.
    generation_match_precondition = blob.generation

    blob.delete(if_generation_match=generation_match_precondition)

    print(f"Blob {blob_name} deleted.")

Este exemplo limpa os ficheiros que foram escritos no contentor na secção Escrever no Cloud Storage.

O que se segue?