슬라이스 객체 다운로드

대용량 파일을 다운로드하는 한 가지 전략을 슬라이스 객체 다운로드라고 합니다. 이 다운로드에서는 범위가 지정된 GET 요청이 동시에 수행되고, 사전 할당된 임시 대상 파일 안에 다운로드한 데이터가 저장됩니다. 모든 슬라이스 다운로드가 완료되면 임시 파일 이름은 대상 파일로 변경됩니다.

슬라이스 객체 다운로드는 네트워크 및 디스크 속도의 제한을 받지 않는 경우 훨씬 더 빨라질 수 있습니다. 그러나 슬라이스 객체 다운로드로 인해 디스크의 다양한 위치에서 다수의 쓰기가 발생하므로 이 다운로드 전략은 특히 많은 수의 슬라이스로 다운로드를 세분화할 때 탐색 시간이 느린 디스크의 성능을 저하시킬 수 있습니다. Google Cloud CLI와 같은 도구에는 성능에 미치는 영향을 최소화하기 위해 만드는 슬라이스 수의 기본값이 낮습니다.

슬라이스 객체 다운로드는 항상 슬라이스의 데이터 무결성을 확인하기 위해 빠른 구성 가능한 체크섬(CRC32C)을 사용해야 합니다. 슬라이스 객체 다운로드를 수행하려면 gcloud CLI와 같은 도구에 다운로드를 수행하는 머신에 대한 컴파일된 crcmod 버전이 필요합니다. 컴파일된 crcmod를 사용할 수 없으면 gcloud CLI는 대신 슬라이스가 아닌 객체 다운로드를 수행합니다.

도구 및 API에서 슬라이스 객체 다운로드를 사용하는 방법

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

콘솔

Google Cloud 콘솔은 슬라이스 객체 다운로드를 수행하지 않습니다.

명령줄

기본적으로 gcloud storage cp는 슬라이스 객체 다운로드를 사용 설정합니다. 다음 속성을 수정하여 gcloud CLI에서 슬라이스 객체 다운로드를 수행하는 방법과 시기를 제어할 수 있습니다.

storage/sliced_object_download_threshold: 슬라이스 객체 다운로드를 수행하는 데 필요한 최소한의 총 파일 크기입니다. 이 값을 0으로 설정하면 슬라이스 모든 객체 다운로드를 중지할 수 있습니다.
storage/sliced_object_download_max_components: 다운로드에 사용할 최대 슬라이스 수입니다. 0으로 설명하면 무제한이며, 이 경우 슬라이스 수는 storage/sliced_object_download_component_size에 의해서만 결정됩니다.
storage/sliced_object_download_component_size: 각 다운로드 슬라이스의 대상 크기입니다. 총 파일 크기가 너무 커서 이 크기의 슬라이스를 다운로드할 때 storage/sliced_object_download_max_components에 설정된 것보다 더 많은 슬라이스가 필요할 경우 이 속성은 무시됩니다.

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

gcloud CLI를 사용하여 슬라이스 객체 다운로드를 수행하는 경우 추가 로컬 디스크 공간이 필요하지 않습니다. 다운로드가 완료되기 전에 실패하면 명령어를 다시 실행하여 실패한 슬라이스를 재개합니다. 다운로드 시도 사이에 소스 객체가 변경된 경우를 제외하고 실패하기 전에 성공적으로 다운로드된 슬라이스는 재시도할 때 다시 다운로드되지 않습니다.

임시로 다운로드된 객체는 이름에 _.gstmp 서픽스가 있는 대상 디렉터리에 나타납니다.

클라이언트 라이브러리

Java

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

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

AllowDivideAndConquer를 true로 설정하여 슬라이스 객체 다운로드를 수행할 수 있습니다. 예를 들면 다음과 같습니다.

import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.transfermanager.DownloadResult;
import com.google.cloud.storage.transfermanager.ParallelDownloadConfig;
import com.google.cloud.storage.transfermanager.TransferManager;
import com.google.cloud.storage.transfermanager.TransferManagerConfig;
import java.nio.file.Path;
import java.util.List;

class AllowDivideAndConquerDownload {

  public static void divideAndConquerDownloadAllowed(
      List<BlobInfo> blobs, String bucketName, Path destinationDirectory) {
    TransferManager transferManager =
        TransferManagerConfig.newBuilder()
            .setAllowDivideAndConquerDownload(true)
            .build()
            .getService();
    ParallelDownloadConfig parallelDownloadConfig =
        ParallelDownloadConfig.newBuilder()
            .setBucketName(bucketName)
            .setDownloadDirectory(destinationDirectory)
            .build();
    List<DownloadResult> results =
        transferManager.downloadBlobs(blobs, parallelDownloadConfig).getDownloadResults();

    for (DownloadResult result : results) {
      System.out.println(
          "Download of "
              + result.getInput().getName()
              + " completed with status "
              + result.getStatus());
    }
  }
}

Node.js

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

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

downloadFileInChunks 메서드를 사용하여 슬라이스 객체 다운로드를 수행할 수 있습니다. 예를 들면 다음과 같습니다.

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

// The ID of the GCS file to download
// const fileName = 'your-file-name';

// The path to which the file should be downloaded
// const destFileName = '/local/path/to/file.txt';

// The size of each chunk to be downloaded
// const chunkSize = 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 downloadFileInChunksWithTransferManager() {
  // Downloads the files
  await transferManager.downloadFileInChunks(fileName, {
    destination: destFileName,
    chunkSizeBytes: chunkSize,
  });

  console.log(
    `gs://${bucketName}/${fileName} downloaded to ${destFileName}.`
  );
}

downloadFileInChunksWithTransferManager().catch(console.error);

Python

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

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

download_chunks_concurrently 메서드를 사용하여 슬라이스 객체 다운로드를 수행할 수 있습니다. 예를 들면 다음과 같습니다.

def download_chunks_concurrently(
    bucket_name, blob_name, filename, chunk_size=32 * 1024 * 1024, workers=8
):
    """Download a single file in chunks, concurrently in a process pool."""

    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The file to be downloaded
    # blob_name = "target-file"

    # The destination filename or path
    # filename = ""

    # 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, but smaller files usually
    # benefit from a higher number of processes. 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(blob_name)

    transfer_manager.download_chunks_concurrently(
        blob, filename, chunk_size=chunk_size, max_workers=workers
    )

    print("Downloaded {} to {}.".format(blob_name, filename))

REST API

JSON API 및 XML API 모두 범위 지정 GET 요청을 지원합니다. 즉, 두 API를 사용하여 슬라이스 객체 다운로드 전략을 구현할 수 있습니다.

다운로드 중에 변경되는 소스 객체로 인한 데이터 손상을 방지하려면 객체 슬라이스의 각 다운로드 요청에서 소스 객체의 세대 번호를 제공해야 합니다.