Oggetti letti

Questa pagina mostra come leggere i dati degli oggetti dai bucket Cloud Storage direttamente nella memoria dell'applicazione o in modo interattivo nel browser web o nel terminale della riga di comando. La lettura degli oggetti in memoria o in modo interattivo è consigliata quando vuoi eseguire lo streaming, l'ispezione o l'elaborazione dei dati in modo da evitare il sovraccarico di CPU, I/O del disco e latenza associato alla scrittura di file in un file system locale persistente.

Per istruzioni sul download degli oggetti nello spazio di archiviazione persistente o locale, vedi Scarica gli oggetti. Per una panoramica concettuale delle letture e dei download degli oggetti, vedi Letture e download degli oggetti.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per leggere i dati degli oggetti, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Visualizzatore oggetti Storage (roles/storage.objectViewer) sul bucket
• Amministratore Storage (roles/storage.admin) sul progetto (richiesto solo per la lettura dei dati degli oggetti utilizzando la Google Cloud console)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer) contiene l'autorizzazione storage.objects.get, necessaria per la lettura degli oggetti. Il ruolo Amministratore Storage (roles/storage.admin) contiene le autorizzazioni storage.buckets.list e storage.buckets.get, oltre all'autorizzazione storage.objects.get. Queste autorizzazioni sono necessarie per elencare i bucket in un progetto e visualizzare informazioni sui bucket. Il ruolo Amministratore Storage (roles/storage.admin) che include queste autorizzazioni è necessario solo quando vuoi leggere gli oggetti in modo interattivo utilizzando la Google Cloud console.

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Per istruzioni sulla concessione dei ruoli sui bucket, vedi Imposta e gestisci i criteri IAM sui bucket.

Leggi gli oggetti in modo programmatico in memoria

Questa sezione descrive come leggere i dati degli oggetti eseguendo lo streaming dei byte degli oggetti direttamente nella memoria dell'applicazione.

Librerie client

C++

Per saperne di più, consulta la documentazione di riferimento dell'APIC++ di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  gcs::ObjectReadStream stream = client.ReadObject(bucket_name, object_name);
  std::string buffer{std::istreambuf_iterator<char>(stream),
                     std::istreambuf_iterator<char>()};
  if (stream.bad()) throw google::cloud::Status(stream.status());

  std::cout << "The object has " << buffer.size() << " characters\n";
}

C#

Per saperne di più, consulta la documentazione di riferimento dell'C# API di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

using Google.Cloud.Storage.V1;
using System;
using System.IO;

public class DownloadObjectIntoMemorySample
{
    public Stream DownloadObjectIntoMemory(
        string bucketName = "unique-bucket-name",
        string objectName = "file-name")
    {
        var storage = StorageClient.Create();
        Stream stream = new MemoryStream();
        storage.DownloadObject(bucketName, objectName, stream);

        Console.WriteLine($"The contents of {objectName} from bucket {bucketName} are downloaded");
        return stream;
    }
}

Go

Per saperne di più, consulta la documentazione di riferimento dell' API Go di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// downloadFileIntoMemory downloads an object.
func downloadFileIntoMemory(w io.Writer, bucket, object string) ([]byte, error) {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*50)
	defer cancel()

	rc, err := client.Bucket(bucket).Object(object).NewReader(ctx)
	if err != nil {
		return nil, fmt.Errorf("Object(%q).NewReader: %w", object, err)
	}
	defer rc.Close()

	data, err := io.ReadAll(rc)
	if err != nil {
		return nil, fmt.Errorf("io.ReadAll: %w", err)
	}
	fmt.Fprintf(w, "Blob %v downloaded.\n", object)
	return data, nil
}

Java

Per saperne di più, consulta la documentazione di riferimento dell'API Java Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.nio.charset.StandardCharsets;

public class DownloadObjectIntoMemory {
  public static void downloadObjectIntoMemory(
      String projectId, String bucketName, String objectName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    byte[] content = storage.readAllBytes(bucketName, objectName);
    System.out.println(
        "The contents of "
            + objectName
            + " from bucket name "
            + bucketName
            + " are: "
            + new String(content, StandardCharsets.UTF_8));
  }
}

Node.js

Per saperne di più, consulta la documentazione di riferimento dell'Node.js API di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function downloadIntoMemory() {
  // Downloads the file into a buffer in memory.
  const contents = await storage.bucket(bucketName).file(fileName).download();

  console.log(
    `Contents of gs://${bucketName}/${fileName} are ${contents.toString()}.`
  );
}

downloadIntoMemory().catch(console.error);

PHP

Per saperne di più, consulta la documentazione di riferimento dell'API PHP Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

use Google\Cloud\Storage\StorageClient;

