재개 가능한 업로드

예시로 이동

이 페이지에서는 Cloud Storage의 재개 가능한 업로드에 대해 설명합니다. 재개 가능한 업로드는 대용량 파일을 업로드할 때 권장되는 방법입니다. 업로드가 진행되는 동안 네트워크 장애가 발생해도 처음부터 다시 시작할 필요가 없기 때문입니다.

소개

재개 가능한 업로드를 사용하면 통신 장애로 인해 데이터 흐름이 중단된 후 Cloud Storage로의 데이터 전송 작업을 재개할 수 있습니다. 재개 가능한 업로드는 업로드하는 객체의 일부를 포함하는 여러 요청을 전송하여 이루어집니다. 이는 단일 요청에 모든 객체 데이터를 포함하고 중간에 실패하면 처음부터 다시 시작해야 하는 단순 업로드와 다른 업로드입니다.

  • 대용량 파일을 업로드하거나 느린 연결을 통해 업로드하는 경우 재개 가능한 업로드를 사용하세요. 재개 가능한 업로드를 사용하기 위한 파일 크기 축소의 예시는 업로드 크기 고려사항을 참조하세요.

  • 완료된 재개 가능한 업로드는 하나의 A 클래스 작업으로 간주됩니다.

도구 및 API가 재개 가능한 업로드를 사용하는 방법

재개 가능한 업로드는 사용자가 Cloud Storage와 어떻게 상호작용하는지에 따라 사용자를 대신하여 자동으로 관리될 수 있습니다. 자세히 알아보려면 아래 표의 탭을 클릭하세요.

Console

Cloud Console은 사용자를 대신하여 재개 가능한 업로드를 자동으로 관리합니다. 하지만 업로드가 진행되는 동안 Cloud Console을 새로고침하거나 벗어나면 업로드가 취소됩니다.

gsutil

gsutil 명령줄 도구를 사용하면 boto 구성 파일resumable_threshold 매개변수로 재개 가능한 업로드를 수행하기 위한 최소 크기를 설정할 수 있습니다. resumable_threshold의 기본값은 8MiB입니다.

클라이언트 라이브러리

C++

WriteObject 메서드의 일부로 재개 가능한 업로드 사용을 전환할 수 있습니다.

C#

CreateObjectUploader를 사용하여 재개 가능한 업로드를 시작할 수 있습니다.

Go

Writer.ChunkSize를 사용하여 재개 가능한 업로드를 수행하기 위한 최소 크기를 제어합니다. Go는 항상 단위로 분할된 재개 가능한 업로드를 수행합니다.

자바

재개 가능한 업로드는 writer 메서드를 통해 제어됩니다.

Node.js

createWriteStream 메서드를 사용하면 재개 가능한 업로드가 자동으로 관리됩니다.

PHP

재개 가능한 업로드는 사용자를 대신하여 자동으로 관리되지만 resumable 옵션을 통해 직접 제어될 수 있습니다.

Python

파일 크기가 8MiB를 초과하면 재개 가능한 업로드가 자동으로 수행됩니다. 또는 재개 가능한 미디어를 사용하여 재개 가능한 업로드를 직접 관리할 수 있습니다.

Ruby

모든 업로드는 재개 가능한 업로드로 취급됩니다.

REST API

JSON API

Cloud Storage JSON API는 쿼리 매개변수 uploadType=resumable이 포함된 POST Object 요청을 사용하여 재개 가능한 업로드를 시작합니다. 이 요청은 그 다음에 하나 이상의 PUT Object 요청에 사용하여 객체 데이터를 업로드하는 세션 URI로 반환됩니다. 재개 가능한 업로드를 수행하기 위해 자체 로직을 빌드하는 단계별 가이드는 재개 가능한 업로드 수행을 참조하세요.

XML API

