이 페이지에서는 Google 포토 라이브러리 API에 재개 가능한 업로드 요청을 하는 방법을 설명합니다. REST 프로토콜을 통해 저장할 수 있습니다 이 프로토콜을 사용하면 업로드 작업을 재개할 수 있습니다. 데이터 흐름이 중단될 때 발생합니다
클라이언트 라이브러리를 사용하는 개발자의 경우 일부 클라이언트 라이브러리가 재개 가능한 업로드에 대한 기본 지원을 제공합니다
다음과 같은 경우 재개 가능한 업로드 옵션을 사용하세요.
- 대용량 파일을 업로드 중입니다.
- 네트워크 중단 또는 기타 전송 실패 가능성은 (예: 모바일 앱에서 파일을 업로드하는 경우)
재개 가능한 업로드를 사용하면 네트워크가 있을 때 대역폭 사용량도 줄일 수 있습니다. 컴퓨터에서 대용량 파일 업로드를 다시 시작할 필요가 없기 때문에 시작하겠습니다
1단계: 업로드 세션 시작
POST 요청을 전송하여 재개 가능한 업로드 세션 시작:
https://photoslibrary.googleapis.com/v1/uploads
재개 가능한 업로드 사용하기
이 요청에서 반환된 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
에는
업로드를 완료합니다. 복사하여 저장
후속 요청에 사용할 수 있습니다.
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]
다중 청크
다음 예는
재개 가능한 세션을 사용하여 여러 청크로 된 3,039,417바이트의 JPEG 파일
URL 및 이전 단계에서 가져온 허용된 단위 크기 세부사항입니다.
이 예에서는
헤더 필드 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
이 아닌 경우 업로드에
이미 해지되었습니다.