Sube objetos desde un sistema de archivos

Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

En esta página, se muestra cómo subir objetos a tu bucket de Cloud Storage desde tu sistema de archivos local. Un objeto subido consiste en los datos que deseas almacenar junto con los metadatos asociados. Para obtener una descripción general conceptual, incluido cómo elegir el método de carga óptimo en función del tamaño del archivo, consulta Cargas y descargas.

Para obtener instrucciones sobre cómo subir objetos desde la memoria, consulta Sube objetos desde la memoria.

Permisos necesarios

Consola

Para completar esta guía con Google Cloud Console, debes tener los permisos de IAM adecuados. Si el bucket que deseas subir existe en un proyecto que no creaste, tal vez necesites que el propietario del proyecto te otorgue un rol con los permisos necesarios.

A fin de obtener una lista de los permisos necesarios para acciones específicas, consulta Permisos de IAM para Google Cloud Console.

Para obtener una lista de los roles relevantes, consulta Funciones de Cloud Storage. Como alternativa, puedes crear un rol personalizado que tenga permisos más limitados.

Línea de comandos

Para completar esta guía con una utilidad de línea de comandos, debes tener los permisos de IAM adecuados. Si el bucket en el que deseas realizar la carga existe en un proyecto que no creaste, tal vez necesites que el propietario del proyecto te otorgue un rol con los permisos necesarios.

Si deseas obtener una lista de los permisos necesarios para acciones específicas, consulta Permisos de IAM para los comandos de gsutil.

Para obtener una lista de los roles relevantes, consulta Funciones de Cloud Storage. Como alternativa, puedes crear un rol personalizado que tenga permisos más limitados.

Muestras de código

Para completar esta guía con las bibliotecas cliente de Cloud Storage, debes tener los permisos de IAM adecuados. Si el bucket que deseas subir existe en un proyecto que no creaste, tal vez necesites que el propietario del proyecto te otorgue un rol con los permisos necesarios. A menos que se indique lo contrario, las solicitudes de la biblioteca cliente se realizan mediante la API de JSON.

Si deseas obtener una lista de los permisos necesarios para acciones específicas, consulta Permisos de IAM para métodos JSON.

Para obtener una lista de los roles relevantes, consulta Funciones de Cloud Storage. Como alternativa, puedes crear un rol personalizado que tenga permisos más limitados.

API de REST

API de JSON

Para completar esta guía con la API de JSON, debes tener los permisos de IAM adecuados. Si el bucket que deseas subir existe en un proyecto que no creaste, tal vez necesites que el propietario del proyecto te otorgue un rol con los permisos necesarios.

Si deseas obtener una lista de los permisos necesarios para acciones específicas, consulta Permisos de IAM para métodos JSON.

Para obtener una lista de los roles relevantes, consulta Funciones de Cloud Storage. Como alternativa, puedes crear un rol personalizado que tenga permisos más limitados.

Sube un objeto a un bucket

Sigue los pasos a continuación para subir un objeto a un bucket:

Console

  1. En la consola de Google Cloud, ve a la página Buckets de Cloud Storage.

    Ir a Buckets

  2. En la lista de bucket s, haz clic en el nombre del bucket en el que deseas subir un objeto.

  3. En la pestaña Objetos para el depósito, realiza una de estas dos acciones:

    • Arrastra y suelta los archivos deseados desde tu escritorio o administrador de archivos en el panel principal de la consola de Google Cloud.

    • Haz clic en el botón Subir archivos, selecciona los archivos que deseas subir en el cuadro de diálogo que aparece y haz clic en Abrir.

Para obtener información sobre cómo ver detalles de errores acerca de operaciones fallidas de Cloud Storage en la consola de Google Cloud, consulta Solución de problemas.

Línea de comandos

gcloud

Usa el comando gcloud storage cp:

gcloud storage cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME/

Aquí:

  • OBJECT_LOCATION es la ruta de acceso local a tu objeto. Por ejemplo, Desktop/dog.png

  • DESTINATION_BUCKET_NAME es el nombre del bucket al que subes el objeto. Por ejemplo, my-bucket

Si es correcto, la respuesta se parece al siguiente ejemplo:

Completed files 1/1 | 164.3kiB/164.3kiB

