재개 가능한 업로드 수행

개요

이 페이지에서는 Cloud Storage JSON 및 XML API에서 재개 가능한 업로드 요청을 수행하는 방법을 설명합니다. 이 프로토콜을 사용하면 통신 장애로 인해 데이터 흐름이 중단된 후에 업로드 작업을 재개할 수 있습니다.

Google Cloud CLI 및 클라이언트 라이브러리에서 재개 가능한 업로드를 사용하는 방법에 대한 자세한 내용은 도구 및 API가 재개 가능한 업로드를 사용하는 방법을 참조하세요.

필요한 역할

재개 가능한 업로드를 수행하는 데 필요한 권한을 얻으려면 관리자에게 다음 역할 중 하나를 부여해 달라고 요청하세요.

• 객체 보관 잠금이 포함된 업로드의 경우 관리자에게 버킷에 대한 스토리지 객체 관리자(roles/storage.objectAdmin) IAM 역할을 부여해 달라고 요청하세요.

• 그 외의 모든 경우에는 관리자에게 버킷에 대한 스토리지 객체 사용자(roles/storage.objectUser) IAM 역할을 부여해 달라고 요청하세요.

이러한 사전 정의된 역할에는 해당하는 경우에 대해 객체를 버킷에 업로드하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.

필수 권한

• storage.objects.create
• storage.objects.delete
• 이 권한은 기존 객체를 덮어쓰는 업로드에만 필요합니다.
• storage.objects.setRetention
  • 이 권한은 객체 보관 잠금이 포함된 업로드에만 필요합니다.

다른 사전 정의된 역할이나 커스텀 역할을 사용하여 이러한 권한을 얻을 수도 있습니다.

버킷의 역할 부여에 대한 자세한 내용은 버킷에 IAM 사용을 참조하세요.

재개 가능한 업로드 세션 시작

재개 가능한 업로드 세션을 시작하려면 다음 단계를 따르세요.

JSON API

1. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

   또는 OAuth 2.0 Playground를 사용하여 액세스 토큰을 만들고 Authorization 헤더에 포함할 수 있습니다.

2. (선택사항) 업로드할 객체에 설정할 메타데이터가 포함된 JSON 파일을 만듭니다. 예를 들어 다음 JSON 파일은 image/png에 업로드할 객체의 contentType 메타데이터를 설정합니다.

   {
       "contentType": "image/png"
   }

3. cURL을 사용하여 POST 객체 요청으로 JSON API를 호출합니다.

   curl -i -X POST --data-binary @METADATA_LOCATION \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json" \
       -H "Content-Length: INITIAL_REQUEST_LENGTH" \
       "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=resumable&name=OBJECT_NAME"

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

   • METADATA_LOCATION은 이전 단계에서 지정한 선택적 메타데이터가 포함된 JSON 파일의 로컬 경로입니다. 메타데이터 파일을 포함하지 않으면 --data-binary @ 및 Content-Type 헤더와 함께 이 값을 제외합니다.
   • INITIAL_REQUEST_LENGTH는 이 초기 요청 본문에 있는 바이트 수입니다. 예를 들면 79입니다.
   • BUCKET_NAME은 객체를 업로드할 버킷의 이름입니다. 예를 들면 my-bucket입니다.
   • OBJECT_NAME은 객체에 지정할 URL 인코딩 이름입니다. 예를 들어 pets/dog.png는 pets%2Fdog.png로 URL 인코딩됩니다. 2단계의 객체 메타데이터 파일에 name을 포함한 경우에는 필요하지 않습니다.

   교차 출처 리소스 공유를 사용 설정한 경우 이 업로드 요청과 이후의 업로드 요청 모두에 Origin 헤더를 포함해야 합니다.

   요청에 추가할 수 있는 선택적 헤더에는 X-Upload-Content-Type 및 X-Upload-Content-Length가 있습니다.

   성공하면 응답에 200 상태 코드가 포함됩니다.

4. POST 객체 요청에 대한 응답의 Location 헤더에 제공된 재개 가능한 세션 URI를 저장합니다.

   이 URI는 후속 요청에서 객체 데이터를 업로드하는 데 사용됩니다.

   주의: 재개 가능한 세션 URI를 공유할 때는 다른 사용자가 추가 인증 없이도 데이터를 대상 버킷에 업로드할 수 있으므로 주의해야 합니다.

