파일 시스템에서 객체 업로드

이 페이지에서는 로컬 파일 시스템에서 Cloud Storage 버킷에 객체를 업로드하는 방법을 보여줍니다. 업로드된 객체는 관련 메타데이터와 저장할 데이터로 구성됩니다. 파일 크기에 따라 최적의 업로드 방법을 선택하는 방법을 포함한 개념 개요는 업로드 및 다운로드를 참조하세요.

메모리에서 업로드에 대한 안내는 메모리에서 객체 업로드를 참조하세요.

필요한 역할

버킷에 객체를 업로드하는 데 필요한 권한을 얻으려면 관리자에게 버킷에 대한 스토리지 객체 사용자(roles/storage.objectUser) IAM 역할을 부여해 달라고 요청하세요. 이 사전 정의된 역할에는 객체를 버킷에 업로드하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.

필수 권한

• storage.objects.create
• storage.objects.delete
  • 이 권한은 기존 객체를 덮어쓰는 업로드에만 필요합니다.
• storage.objects.get
  • 이 권한은 Google Cloud CLI를 사용하여 이 페이지의 태스크를 수행하려는 경우에만 필요합니다.
• storage.objects.list
  • 이 권한은 Google Cloud CLI를 사용하여 이 페이지의 태스크를 수행하려는 경우에만 필요합니다. Google Cloud 콘솔을 사용하여 업로드한 객체를 확인하려면 이 권한도 필요합니다.

Google Cloud 콘솔을 사용하여 이 페이지의 태스크를 수행하려면 스토리지 객체 사용자(roles/storage.objectUser) 역할에 포함되지 않은 storage.buckets.list 권한도 필요합니다. 이 권한을 얻으려면 관리자에게 프로젝트에 대한 스토리지 관리자(roles/storage.admin) 역할을 부여해 달라고 요청하세요.

다른 사전 정의된 역할이나 커스텀 역할을 사용하여 이러한 권한을 얻을 수도 있습니다.

버킷의 역할 부여에 대한 자세한 내용은 버킷에 IAM 사용을 참조하세요.

버킷에 객체 업로드

버킷에 객체를 업로드하려면 다음 단계를 완료하세요.

콘솔

1. Google Cloud 콘솔에서 Cloud Storage 버킷 페이지로 이동합니다.
   

   버킷으로 이동

2. 버킷 목록에서 객체를 업로드할 버킷의 이름을 클릭합니다.

3. 버킷의 객체 탭에서 다음 중 하나를 수행합니다.

   • 바탕화면이나 파일 관리자에서 Google Cloud 콘솔의 기본 창으로 파일을 드래그합니다.

   • 파일 업로드 버튼을 클릭하고 나타나는 대화상자에서 업로드할 파일을 선택하고 열기를 클릭합니다.

   참고: Chrome 브라우저를 사용하고 있으면 폴더 업로드도 지원됩니다.

Google Cloud 콘솔에서 실패한 Cloud Storage 작업에 대한 자세한 오류 정보를 가져오는 방법은 문제 해결을 참조하세요.

명령줄

gcloud storage cp 명령어를 사용합니다.

gcloud storage cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME

각 항목의 의미는 다음과 같습니다.

• OBJECT_LOCATION은 객체의 로컬 경로입니다. 예를 들면 Desktop/dog.png입니다.

• DESTINATION_BUCKET_NAME은 객체를 업로드할 버킷의 이름입니다. 예를 들면 my-bucket입니다.

성공하면 응답은 다음 예시와 같습니다.

Completed files 1/1 | 164.3kiB/164.3kiB

참고: --recursive 플래그를 사용하여 디렉터리를 재귀적으로 업로드하세요.

명령어 플래그를 사용하여 객체 업로드 중에 고정 키 및 커스텀 객체 메타데이터를 설정할 수 있습니다.

클라이언트 라이브러리

C++

자세한 내용은 Cloud Storage C++ API 참고 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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::move(metadata).status();

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

C#

자세한 내용은 Cloud Storage C# API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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

