객체 업로드

이 페이지에서는 Cloud Storage 버킷에 객체를 업로드하는 방법을 설명합니다. 업로드된 객체는 관련 메타데이터와 저장할 데이터로 구성됩니다. 개념 개요는 업로드 및 다운로드를 참조하세요.

기본 요건

프로젝트의 버킷에 객체를 업로드하려면 프로젝트에 대한 storage.objects.create IAM 권한이 있어야 합니다. 직접 만들지 않은 프로젝트 내에서 작업을 수행하는 경우 프로젝트 소유자에게 이 권한을 포함하는 스토리지 객체 생성자 같은 역할을 부여해 달라고 해야 할 수 있습니다.

전체 역할 목록은 Cloud Storage 역할을 참조하세요. 보다 제한된 권한이 있는 역할이 필요하면 커스텀 역할 만들기 및 관리를 참조하세요.

버킷에 객체 업로드

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

콘솔

  1. Google Cloud Console에서 Cloud Storage 브라우저 페이지로 이동합니다.

    브라우저로 이동

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

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

    • 원하는 파일을 바탕화면이나 파일 관리자에서 Cloud Console의 기본 창으로 드래그 앤 드롭합니다.

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

Cloud Storage 브라우저에서 실패한 작업에 대한 자세한 오류 정보를 얻는 방법은 문제 해결을 참조하세요.

gsutil

gsutil cp 명령어를 사용합니다.

gsutil cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME/

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

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

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

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

Operation completed over 1 objects/58.8 KiB.

-h 최상위 수준 옵션을 사용하여 요청 헤더에서 객체 업로드의 일부로 고정 키 및 커스텀 객체 메타데이터를 설정할 수 있습니다.

코드 샘플

C++

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

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#

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


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 참조 문서를 확인하세요.

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()

	// Upload an object with storage.Writer.
	wc := client.Bucket(bucket).Object(object).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
}

자바

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

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"

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

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

Node.js

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

스트림, 문자열, 버퍼 업로드에 대한 자세한 내용은 File.save()를 참조하세요.
/**
 * 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() {
  await storage.bucket(bucketName).upload(filePath, {
    destination: destFileName,
  });

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

uploadFile().catch(console.error);

PHP

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

use Google\Cloud\Storage\StorageClient;

/**
 * Upload a file.
 *
 * @param string $bucketName the name of your Google Cloud bucket.
 * @param string $objectName the name of the object.
 * @param string $source the path to the file to upload.
 *
 * @return Psr\Http\Message\StreamInterface
 */
function upload_object($bucketName, $objectName, $source)
{
    $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

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

Blob.upload_from_file(), Blob.upload_from_filename() 또는 Blob.upload_from_string() 메서드를 사용하여 객체를 업로드합니다.
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(
        "File {} uploaded to {}.".format(
            source_file_name, destination_blob_name
        )
    )

Ruby

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

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

  file = bucket.create_file local_file_path, file_name

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

REST API

JSON API

객체 메타데이터가 없는 단일 요청 업로드

  1. OAuth 2.0 Playground에서 승인 액세스 토큰을 가져옵니다. 자체 OAuth 사용자 인증 정보를 사용하도록 플레이그라운드를 구성합니다.
  2. cURL을 사용하여 POST 객체 요청으로 JSON API를 호출합니다.

    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"

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

    • OBJECT_LOCATION은 객체의 로컬 경로입니다. 예를 들면 Desktop/dog.png입니다.
    • OAUTH2_TOKEN은 1단계에서 생성한 액세스 토큰입니다.
    • OBJECT_CONTENT_TYPE은 객체의 콘텐츠 유형입니다. 예를 들면 image/png입니다.
    • BUCKET_NAME은 객체를 업로드할 버킷의 이름입니다. 예를 들면 my-bucket입니다.
    • OBJECT_NAME은 객체에 지정하려는 이름입니다. 예를 들면 pets/dog.png입니다.

객체 메타데이터가 포함된 단일 요청 업로드

  1. OAuth 2.0 Playground에서 승인 액세스 토큰을 가져옵니다. 자체 OAuth 사용자 인증 정보를 사용하도록 플레이그라운드를 구성합니다.
  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은 멀티파트 파일의 여러 부분을 식별하는 문자열입니다. 예를 들면 my-boundary입니다.
    • OBJECT_METADATA는 JSON 형식으로 파일에 포함할 메타데이터입니다. 이 섹션에는 최소한 객체의 name 속성(예: {"name": "myObject"})이 포함되어야 합니다.
    • OBJECT_CONTENT_TYPE은 객체의 콘텐츠 유형입니다. 예를 들면 image/png입니다.
    • OBJECT_DATA는 객체의 데이터입니다.
  3. cURL을 사용하여 POST 객체 요청으로 JSON API를 호출합니다.

    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"

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

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

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

XML API

  1. OAuth 2.0 Playground에서 승인 액세스 토큰을 가져옵니다. 자체 OAuth 사용자 인증 정보를 사용하도록 플레이그라운드를 구성합니다.
  2. cURL을 사용하여 PUT 객체 요청으로 XML API를 호출합니다.

    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"

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

    • OBJECT_LOCATION은 객체의 로컬 경로입니다. 예를 들면 Desktop/dog.png입니다.
    • OAUTH2_TOKEN은 1단계에서 생성한 액세스 토큰입니다.
    • OBJECT_CONTENT_TYPE은 객체의 콘텐츠 유형입니다. 예를 들면 image/png입니다.
    • BUCKET_NAME은 객체를 업로드할 버킷의 이름입니다. 예를 들면 my-bucket입니다.
    • OBJECT_NAME은 객체에 지정하려는 이름입니다. 예를 들면 pets/dog.png입니다.

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

다음 단계

직접 사용해 보기

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

Cloud Storage 무료로 사용해 보기