XML API

1. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

   또는 OAuth 2.0 Playground를 사용하여 액세스 토큰을 만들고 Authorization 헤더에 포함할 수 있습니다.

2. cURL을 사용하여 빈 본문이 있는 POST 객체 요청으로 XML API를 호출합니다.

   curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Length: 0" \
       -H "Content-Type: OBJECT_CONTENT_TYPE" \
       -H "x-goog-resumable: start" \
       "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

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

   • OBJECT_CONTENT_TYPE은 객체의 콘텐츠 유형입니다. 예를 들면 image/png입니다. 콘텐츠 유형을 지정하지 않으면 Cloud Storage 시스템은 객체의 Content-Type 메타데이터를 application/octet-stream으로 설정합니다.
   • BUCKET_NAME은 객체를 업로드할 버킷의 이름입니다. 예를 들면 my-bucket입니다.
   • OBJECT_NAME은 객체에 지정할 URL 인코딩 이름입니다. 예를 들어 pets/dog.png는 pets%2Fdog.png로 URL 인코딩됩니다.

   교차 출처 리소스 공유를 사용 설정한 경우 이 업로드 요청과 이후의 업로드 요청 모두에 Origin 헤더를 포함해야 합니다.

   성공하면 응답에 201 상태 메시지가 포함됩니다.

3. POST 객체 요청에 대한 응답의 Location 헤더에 제공된 재개 가능한 세션 URI를 저장합니다.

   이 URI는 후속 요청에서 객체 데이터를 업로드하는 데 사용됩니다.

   주의: 재개 가능한 세션 URI를 공유할 때는 다른 사용자가 추가 인증 없이도 데이터를 대상 버킷에 업로드할 수 있으므로 주의해야 합니다.

데이터 업로드하기

재개 가능한 업로드를 시작한 후에는 다음 두 가지 방법으로 객체 데이터를 업로드할 수 있습니다.

• 단일 청크: 일반적으로 이 방식은 요청이 더 적게 필요하므로 성능이 좋습니다.
• 여러 단위: 단일 요청으로 전송되는 데이터 양을 줄여야 하는 경우(예: 개별 요청에 고정된 제한 시간이 있는 경우) 또는 업로드가 시작될 때 총 업로드 크기를 알 수 없는 경우 이 방식을 사용하세요.

단일 청크 업로드

단일 청크로 데이터를 업로드하는 방법은 다음과 같습니다.

JSON API

1. cURL을 사용하여 PUT 객체 요청으로 JSON API를 호출합니다.

   curl -i -X PUT --data-binary @OBJECT_LOCATION \
       -H "Content-Length: OBJECT_SIZE" \
       "SESSION_URI"

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

   • OBJECT_LOCATION은 객체의 로컬 경로입니다. 예를 들면 Desktop/dog.png입니다.
   • OBJECT_SIZE는 객체의 바이트 수입니다. 예를 들면 20000000입니다.
   • SESSION_URI는 재개 가능한 업로드를 시작할 때 Location 헤더에 반환되는 값입니다.

   원하는 경우 X-Goog-Meta- 프리픽스가 있는 헤더를 포함하여 이 요청의 일부로 객체에 대한 커스텀 메타데이터를 추가할 수 있습니다.

XML API

1. cURL을 사용하여 PUT 객체 요청으로 XML API를 호출합니다.

   curl -i -X PUT --data-binary @OBJECT_LOCATION \
       -H "Content-Length: OBJECT_SIZE" \
       "SESSION_URI"

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

   • OBJECT_LOCATION은 객체의 로컬 경로입니다. 예를 들면 Desktop/dog.png입니다.
   • OBJECT_SIZE는 객체의 바이트 수입니다. 예를 들면 20000000입니다.
   • SESSION_URI는 재개 가능한 업로드를 시작할 때 Location 헤더에 반환되는 값입니다.

업로드가 완전히 완료되면 리소스에 연결된 모든 메타데이터와 함께 200 OK 또는 201 Created 응답을 받습니다.

업로드 요청이 중단되거나 5xx 응답을 받는 경우 중단된 업로드 재개 절차를 따릅니다.

여러 단위 업로드

데이터를 여러 단위로 업로드하려면 다음 단계를 따르세요.

JSON API