자세한 내용은 Cloud Storage Go API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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: %w", err)
	}
	defer client.Close()

	// Open local file.
	f, err := os.Open("notes.txt")
	if err != nil {
		return fmt.Errorf("os.Open: %w", 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: %w", 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: %w", err)
	}
	if err := wc.Close(); err != nil {
		return fmt.Errorf("Writer.Close: %w", err)
	}
	fmt.Fprintf(w, "Blob %v uploaded.\n", object)
	return nil
}

Java

자세한 내용은 Cloud Storage Java API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

다음 샘플은 개별 객체를 업로드합니다.

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

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId blobId = BlobId.of(bucketName, objectName);
    BlobInfo blobInfo = BlobInfo.newBuilder(blobId).build();

    // 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.
    Storage.BlobWriteOption precondition;
    if (storage.get(bucketName, objectName) == null) {
      // For a target object that does not yet exist, set the DoesNotExist precondition.
      // This will cause the request to fail if the object is created before the request runs.
      precondition = Storage.BlobWriteOption.doesNotExist();
    } else {
      // If the destination already exists in your bucket, instead set a generation-match
      // precondition. This will cause the request to fail if the existing object's generation
      // changes before the request runs.
      precondition =
          Storage.BlobWriteOption.generationMatch(
              storage.get(bucketName, objectName).getGeneration());
    }
    storage.createFrom(blobInfo, Paths.get(filePath), precondition);

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

다음 샘플은 객체 여러 개를 동시에 업로드합니다.

import com.google.cloud.storage.transfermanager.ParallelUploadConfig;
import com.google.cloud.storage.transfermanager.TransferManager;
import com.google.cloud.storage.transfermanager.TransferManagerConfig;
import com.google.cloud.storage.transfermanager.UploadResult;
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;

class UploadMany {

  public static void uploadManyFiles(String bucketName, List<Path> files) throws IOException {
    TransferManager transferManager = TransferManagerConfig.newBuilder().build().getService();
    ParallelUploadConfig parallelUploadConfig =
        ParallelUploadConfig.newBuilder().setBucketName(bucketName).build();
    List<UploadResult> results =
        transferManager.uploadFiles(files, parallelUploadConfig).getUploadResults();
    for (UploadResult result : results) {
      System.out.println(
          "Upload for "
              + result.getInput().getName()
              + " completed with status "
              + result.getStatus());
    }
  }
}

다음 샘플에서는 공통 프리픽스가 있는 모든 객체를 동시에 업로드합니다.

import com.google.cloud.storage.transfermanager.ParallelUploadConfig;
import com.google.cloud.storage.transfermanager.TransferManager;
import com.google.cloud.storage.transfermanager.TransferManagerConfig;
import com.google.cloud.storage.transfermanager.UploadResult;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Stream;

class UploadDirectory {

  public static void uploadDirectoryContents(String bucketName, Path sourceDirectory)
      throws IOException {
    TransferManager transferManager = TransferManagerConfig.newBuilder().build().getService();
    ParallelUploadConfig parallelUploadConfig =
        ParallelUploadConfig.newBuilder().setBucketName(bucketName).build();

    // Create a list to store the file paths
    List<Path> filePaths = new ArrayList<>();
    // Get all files in the directory
    // try-with-resource to ensure pathStream is closed
    try (Stream<Path> pathStream = Files.walk(sourceDirectory)) {
      pathStream.filter(Files::isRegularFile).forEach(filePaths::add);
    }
    List<UploadResult> results =
        transferManager.uploadFiles(filePaths, parallelUploadConfig).getUploadResults();
    for (UploadResult result : results) {
      System.out.println(
          "Upload for "
              + result.getInput().getName()
              + " completed with status "
              + result.getStatus());
    }
  }
}

Node.js

자세한 내용은 Cloud Storage Node.js API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

다음 샘플은 개별 객체를 업로드합니다.

