이 페이지에서는 Cloud Storage JSON 및 XML API에서 재개 가능한 업로드 요청을 수행하는 방법을 설명합니다. 이 프로토콜을 사용하면 통신 장애로 인해 데이터 흐름이 중단된 후 업로드 작업을 재개할 수 있습니다.
재개 가능한 업로드 세션 시작
재개 가능한 업로드 세션을 시작하려면 다음 단계를 따르세요.
JSON API
- OAuth 2.0 Playground에서 승인 액세스 토큰을 가져옵니다. OAuth 사용자 인증 정보를 사용하도록 Playground를 구성합니다.
(선택사항) 업로드할 객체에 설정할 메타데이터가 포함된
.json
파일을 만듭니다.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
은 객체에 지정하려는 이름입니다. 예를 들면pets/dog.png
입니다. 2단계의 객체 메타데이터 파일에name
을 포함한 경우에는 필요하지 않습니다.
교차 출처 리소스 공유를 사용 설정한 경우 이 업로드 요청과 이후의 업로드 요청 모두에
Origin
헤더를 포함해야 합니다.요청에 추가할 수 있는 선택적 헤더에는
X-Upload-Content-Type
및X-Upload-Content-Length
가 있습니다.성공하면 응답에
200
상태 코드가 포함됩니다.POST
객체 요청에 대한 응답의Location
헤더에 제공된 재개 가능한 세션 URI를 저장합니다.이 URI는 후속 요청에서 객체 데이터를 업로드하는 데 사용됩니다.
XML API
- OAuth 2.0 Playground에서 승인 액세스 토큰을 가져옵니다. OAuth 사용자 인증 정보를 사용하도록 Playground를 구성합니다.
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
은 객체에 지정하려는 이름입니다. 예를 들면pets/dog.png
입니다.
교차 출처 리소스 공유를 사용 설정한 경우 이 업로드 요청과 이후의 업로드 요청 모두에
Origin
헤더를 포함해야 합니다.성공하면 응답에
201
상태 메시지가 포함됩니다.POST
객체 요청에 대한 응답의Location
헤더에 제공된 재개 가능한 세션 URI를 저장합니다.이 URI는 후속 요청에서 객체 데이터를 업로드하는 데 사용됩니다.
파일 업로드
재개 가능한 업로드를 시작한 후에는 다음 두 가지 방법으로 객체 데이터를 업로드할 수 있습니다.
- 단일 요청: 일반적으로 이 방식은 요청이 더 적게 필요하므로 성능이 좋습니다.
- 여러 단위: 단일 요청으로 전송되는 데이터 양을 줄여야 하는 경우(예: 개별 요청에 고정된 제한 시간이 있는 경우) 또는 업로드가 시작될 때 총 업로드 크기를 알 수 없는 경우 이 방식을 사용하세요.
단일 요청 업로드
단일 요청으로 파일을 업로드하는 방법은 다음과 같습니다.
JSON API
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
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
업로드할 파일에서 데이터 단위를 만듭니다.
업로드를 완료하는 마지막 단위가 아닌 경우 단위 크기는 256KiB(256 x 1,024바이트)의 배수여야 합니다. 단위 크기가 클수록 일반적으로 업로드가 더 효율적입니다. 단위 크기로 8MiB를 사용하는 것이 좋습니다.
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
헤더가 포함됩니다. 이 헤더의 범위 중 큰 값을 사용하여 다음 단위를 시작할 위치를 결정합니다. 서버가 요청에서 보낸 모든 바이트를 수신했다고 가정해서는 안 됩니다.업로드할 데이터의 나머지 단위마다 위 단계를 반복합니다.
XML API
업로드할 파일에서 데이터 단위를 만듭니다.
업로드를 완료하는 마지막 단위가 아닌 경우 단위 크기는 256KiB(256 x 1,024바이트)의 배수여야 합니다. 단위 크기가 클수록 일반적으로 업로드가 더 효율적입니다. 단위 크기로 8MiB를 사용하는 것이 좋습니다.
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
헤더가 포함됩니다. 이 헤더의 범위 중 큰 값을 사용하여 다음 단위를 시작할 위치를 결정합니다. 서버가 요청에서 보낸 모든 바이트를 수신했다고 가정해서는 안 됩니다.업로드할 데이터의 나머지 단위마다 위 단계를 반복합니다.
업로드가 완전히 완료되면 리소스에 연결된 모든 메타데이터와 함께 200 OK
또는 201 Created
응답을 받습니다.
단위 업로드가 중단되거나 5xx
응답을 받은 경우 중단된 업로드 재개 절차를 따르세요.
재개 가능한 업로드 상태 확인
재개 가능한 업로드가 중단되거나 업로드 완료 여부가 확실하지 않은 경우 업로드 상태를 확인할 수 있습니다.
JSON API
cURL
을 사용하여PUT
객체 요청으로 XML API를 호출합니다.curl -i -X PUT \ -H "Content-Length: 0" \ -H "Content-Range: bytes */OBJECT_SIZE" \ "SESSION_URI"
각 항목의 의미는 다음과 같습니다.
OBEJCT_SIZE
는 객체의 총 바이트 수입니다. 객체의 전체 크기를 모르는 경우 이 값에*
를 사용하세요.SESSION_URI
는 재개 가능한 업로드를 시작할 때Location
헤더에 반환되는 값입니다.
XML API
cURL
을 사용하여PUT
객체 요청으로 XML API를 호출합니다.curl -i -X PUT \ -H "Content-Length: 0" \ -H "Content-Range: bytes */OBJECT_SIZE" \ "SESSION_URI"
각 항목의 의미는 다음과 같습니다.
OBEJCT_SIZE
는 객체의 총 바이트 수입니다. 객체의 전체 크기를 모르는 경우 이 값에*
를 사용하세요.SESSION_URI
는 재개 가능한 업로드를 시작할 때Location
헤더에 반환되는 값입니다.
200 OK
또는 201 Created
응답은 업로드가 완료되었으며 추가 작업이 필요하지 않음을 나타냅니다.
308 Resume Incomplete
응답은 파일을 계속 업로드해야 함을 나타냅니다.
- Cloud Storage에서 아직 바이트를 받지 못한 경우
308
응답에Range
헤더가 없습니다. 이 경우에는 처음부터 업로드를 시작해야 합니다. - 그렇지 않으면
308
응답에 지금까지 Cloud Storage에서 수신한 바이트를 지정하는Range
헤더가 있습니다. 중단된 업로드를 재개할 때 이 값을 사용합니다.
중단된 업로드 재개
응답을 받기 전에 업로드 요청이 종료되거나 503
또는 500
응답을 받은 경우에는 중단된 업로드를 중단된 시점부터 재개해야 합니다. 중단된 업로드를 재개하려면 다음 단계를 따르세요.
JSON API
재개 가능한 업로드의 상태를 확인합니다.
상태 확인에 대한 응답에 포함된
Range
헤더의 범위 중 큰 값을 저장합니다. 응답에Range
헤더가 없으면 Cloud Storage에서 아직 바이트를 받지 못한 것이므로 처음부터 업로드해야 합니다.업로드할 객체 데이터가
Range
헤더의 범위 중 큰 값 뒤에 오는 바이트에서 시작되는지 확인합니다.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
재개 가능한 업로드의 상태를 확인합니다.
상태 확인에 대한 응답에 포함된
Range
헤더의 범위 중 큰 값을 저장합니다. 응답에Range
헤더가 없으면 Cloud Storage에서 아직 바이트를 받지 못한 것이므로 처음부터 업로드해야 합니다.업로드할 객체 데이터가
Range
헤더의 범위 중 큰 값 뒤에 오는 바이트에서 시작되는지 확인합니다.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
cURL
을 사용하여DELETE
요청으로 JSON API를 호출합니다.curl -X DELETE -H "Content-Length: 0" \ "SESSION_URI"
각 항목의 의미는 다음과 같습니다.
SESSION_URI
는 재개 가능한 업로드를 시작할 때Location
헤더에 반환되는 값입니다.
XML API
cURL
을 사용하여DELETE
요청으로 XML API를 호출합니다.curl -X DELETE -H "Content-Length: 0" \ "SESSION_URI"
각 항목의 의미는 다음과 같습니다.
SESSION_URI
는 재개 가능한 업로드를 시작할 때Location
헤더에 반환되는 값입니다.
성공하면 응답에 499
상태 코드가 포함됩니다. 이후 업로드를 쿼리하거나 재개하려고 하면 4xx
응답이 발생합니다.
다음 단계
- 재개 가능한 업로드에 관해 자세히 알아보기
- JSON API 및 XML API 개요 읽기
- 알 수 없는 크기의 스트림 업로드
- Cloud Storage JSON API에 대한 여러 요청을 일괄 처리하는 방법 알아보기