Puedes configurar metadatos de objetos de clave fija y personalizada como parte de la carga de objetos mediante marcas de comandos.

gsutil

Usa el comando gsutil cp:

gsutil cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME/

Aquí:

  • OBJECT_LOCATION es la ruta de acceso local a tu objeto. Por ejemplo, Desktop/dog.png

  • DESTINATION_BUCKET_NAME es el nombre del bucket al que subes el objeto. Por ejemplo, my-bucket

Si es correcto, la respuesta se parece al siguiente ejemplo:

Operation completed over 1 objects/58.8 KiB.

Puedes configurar metadatos de objetos de clave fija y personalizados como parte de la carga de tu objeto en los encabezados de la solicitud mediante la opción global -h.

Muestras de código

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

En el siguiente ejemplo, se sube un objeto de un archivo:

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& file_name,
   std::string const& bucket_name, std::string const& object_name) {
  // Note that the client library automatically computes a hash on the
  // client-side to verify data integrity during transmission.
  StatusOr<gcs::ObjectMetadata> metadata = client.UploadFile(
      file_name, bucket_name, object_name, gcs::IfGenerationMatch(0));
  if (!metadata) throw std::runtime_error(metadata.status().message());

  std::cout << "Uploaded " << file_name << " to object " << metadata->name()
            << " in bucket " << metadata->bucket()
            << "\nFull metadata: " << *metadata << "\n";
}

C#

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.

En el siguiente ejemplo, se sube un objeto de un archivo:


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

public class UploadFileSample
{
    public void UploadFile(
        string bucketName = "your-unique-bucket-name",
        string localPath = "my-local-path/my-file-name",
        string objectName = "my-file-name")
    {
        var storage = StorageClient.Create();
        using var fileStream = File.OpenRead(localPath);
        storage.UploadObject(bucketName, objectName, null, fileStream);
        Console.WriteLine($"Uploaded {objectName}.");
    }
}

Go

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Go.

En el siguiente ejemplo, se sube un objeto de un archivo:

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

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

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

	// Open local file.
	f, err := os.Open("notes.txt")
	if err != nil {
		return fmt.Errorf("os.Open: %v", err)
	}
	defer f.Close()

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

	o := client.Bucket(bucket).Object(object)

	// Optional: set a generation-match precondition to avoid potential race
	// conditions and data corruptions. The request to upload is aborted if the
	// object's generation number does not match your precondition.
	// For an object that does not yet exist, set the DoesNotExist precondition.
	o = o.If(storage.Conditions{DoesNotExist: true})
	// If the live object already exists in your bucket, set instead a
	// generation-match precondition using the live object's generation number.
	// attrs, err := o.Attrs(ctx)
	// if err != nil {
	// 	return fmt.Errorf("object.Attrs: %v", err)
	// }
	// o = o.If(storage.Conditions{GenerationMatch: attrs.Generation})

	// Upload an object with storage.Writer.
	wc := o.NewWriter(ctx)
	if _, err = io.Copy(wc, f); err != nil {
		return fmt.Errorf("io.Copy: %v", err)
	}
	if err := wc.Close(); err != nil {
		return fmt.Errorf("Writer.Close: %v", err)
	}
	fmt.Fprintf(w, "Blob %v uploaded.\n", object)
	return nil
}

Java

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.

En el siguiente ejemplo, se sube un objeto de un archivo:


import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;

public class UploadObject {
  public static void uploadObject(
      String projectId, String bucketName, String objectName, String filePath) throws IOException {
    // 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";

    // The path to your file to upload
    // String filePath = "path/to/your/file"

    // Optional: set a generation-match precondition to avoid potential race
    // conditions and data corruptions. The request returns a 412 error if the
    // preconditions are not met.
    // For a target object that does not yet exist, set the DoesNotExist precondition.
    Storage.BlobTargetOption precondition = Storage.BlobTargetOption.doesNotExist();
    // If the destination already exists in your bucket, instead set a generation-match
    // precondition:
    // Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId blobId = BlobId.of(bucketName, objectName);
    BlobInfo blobInfo = BlobInfo.newBuilder(blobId).build();
    storage.create(blobInfo, Files.readAllBytes(Paths.get(filePath)), precondition);

    System.out.println(
        "File " + filePath + " uploaded to bucket " + bucketName + " as " + objectName);
  }
}

