재개 가능한 업로드 수행

이 페이지에서는 Street View Publish API에서 재개 가능한 업로드를 요청하는 방법을 설명합니다. 이 프로토콜을 사용하면 통신 실패로 데이터 흐름이 중단된 후 업로드 작업을 재개할 수 있습니다. 다음과 같은 경우 이 옵션을 사용합니다.

  • 대용량 파일을 업로드하려고 합니다.
  • 네트워크 중단이나 기타 전송 실패가 발생할 가능성이 높습니다 (예: 모바일 앱에서 파일을 업로드하는 경우).

또한 재개 가능한 업로드는 네트워크 장애 발생 시 대역폭 사용량을 줄일 수 있습니다. 대용량 파일 업로드를 처음부터 다시 시작할 필요가 없기 때문입니다.

안정적인 네트워크 연결을 통해 작은 파일을 전송하는 경우 간단한 업로드를 대신 사용할 수 있습니다.

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

uploadUrl를 가져온 후에는 재개 가능한 업로드 세션을 시작할 수 있습니다.

  1. uploadUrl에 대한 POST 요청을 만듭니다.

  2. 다음 HTTP 헤더를 추가합니다.

    • X-Goog-Upload-Protocol: resumable로 설정합니다.
    • X-Goog-Upload-Header-Content-Length: 후속 요청에서 전송될 파일 데이터의 총 바이트 수로 설정합니다.
    • X-Goog-Upload-Header-Content-Type: 파일 데이터의 MIME 유형으로 설정합니다.
    • X-Goog-Upload-Command: start로 설정합니다.

  3. 요청을 전송합니다.

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

다음 예시에서는 재개 가능한 세션을 시작하여 새 파일을 업로드하는 방법을 보여줍니다. 이 경우 파일은 이미지이고 파일의 총 바이트 수는 4200000입니다. 요청 본문이 비어 있으므로 Content-Length 헤더가 0으로 설정됩니다.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

재개 가능한 세션 URL 저장에서는 재개 가능한 업로드 세션을 시작하기 위한 요청에 대한 응답을 처리하는 방법을 설명합니다.

재개 가능한 세션 URL 저장

재개 가능한 업로드 세션을 시작하기 위해 전송된 요청의 경우 서버는 다음 헤더를 포함한 200 OK HTTP 상태 코드로 응답합니다.

  • X-Goog-Upload-URL: 나머지 모든 요청을 통해 업로드를 완료하는 데 사용해야 하는 고유한 URL입니다.

후속 요청에 사용할 수 있도록 재개 가능한 보관 URL을 복사하여 저장합니다.

예: 재개 가능한 세션 URL 저장

다음 예는 재개 가능한 세션 URL과 크기 세부사항 요구사항이 포함된 응답을 보여줍니다.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

파일 업로드

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

  1. 단일 요청. 일반적으로 이 접근 방식은 요청이 더 적고 성능이 더 우수하므로 가장 좋습니다.
  2. 여러 단위. 다음과 같은 경우 이 방법을 사용합니다.
    • 단일 요청으로 전송되는 데이터의 양을 줄여야 합니다. 개별 요청에 정해진 시간제한이 있는 경우 이 작업을 수행해야 할 수 있습니다.
    • 업로드 진행률을 나타내는 맞춤 표시기를 제공해야 합니다.
    • 데이터를 삭제해도 안전한지 알아야 합니다.

단일 요청

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

  1. 재개 가능한 세션 URL에 대한 POST 요청을 만듭니다.
  2. 파일의 데이터를 요청 본문에 추가합니다.

  3. 다음 HTTP 헤더를 추가합니다.

    • Content-Length: 파일의 바이트 수로 설정합니다.
    • X-Goog-Upload-Command: upload, finalize로 설정합니다.

  4. 요청을 전송합니다.

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

다중 덩어리

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

  1. 재개 가능한 세션 URL에 대한 POST 요청을 만듭니다.
  2. 단위의 데이터를 요청 본문에 추가합니다. 업로드를 완료하는 마지막 단위를 제외하고 2MiB (메비바이트)의 배수로 단위를 만듭니다. 효율적인 업로드를 위해 단위 크기를 최대한 크게 유지합니다.

  3. 다음 HTTP 헤더를 추가합니다.

    • Content-Length: 청크의 바이트 수로 설정합니다.
    • X-Goog-Upload-Command: upload로 설정합니다. 마지막 청크의 경우 upload, finalize로 설정합니다.
    • X-Goog-Upload-Offset: 바이트를 써야 하는 오프셋으로 설정합니다. 바이트는 순차적으로 업로드되어야 합니다.

  4. 요청을 전송합니다. 업로드 요청이 중단되거나 5xx 응답을 받으면 중단된 업로드 재개 절차를 따릅니다.

  5. 파일의 나머지 단위에 대해 1~4단계를 반복합니다.

예: 파일 업로드

단일 요청

다음 예시는 이전 단계에서 얻은 재개 가능한 세션 URL을 사용하여 단일 요청으로 4,200,000바이트 크기의 JPEG 파일 전체를 업로드하는 재개 가능한 요청을 보여줍니다.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

요청이 성공하면 200 OK HTTP 상태 코드가 수신됩니다.

다중 덩어리

다음 예는 재개 가능한 세션 URL과 이전 단계에서 얻은 크기 세분화를 사용하여 4,200,000바이트 크기의 JPEG 파일을 여러 단위로 업로드하기 위한 재개 가능한 요청을 보여줍니다. 이 예시에서는 2MiB (메비바이트)의 배수인 2097, 000바이트의 청크 크기를 사용합니다.

첫 번째 청크:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

두 번째 청크:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

마지막 청크:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

중단된 업로드 재개

업로드 요청이 중단되거나 200이 아닌 HTTP 상태 코드를 수신하면 서버에 쿼리하여 업로드가 얼마나 성공했는지 확인합니다.

  1. 재개 가능한 세션 URL에 대한 POST 요청을 만듭니다.
  2. X-Goog-Upload-Command를 query로 설정합니다.
  3. 요청을 전송합니다.

서버에서 200 OK HTTP 상태 코드와 현재 업로드 크기를 응답합니다.

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

그런 다음 이 오프셋에서 업로드를 재개할 수 있습니다. 결합된 업로드 및 완료 명령어를 전송하지 않는 한 서버에서 제공한 오프셋에서 재개해야 합니다. 이 경우 오프셋 0에서 재개할 수도 있습니다.

쿼리 명령어의 HTTP 응답에 X-Goog-Upload-Status 헤더가 있고 값이 active이 아니면 업로드가 이미 종료된 것입니다.