이 페이지에서는 로컬 파일 시스템에서 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 사용을 참조하세요.
버킷에 객체 업로드
버킷에 객체를 업로드하려면 다음 단계를 완료하세요.
콘솔
- Google Cloud 콘솔에서 Cloud Storage 버킷 페이지로 이동합니다.
버킷 목록에서 객체를 업로드할 버킷의 이름을 클릭합니다.
버킷의 객체 탭에서 다음 중 하나를 수행합니다.
바탕화면이나 파일 관리자에서 Google Cloud 콘솔의 기본 창으로 파일을 드래그합니다.
파일 업로드 버튼을 클릭하고 나타나는 대화상자에서 업로드할 파일을 선택하고 열기를 클릭합니다.
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
클라이언트 라이브러리
C++
자세한 내용은 Cloud Storage C++ API 참고 문서를 확인하세요.
Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
C#
자세한 내용은 Cloud Storage C# API 참고 문서를 확인하세요.
Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Go
자세한 내용은 Cloud Storage Go API 참고 문서를 확인하세요.
Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Java
자세한 내용은 Cloud Storage Java API 참고 문서를 확인하세요.
Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
다음 샘플은 개별 객체를 업로드합니다.
다음 샘플은 객체 여러 개를 동시에 업로드합니다.
다음 샘플에서는 공통 프리픽스가 있는 모든 객체를 동시에 업로드합니다.
Node.js
자세한 내용은 Cloud Storage Node.js API 참조 문서를 확인하세요.
Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
다음 샘플은 개별 객체를 업로드합니다.
다음 샘플은 객체 여러 개를 동시에 업로드합니다.
다음 샘플에서는 공통 프리픽스가 있는 모든 객체를 동시에 업로드합니다.
PHP
자세한 내용은 Cloud Storage PHP API 참조 문서를 확인하세요.
Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Python
자세한 내용은 Cloud Storage Python API 참고 문서를 확인하세요.
Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
다음 샘플은 개별 객체를 업로드합니다.
다음 샘플은 객체 여러 개를 동시에 업로드합니다.
다음 샘플에서는 공통 프리픽스가 있는 모든 객체를 동시에 업로드합니다.
Ruby
자세한 내용은 Cloud Storage Ruby API 참조 문서를 확인하세요.
Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Terraform
Terraform 리소스를 사용하여 객체를 업로드할 수 있습니다.
content
또는 source
를 지정해야 합니다.
REST API
JSON API
JSON API에서는 요청에 객체 데이터만 포함된 미디어 업로드와 요청에 객체 데이터와 객체 메타데이터가 모두 포함된 JSON API 멀티파트 업로드를 구분합니다.
미디어 업로드(객체 메타데이터가 없는 단일 요청 업로드)
Authorization
헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.또는 OAuth 2.0 Playground를 사용하여 액세스 토큰을 만들고
Authorization
헤더에 포함할 수 있습니다.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 멀티파트 업로드(객체 메타데이터가 포함된 단일 요청 업로드)
Authorization
헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.또는 OAuth 2.0 Playground를 사용하여 액세스 토큰을 만들고
Authorization
헤더에 포함할 수 있습니다.다음 정보를 포함하는
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--
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
Authorization
헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.또는 OAuth 2.0 Playground를 사용하여 액세스 토큰을 만들고
Authorization
헤더에 포함할 수 있습니다.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 무료로 사용해 보기