/**
 * 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);

다음 샘플은 객체 여러 개를 동시에 업로드합니다.

/**
 * 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 the first GCS file to upload
// const firstFilePath = 'your-first-file-name';

// The ID of the second GCS file to upload
// const secondFilePath = 'your-second-file-name';

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

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

// Creates a transfer manager client
const transferManager = new TransferManager(storage.bucket(bucketName));

async function uploadManyFilesWithTransferManager() {
  // Uploads the files
  await transferManager.uploadManyFiles([firstFilePath, secondFilePath]);

  for (const filePath of [firstFilePath, secondFilePath]) {
    console.log(`${filePath} uploaded to ${bucketName}.`);
  }
}

uploadManyFilesWithTransferManager().catch(console.error);

다음 샘플에서는 공통 프리픽스가 있는 모든 객체를 동시에 업로드합니다.

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

// The local directory to upload
// const directoryName = 'your-directory';

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

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

// Creates a transfer manager client
const transferManager = new TransferManager(storage.bucket(bucketName));

async function uploadDirectoryWithTransferManager() {
  // Uploads the directory
  await transferManager.uploadManyFiles(directoryName);

  console.log(`${directoryName} uploaded to ${bucketName}.`);
}

uploadDirectoryWithTransferManager().catch(console.error);

PHP

자세한 내용은 Cloud Storage PHP API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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();
    if (!$file = fopen($source, 'r')) {
        throw new \InvalidArgumentException('Unable to open file for reading');
    }
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->upload($file, [
        'name' => $objectName
    ]);
    printf('Uploaded %s to gs://%s/%s' . PHP_EOL, basename($source), $bucketName, $objectName);
}

Python

자세한 내용은 Cloud Storage Python API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

다음 샘플은 개별 객체를 업로드합니다.

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)

    # 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 if_generation_match precondition to 0.
    # If the destination object already exists in your bucket, set instead a
    # generation-match precondition using its generation number.
    generation_match_precondition = 0

    blob.upload_from_filename(source_file_name, if_generation_match=generation_match_precondition)

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

다음 샘플은 객체 여러 개를 동시에 업로드합니다.

def upload_many_blobs_with_transfer_manager(
    bucket_name, filenames, source_directory="", workers=8
):
    """Upload every file in a list to a bucket, concurrently in a process pool.

    Each blob name is derived from the filename, not including the
    `source_directory` parameter. For complete control of the blob name for each
    file (and other aspects of individual blob metadata), use
    transfer_manager.upload_many() instead.
    """

    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # A list (or other iterable) of filenames to upload.
    # filenames = ["file_1.txt", "file_2.txt"]

    # The directory on your computer that is the root of all of the files in the
    # list of filenames. This string is prepended (with os.path.join()) to each
    # filename to get the full path to the file. Relative paths and absolute
    # paths are both accepted. This string is not included in the name of the
    # uploaded blob; it is only used to find the source files. An empty string
    # means "the current working directory". Note that this parameter allows
    # directory traversal (e.g. "/", "../") and is not intended for unsanitized
    # end user input.
    # source_directory=""

    # The maximum number of processes to use for the operation. The performance
    # impact of this value depends on the use case, but smaller files usually
    # benefit from a higher number of processes. Each additional process occupies
    # some CPU and memory resources until finished. Threads can be used instead
    # of processes by passing `worker_type=transfer_manager.THREAD`.
    # workers=8

    from google.cloud.storage import Client, transfer_manager

    storage_client = Client()
    bucket = storage_client.bucket(bucket_name)

    results = transfer_manager.upload_many_from_filenames(
        bucket, filenames, source_directory=source_directory, max_workers=workers
    )

    for name, result in zip(filenames, results):
        # The results list is either `None` or an exception for each filename in
        # the input list, in order.

        if isinstance(result, Exception):
            print("Failed to upload {} due to exception: {}".format(name, result))
        else:
            print("Uploaded {} to {}.".format(name, bucket.name))

다음 샘플에서는 공통 프리픽스가 있는 모든 객체를 동시에 업로드합니다.

def upload_directory_with_transfer_manager(bucket_name, source_directory, workers=8):
    """Upload every file in a directory, including all files in subdirectories.

    Each blob name is derived from the filename, not including the `directory`
    parameter itself. For complete control of the blob name for each file (and
    other aspects of individual blob metadata), use
    transfer_manager.upload_many() instead.
    """

    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The directory on your computer to upload. Files in the directory and its
    # subdirectories will be uploaded. An empty string means "the current
    # working directory".
    # source_directory=""

    # The maximum number of processes to use for the operation. The performance
    # impact of this value depends on the use case, but smaller files usually
    # benefit from a higher number of processes. Each additional process occupies
    # some CPU and memory resources until finished. Threads can be used instead
    # of processes by passing `worker_type=transfer_manager.THREAD`.
    # workers=8

    from pathlib import Path

    from google.cloud.storage import Client, transfer_manager

    storage_client = Client()
    bucket = storage_client.bucket(bucket_name)

    # Generate a list of paths (in string form) relative to the `directory`.
    # This can be done in a single list comprehension, but is expanded into
    # multiple lines here for clarity.

    # First, recursively get all files in `directory` as Path objects.
    directory_as_path_obj = Path(source_directory)
    paths = directory_as_path_obj.rglob("*")

    # Filter so the list only includes files, not directories themselves.
    file_paths = [path for path in paths if path.is_file()]

    # These paths are relative to the current working directory. Next, make them
    # relative to `directory`
    relative_paths = [path.relative_to(source_directory) for path in file_paths]

    # Finally, convert them all to strings.
    string_paths = [str(path) for path in relative_paths]

    print("Found {} files.".format(len(string_paths)))

    # Start the upload.
    results = transfer_manager.upload_many_from_filenames(
        bucket, string_paths, source_directory=source_directory, max_workers=workers
    )

    for name, result in zip(string_paths, results):
        # The results list is either `None` or an exception for each filename in
        # the input list, in order.

        if isinstance(result, Exception):
            print("Failed to upload {} due to exception: {}".format(name, result))
        else:
            print("Uploaded {} to {}.".format(name, bucket.name))

Ruby

자세한 내용은 Cloud Storage Ruby API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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

Terraform 리소스를 사용하여 객체를 업로드할 수 있습니다. content 또는 source를 지정해야 합니다.

# Create a text object in Cloud Storage
resource "google_storage_bucket_object" "default" {
  name = "new-object"
  # Use `source` or `content`
  # source       = "/path/to/an/object"
  content      = "Data as string to be uploaded"
  content_type = "text/plain"
  bucket       = google_storage_bucket.static.id
}

REST API

JSON API

JSON API에서는 요청에 객체 데이터만 포함된 미디어 업로드와 요청에 객체 데이터와 객체 메타데이터가 모두 포함된 JSON API 멀티파트 업로드를 구분합니다.

미디어 업로드(객체 메타데이터가 없는 단일 요청 업로드)

1. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

2. cURL를 사용하여 POST 객체 요청으로 JSON API를 호출합니다.

   curl -X POST --data-binary @OBJECT_LOCATION \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: OBJECT_CONTENT_TYPE" \
       "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=media&name=OBJECT_NAME"

   각 항목의 의미는 다음과 같습니다.

   • OBJECT_LOCATION은 객체의 로컬 경로입니다. 예를 들면 Desktop/dog.png입니다.
   • OBJECT_CONTENT_TYPE은 객체의 콘텐츠 유형입니다. 예를 들면 image/png입니다.
   • BUCKET_NAME은 객체를 업로드할 버킷의 이름입니다. 예를 들면 my-bucket입니다.
   • OBJECT_NAME은 객체에 지정할 URL 인코딩 이름입니다. 예를 들어 pets/dog.png는 pets%2Fdog.png로 URL 인코딩됩니다.

JSON API 멀티파트 업로드(객체 메타데이터가 포함된 단일 요청 업로드)

참고: Cloud Storage에서 기존 객체의 메타데이터를 추가하거나 변경하려면 객체 메타데이터 보기 및 수정을 참조하세요.

1. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

2. 다음 정보가 포함된 multipart/related 파일을 만듭니다.

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

   각 항목의 의미는 다음과 같습니다.

   • BOUNDARY_STRING은 멀티파트 파일의 여러 부분을 식별하는 문자열입니다. 예를 들면 separator_string입니다.
   • OBJECT_METADATA는 JSON 형식으로 파일에 포함할 메타데이터입니다. 이 섹션에는 최소한 객체의 name 속성(예: {"name": "myObject"})이 포함되어야 합니다.
   • OBJECT_CONTENT_TYPE은 객체의 콘텐츠 유형입니다. 예를 들면 text/plain입니다.
   • OBJECT_DATA는 객체의 데이터입니다.

   예를 들면 다음과 같습니다.

   --separator_string
   Content-Type: application/json; charset=UTF-8
   
   {"name":"my-document.txt"}
   
   --separator_string
   Content-Type: text/plain
   
   This is a text file.
   --separator_string--

3. cURL을 사용하여 POST 객체 요청으로 JSON API를 호출합니다.

   curl -X POST --data-binary @MULTIPART_FILE_LOCATION \
       -H "Authorization: Bearer $(gcloud auth print-access-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"

   각 항목의 의미는 다음과 같습니다.

   • MULTIPART_FILE_LOCATION은 2단계에서 만든 멀티파트 파일의 로컬 경로입니다. 예를 들면 Desktop/my-upload.multipart입니다.
   • BOUNDARY_STRING은 2단계에서 정의한 경계 문자열입니다. 예를 들면 my-boundary입니다.
   • MULTIPART_FILE_SIZE는 2단계에서 만든 멀티파트 파일의 총 크기(바이트)입니다. 예를 들면 2000000입니다.
   • BUCKET_NAME은 객체를 업로드할 버킷의 이름입니다. 예를 들면 my-bucket입니다.

요청이 성공하면 서버는 HTTP 200 OK 상태 코드와 해당 파일의 메타데이터를 반환합니다.

XML API

1. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

2. cURL를 사용하여 PUT 객체 요청으로 XML API를 호출합니다.

   curl -X PUT --data-binary @OBJECT_LOCATION \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: OBJECT_CONTENT_TYPE" \
       "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

   각 항목의 의미는 다음과 같습니다.

   • OBJECT_LOCATION은 객체의 로컬 경로입니다. 예를 들면 Desktop/dog.png입니다.
   • OBJECT_CONTENT_TYPE은 객체의 콘텐츠 유형입니다. 예를 들면 image/png입니다.
   • BUCKET_NAME은 객체를 업로드할 버킷의 이름입니다. 예를 들면 my-bucket입니다.
   • OBJECT_NAME은 객체에 지정할 URL 인코딩 이름입니다. 예를 들어 pets/dog.png는 pets%2Fdog.png로 URL 인코딩됩니다.

위의 예시에서 Content-Type을 설정하는 것과 같은 방식으로 요청 헤더에서 객체 업로드의 일부로 추가 객체 메타데이터를 설정할 수 있습니다. XML API를 사용할 때는 객체를 업로드, 이동 또는 복사할 때처럼 객체가 쓰여지는 시점에만 메타데이터를 설정할 수 있습니다. 자세한 내용은 객체 메타데이터 수정을 참조하세요.

다음 단계

• 객체 이름 지정 요구사항 알아보기
• 폴더를 사용하여 객체를 정리하는 방법을 알아보세요.
• Compute Engine 인스턴스에서 객체 전송
• 클라우드 제공업체 또는 기타 온라인 소스에서 데이터 전송(예: URL 목록)
• 객체 및 버킷에 액세스할 수 있는 사용자 제어
• 객체 URL을 포함한 객체 메타데이터 보기

직접 사용해 보기

Google Cloud를 처음 사용하는 경우 계정을 만들어 실제 시나리오에서 Cloud Storage의 성능을 평가할 수 있습니다. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

Cloud Storage 무료로 사용해 보기