Node.js

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Node.js.

En el siguiente ejemplo, se sube un objeto de un archivo:

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

// The path to your file to upload
// const filePath = 'path/to/your/file';

// The new ID for your GCS file
// const destFileName = 'your-new-file-name';

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

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

async function uploadFile() {
  const options = {
    destination: destFileName,
    // Optional:
    // Set a generation-match precondition to avoid potential race conditions
    // and data corruptions. The request to upload is aborted if the object's
    // generation number does not match your precondition. For a destination
    // object that does not yet exist, set the ifGenerationMatch precondition to 0
    // If the destination object already exists in your bucket, set instead a
    // generation-match precondition using its generation number.
    preconditionOpts: {ifGenerationMatch: generationMatchPrecondition},
  };

  await storage.bucket(bucketName).upload(filePath, options);
  console.log(`${filePath} uploaded to ${bucketName}`);
}

uploadFile().catch(console.error);

PHP

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

En el siguiente ejemplo, se sube un objeto de un archivo:

use Google\Cloud\Storage\StorageClient;

/**
 * Upload a file.
 *
 * @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')
 * @param string $source The path to the file to upload.
 *        (e.g. '/path/to/your/file')
 */
function upload_object(string $bucketName, string $objectName, string $source): void
{
    $storage = new StorageClient();
    $file = fopen($source, 'r');
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->upload($file, [
        'name' => $objectName
    ]);
    printf('Uploaded %s to gs://%s/%s' . PHP_EOL, basename($source), $bucketName, $objectName);
}

Python

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.

En el siguiente ejemplo, se sube un objeto de un archivo:

from google.cloud import storage

