동시 복합 업로드

대용량 파일을 업로드하는 한 가지 방법은 동시 복합 업로드입니다. 이러한 업로드에서 파일은 최대 32개의 청크로 분할되고, 청크가 임시 객체에 동시에 업로드된 다음, 최종 객체가 임시 객체를 사용하여 다시 생성되고, 임시 객체가 삭제됩니다.

네트워크 및 디스크 속도가 제한 요소가 아닌 경우 동시 복합 업로드 속도가 훨씬 빨라질 수 있습니다. 하지만 버킷에 저장된 최종 객체는 복합 객체이며, MD5 해시가 아닌 crc32c 해시만 있습니다. 따라서 Python 애플리케이션으로 객체를 다운로드할 때 crcmod를 사용하여 무결성 검사를 수행해야 합니다. 다음이 적용되는 경우에만 동시 복합 업로드를 수행해야 합니다.

업로드된 객체에는 MD5 해시가 없어도 됩니다.
gsutil 사용자를 포함하여 객체를 다운로드해야 하는 모든 Python 사용자에게 google-crc32c 또는 crcmod가 설치되어 있습니다.

예를 들어 Python을 사용하여 Java 애플리케이션에서만 제공하는 동영상 애셋을 업로드하는 경우 Java에서 사용할 수 있는 효율적인 CRC32C 구현이 있으므로 동시 복합 업로드가 적합합니다.

도구 및 API에서 동시 복합 업로드를 사용하는 방법

Cloud Storage와 상호작용하는 방법에 따라 동시 복합 업로드가 자동으로 대신 관리될 수 있습니다. 이 섹션에서는 다양한 도구에 대한 동시 복합 업로드 동작을 설명하고 동작을 수정하는 방법에 대한 정보를 제공합니다.

Console

Google Cloud 콘솔은 동시 복합 업로드를 수행하지 않습니다.

명령줄

다음 속성을 수정하여 gcloud storage cp에서 동시 복합 업로드의 수행 방법과 시기를 구성할 수 있습니다.

storage/parallel_composite_upload_enabled: 동시 복합 업로드를 사용 설정하는 속성입니다. False인 경우 동시 복합 업로드를 사용 중지합니다. True 또는 None인 경우 다른 속성에 정의된 기준을 충족하는 객체에 대해 동시 복합 업로드를 수행합니다. 기본 설정은 None입니다.
storage/parallel_composite_upload_compatibility_check: 안전 확인을 전환하는 속성입니다. True이면 gcloud storage는 다음 조건이 모두 충족되는 경우에만 동시 복합 업로드를 수행합니다.
- 업로드된 객체의 스토리지 클래스는 STANDARD입니다.
- 대상 버킷에 보관 정책이 없습니다.
- 대상 버킷에 기본 객체 보존 조치가 사용 설정되지 않았습니다.
이러한 조건을 확인하기 위해 gcloud CLI는 업로드 명령어의 일부로 대상 버킷에 대해 메타데이터를 검색합니다.

False이면 gcloud storage는 확인을 수행하지 않습니다. 기본 설정은 True입니다.
storage/parallel_composite_upload_threshold: 동시 복합 업로드를 수행하는 데 필요한 최소한의 총 파일 크기입니다. 기본 설정은 150MiB입니다.
storage/parallel_composite_upload_component_size: 각 임시 객체의 최대 크기입니다. 총 파일 크기가 너무 커서 이 크기에서 32개 청크를 초과해야 하는 경우 속성은 무시됩니다.
storage/parallel_composite_upload_component_prefix: 임시 객체의 이름을 지정할 때 사용되는 프리픽스입니다. 이 속성은 절대 경로 또는 최종 객체에 상대적인 경로로 설정할 수 있습니다. 자세한 내용은 속성 설명을 참조하세요. 기본 프리픽스는 절대 경로 /gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details입니다.

이름이 지정된 구성을 만들고 --configuration project-wide 플래그를 사용하여 명령별로 구성을 적용하거나 gcloud config set 명령어를 사용하여 모든 gcloud CLI 명령어에 대해 구성을 적용하여 이러한 속성을 수정할 수 있습니다.

gcloud CLI를 사용하여 동시 복합 업로드를 수행하면 로컬 디스크 공간이 추가로 필요하지 않습니다. 조합하기 전에 동시 복합 업로드가 실패하면 gcloud CLI 명령어를 다시 실행하여 실패한 임시 객체에 재개 가능한 업로드를 활용합니다. 업로드가 실패하기 전에 성공적으로 업로드된 임시 객체는 업로드를 재개할 때 다시 업로드되지 않습니다.

임시 객체의 이름은 다음과 같은 방식으로 지정됩니다.

TEMPORARY_PREFIX/RANDOM_VALUE_HEX_DIGEST_COMPONENT_ID

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

TEMPORARY_PREFIX는 storage/parallel_composite_upload_component_prefix 속성에 의해 제어됩니다.
RANDOM_VALUE은 임의의 숫자 값입니다.
HEX_DIGEST는 소스 리소스 이름에서 파생된 해시입니다.
COMPONENT_ID는 구성요소의 순차 번호입니다.

일반적으로 임시 객체는 동시 복합 업로드 종료 시 삭제되지만, 임시 객체가 주변에 남지 않도록 하려면 gcloud CLI 명령어에서 종료 상태를 확인한 후 중단된 업로드의 일부로 업로드된 임시 객체를 수동으로 삭제해야 합니다.

클라이언트 라이브러리

Java

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

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

AllowParallelCompositeUpload를 true로 설정하여 동시 복합 업로드를 수행할 수 있습니다. 예를 들면 다음과 같습니다.

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 AllowParallelCompositeUpload {

  public static void parallelCompositeUploadAllowed(String bucketName, List<Path> files)
      throws IOException {
    TransferManager transferManager =
        TransferManagerConfig.newBuilder()
            .setAllowParallelCompositeUpload(true)
            .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());
    }
  }
}

Node.js

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

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

Node.js 클라이언트 라이브러리는 동시 복합 업로드를 지원하지 않습니다. 대신 XML API 멀티파트 업로드를 사용하세요.

Python

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

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

Python 클라이언트 라이브러리는 동시 복합 업로드를 지원하지 않습니다. 대신 XML API 멀티파트 업로드를 사용하세요.

REST API

JSON API 및 XML API 모두 객체 청크를 동시에 업로드하고 compose 작업을 사용하여 단일 객체로 다시 통합할 수 있습니다.

동시 복합 업로드의 코드를 설계할 때는 다음 사항에 유의하세요.

compose 작업을 사용하는 경우 소스 객체는 조합 프로세스의 영향을 받지 않습니다.

즉, 임시로 사용하려는 경우에는 조합이 성공적으로 완료된 후 이를 명시적으로 삭제해야 합니다. 그렇지 않으면 소스 객체가 버킷에 남아 있고 그에 따라 요금이 청구됩니다.
업로드 및 조합 요청 간에 소스 객체가 변경되지 않도록 보호하려면 각 소스에 대해 예상되는 생성 수를 제공해야 합니다.