헤더 필드 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 파일
URL 및 이전 단계에서 가져온 허용된 단위 크기 세부사항입니다.
이 예에서는
헤더 필드 x-goog-upload-chunk-granularity가 반환되면
업로드 세션이 초기화되었습니다. 각 업로드에는
262,144의 배수입니다
[null,null,["최종 업데이트: 2025-08-29(UTC)"],[[["\u003cp\u003eThis guide explains how to make resumable upload requests to the Google Photos Library API using the REST protocol, enabling you to resume interrupted uploads.\u003c/p\u003e\n"],["\u003cp\u003eResumable uploads are recommended for large files or unreliable network connections, offering bandwidth savings and the ability to pause and resume.\u003c/p\u003e\n"],["\u003cp\u003eThe process involves initiating an upload session, saving the session URL, and then uploading the file either in a single request or in multiple chunks.\u003c/p\u003e\n"],["\u003cp\u003eIf an upload is interrupted, you can query the server to determine the progress and resume from the appropriate offset.\u003c/p\u003e\n"],["\u003cp\u003eResumable uploads are optimized for large files and unstable networks, preventing data loss and ensuring efficient transfer, especially for mobile app scenarios.\u003c/p\u003e\n"]]],["To make a resumable upload to the Google Photos Library API, first initiate a session with a POST request to `https://photoslibrary.googleapis.com/v1/uploads`, including specific headers like `X-Goog-Upload-Command: start`. Save the returned `X-Goog-Upload-URL` and `X-Goog-Upload-Chunk-Granularity`. Then, upload the file either in a single request or multiple chunks, using POST requests to the saved URL, including the data, `Content-Length`, and `X-Goog-Upload-Command: upload` (or `upload, finalize` for the last chunk). If interrupted, query the server with `X-Goog-Upload-Command: query` to resume at the correct offset.\n"],null,["# Resumable uploads\n\nThis page describes how to make a resumable upload request to the Google Photos Library API\nvia the REST protocol. This protocol allows you to resume an upload operation\nafter a communication failure interrupts the flow of data.\n\nIf you are a developer using client libraries, note that some client libraries\nprovide native support for resumable uploads.\n\nUse the resumable upload option if:\n\n- You are uploading large files.\n- The likelihood of network interruption or some other transmission failure is high (for example, if you are uploading a file from a mobile app).\n\nResumable uploads can also reduce your bandwidth usage when there is a network\nfailure, because you don't have to restart large file uploads from the\nbeginning.\n| **Note:** If you are sending small files over a reliable network connection, you can use a [simple upload](/photos/library/guides/upload-media).\n\nStep 1: Initiating an upload session\n------------------------------------\n\nInitiate a resumable upload session by sending a POST request to\n`https://photoslibrary.googleapis.com/v1/uploads`. Using the resumable upload\nURL returned in this request, upload the file.\n\nThe POST request must include the following headers:\n\n| Header fields ||\n|------------------------------|----------------------------------------------------------------------|\n| `Content-Length` | Set to `0` as the request body is empty. |\n| `X-Goog-Upload-Command` | Set to `start`. |\n| `X-Goog-Upload-Content-Type` | Set to the mime type of the file, for example, `image/jpeg`. |\n| `X-Goog-Upload-Protocol` | Set to `resumable`. |\n| `X-Goog-Upload-Raw-Size` | Set to the total number of bytes of the file data to be transferred. |\n\nHere is a POST request header: \n\n```\nPOST https://photoslibrary.googleapis.com/v1/uploads\nAuthorization: Bearer oauth2-token\nContent-Length: 0\nX-Goog-Upload-Command: start\nX-Goog-Upload-Content-Type: mime-type\nX-Goog-Upload-Protocol: resumable\nX-Goog-Upload-Raw-Size: bytes-of-file\n```\n\nStep 2: Saving the session URL\n------------------------------\n\nIf successful, the POST request returns a `200 OK` HTTP status code, including\nthe following header. \n\n```\nX-Goog-Upload-URL: url-to-make-uploads-to\nX-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes\n```\n\nThe header field `x-goog-upload-chunk-granularity` contains the byte alignment\nand size granularity for all data chunks sent by the client. If the upload is\ndone in [multiple chunks](#upload-file), all uploads, except the last upload,\nmust be done in multiples of this value. That is, the upload bytes of the file\nmust be aligned to this value. In the last chunk, you can upload the remaining\nbytes.\n\nThe header field `X-Goog-Upload-URL` contains a unique URL that must be used to\ncomplete the upload through all of the remaining requests. Copy and save this\nresumable session URL, so that you can use it for subsequent requests.\n| **Note:** A resumable session URL expires after 7 days.\n\nStep 3: Uploading the file\n--------------------------\n\nThere are two ways to upload a file with a resumable session:\n\n1. **In a single request.** This approach is usually the best, because it requires fewer requests, and thus has better performance.\n2. **In multiple chunks.** In this approach, uploads are made\n in multiple requests by chunking the data. The data is chunked in\n multiples of `x-goog-upload-chunk-granularity`. If necessary,\n the chunked requests can be re-tried.\n\n Use this approach if:\n - You need to reduce the amount of data transferred in any single request. You might need to do this when there is a fixed time limit for individual requests.\n - You need to provide a customized indicator showing the upload progress.\n - You need to know when it is safe to discard data.\n\n### Single Request\n\nTo upload the file in a single request:\n\n1. Create a `POST` request to the resumable session URL.\n2. Add the file's data to the request body.\n3. Add the following HTTP headers:\n\n - `Content-Length`: Set to the number of bytes in the file.\n - `X-Goog-Upload-Command`: Set to `upload,\n finalize`.\n4. Send the request.\n\nIf the upload request is interrupted or you receive a `5xx`\nresponse, follow the procedure in [Resuming an\ninterrupted upload](#resume-upload).\n\nIf the request succeeds, you receive a `200 OK` HTTP status\ncode and an upload token in the response body.\n[Create\nthe media item](/photos/library/guides/upload-media#creating-media-item) using this upload token.\n\n### Multiple Chunks\n\nTo upload the file in multiple chunks:\n\n1. Create a `POST` request to the resumable session URL.\n2. Add the chunk's data to the request body.\n\n Except for the final chunk that completes the upload, create the\n other chunks in multiples of the accepted size of chunks. Keep the\n chunk size as large as possible so that the upload is efficient.\n3. Add the following HTTP headers:\n\n - `Content-Length`: Set to the number of bytes in the chunk.\n - `X-Goog-Upload-Command`: Set to `upload`. For the last chunk, set to `upload, finalize`.\n - `X-Goog-Upload-Offset`: Set to the offset at which the bytes should be written. Note that the bytes must be uploaded serially. The first offset is `0`.\n4. Send the request. If the upload request is interrupted or you receive a `5xx`\n response, follow the procedure in [Resuming an\n interrupted upload](#resume-upload).\n\n5. Repeat the above steps for each remaining chunk in the file.\n\nIf the request succeeds, you receive a `200 OK` HTTP status\ncode and an upload token in the response body.\n[Create\nthe media item](/photos/library/guides/upload-media#creating-media-item) using this upload token.\n\n### Example\n\n### Single Request\n\nThe following example shows a resumable request to upload a\n3,039,417-byte JPEG file in a single request. \n\n```\nPOST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1\nContent-Length: 0\nX-Goog-Upload-Command: start\nX-Goog-Upload-Content-Type: image/jpeg\nX-Goog-Upload-Protocol: resumable\nX-Goog-Upload-Raw-Size: 3039417\n[no body]\n```\n\nThe response contains the upload URL and the expected chunk size: \n\n```\nHTTP/1.1 200 OK\nX-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable\nX-Goog-Upload-Chunk-Granularity: 262144\n```\n\nThe final upload request: \n\n```\nPOST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1\nContent-Length: 3039417\nX-Goog-Upload-Command: upload, finalize\nX-Goog-Upload-Offset: 0\n\n[BYTES 0-4199999]\n```\n\n### Multiple Chunks\n\nThe following example shows a resumable request to upload a\n3,039,417-byte JPEG file in multiple chunks, using the resumable session\nURL and the accepted chunk size granularity obtained in the previous step.\nThis example uses a chunk size of 262,144 bytes which was returned in the\nheader field, `x-goog-upload-chunk-granularity`, when the\nupload session was initialized. Note that each upload contains bytes that\nare in multiples of 262,144.\n\nInitialize the upload session to receive the upload URL and chunk size\nas described in the previous step: \n\n```\nPOST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1\nContent-Length: 0\nX-Goog-Upload-Command: start\nX-Goog-Upload-Content-Type: image/jpeg\nX-Goog-Upload-Protocol: resumable\nX-Goog-Upload-Raw-Size: 3039417\n[no body]\n```\n\nThe response contains the upload URL and the expected chunk size: \n\n```\nHTTP/1.1 200 OK\nX-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable\nX-Goog-Upload-Chunk-Granularity: 262144\n```\n\nFirst chunk: \n\n```\nPOST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1\nContent-Length: 1048576\nX-Goog-Upload-Command: upload\nX-Goog-Upload-Offset: 0\n\n[BYTES 0-1048575]\n```\n\nSecond chunk: \n\n```\nPOST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1\nContent-Length: 1048576\nX-Goog-Upload-Command: upload\nX-Goog-Upload-Offset: 1048576\n\n[BYTES 1048576-2097151]\n```\n\nLast chunk: \n\n```\nPOST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1\nContent-Length: 942265\nX-Goog-Upload-Command: upload, finalize\nX-Goog-Upload-Offset: 2097152\n\n[BYTES 2097152-4200000]\n```\n\nResuming an interrupted upload\n------------------------------\n\nIf the upload request is interrupted or if you receive a non-`200` HTTP status\ncode, query the server to find out how much of the upload succeeded.\n\nHere is a `POST` request to the resumable session URL. `X-Goog-Upload-Command`\nshould be set to `query`. \n\n```\nPOST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1\nContent-Length: 0\nX-Goog-Upload-Command: query\n```\n\nThe response from the server includes a `200 OK` HTTP status code and the\ncurrent size of the upload. \n\n```\nHTTP/1.1 200 OK\nX-Goog-Upload-Status: active\nX-Goog-Upload-Size-Received: 100\n```\n\nYou can then resume uploading at this offset. You must resume at the offset\nprovided by the server unless you send a combined upload and finalize command,\nin which case you can also resume at offset 0.\n\nIf the `X-Goog-Upload-Status` header in the HTTP response of your query command\nis present and the value is not `active`, that indicates that the upload has\nalready been terminated."]]