def upload_blob(bucket_name, source_file_name, destination_blob_name):
    """Uploads a file to the bucket."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"
    # The path to your file to upload
    # source_file_name = "local/path/to/file"
    # The ID of your GCS object
    # destination_blob_name = "storage-object-name"

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

    blob.upload_from_filename(source_file_name)

    print(
        f"File {source_file_name} uploaded to {destination_blob_name}."
    )

Ruby

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Ruby.

En el siguiente ejemplo, se sube un objeto de un archivo:

def upload_file bucket_name:, local_file_path:, file_name: nil
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The path to your file to upload
  # local_file_path = "/local/path/to/file.txt"

  # The ID of your GCS object
  # file_name = "your-file-name"

  require "google/cloud/storage"

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

  file = bucket.create_file local_file_path, file_name

  puts "Uploaded #{local_file_path} as #{file.name} in bucket #{bucket_name}"
end

Terraform

Puedes usar un recurso de Terraform para subir un objeto. Se debe especificar content o source (también puedes especificar ambos).

# Upload files
# Discussion about using tf to upload a large number of objects
# https://stackoverflow.com/questions/68455132/terraform-copy-multiple-files-to-bucket-at-the-same-time-bucket-creation

# The text object in Cloud Storage
resource "google_storage_bucket_object" "default" {
  name = "new-object"
  # Uncomment and add valid path to an object.
  #  source       = "/path/to/an/object"
  content      = "Data as string to be uploaded"
  content_type = "text/plain"
  bucket       = google_storage_bucket.static.id
}

API de REST

API de JSON

La API de JSON distingue entre las cargas de contenido multimedia, en las que solo se incluyen datos de objetos en la solicitud, y las cargas de varias partes de la API de JSON, en las que los datos de objeto y los metadatos de objeto se incluyen en la solicitud.

Carga de contenido multimedia (carga de una sola solicitud sin metadatos de objeto)

  1. Obtén un token de autorización de acceso de OAuth 2.0 Playground. Configura Playground para usar tus credenciales de OAuth. Para obtener instrucciones, consulta Autenticación de la API.

  2. Usa cURL para llamar a la API de JSON con una solicitud de objeto POST:

    curl -X POST --data-binary @OBJECT_LOCATION \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: OBJECT_CONTENT_TYPE" \
    "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=media&name=OBJECT_NAME"

    Donde:

    • OBJECT_LOCATION es la ruta de acceso local a tu objeto. Por ejemplo, Desktop/dog.png.
    • OAUTH2_TOKEN es el token de acceso que generaste en el paso 1.
    • OBJECT_CONTENT_TYPE es el tipo de contenido del objeto. Por ejemplo, image/png.
    • BUCKET_NAME es el nombre del bucket al que subes el objeto. Por ejemplo, my-bucket.
    • OBJECT_NAME es el nombre codificado en URL que deseas darle a tu objeto. Por ejemplo, pets/dog.png, codificado en URL como pets%2Fdog.png.

Carga de varias partes de la API de JSON (carga de una sola solicitud que incluye metadatos de objeto)

  1. Obtén un token de autorización de acceso de OAuth 2.0 Playground. Configura Playground para usar tus credenciales de OAuth. Para obtener instrucciones, consulta Autenticación de la API.

  2. Crea un archivo multipart/related que contenga la siguiente información:

    --BOUNDARY_STRING
Content-Type: application/json; charset=UTF-8

OBJECT_METADATA

--BOUNDARY_STRING
Content-Type: OBJECT_CONTENT_TYPE

OBJECT_DATA
--BOUNDARY_STRING--

    Donde:

    • BOUNDARY_STRING es una string que defines para identificar las diferentes partes del archivo de varias partes. Por ejemplo, my-boundary.
    • OBJECT_METADATA son metadatos que deseas incluir para el archivo, en formato JSON. Como mínimo, esta sección debe incluir un atributo name para el objeto, por ejemplo {"name": "myObject"}.
    • OBJECT_CONTENT_TYPE es el tipo de contenido del objeto. Por ejemplo, image/png.
    • OBJECT_DATA son los datos del objeto.

  3. Usa cURL para llamar a la API de JSON con una solicitud de objeto POST:

    curl -X POST --data-binary @MULTIPART_FILE_LOCATION \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: multipart/related; boundary=BOUNDARY_STRING" \
    -H "Content-Length: MULTIPART_FILE_SIZE" \
    "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=multipart"

    Donde:

    • MULTIPART_FILE_LOCATION es la ruta local al archivo multiparte que creaste en el paso 2. Por ejemplo, Desktop/my-upload.multipart.
    • OAUTH2_TOKEN es el token de acceso que generaste en el paso 1.
    • BOUNDARY_STRING es la string de límite que definiste en el paso 2. Por ejemplo, my-boundary.
    • MULTIPART_FILE_SIZE es el tamaño total, en bytes, del archivo de varias partes que creaste en el paso 2. Por ejemplo, 2000000.
    • BUCKET_NAME es el nombre del bucket al que subes el objeto. Por ejemplo, my-bucket.

Si la solicitud se realiza correctamente, el servidor muestra el código de estado HTTP 200 OK junto con los metadatos del archivo.

API de XML

  1. Obtén un token de autorización de acceso de OAuth 2.0 Playground. Configura Playground para usar tus credenciales de OAuth. Para obtener instrucciones, consulta Autenticación de la API.

  2. Usa cURL para llamar a la API de XML con una solicitud de objeto PUT:

    curl -X PUT --data-binary @OBJECT_LOCATION \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: OBJECT_CONTENT_TYPE" \
    "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    Donde:

    • OBJECT_LOCATION es la ruta de acceso local a tu objeto. Por ejemplo, Desktop/dog.png.
    • OAUTH2_TOKEN es el token de acceso que generaste en el paso 1.
    • OBJECT_CONTENT_TYPE es el tipo de contenido del objeto. Por ejemplo, image/png.
    • BUCKET_NAME es el nombre del bucket al que subes el objeto. Por ejemplo, my-bucket.
    • OBJECT_NAME es el nombre codificado en URL que deseas darle a tu objeto. Por ejemplo, pets/dog.png, codificado en URL como pets%2Fdog.png.

Puedes configurar metadatos de objeto adicionales como parte de la carga del objeto en los encabezados de la solicitud, de la misma manera que el ejemplo anterior configura Content-Type. Cuando trabajas con la API de XML, los metadatos solo pueden configurarse en el momento en que se escribe el objeto, como cuando se lo sube, copia o reemplaza. Para obtener más información, consulta Edita los metadatos de objetos.

¿Qué sigue?

Pruébalo tú mismo

Si es la primera vez que usas Google Cloud, crea una cuenta para evaluar el rendimiento de Cloud Storage en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

Probar Cloud Storage gratis