재개 가능한 업로드 수행

개념으로 이동

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

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

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

JSON API

URI https://storage.googleapis.com/upload/storage/v1/b/[BUCKET_NAME]/o에 대한 POST 요청을 생성합니다.
쿼리 매개변수 uploadType=resumable을 추가합니다. 예를 들어 이름이 myBucket인 버킷의 경우 다음과 같습니다.
```
POST https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable
```
파일의 메타데이터가 없는 경우 name 쿼리 매개변수를 사용하여 업로드와 관련된 리소스를 식별합니다. 예를 들어 다음과 같이 객체 이름을 myObject로 지정합니다.
```
POST https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&name=myObject
```
파일의 메타데이터가 있는 경우 메타데이터를 JSON 형식으로 요청 본문에 추가합니다. 그렇지 않으면 요청 본문을 비워 둡니다.
다음 HTTP 헤더를 추가합니다.
- X-Upload-Content-Type. 선택사항입니다. 후속 요청에서 전송되는 파일 데이터의 MIME 유형으로 설정합니다. 데이터의 MIME 유형이 메타데이터에 또는 이 헤더를 통해 지정되지 않은 경우 객체는 application/octet-stream으로 제공됩니다.
- X-Upload-Content-Length. 선택사항입니다. 후속 요청에서 전송되는 파일 데이터의 바이트 수로 설정합니다.
- Content-Type. 파일의 메타데이터가 있는 경우에 필요합니다. application/json; charset=UTF-8로 설정합니다.
- Content-Length. 단위 분할된 전송 인코딩을 사용하지 않는 경우에 필요합니다. 이 초기 요청 본문의 바이트 수로 설정합니다.
- Origin. 교차 출처 리소스 공유를 사용 설정한 경우에 추가합니다. 후속 업로드 요청에서도 이 헤더를 사용해야 합니다.
요청을 전송합니다.

예시

다음은 myBucket이라는 버킷을 사용하여 재개 가능한 세션을 시작하는 방법을 보여주는 예시입니다. OAuth 2.0 Playground에서 승인 액세스 토큰을 가져올 수 있습니다.

POST https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable HTTP/1.1
  Authorization: Bearer [YOUR_AUTH_TOKEN]
  Content-Length: 38
  Content-Type: application/json; charset=UTF-8
  X-Upload-Content-Type: image/jpeg
  X-Upload-Content-Length: 2000000
  {
    "name": "myObject"
  }

다음 섹션에서는 응답을 처리하는 방법을 설명합니다.

XML API

재개 가능한 업로드를 시작하려면 Cloud Storage에 POST 객체 요청을 보냅니다. POST 객체 요청에는 업로드할 파일이 포함되지 않습니다. 대신, 재개 가능한 업로드를 수행하려 함을 Cloud Storage 시스템에 알리는 몇 가지 헤더가 포함됩니다. 특히 POST 객체 요청에는 다음이 포함되어야 합니다.

빈 항목 본문
Content-Length 요청 헤더이며, 0으로 설정해야 합니다.
x-goog-resumable 헤더이며, start로 설정해야 합니다.
교차 출처 리소스 공유를 사용 설정한 경우, 업로드할 파일에 대한 후속 업로드 요청에 사용하는 Origin 헤더입니다.

예시: 다음은 example이라고 하는 버킷에 업로드되는 music.mp3라는 파일에 대한 재개 가능한 업로드를 시작하는 방법을 보여주는 예시입니다.

    POST /music.mp3 HTTP/1.1
    Host: example.storage.googleapis.com
    Date: Fri, 01 Oct 2010 21:56:18 GMT
    Content-Length: 0
    Content-Type: audio/mpeg
    x-goog-resumable: start
    Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

재개 가능한 세션 URI 저장

후속 요청에 사용할 수 있도록 재개 가능한 세션 URI를 복사 및 저장합니다.

JSON API

세션 시작 요청이 성공하면 응답에 200 OK HTTP 상태 코드가 포함됩니다. 또한 여기에는 재개 가능한 세션 URI를 지정하는 Location 헤더가 포함됩니다. 재개 가능한 세션 URI를 사용하여 파일 데이터를 업로드하고 업로드 상태를 쿼리합니다.

예시

다음은 이름이 myBucket인 버킷에 대한 재개 가능한 세션 URI가 포함된 응답을 보여주는 예시입니다.

HTTP/1.1 200 OK
  Location: https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2
  Content-Length: 0

XML API

POST 객체 요청으로 재개 가능한 업로드를 시작하면 Cloud Storage가 201 Created 상태 메시지로 응답합니다. 상태 메시지에는 값이 재개 가능한 세션 URI인 Location 헤더가 포함됩니다. 세션 URI는 업로드 작업 중에 모든 추가 요청에 사용되므로 저장해야 합니다.

예시: 다음은 '재개 가능한 업로드 시작' 섹션에 표시된 Post 객체 요청에 대한 응답을 보여주는 예시입니다.

  HTTP/1.1 201 Created
  Location: https://example.storage.googleapis.com/music.mp3?upload_id=tvA0ExBntDa...gAAEnB2Uowrot
  Date: Fri, 01 Oct 2010 21:56:18 GMT
  Content-Length: 0
  Content-Type: audio/mpeg

