재개 가능한 업로드

이 페이지에서는 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단계: 파일 업로드

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

  1. 단일 요청. 이 접근 방식이 일반적으로 가장 좋으며 필요한 요청이 더 적기 때문에 성능이 더 우수하기 때문입니다.

  2. 여러 단위. 이 접근 방식에서는 여러 개의 요청으로 분할할 수 있습니다 데이터는 x-goog-upload-chunk-granularity의 배수입니다. 필요한 경우 청크로 분할된 요청을 다시 시도할 수 있습니다.

    다음과 같은 경우 이 방법을 사용합니다.

    • 단일 전송에서 전송되는 데이터의 양을 줄여야 하고 합니다. 정해진 시간제한이 있는 경우 개별 요청에 따라 다릅니다
    • 업로드를 표시하는 맞춤 표시기를 제공해야 합니다. 있습니다.
    • 데이터를 삭제해도 안전한 시기를 알아야 합니다.

단일 요청

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

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

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

    • Content-Length: 파일에서 참조됩니다.
    • X-Goog-Upload-Command: upload, finalize로 설정합니다.

  4. 요청을 전송합니다.

업로드 요청이 중단되거나 5xx을 수신하는 경우 응답을 재개하려면 재개 업로드 중단이 발생할 수 있습니다.

요청이 성공하면 200 OK HTTP 상태가 수신됩니다. 응답 본문에 업로드 토큰이 있어야 합니다 만들기 미디어 항목을 선택합니다.

다중 청크

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

  1. 재개 가능한 세션 URL에 대한 POST 요청을 생성합니다.

  2. 단위의 데이터를 요청 본문에 추가합니다.

    업로드를 완료하는 마지막 단위를 제외하고 다른 청크를 허용되는 청크 크기의 배수로 반환합니다. 이 효율적으로 업로드할 수 있도록 단위 크기를 최대한 크게 설정합니다.

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

    • Content-Length: 덩어리에요.
    • X-Goog-Upload-Command: upload로 설정합니다. 마지막 청크의 경우 upload, finalize로 설정합니다.
    • X-Goog-Upload-Offset: 작성해야 합니다. 바이트를 업로드해야 합니다. 순차적으로 전달되어야 합니다. 첫 번째 오프셋은 0입니다.
  4. 요청을 전송합니다.

    업로드 요청이 중단되거나 5xx을 수신하는 경우 다시 시작하려면 업로드 중단이 발생할 수 있습니다.

  5. 파일의 나머지 청크마다 위 단계를 반복합니다.

요청이 성공하면 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이 아닌 경우 업로드에 이미 해지되었습니다.