재개 가능한 업로드 수행

개념으로 이동

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

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

기본 요건

기본 요건은 사용되는 도구에 따라 다를 수 있습니다.

JSON API

JSON API를 사용하여 이 가이드를 완료하려면 적절한 IAM 권한이 있어야 합니다. 업로드하려는 버킷이 자신이 만들지 않은 프로젝트에 존재하는 경우 프로젝트 소유자가 필요한 권한이 포함된 역할을 부여해야 할 수 있습니다.

특정 작업에 필요한 권한 목록은 JSON 메서드에 대한 IAM 권한을 참조하세요.

관련 역할 목록은 Cloud Storage 역할을 참조하세요. 또는 특별히 제한된 권한이 있는 커스텀 역할을 만들 수 있습니다.

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

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

JSON API

1. OAuth 2.0 Playground에서 승인 액세스 토큰을 가져옵니다. 자체 OAuth 사용자 인증 정보를 사용하도록 Playground를 구성합니다. 자세한 내용은 API 인증을 참조하세요.

2. (선택사항) 업로드할 객체에 설정할 메타데이터가 포함된 JSON 파일을 만듭니다.

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

   curl -i -X POST --data-binary @METADATA_LOCATION \
       -H "Authorization: Bearer OAUTH2_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 헤더와 함께 이 값을 제외합니다.
   • OAUTH2_TOKEN은 1단계에서 생성한 액세스 토큰입니다.
   • 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. OAuth 2.0 Playground에서 승인 액세스 토큰을 가져옵니다. 자체 OAuth 사용자 인증 정보를 사용하도록 Playground를 구성합니다. 자세한 내용은 API 인증을 참조하세요.

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

   curl -i -X POST -H "Authorization: Bearer OAUTH2_TOKEN" \
       -H "Content-Length: 0" \
       -H "Content-Type: OBJECT_CONTENT_TYPE" \
       -H "x-goog-resumable: start" \
       "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

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

   • OAUTH2_TOKEN은 1단계에서 생성한 액세스 토큰입니다.
   • 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 헤더에 반환되는 값입니다.

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는 현재 요청에 업로드하는 바이트 수입니다. 예를 들면 524288입니다.
   • CHUNK_FIRST_BYTE는 업로드하는 단위에 포함된 전체 객체의 시작 바이트입니다.
   • CHUNK_LAST_BYTE는 업로드하는 단위에 포함된 전체 객체의 종료 바이트입니다.
   • TOTAL_OBJECT_SIZE는 업로드할 객체의 총 크기입니다.
   • SESSION_URI는 재개 가능한 업로드를 시작할 때 Location 헤더에 반환되는 값입니다.

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

   요청이 성공하면 서버가 308 Resume Incomplete로 응답합니다. 응답에는 Range 헤더가 포함됩니다. 이 헤더의 범위 중 큰 값을 사용하여 다음 단위를 시작할 위치를 결정합니다. 서버가 요청에서 보낸 모든 바이트를 수신했다고 가정해서는 안 됩니다.

3. 업로드할 데이터의 나머지 단위마다 위 단계를 반복합니다.

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는 현재 요청에 업로드하는 바이트 수입니다. 예를 들면 524288입니다.
   • CHUNK_FIRST_BYTE는 업로드하는 단위에 포함된 전체 객체의 시작 바이트입니다.
   • CHUNK_LAST_BYTE는 업로드하는 단위에 포함된 전체 객체의 종료 바이트입니다.
   • TOTAL_OBJECT_SIZE는 업로드할 객체의 총 크기입니다.
   • SESSION_URI는 재개 가능한 업로드를 시작할 때 Location 헤더에 반환되는 값입니다.

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

   요청이 성공하면 서버가 308 Resume Incomplete로 응답합니다. 응답에는 Range 헤더가 포함됩니다. 이 헤더의 범위 중 큰 값을 사용하여 다음 단위를 시작할 위치를 결정합니다. 서버가 요청에서 보낸 모든 바이트를 수신했다고 가정해서는 안 됩니다.

3. 업로드할 데이터의 나머지 단위마다 위 단계를 반복합니다.

업로드가 완전히 완료되면 리소스에 연결된 모든 메타데이터와 함께 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. 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이 1999957입니다.
   • NEXT_BYTE는 2단계에서 저장한 값 이후의 다음 정수입니다. 예를 들어 42가 2단계에서 큰 값인 경우 NEXT_BYTE 값은 43입니다.
   • LAST_BYTE는 이 PUT 요청에 포함된 종료 바이트입니다. 예를 들어 총 크기가 20000000인 객체의 업로드를 완료하려면 LAST_BYTE의 값은 1999999입니다.
   • 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이 1999957입니다.
   • NEXT_BYTE는 2단계에서 저장한 값 이후의 다음 정수입니다. 예를 들어 42가 2단계에서 큰 값인 경우 NEXT_BYTE 값은 43입니다.
   • LAST_BYTE는 이 PUT 요청에 포함된 종료 바이트입니다. 예를 들어 총 크기가 20000000인 객체의 업로드를 완료하려면 LAST_BYTE의 값은 1999999입니다.
   • 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 응답이 발생합니다.

다음 단계

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