1. 업로드할 전체 데이터에서 데이터 청크를 만듭니다.

   업로드를 완료하는 마지막 단위가 아닌 경우 단위 크기는 256KiB(256 x 1,024바이트)의 배수여야 합니다. 청크 크기가 클수록 일반적으로 업로드 속도가 빨라지지만 속도와 메모리 사용량 간에는 상충 관계가 있습니다. 청크 크기로 8MiB 이상을 사용하는 것이 좋습니다.

2. cURL을 사용하여 PUT 객체 요청으로 JSON API를 호출합니다.

   curl -i -X PUT --data-binary @CHUNK_LOCATION \
       -H "Content-Length: CHUNK_SIZE" \
       -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
       "SESSION_URI"

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

   • CHUNK_LOCATION은 현재 업로드하는 단위의 로컬 경로입니다.
   • CHUNK_SIZE는 현재 요청에 업로드하는 바이트 수입니다. 예를 들면 8388608입니다.
   • CHUNK_FIRST_BYTE는 업로드하는 단위에 포함된 전체 객체의 시작 바이트입니다.
   • CHUNK_LAST_BYTE는 업로드하는 단위에 포함된 전체 객체의 종료 바이트입니다.
   • TOTAL_OBJECT_SIZE는 업로드할 객체의 총 크기입니다.
   • SESSION_URI는 재개 가능한 업로드를 시작할 때 Location 헤더에 반환되는 값입니다.

   예시 Content-Range는 Content-Range: bytes 0-8388607/20000000입니다. 이 헤더에 대한 자세한 내용은 Content-Range를 참조하세요.

   요청이 성공하면 서버가 308 Resume Incomplete로 응답합니다. 응답에는 Range 헤더가 포함됩니다.

3. 업로드할 각 데이터 청크에 대해 위 단계를 반복하여 각 응답의 Range 헤더에 포함된 범위 중 큰 값을 사용하여 연속된 청크를 시작할 위치를 결정합니다. 서버가 특정 요청에서 전송되는 모든 바이트를 수신했다고 가정해서는 안 됩니다.

   필요한 경우 재개 가능한 업로드의 최종 요청에서 X-Goog-Meta- 프리픽스가 있는 헤더를 포함하여 해당 객체의 커스텀 메타데이터를 추가할 수 있습니다.

XML API

1. 업로드할 전체 데이터에서 데이터 청크를 만듭니다.

   업로드를 완료하는 마지막 단위가 아닌 경우 단위 크기는 256KiB(256 x 1,024바이트)의 배수여야 합니다. 청크 크기가 클수록 일반적으로 업로드 속도가 빨라지지만 속도와 메모리 사용량 간에는 상충 관계가 있습니다. 청크 크기로 8MiB 이상을 사용하는 것이 좋습니다.

2. cURL을 사용하여 PUT 객체 요청으로 XML API를 호출합니다.

   curl -i -X PUT --data-binary @CHUNK_LOCATION \
       -H "Content-Length: CHUNK_SIZE" \
       -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
       "SESSION_URI"

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

   • CHUNK_LOCATION은 현재 업로드하는 단위의 로컬 경로입니다.
   • CHUNK_SIZE는 현재 요청에 업로드하는 바이트 수입니다. 예를 들면 8388608입니다.
   • CHUNK_FIRST_BYTE는 업로드하는 단위에 포함된 전체 객체의 시작 바이트입니다.
   • CHUNK_LAST_BYTE는 업로드하는 단위에 포함된 전체 객체의 종료 바이트입니다.
   • TOTAL_OBJECT_SIZE는 업로드할 객체의 총 크기입니다.
   • SESSION_URI는 재개 가능한 업로드를 시작할 때 Location 헤더에 반환되는 값입니다.

   예시 Content-Range는 Content-Range: bytes 0-8388607/20000000입니다. 이 헤더에 대한 자세한 내용은 Content-Range를 참조하세요.

   요청이 성공하면 서버가 308 Resume Incomplete로 응답합니다. 응답에는 Range 헤더가 포함됩니다.

3. 업로드할 각 데이터 청크에 대해 위 단계를 반복하여 각 응답의 Range 헤더에 포함된 범위 중 큰 값을 사용하여 연속된 청크를 시작할 위치를 결정합니다. 서버가 특정 요청에서 전송되는 모든 바이트를 수신했다고 가정해서는 안 됩니다.

업로드가 완전히 완료되면 리소스에 연결된 모든 메타데이터와 함께 200 OK 또는 201 Created 응답을 받습니다.

