이 페이지에서는 Google 포토 라이브러리 API에 재개 가능한 업로드 요청을 하는 방법을 설명합니다. REST 프로토콜을 통해 저장할 수 있습니다 이 프로토콜을 사용하면 업로드 작업을 재개할 수 있습니다. 데이터 흐름이 중단될 때 발생합니다
다음과 같은 경우 재개 가능한 업로드 옵션을 사용하세요.
- 대용량 파일을 업로드 중입니다.
- 네트워크 중단 또는 기타 전송 실패가 발생할 가능성이 높습니다(예: 모바일 앱에서 파일을 업로드하는 경우).
대용량 파일 업로드를 처음부터 다시 시작할 필요가 없으므로 재개 가능한 업로드는 네트워크 장애가 있을 때 대역폭 사용량을 줄일 수도 있습니다.
1단계: 업로드 세션 시작
https://photoslibrary.googleapis.com/v1/uploads에 POST 요청을 전송하여 재개 가능한 업로드 세션을 시작합니다. 이 요청에서 반환된 재개 가능한 업로드 URL을 사용하여 파일을 업로드합니다.
POST 요청에는 다음 헤더가 포함되어야 합니다.
| 헤더 필드 | |
|---|---|
Content-Length |
요청 본문이 비어 있으므로 0로 설정합니다. |
X-Goog-Upload-Command |
start로 설정합니다. |
X-Goog-Upload-Content-Type |
파일의 MIME 유형으로 설정합니다(예: image/jpeg). |
X-Goog-Upload-Protocol |
resumable로 설정합니다. |
X-Goog-Upload-Raw-Size |
전송할 파일 데이터의 총 바이트 수로 설정합니다. |
다음은 POST 요청 헤더입니다.
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: bytes-of-file
2단계: 세션 URL 저장
성공하면 POST 요청은 다음 헤더를 포함하여 200 OK HTTP 상태 코드를 반환합니다.
X-Goog-Upload-URL: url-to-make-uploads-to X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes
헤더 필드 x-goog-upload-chunk-granularity에는 바이트 정렬이 포함되어 있습니다.
및 크기 세부사항을 설정할 수 있습니다. 업로드 상태가
여러 단위로 수행(마지막 업로드를 제외한 모든 업로드)
이 값의 배수로 지정해야 합니다. 즉, 파일의 업로드 바이트가 이 값에 정렬되어야 합니다. 마지막 청크에서 나머지 덩어리를
바이트.
헤더 필드 X-Goog-Upload-URL에는 나머지 모든 요청을 통해 업로드를 완료하는 데 사용해야 하는 고유한 URL이 포함되어 있습니다. 후속 요청에 사용할 수 있도록 이 재개 가능한 세션 URL을 복사하여 저장합니다.
3단계: 파일 업로드
재개 가능한 세션으로 파일을 업로드하는 방법에는 두 가지가 있습니다.
- 단일 요청. 이 접근 방식이 일반적으로 가장 좋으며 필요한 요청이 더 적기 때문에 성능이 더 우수하기 때문입니다.
-
여러 단위. 이 접근 방식에서는 데이터를 청크로 나눠 여러 요청으로 업로드합니다. 데이터는
x-goog-upload-chunk-granularity의 배수입니다. 필요한 경우 청크로 분할된 요청을 다시 시도할 수 있습니다.다음과 같은 경우 이 방법을 사용합니다.
- 단일 전송에서 전송되는 데이터의 양을 줄여야 하고 요청을 수행합니다. 개별 요청에 고정된 시간 제한이 있는 경우 이 작업을 수행해야 할 수 있습니다.
- 업로드를 표시하는 맞춤 표시기를 제공해야 합니다. 있습니다.
- 데이터를 삭제해도 되는 경우를 알아야 합니다.
단일 요청
단일 요청으로 파일을 업로드하는 방법은 다음과 같습니다.
- 재개 가능한 세션 URL에 대한
POST요청을 만듭니다. - 파일의 데이터를 요청 본문에 추가합니다.
다음 HTTP 헤더를 추가합니다.
Content-Length: 파일에서 참조됩니다.X-Goog-Upload-Command:upload, finalize로 설정합니다.
요청을 전송합니다.
업로드 요청이 중단되거나 5xx 응답을 받는 경우 중단된 업로드 재개 절차를 따릅니다.
요청이 성공하면 200 OK HTTP 상태가 수신됩니다.
응답 본문에 업로드 토큰이 있어야 합니다
만들기
미디어 항목을 선택합니다.
여러 청크
파일을 여러 단위로 업로드하려면 다음 단계를 따르세요.
- 재개 가능한 세션 URL에 대한
POST요청을 만듭니다. -
단위의 데이터를 요청 본문에 추가합니다.
업로드를 완료하는 마지막 단위를 제외하고 허용되는 단위 크기의 배수로 다른 단위를 만듭니다. 효율적인 업로드를 위해 단위 크기를 최대한 크게 유지합니다.
-
다음 HTTP 헤더를 추가합니다.
Content-Length: 덩어리에요.X-Goog-Upload-Command:upload로 설정합니다. 마지막 청크의 경우upload, finalize로 설정합니다.X-Goog-Upload-Offset: 바이트가 쓰여야 하는 오프셋으로 설정합니다. 바이트를 업로드해야 합니다. 순차적으로 전달되어야 합니다 첫 번째 오프셋은0입니다.
- 요청을 전송합니다.
업로드 요청이 중단되거나
5xx을 수신하는 경우 응답을 재개하려면 재개 업로드 중단이 발생할 수 있습니다. - 파일의 나머지 청크마다 이 단계를 반복합니다.
요청이 성공하면 200 OK HTTP 상태가 수신됩니다.
응답 본문에 업로드 토큰이 있어야 합니다
만들기
미디어 항목을 선택합니다.
예
단일 요청
다음 예는 3,039,417바이트의 JPEG 파일을 포함할 수 있습니다.
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
응답에는 업로드 URL과 예상 청크 크기가 포함됩니다.
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
최종 업로드 요청:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 3039417 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 0 [BYTES 0-4199999]
다중 청크
다음 예는 재개 가능한 세션 URL과 이전 단계에서 가져온 허용된 청크 크기 세부사항을 사용하여 3,039,417바이트 JPEG 파일을 여러 청크로 업로드하는 재개 가능한 요청을 보여줍니다.
이 예에서는
헤더 필드 x-goog-upload-chunk-granularity가 반환되면
업로드 세션이 초기화되었습니다. 각 업로드에는
262,144의 배수입니다
업로드 URL 및 단위 크기를 수신하도록 업로드 세션 초기화 아래 단계를 따르세요.
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
응답에는 업로드 URL과 예상 단위 크기가 포함됩니다.
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
첫 번째 청크:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 0 [BYTES 0-1048575]
두 번째 청크:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 1048576 [BYTES 1048576-2097151]
마지막 청크:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 942265 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 2097152 [BYTES 2097152-4200000]
중단된 업로드 재개
업로드 요청이 중단되거나 200가 아닌 HTTP 상태 코드가 수신되면 서버에 쿼리하여 업로드가 얼마나 성공했는지 확인합니다.
다음은 재개 가능한 세션 URL에 대한 POST 요청입니다. X-Goog-Upload-Command는 query로 설정해야 합니다.
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: query
서버의 응답에는 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이 아닌 경우 업로드가 이미 종료되었음을 나타냅니다.