Cloud Storage JSON API는 쿼리 매개변수 uploadType=resumable이 포함된 POST Object 요청을 사용하여 재개 가능한 업로드를 시작합니다. 이 요청은 그 다음에 하나 이상의 PUT Object 요청에 사용하여 객체 데이터를 업로드하는 세션 URI로 반환됩니다. 재개 가능한 업로드를 수행하기 위해 자체 로직을 빌드하는 단계별 가이드는 재개 가능한 업로드 수행을 참조하세요.

알 수 없는 크기의 재개 가능한 업로드

재개 가능한 업로드 메커니즘은 파일 크기를 미리 알 수 없는 전송을 지원합니다. 이는 업로드 도중 객체를 압축하는 경우 등에 유용할 수 있습니다. 전송이 시작될 때 압축된 파일의 정확한 파일 크기를 예측하기 어렵기 때문입니다. 이 메커니즘은 중단 후 재개할 수 있는 전송을 스트리밍하려는 경우 또는 단위 분할 전송 인코딩이 애플리케이션에서 작동하지 않는 경우에 유용합니다.

자세한 내용은 스트리밍 이전을 참조하세요.

고려사항

이 섹션은 재개 가능한 업로드 요청을 JSON 또는 XML API로 직접 보내는 자체 클라이언트를 빌드하는 경우에 유용합니다.

세션 URI

재개 가능한 업로드를 시작하면 Cloud Storage는 후속 요청에서 사용하여 실제 데이터를 업로드하는 세션 URI를 반환합니다. JSON API의 세션 URI 예시는 다음과 같습니다.

https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=my-file.jpg&upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

XML API의 세션 URI 예시는 다음과 같습니다.

 https://storage.googleapis.com/my-bucket/my-file.jpg?upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

이 세션 URI는 인증 토큰 역할을 하므로 이 토큰을 사용하는 요청은 서명이 필요 없으며 누구나 추가 인증 없이 대상 버킷에 데이터를 업로드하는 데 사용할 수 있습니다. 그러므로 세션 URI를 공유할 때는 신중을 기하고 HTTPS를 통해서만 공유하세요.

세션 URI는 일주일 후에 만료됩니다. 요청에서 만료된 세션 URI를 사용하는 경우 404 Not Found 상태 코드가 수신됩니다. 이 경우 재개 가능한 새 업로드를 시작하고, 새 세션 URI를 가져오고, 새 세션 URI를 사용하여 업로드를 처음부터 시작해야 합니다.

업로드 성능

재개 가능한 업로드는 업로드가 시작되는 리전에 고정됩니다. 예를 들어 미국에서 재개 가능한 업로드를 시작하고 세션 URI를 아시아의 클라이언트에 제공하는 경우에도 업로드는 여전히 미국을 거치게 됩니다. 업로드가 시작되지 않은 리전에서 재개 가능한 업로드를 계속하면 업로드 속도가 느려질 수 있습니다.

Compute Engine 인스턴스를 사용하여 재개 가능한 업로드를 시작하는 경우 인스턴스는 업로드하는 Cloud Storage 버킷과 같은 위치에 있어야 합니다. 그런 다음에 지역 IP 서비스를 사용하여 고객 요청을 라우팅할 Compute Engine 리전을 선택할 수 있습니다. 이렇게 하면 트래픽을 리전에 맞게 현지화하는 데 도움이 됩니다.

재시도 가이드라인

  • 다음 상태 코드를 반환하는 요청은 다시 시도해야 합니다.

    • 408 Request Timeout
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • 재개 가능한 새 업로드를 시작하여 404 Not Found 오류를 처리합니다.

  • 재시도 요청을 수행할 때 잘린 지수 백오프를 사용하세요.

무결성 검사

소스 파일과 일치하는지 확인하기 위해 최종 업로드된 객체의 무결성 검사를 요청하는 것이 좋습니다. 소스 파일의 MD5 다이제스트를 계산하여 Content-MD5 요청 헤더에 추가하면 됩니다.

장기간에 걸쳐 대용량 파일을 업로드하는 경우 업로드 작업 중에 소스 파일이 수정될 가능성이 높기 때문에 업로드된 파일의 무결성 검사가 특히 중요합니다.

다음 단계