모든 청크 업로드가 중단되거나 5xx 응답을 수신하면 중단된 청크를 모두 다시 전송하거나 중단된 위치부터 중단된 업로드를 계속해야 합니다.

재개 가능한 업로드 상태 확인

재개 가능한 업로드가 중단되거나 업로드 완료 여부가 확실하지 않은 경우 업로드 상태를 확인할 수 있습니다.

JSON API

1. cURL을 사용하여 PUT 객체 요청으로 JSON API를 호출합니다.

   curl -i -X PUT \
       -H "Content-Length: 0" \
       -H "Content-Range: bytes */OBJECT_SIZE" \
       "SESSION_URI"

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

   • OBJECT_SIZE는 객체의 총 바이트 수입니다. 객체의 전체 크기를 모르는 경우 이 값에 *를 사용하세요.
   • SESSION_URI는 재개 가능한 업로드를 시작할 때 Location 헤더에 반환되는 값입니다.

XML API

1. cURL을 사용하여 PUT 객체 요청으로 XML API를 호출합니다.

   curl -i -X PUT \
       -H "Content-Length: 0" \
       -H "Content-Range: bytes */OBJECT_SIZE" \
       "SESSION_URI"

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

   • OBJECT_SIZE는 객체의 총 바이트 수입니다. 객체의 전체 크기를 모르는 경우 이 값에 *를 사용하세요.
   • SESSION_URI는 재개 가능한 업로드를 시작할 때 Location 헤더에 반환되는 값입니다.

200 OK 또는 201 Created 응답은 업로드가 완료되었으며 추가 작업이 필요하지 않음을 나타냅니다.

308 Resume Incomplete 응답은 데이터를 계속 업로드해야 함을 나타냅니다.

• Cloud Storage에서 아직 바이트를 유지하지 못한 경우 308 응답에 Range 헤더가 없습니다. 이 경우에는 처음부터 업로드를 시작해야 합니다.
• 그렇지 않으면 308 응답에 지금까지 Cloud Storage에서 유지한 바이트를 지정하는 Range 헤더가 있습니다. 중단된 업로드를 재개할 때 이 값을 사용합니다.

중단된 업로드 재개

중요: Cloud Storage는 Cloud Storage가 이미 유지한 오프셋으로 보내는 바이트를 무시합니다.

응답을 받기 전에 업로드 요청이 종료되거나 503 또는 500 응답을 받은 경우에는 중단된 업로드를 중단된 시점부터 재개해야 합니다. 중단된 업로드를 재개하려면 다음 단계를 따르세요.

JSON API

1. 재개 가능한 업로드의 상태를 확인합니다.

2. 상태 확인에 대한 응답에 포함된 Range 헤더의 범위 중 큰 값을 저장합니다. 응답에 Range 헤더가 없으면 Cloud Storage에서 아직 바이트를 유지하지 못한 것이므로 처음부터 업로드해야 합니다.

3. 업로드할 객체 데이터가 Range 헤더의 범위 중 큰 값 뒤에 오는 바이트에서 시작되는지 확인합니다.

4. 중단된 요청에 X-Goog-Meta- 프리픽스가 있는 헤더가 포함된 경우 업로드를 재개하기 위해 요청에 해당 헤더를 포함합니다.

5. cURL을 사용하여 Range 헤더의 값 뒤에 오는 바이트에서 다시 시작하는 PUT 객체 요청으로 JSON API를 호출합니다.

   curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
       -H "Content-Length: UPLOAD_SIZE_REMAINING" \
       -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
       "SESSION_URI"

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

   • PARTIAL_OBJECT_LOCATION은 업로드할 데이터의 나머지 부분에 대한 로컬 경로입니다.
   • UPLOAD_SIZE_REMAINING은 현재 요청에 업로드하는 바이트 수입니다. 예를 들어 0~42바이트가 업로드된 후 중단된 총 크기가 20,000,000인 객체의 나머지 업로드에서는 UPLOAD_SIZE_REMAINING이 19999957입니다.
   • NEXT_BYTE는 2단계에서 저장한 값 이후의 다음 정수입니다. 예를 들어 42가 2단계에서 큰 값인 경우 NEXT_BYTE 값은 43입니다.
   • LAST_BYTE는 이 PUT 요청에 포함된 종료 바이트입니다. 예를 들어 총 크기가 20000000인 객체의 업로드를 완료하려면 LAST_BYTE의 값은 19999999입니다.
   • TOTAL_OBJECT_SIZE는 업로드할 객체의 총 크기입니다. 예를 들면 20000000입니다.
   • SESSION_URI는 재개 가능한 업로드를 시작할 때 Location 헤더에 반환되는 값입니다.

