재개 가능한 업로드 수행

이 페이지에서는 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(메비바이트)의 배수인 2,097,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이 아닌 경우 업로드가 이미 종료된 것입니다.