파일 업로드

JSON API

재개 가능한 세션으로 파일을 업로드하는 방법에는 두 가지가 있습니다.

단일 요청. 일반적으로 이 방법은 요청이 더 적게 필요하므로 성능이 좋습니다.
여러 단위. 다음과 같은 경우 이 방법을 사용합니다.
- 단일 요청에서 전송되는 데이터의 양을 줄여야 합니다. App Engine 요청의 특정 클래스처럼 개별 요청에 고정된 시간 제한이 있는 경우 이 작업을 수행해야 할 수 있습니다.
- 업로드 진행 상황을 표시하는 맞춤 표시기를 제공해야 합니다.

단일 요청

단일 요청으로 파일을 업로드하는 방법은 다음과 같습니다.

재개 가능한 세션 URI에 대한 PUT 요청을 작성합니다.
파일의 데이터를 요청 본문에 추가합니다.
Content-Length HTTP 헤더를 추가하고 파일의 바이트 수로 설정합니다.
요청을 전송합니다.

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

요청이 성공하면 리소스와 관련된 모든 메타데이터와 함께 200 OK 또는 201 Created 응답을 받습니다.

예시: 다음은 이전에 가져온 재개 가능한 세션 URI를 사용해 myBucket에 전체 2,000,000바이트 크기의 JPEG 파일을 업로드할 수 있는 재개 가능한 요청을 보여주는 예시입니다.

PUT https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/jpeg
Content-Range: bytes 0-1999999

여러 단위

파일을 여러 단위로 업로드하려면 다음 단계를 따르세요.

재개 가능한 세션 URI에 대한 PUT 요청을 작성합니다.
단위의 데이터를 요청 본문에 추가합니다. 업로드를 완료하는 마지막 단위를 제외하고 256KB의 배수(256 x 1,024바이트)로 단위를 작성합니다. 효율적인 업로드를 위해 단위 크기를 최대한 크게 유지합니다.
다음 HTTP 헤더를 추가합니다.
- Content-Length. 현재 단위의 바이트 수로 설정합니다.
- Content-Range: 업로드할 파일의 바이트 수를 표시하도록 설정합니다. 예를 들어 Content-Range: bytes 0-524287/2000000은 2,000,000바이트 크기의 파일 중 첫 524,288바이트(256 x 1,024 x 2)를 업로드한다는 의미입니다.
요청을 전송하고 응답을 처리합니다. 업로드 요청이 중단되거나 5xx 응답을 받는 경우 중단된 업로드 재개 절차를 따릅니다.
파일의 나머지 단위에 대해 1~4단계를 반복합니다. 응답의 Range 헤더를 사용하여 다음 단위를 시작할 위치를 결정합니다. 서버가 이전 요청에서 보낸 모든 바이트를 수신했다고 가정하지 마세요.

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

예시

다음은 이전에 가져온 재개 가능한 세션 URI를 사용해 파일의 첫 524,288바이트(512KB)를 myBucket에 보내는 요청을 보여주는 예시입니다.

PUT https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
      Content-Length: 524288
      Content-Type: image/jpeg
      Content-Range: bytes 0-524287/2000000

요청이 성공하면 서버는 지금까지 저장된 총 바이트 수를 식별하는 308 Resume Incomplete' along with aRange` 헤더로 응답합니다.

HTTP/1.1 308 Resume Incomplete
    Content-Length: 0
    Content-Range: bytes=0-524287

Range 헤더에 반환된 범위 중 큰 값을 사용해 다음 단위를 시작할 위치를 결정합니다. 전체 파일이 업로드될 때까지 파일의 각 단위를 계속 PUT합니다.

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

XML API

Cloud Storage에 파일 블록을 전송하는 PUT 객체 요청을 구현합니다. 가져온 세션 URI를 PUT 요청의 요청 URI로 사용합니다. 또한 요청에는 Content-Length 헤더가 포함되어 이를 사용해 업로드할 파일의 크기를 지정해야 합니다.

POST 객체 요청과 마찬가지로 요청에 표준 Cloud Storage 호스트 이름(storage.googleapis.com)을 사용해야 합니다. 실제로 세션 URI는 인증 토큰이므로 명시적 인증 토큰을 사용할 필요가 없습니다.

예시

다음은 시작된 재개 가능한 업로드에 대해 music.mp3 파일을 업로드하는 방법을 보여주는 예시입니다.

  PUT https://example.storage.googleapis.com/music.mp3?upload_id=tvA0ExBntDa...gAAEnB2Uowrot HTTP/1.1
  Date: Fri, 01 Oct 2010 21:56:18 GMT
  Content-Length: 7351375

PUT 객체 요청이 중단되지 않고 파일이 성공적으로 업로드되면 Cloud Storage는 200 OK 상태 코드로 응답합니다. 업로드가 중단되면 업로드를 재개할 수 있습니다.