XML API

1. 재개 가능한 업로드의 상태를 확인합니다.

2. 상태 확인에 대한 응답에 포함된 Range 헤더의 범위 중 큰 값을 저장합니다. 응답에 Range 헤더가 없으면 Cloud Storage에서 아직 바이트를 유지하지 못한 것이므로 처음부터 업로드해야 합니다.

3. 업로드할 객체 데이터가 Range 헤더의 범위 중 큰 값 뒤에 오는 바이트에서 시작되는지 확인합니다.

4. cURL을 사용하여 Range 헤더의 값 뒤에 오는 바이트에서 다시 시작하는 PUT 객체 요청으로 XML API를 호출합니다.

   curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
       -H "Content-Length: UPLOAD_SIZE_REMAINING" \
       -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
       "SESSION_URI"

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

   • PARTIAL_OBJECT_LOCATION은 업로드할 데이터의 나머지 부분에 대한 로컬 경로입니다.
   • UPLOAD_SIZE_REMAINING은 현재 요청에 업로드하는 바이트 수입니다. 예를 들어 0~42바이트가 업로드된 후 중단된 총 크기가 20,000,000인 객체의 나머지 업로드에서는 UPLOAD_SIZE_REMAINING이 19999957입니다.
   • NEXT_BYTE는 2단계에서 저장한 값 이후의 다음 정수입니다. 예를 들어 42가 2단계에서 큰 값인 경우 NEXT_BYTE 값은 43입니다.
   • LAST_BYTE는 이 PUT 요청에 포함된 종료 바이트입니다. 예를 들어 총 크기가 20000000인 객체의 업로드를 완료하려면 LAST_BYTE의 값은 19999999입니다.
   • TOTAL_OBJECT_SIZE는 업로드할 객체의 총 크기입니다. 예를 들면 20000000입니다.
   • SESSION_URI는 재개 가능한 업로드를 시작할 때 Location 헤더에 반환되는 값입니다.

세션 URI가 활성화되어 있는 동안 필요한 만큼 업로드를 재개할 수 있습니다. 세션 URI는 일주일 후에 만료됩니다. 데이터가 성공적으로 업로드되면 Cloud Storage에서 200 OK 또는 201 created 상태 코드로 응답합니다.

업로드 취소

완료되지 않은 재개 가능한 업로드를 취소하고 추가 작업을 하지 않으려면 다음 안내를 따르세요.

JSON API

1. cURL을 사용하여 DELETE 요청으로 JSON API를 호출합니다.

   curl -i -X DELETE -H "Content-Length: 0" \
     "SESSION_URI"

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

   • SESSION_URI는 재개 가능한 업로드를 시작할 때 Location 헤더에 반환되는 값입니다.

성공하면 응답에 499 상태 코드가 포함됩니다. 이후 업로드를 쿼리하거나 재개하려고 하면 4xx 응답이 발생합니다.

XML API

1. cURL을 사용하여 DELETE 요청으로 XML API를 호출합니다.

   curl -i -X DELETE -H "Content-Length: 0" \
     "SESSION_URI"

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

   • SESSION_URI는 재개 가능한 업로드를 시작할 때 Location 헤더에 반환되는 값입니다.

성공하면 응답에 204 상태 코드가 포함되며 이후 업로드를 쿼리하거나 재개하려고 해도 204 응답이 발생합니다.

실패 처리

드물지만 버킷의 권한이 변경되었거나 최종 업로드된 객체의 무결성 확인에서 불일치가 감지되어 중단된 업로드를 재개하라는 요청이 재시도 불가능한 '4xx' 오류와 함께 실패할 수 있습니다. 이 경우 재개 가능한 새 업로드 세션을 시작하여 업로드를 다시 시도합니다.

다음 단계

• 재개 가능한 업로드 자세히 알아보기
• JSON API 및 XML API 개요 읽기
• 알 수 없는 크기의 스트림 업로드
• Cloud Storage JSON API에 여러 요청 일괄 처리