/**
 * Download an object from Cloud Storage and save into a buffer in memory.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 */
function download_object_into_memory(
    string $bucketName,
    string $objectName
): void {
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $contents = $object->downloadAsString();
    printf(
        'Downloaded %s from gs://%s/%s' . PHP_EOL,
        $contents,
        $bucketName,
        $objectName
    );
}

Python

Per saperne di più, consulta la documentazione di riferimento dell' API Python di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

from google.cloud import storage


def download_blob_into_memory(bucket_name, blob_name):
    """Downloads a blob into memory."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

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

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)

    # Construct a client side representation of a blob.
    # Note `Bucket.blob` differs from `Bucket.get_blob` as it doesn't retrieve
    # any content from Google Cloud Storage. As we don't need additional data,
    # using `Bucket.blob` is preferred here.
    blob = bucket.blob(blob_name)
    contents = blob.download_as_bytes()

    print(
        "Downloaded storage object {} from bucket {} as the following bytes object: {}.".format(
            blob_name, bucket_name, contents.decode("utf-8")
        )
    )

Ruby

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Ruby.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

# The name of the bucket to access
# bucket_name = "my-bucket"

# The name of the remote file to download
# file_name = "file.txt"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name, skip_lookup: true
file    = bucket.file file_name

downloaded = file.download
downloaded.rewind # Optional - not needed on first read
contents = downloaded.read

puts "Contents of storage object #{file.name} in bucket #{bucket_name} are: #{contents}"

Rust

use google_cloud_storage::client::Storage;

pub async fn sample(client: &Storage, bucket: &str) -> Result<(), anyhow::Error> {
    const NAME: &str = "object-to-download.txt";
    let mut reader = client
        .read_object(format!("projects/_/buckets/{bucket}"), NAME)
        .send()
        .await?;

    let mut content = Vec::new();
    while let Some(data) = reader.next().await.transpose()? {
        content.extend_from_slice(&data);
    }

    println!(
        "Downloaded {} bytes of object {NAME} in bucket {bucket}.",
        content.len()
    );
    Ok(())
}

Leggi gli oggetti in modo interattivo

Questa sezione descrive come leggere gli oggetti in modo interattivo nella Google Cloud finestra del browser della console o in stdout del terminale della riga di comando.

Console

1. Nella Google Cloud console, vai alla pagina Bucket in Cloud Storage.
   

   Vai a Bucket

2. Nell'elenco dei bucket, fai clic sul nome del bucket di cui vuoi visualizzare i contenuti.

3. Nella scheda Oggetti, fai clic sul nome dell'oggetto che vuoi leggere.

4. Nella pagina Dettagli oggetto, fai clic sull'URL pubblico o sull'URL autenticato dell'oggetto per leggerne i dati.

Riga di comando

Per eseguire lo streaming del payload di byte di un oggetto direttamente in stdout del terminale, utilizza il comando gcloud storage cat:

gcloud storage cat gs://BUCKET_NAME/OBJECT_NAME

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket che contiene l'oggetto che vuoi leggere. Ad esempio, my-bucket.

• OBJECT_NAME: il nome dell'oggetto che vuoi leggere. Ad esempio, dog.png.

API REST

Per leggere i byte di un oggetto e indirizzare il flusso di output a stdout del terminale, segui queste istruzioni.

API JSON

1. Assicurati di aver installato e inizializzato gcloud CLI, che ti consente di generare un token di accesso per l'intestazione Authorization.

2. Utilizza cURL per chiamare l'API JSON con una richiestaobjects.get che includa l'opzione -o - e il parametro di query alt=media:

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -o - \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media"

   Sostituisci quanto segue:

   • BUCKET_NAME: il nome del bucket che contiene l'oggetto che vuoi leggere. Ad esempio, my-bucket.

   • OBJECT_NAME: il nome con codifica URL dell'oggetto che vuoi leggere. Ad esempio, pets/dog.png, con codifica URL pets%2Fdog.png.

API XML

1. Assicurati di aver installato e inizializzato gcloud CLI, che ti consente di generare un token di accesso per l'intestazione Authorization.

2. Utilizza cURL per chiamare l'API XML con una GET Object richiesta:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

   Sostituisci quanto segue:

   • BUCKET_NAME: il nome del bucket che contiene l'oggetto che vuoi leggere. Ad esempio, my-bucket.

   • OBJECT_NAME: il nome con codifica URL dell'oggetto che vuoi leggere. Ad esempio, pets/dog.png, con codifica URL pets%2Fdog.png.

Passaggi successivi

• Trasferisci i dati da cloud provider o altre origini online, ad esempio elenchi di URL.

• Trasferisci gli oggetti all'istanza Compute Engine.