다른 PUT 객체 요청을 전송하여 받은 바이트 수를 쿼리해야 합니다. PUT 객체 요청에는 다음이 포함되어야 합니다.

빈 항목 본문
Content-Length 요청 헤더이며, 0으로 설정해야 합니다.
Content-Range 요청 헤더이며, 상태가 필요한 바이트 범위를 지정합니다.
재개 가능한 업로드의 세션 URI와 동일한 요청 URI

Content-Range 요청 헤더의 값은 다음 형식이어야 합니다.

Content-Range: bytes */<content-length>

여기서 <content-length>는 원래의 PUT 객체 요청에 지정한 Content-Length 헤더의 값입니다.

또한 요청에 표준 Cloud Storage 호스트 이름(storage.googleapis.com)을 사용해야 합니다.

다음은 재개 가능한 업로드가 중단된 후 Cloud Storage 시스템을 쿼리하는 방법을 보여주는 예시입니다.

  PUT https://example.storage.googleapis.com/music.mp3?upload_id=tvA0ExBntDa...gAAEnB2Uowrot HTTP/1.1
  Date: Fri, 01 Oct 2010 22:25:53 GMT
  Content-Range: bytes */7351375
  Content-Length: 0

중단된 업로드 재개

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

JSON API

업로드 상태를 요청하려면 재개 가능한 세션 URI에 대한 비어 있는 PUT 요청을 작성합니다.
파일의 현재 위치를 알 수 없음을 나타내는 Content-Range 헤더를 추가합니다.

예를 들어 총 파일 길이가 2,000,000바이트인 경우 Content-Range를 */2000000으로 설정합니다.

파일의 전체 크기를 모르는 경우 Content-Range를 */*로 설정합니다.
요청을 전송합니다.
응답을 처리합니다.
- 200 OK 또는 201 Created 응답은 업로드가 완료되었으며 추가 작업이 필요하지 않음을 나타냅니다.
- 308 Resume Incomplete 응답은 파일을 계속 업로드해야 함을 나타냅니다.
308 Resume Incomplete 응답을 받은 경우 Cloud Storage가 지금까지 수신한 바이트를 지정하는 응답의 Range 헤더를 처리합니다. 다음 단계에서 이 숫자를 사용합니다. Cloud Storage에서 아직 바이트를 수신하지 않은 경우 응답에 Range 헤더가 없습니다.

예를 들어 Range 헤더 값이 bytes=0-42이면 파일의 처음 43바이트가 수신되었음을 나타냅니다.
업로드를 재개할 위치를 파악했으므로 나머지 데이터 또는 다음 단위를 전송하여 파일을 계속 업로드합니다. 보내는 파일의 부분을 나타내는 Content-Range 헤더를 포함합니다.

예를 들어 Content-Range: bytes 43-1999999/2000000은 43~1,999,999바이트를 전송함을 나타냅니다.

XML API

PUT 객체 요청을 전송하여 업로드 작업을 재개할 수 있습니다. PUT 객체 요청에는 다음이 포함되어야 합니다.

아직 업로드해야 하는 바이트 범위를 포함하는 항목 본문. Content-Length에서 이전에 가져온 Range를 빼서 이 범위를 결정할 수 있습니다.
Content-Length 요청 헤더이며, 현재 요청에서 업로드할 바이트 수를 지정합니다.
Content-Range 요청 헤더이며, 요청에서 업로드할 바이트 범위를 지정합니다.
재개 가능한 업로드의 세션 URI와 동일한 요청 URI

요청에 표준 Cloud Storage 호스트 이름(storage.googleapis.com)을 사용해야 합니다.

예시

다음은 예시 버킷으로 music.mp3 파일 업로드를 재개하는 PUT 객체 요청을 보여주는 예시입니다.

PUT https://example.storage.googleapis.com/music.mp3?upload_id=tvA0ExBntDa...gAAEnB2Uowrot HTTP/1.1
Date: Fri, 01 Oct 2010 22:25:53 GMT
Content-Range: bytes 2359296-7351374/7351375
Content-Length: 4992079

업로드를 필요한 만큼 재개할 수 있지만, 요청을 재시도할 때는 잘린 지수 백오프를 사용합니다. 예시를 보려면 이 로직의 boto 구현을 참조하세요.

파일이 성공적으로 업로드되면 Cloud Storage에서 200 OK 상태 코드로 응답합니다.

선택적 최적화에 대해 자세히 알아보세요.

업로드 취소

업로드를 취소하고 추가 작업을 하지 않으려면 고유한 업로드 URI에서 DELETE 요청을 실행합니다. DELETE 요청이 성공한 이후 업로드를 쿼리하거나 재개하려고 하면 4xx 응답이 발생합니다.

JSON API

예시

다음은 재개 가능한 업로드를 취소하는 방법을 보여주는 예시입니다.

DELETE https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 0

XML API

예시

다음은 재개 가능한 업로드를 취소하는 방법을 보여주는 예시입니다.

 DELETE https://example.storage.googleapis.com/myFile.zip?upload_id=tvA0ExBntDa...gAAEnB2Uowrot HTTP/1.1
    Content-Length: 0