XML API 멀티파트 업로드

이 페이지에서는 Cloud Storage의 XML API 멀티파트 업로드에 대해 설명합니다. 이 업로드 메서드는 파일을 여러 부분으로 업로드한 후 최종 요청을 사용해서 이를 단일 객체로 조합합니다. XML API 멀티파트 업로드는 Amazon S3 멀티파트 업로드와 호환됩니다.

개요

XML API 멀티파트 업로드를 사용하면 데이터를 여러 부분으로 업로드한 후 이를 최종 객체로 조합할 수 있습니다. 이 동작은 특히 대용량 파일에서 여러 이점이 있습니다.

  • 여러 부분을 동시에 업로드할 수 있으므로 데이터 전체를 업로드하는 데 걸리는 시간이 단축됩니다.

  • 업로드 작업 중 하나가 실패하면 처음부터 다시 시작할 필요 없이 전체 객체의 일부만 다시 업로드하면 됩니다.

  • 전체 파일 크기가 미리 지정되지 않았으므로 스트리밍 업로드 또는 업로드하는 동안 데이터를 즉시 압축하기 위해 XML API 멀티파트 업로드를 사용할 수 있습니다.

XML API 멀티파트 업로드에는 다음 세 가지 필수 단계가 있습니다.

  1. 완료된 객체에 포함되어야 하는 메타데이터 지정이 포함된 POST 요청을 사용하여 업로드를 시작합니다. 업로드와 연관된 모든 이후 요청에 사용하는 UploadId가 응답으로 반환됩니다.

  2. 하나 이상의 PUT 요청을 사용하여 데이터를 업로드합니다.

  3. POST 요청을 사용하여 업로드를 완료합니다. 이 요청은 동일한 이름의 버킷에 있는 기존 객체를 덮어씁니다.

멀티파트 업로드 및 업로드된 부분이 버킷에서 미완료 상태로 유지되거나 유휴 상태로 유지될 수 있는 시간에는 제한이 없습니다.

  • 성공적으로 업로드된 부분은 월별 스토리지 사용량에 포함됩니다.
  • 객체 수명 주기 관리를 사용하여 지정된 기간에 도달할 때 멀티파트 업로드를 자동으로 삭제하여 폐기된 멀티파트 업로드 축적을 방지할 수 있습니다.

고려사항

XML API 멀티파트 업로드를 사용할 때 다음 제한사항이 적용됩니다.

  • 한 파트의 최소 크기, 최대 크기, 완료된 업로드를 조합하는 데 사용되는 파트 수에 한도가 있습니다.
  • 전제조건은 이 요청에서 지원되지 않습니다.
  • 이 메서드를 사용하여 업로드된 객체에 대해서는 MD5 해시가 존재하지 않습니다.
  • 이 업로드 메서드는 Google Cloud 콘솔 또는 Google Cloud CLI에서 지원되지 않습니다.

XML API 멀티파트 업로드로 작업할 때는 다음 사항에 유의하세요.

  • XML API 멀티파트 업로드에는 특정 IAM 권한이 있습니다. 커스텀 IAM 역할을 사용하는 경우 이러한 역할에 필요한 권한이 있는지 확인해야 합니다.

  • 부분 업로드를 시작하고 업로드할 수는 있지만 보존 조치가 적용된 객체 또는 처리되지 않은 보관 기간이 있는 객체를 덮어쓰는 경우 업로드 완료 요청이 실패합니다.

  • 버킷에서 진행 중인 업로드를 나열할 수 있지만 완료된 업로드만 버킷의 정상 객체 목록에 표시됩니다.

  • 업로드된 부분을 사용하지 않으면 조기 삭제 요금이 적용될 수 있습니다.

클라이언트 라이브러리가 XML API 멀티파트 업로드를 사용하는 방법

이 섹션에서는 이를 지원하는 클라이언트 라이브러리로 XML API 멀티파트 업로드를 수행하는 방법을 설명합니다.

클라이언트 라이브러리

Java

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

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

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

Node.js

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

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

uploadFileInChunks 메서드를 사용하여 XML API 멀티파트 업로드를 수행할 수 있습니다. 예를 들면 다음과 같습니다.

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

// The path of file to upload
// const filePath = 'path/to/your/file';

// The size of each chunk to be uploaded
// const chunkSize = 32 * 1024 * 1024;

// 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 uploadFileInChunksWithTransferManager() {
  // Uploads the files
  await transferManager.uploadFileInChunks(filePath, {
    chunkSizeBytes: chunkSize,
  });

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

uploadFileInChunksWithTransferManager().catch(console.error);

Python

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

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

upload_chunks_concurrently 메서드를 사용하여 XML API 멀티파트 업로드를 수행할 수 있습니다. 예를 들면 다음과 같습니다.

def upload_chunks_concurrently(
    bucket_name,
    source_filename,
    destination_blob_name,
    chunk_size=32 * 1024 * 1024,
    workers=8,
):
    """Upload a single file, in chunks, concurrently in a process pool."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The path to your file to upload
    # source_filename = "local/path/to/file"

    # The ID of your GCS object
    # destination_blob_name = "storage-object-name"

    # The size of each chunk. The performance impact of this value depends on
    # the use case. The remote service has a minimum of 5 MiB and a maximum of
    # 5 GiB.
    # chunk_size = 32 * 1024 * 1024 (32 MiB)

    # The maximum number of processes to use for the operation. The performance
    # impact of this value depends on the use case. 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)
    blob = bucket.blob(destination_blob_name)

    transfer_manager.upload_chunks_concurrently(
        source_filename, blob, chunk_size=chunk_size, max_workers=workers
    )

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


if __name__ == "__main__":
    argparse = argparse.ArgumentParser(
        description="Upload a file to GCS in chunks concurrently."
    )
    argparse.add_argument(
        "--bucket_name", help="The name of the GCS bucket to upload to."
    )
    argparse.add_argument(
        "--source_filename", help="The local path to the file to upload."
    )
    argparse.add_argument(
        "--destination_blob_name", help="The name of the object in GCS."
    )
    argparse.add_argument(
        "--chunk_size",
        type=int,
        default=32 * 1024 * 1024,
        help="The size of each chunk in bytes (default: 32 MiB). The remote\
              service has a minimum of 5 MiB and a maximum of 5 GiB",
    )
    argparse.add_argument(
        "--workers",
        type=int,
        default=8,
        help="The number of worker processes to use (default: 8).",
    )
    args = argparse.parse_args()
    upload_chunks_concurrently(
        args.bucket_name,
        args.source_filename,
        args.destination_blob_name,
        args.chunk_size,
        args.workers,
    )

다음 단계