이 페이지에서는 Cloud Storage의 리소스인 객체를 설명합니다. Cloud Storage 작동 방식에 대한 일반적인 개요는 Cloud Storage 제품 개요를 참조하세요.
객체
객체는 Cloud Storage에 저장되는 개별 데이터 조각입니다. 버킷에서 만들 수 있는 객체 수에는 제한이 없습니다.
객체에는 객체 데이터와 객체 메타데이터의 두 가지 구성요소가 있습니다. 객체 데이터는 일반적으로 Cloud Storage에 저장하려는 파일이며 Cloud Storage에 완전히 불투명합니다. 객체 메타데이터는 객체의 다양한 질적 측면을 설명하는 이름-값 쌍의 모음입니다.
모든 객체에 일반적인 객체 메타데이터에서 중요한 두 가지 항목은 해당 객체의 이름과 생성 번호입니다. Cloud Storage 버킷에 객체를 추가할 때 객체 이름을 지정하면 Cloud Storage가 생성 번호를 할당합니다. 이름과 생성 번호는 버킷 내에서 객체를 고유하게 식별합니다.
액세스 제어 목록(ACL)을 사용하여 개별 객체에 대한 액세스를 제어할 수 있습니다. Identity and Access Management(IAM)를 사용하여 버킷이나 관리형 폴더 내 모든 객체에 대한 액세스를 제어할 수도 있습니다.
이름 지정 고려사항
Cloud Storage에서 객체 이름을 지정할 때는 호환성을 보장하고 오류를 방지하기 위해 특정 요구사항을 준수해야 합니다. 이 요구사항은 평면 네임스페이스 버킷과 계층적 네임스페이스가 사용 설정된 버킷 모두에 적용됩니다.
일반 요구사항
- 객체 이름에는 유효한 Unicode 문자를 어떤 순서로든 포함할 수 있습니다.
- 객체 이름에는 캐리지 리턴 문자나 줄바꿈 문자가 포함될 수 없습니다.
- 객체 이름은
.well-known/acme-challenge/로 시작할 수 없습니다. - 객체 이름은
.또는..으로 지정할 수 없습니다.
네임스페이스별 객체 크기 제한
객체 이름의 최대 크기는 버킷의 네임스페이스에 따라 다릅니다.
- 단일 구조 네임스페이스 버킷의 객체 이름 크기: UTF-8로 인코딩 시 1~1,024바이트
계층적 네임스페이스가 사용 설정된 버킷의 객체 이름 크기: 객체 이름은 두 부분으로 나눌 수 있습니다.
- Folder name(폴더 이름): 객체가 있는 폴더의 이름입니다. UTF-8로 인코딩된 경우 폴더 이름의 최대 크기는 512바이트입니다.
- Base name: 폴더에 있는 객체의 이름입니다. UTF-8로 인코딩된 경우 기본 이름의 최대 크기는 512바이트입니다.
예를 들어 경로
my-folder/my-object.txt는my-folder/라는 폴더 내에 저장된 기본 이름이my-object.txt인 객체를 나타냅니다.
권장사항
객체 이름에 다음을 사용하지 않는 것이 좋습니다.
- XML 1.0에서 허용되지 않는 제어 문자(#x7F–#x84 and #x86–#x9F): 객체 나열 시 이러한 문자로 인해 XML 나열 문제가 발생합니다.
#문자: Google Cloud CLI 명령어는 #<숫자 문자열>로 끝나는 객체 이름을 버전 식별자로 해석하므로 객체 이름에#을 포함하면 gcloud CLI를 사용하여 이러한 버전 관리 객체에 대한 작업을 수행하는 것이 어렵거나 불가능할 수 있습니다.[,],*,?문자: Google Cloud CLI 명령어는 이러한 문자를 와일드 카드로 해석하므로 객체 이름에 이러한 문자를 포함하면 와일드 카드 작업 수행이 어렵거나 불가능할 수 있습니다. 또한*와?는 Windows에서 파일 이름에 유효한 문자가 아닙니다.:,",<,>,|문자: Windows에서 파일 이름에 유효한 문자가 아니므로 다운로드 방법에 Windows 파일 이름 변경이 포함되지 않는 한 이름에 이러한 문자를 사용하는 객체를 Windows 파일에 다운로드하지 못합니다./문자도 Windows에서 파일 이름에 유효한 문자는 아니지만 일반적으로 디렉터리 구조를 모방하기 위해 객체 이름에 사용할 수 있습니다. Google Cloud CLI와 같은 도구는 Windows 환경에 다운로드할 때 문자를 자동으로\로 변환합니다.- 민감한 정보나 개인 식별 정보(PII): 객체 이름이 객체 데이터보다 더 광범위하게 표시됩니다. 예를 들어, 객체 이름은 객체의 URL과 버킷의 객체를 나열할 때 표시됩니다.
기존 객체의 이름을 직접 바꿀 수는 없지만 원본 객체를 복사하고 삭제하여 객체의 이름을 간접적으로 변경할 수 있습니다.
객체 네임스페이스
다음 네임스페이스에 객체를 저장할 수 있습니다.
평면 네임스페이스
플랫 네임스페이스가 있는 버킷은 계층 구조가 없는 플랫 구조에 객체를 저장합니다. 즉, 디렉터리나 폴더가 없습니다.
편의를 위해 객체는 폴더 계층 구조에 저장된 것처럼 처리되는 방법이 여러 가지 있습니다.
관리형 폴더는 공유 이름 접두사가 있는 객체 그룹에 대한 확장된 액세스를 제공하는 Cloud Storage 리소스입니다.
Google Cloud 콘솔 및 Google Cloud CLI와 같은 도구는 버킷의 폴더를 시뮬레이션하기 위해 객체 이름의 슬래시 (
/) 문자를 구분 기호로 해석합니다.
예를 들어 your-bucket 버킷에 folder1/file.txt라는 객체를 만들면 객체의 경로는 your-bucket/folder1/file.txt이고 Cloud Storage에는 그 안에 저장된 folder1이라는 폴더가 없습니다. Cloud Storage의 관점에서 문자열 folder1/은 객체 이름의 일부입니다.
그러나 객체의 이름에 /가 있으므로 일부 도구는 폴더의 모습을 구현합니다. 예를 들어 Google Cloud 콘솔을 사용하면 folder1이라는 이름이 지정된 폴더 내에 이름이 file1.txt인 객체가 있다고 간주하여 folder1/file1.txt 객체로 이동합니다. 마찬가지로 folder1이라는 관리형 폴더를 만들면 file1.txt가 이 관리형 폴더에 설정된 액세스 정책의 적용을 받습니다.
객체는 플랫 네임스페이스에 있으므로 복잡하게 중첩된 디렉터리 형태의 구조에는 복잡하게 중첩된 하위 디렉터리를 나열하는 기본 파일 시스템의 성능이 없습니다.
대규모 업로드 중에 순차적 이름을 사용하지 않고 성능을 최적화하는 방법은 요청 비율 권장사항을 참조하세요. 순차적 이름으로 업로드된 객체는 동일한 백엔드 서버에 도달하여 성능을 제한할 수 있습니다.
시뮬레이션된 폴더
Cloud Storage 버킷에서 객체를 구성하는 데 도움이 되도록 일부 도구는 폴더를 시뮬레이션하며 JSON 및 XML API 모두 개발자가 고유한 이름 지정 스킴을 설계하여 폴더를 시뮬레이션할 수 있는 기능이 있습니다. 다음 탭을 클릭하여 여러 도구에서 시뮬레이션된 폴더를 처리하는 방식을 확인합니다.
콘솔
Google Cloud 콘솔은 로컬 파일 브라우저와 유사하게 폴더를 시각적으로 표현합니다.
Google Cloud 콘솔에서 버킷에 빈 폴더를 만들거나 기존 폴더를 업로드할 수 있습니다.
기존 폴더를 업로드하면 폴더 이름이 폴더에 포함된 모든 객체의 경로에 포함됩니다. 모든 하위 폴더 및 하위 폴더에 포함된 객체도 업로드에 포함됩니다.
폴더를 만드는 방법은 다음과 같습니다.
- Google Cloud 콘솔에서 Cloud Storage 버킷 페이지로 이동합니다.
버킷으로 이동합니다.
폴더 만들기를 클릭하여 비어 있는 새 폴더를 만들거나 폴더 업로드를 클릭하여 기존 폴더를 업로드합니다.
명령줄
Cloud Storage CLI는 다양한 규칙을 사용하여 일반적인 명령줄 디렉터리 환경을 시뮬레이션합니다.
계층적 파일 트리를 갖춘 것 같은 효과를 내기 위해 gcloud CLI는 다음 규칙을 적용하여 명령어의 도착 URL을 객체 이름으로 취급할지 또는 폴더로 취급할지 여부를 결정합니다.
도착 URL이
/문자로 끝나면 gcloud CLI 명령어는 도착 URL을 폴더로 처리합니다. 예를 들어 다음 명령어를 가정해 보겠습니다. 여기서your-file은 파일 이름입니다.gcloud storage cp your-file gs://your-bucket/abc/
이 명령어의 결과로 Cloud Storage는
your-bucket버킷에abc/your-file이라는 객체를 만듭니다.--recursive플래그 또는**와 같은 와일드 카드를 사용하여 소스 파일 여러 개를 대상 URL에 복사하면 gcloud CLI에서 대상 URL을 폴더로 처리합니다. 예를 들어 다음 명령어를 가정해 보겠습니다. 여기서top-dir은file1및file2와 같은 파일이 포함된 폴더입니다.gcloud storage cp top-dir gs://your-bucket/abc --recursive
이 명령어의 결과로 Cloud Storage는
your-bucket버킷에abc/top-dir/file1및abc/top-dir/file2객체를 만듭니다.이러한 규칙 중 어느 규칙이라도 적용되지 않으면 gcloud CLI가 버킷의 객체를 검사하여 도착 URL이 객체 이름인지 폴더인지 확인합니다. 예를 들어 다음 명령어를 가정해 보겠습니다. 여기서
your-file은 파일 이름입니다.gcloud storage cp your-file gs://your-bucket/abc
gcloud CLI는 경로가
abc/로 시작하는your-bucket에 객체가 있는지 확인하기 위해/구분 기호와 프리픽스=abc를 사용하여your-bucket에 객체 나열 요청을 수행합니다. 이런 경우 gcloud CLI는abc/를 폴더 이름으로 취급하며 명령어는your-bucket버킷에abc/your-file객체를 만듭니다. 그렇지 않으면 gcloud CLI에서abc객체를your-bucket에 만듭니다.
이 규칙 기반 접근 방식은 대부분의 도구가 폴더 존재를 표시하기 위해 0바이트 객체를 만드는 방식으로 작동하는 것과 다릅니다. gcloud CLI는 0바이트 객체 이름 끝에 _$folder$를 추가하는 규칙과 같이 이러한 도구에서 사용되는 여러 규칙을 이해하지만 UNIX 명령어와 일관된 이름 지정 동작을 구현할 때 이러한 마커 객체가 필요하지 않습니다.
이러한 규칙 외에도 gcloud CLI에서 소스 파일을 처리하는 방식은 --recursive 플래그를 사용하는지 여부에 따라 다릅니다. 이 플래그를 사용하면 gcloud CLI는 재귀 처리 지점부터 소스 디렉터리 구조를 미러링하는 객체 이름을 구성합니다. 예를 들어 다음 명령어를 가정해 보겠습니다. 여기서 home/top-dir은 file1 및 sub-dir/file2와 같은 파일이 포함된 폴더입니다.
gcloud storage cp home/top-dir gs://your-bucket --recursive
이 명령어의 결과로 Cloud Storage는 your-bucket 버킷에 top-dir/file1 및 top-dir/sub-dir/file2 객체를 만듭니다.
반면 --recursive 플래그 없이 복사하면 **와 같은 와일드 카드가 있어 여러 파일이 복사되더라도 소스 파일의 최종 경로 구성요소로 이름이 지정된 객체가 생성됩니다. 예를 들어 home/top-dir이 file1 및 sub-dir/file2와 같은 파일이 포함된 폴더라고 가정하면 명령어가 다음을 수행합니다.
gcloud storage cp home/top-dir/** gs://your-bucket
your-bucket 버킷에 file1이라는 객체와 file2라는 객체를 만듭니다.
재시도 및 이름 지정
gcloud CLI가 중단된 요청을 재시도할 때 첫 번째 시도에서 파일의 하위 집합을 복사하면 이후 시도에 이미 존재하는 대상 폴더가 발생하고 이로 인해 객체 이름이 잘못 지정되는 문제가 생길 수 있습니다.
예를 들어 your-dir/ 아래에 dir1 및 dir2와 같은 하위 폴더가 있고 두 하위 폴더에 abc 파일이 포함되어 있다고 가정해 보겠습니다.
gcloud storage cp ./your-dir gs://your-bucket/new --recursive
경로 gs://your-bucket/new가 아직 없으면 첫 번째 성공적인 시도에서 gcloud CLI가 다음 객체를 만듭니다.
new/dir1/abc new/dir2/abc
하지만 다음에 같은 명령어를 성공적으로 시도하면 gcloud CLI에서 다음 객체를 만듭니다.
new/your-dir/dir1/abc new/your-dir/dir2/abc
모든 시도에서 gcloud CLI를 일관되게 사용하려면 다음을 시도해 보세요.
도착 URL 끝에 슬래시를 추가하여 gcloud CLI에서 항상 폴더로 처리하도록 합니다.
gcloud storage rsync을 사용합니다.rsync는 Unix cp 정의 폴더 이름 지정 규칙을 사용하지 않으므로 대상 하위 폴더 존재 여부에 관계없이 일관되게 작동합니다.
기타 참고사항
gcloud CLI를 사용하여 0바이트 객체를 만들어 빈 폴더로 위장할 수 없습니다
로컬 파일 시스템에 다운로드할 때 gcloud CLI는 이름이
/문자로 끝나는 객체를 건너뜁니다. Linux 및 macOS에서는/로 끝나는 파일을 만들 수 없기 때문입니다.스크립트를 사용하여 하위 경로를 결합하여 파일 경로를 만드는 경우
/는 객체 이름에 발생하는 문자이므로 CLI는gs://your-bucket/folder/를gs://your-bucket//folder에 있는 다른 객체로 해석합니다.
REST API
JSON API
폴더는 JSON API에 존재하지 않습니다. prefix 및 delimiter 쿼리 매개변수를 사용하여 나열하는 객체 범위를 좁히고 폴더를 시뮬레이션할 수 있습니다.
예를 들어 프리픽스 folder/subfolder/가 있는 my-bucket 버킷의 모든 객체를 나열하려면 다음 URL을 사용하여 객체 나열 요청을 보냅니다.
"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"
XML API
XML API에 폴더가 없으므로 나열하는 객체의 범위를 좁히고 prefix 및 delimiter 쿼리 매개변수를 사용하여 폴더를 시뮬레이션할 수 있습니다.
예를 들어 프리픽스 folder/subfolder/가 있는 my-bucket 버킷의 모든 객체를 나열하려면 다음 URL을 사용하여 객체 나열 요청을 보냅니다.
"https://storage.googleapis.com/my-bucket?prefix=folder/subfolder/"
시뮬레이션된 폴더 삭제
시뮬레이션된 폴더는 실제로 존재하지 않으므로 시뮬레이션된 폴더가 더 이상 객체 이름의 일부가 되지 않도록 객체 이름을 변경하여 시뮬레이션된 폴더를 삭제할 수 있습니다. 예를 들어 folder1/file 객체가 있는 경우 객체 이름을 file로 바꿔 시뮬레이션된 폴더 folder1/을 삭제할 수 있습니다.
그러나 Google Cloud 콘솔과 같이 폴더 자리표시자로 0바이트 객체를 만드는 도구를 사용한 경우 폴더를 삭제하려면 0바이트 객체를 삭제해야 합니다.
계층적 네임스페이스
계층적 네임스페이스를 사용하면 폴더 계층 구조와 같은 파일 시스템에서 Cloud Storage 버킷 내의 객체를 구성할 수 있습니다. 계층적 네임스페이스는 성능을 개선하고 데이터를 효율적으로 관리하는 데 도움이 됩니다. 계층적 네임스페이스 및 사용 시기 자세히 알아보기: 계층적 네임스페이스
객체 불변성
객체는 변경이 불가능합니다. 즉, 스토리지 전체 기간 동안 업로드한 객체를 변경할 수 없습니다. 객체의 스토리지 전체 기간은 업로드와 같은 성공적인 객체 생성과 성공적인 객체 삭제 사이의 시간입니다. 즉, 추가 작업이나 자르기 작업과 같이 객체를 점진적으로 변경할 수 없습니다. 하지만 Cloud Storage에 저장된 객체를 대체할 수 있으며 이 작업은 원자적으로 수행됩니다. 즉, 새 업로드가 완료될 때까지 이전 버전의 객체가 리더에 제공되고 업로드가 완료되면 새 버전의 객체가 리더에 제공됩니다. 대체 작업 하나는 불변 객체 하나의 수명 기간이 끝나고 새로운 불변 객체 수명 기간이 시작됨을 나타냅니다.
객체의 세대 번호는 객체 데이터를 바꿀 때마다 변경됩니다. 따라서 세대 번호는 변경할 수 없는 객체를 고유하게 식별합니다.
동일한 객체를 빠르게 바꿀 수 있는 초당 1회 한도가 있습니다. 동일한 객체를 자주 교체하면 429 Too Many Requests 오류가 발생할 수 있습니다. 초당 1회 이하로 특정 객체의 데이터를 업로드하고 지수 백오프 재시도 전략을 사용하여 비정기적인 429 Too Many Requests 오류를 처리하도록 애플리케이션을 설계해야 합니다.