קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
בדף הזה מוסבר איך ליצור בקשת העלאה שניתן להמשיך ל-Google Photos Library 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
מגדירים את המספר הכולל של הבייטים של נתוני הקובץ
הועברה.
שדה הכותרת x-goog-upload-chunk-granularity מכיל את היישור של הבייטים
ואת רמת הפירוט של הגודל של כל מקטעי הנתונים שהלקוח שולח. אם ההעלאה
מתבצע במספר מקטעים, כל ההעלאות, מלבד ההעלאה האחרונה,
חייב להתבצע בכפולות של הערך הזה. כלומר, העלאת הבייטים של הקובץ
חייב להיות תואם לערך הזה. במקטע האחרון אפשר להעלות את שאר
בייטים.
שדה הכותרת X-Goog-Upload-URL מכיל כתובת URL ייחודית שחובה להשתמש בה
להשלים את ההעלאה באמצעות כל הבקשות שנותרו. העתקה ושמירה של הפריט
כתובת URL של סשן שניתן להמשיך, כך שאפשר יהיה להשתמש בה בבקשות הבאות.
שלב 3: העלאת הקובץ
יש שתי דרכים להעלות קובץ באמצעות סשן שניתן להמשיך:
בבקשה אחת. בדרך כלל הגישה הזו היא הטובה ביותר,
כי הוא דורש פחות בקשות, ולכן הביצועים שלו טובים יותר.
במספר מקטעים. בשיטה הזו, מתבצעות העלאות
בבקשות מרובות על ידי קיבוץ הנתונים. הנתונים מפולחים לפי
כפולות של x-goog-upload-chunk-granularity. במקרה הצורך,
אפשר לנסות שוב את הבקשות במקטעים.
כדאי להשתמש בגישה הזו אם:
צריך להפחית את כמות הנתונים שמועברים בכל
בקשה. יכול להיות שתצטרכו לעשות זאת כשיש מגבלת זמן קבועה עבור
לבקשות נפרדות.
צריך לספק אינדיקטור מותאם אישית שמראה את ההעלאה
על ההתקדמות במשחק.
עליכם לדעת מתי אפשר למחוק נתונים בבטחה.
בקשה יחידה
כדי להעלות את הקובץ בבקשה אחת:
יוצרים בקשת POST לכתובת ה-URL של הסשן שניתן להמשיך.
מוסיפים את נתוני הקובץ לגוף הבקשה.
מוסיפים את כותרות ה-HTTP הבאות:
Content-Length: מוגדר למספר הבייטים בקובץ ה-
חדש.
X-Goog-Upload-Command: מוגדר ל-upload,
finalize.
שולחים את הבקשה.
אם בקשת ההעלאה נקטעת או אם מקבלים 5xx
יש לבצע את התהליך שבקטע המשך של
ההעלאה הופסקה.
אם הבקשה תתבצע בהצלחה, תקבלו סטטוס HTTP 200 OK
ואסימון העלאה בגוף התגובה.
יצירה
פריט המדיה באמצעות אסימון ההעלאה הזה.
גושים מרובים
כדי להעלות את הקובץ במספר מקטעים:
יוצרים בקשת POST לכתובת ה-URL של הסשן שניתן להמשיך.
מוסיפים את נתוני המקטע לגוף הבקשה.
מלבד המקטע הסופי שמבצע את ההעלאה, יוצרים את המקטע
מקטעים אחרים בכפולות של גודל המקטעים המקובל. להשאיר את
גודל מקטע גדול ככל האפשר כדי שההעלאה תהיה יעילה.
מוסיפים את כותרות ה-HTTP הבאות:
Content-Length: מוגדר למספר הבייטים בקובץ ה-
של מקטע הנתונים.
X-Goog-Upload-Command: מוגדר ל-upload.
למקטע האחרון, מגדירים את הערך upload, finalize.
X-Goog-Upload-Offset: מוגדר לקיזוז שבו
צריך לכתוב בייטים. הערה: צריך להעלות את הבייטים
מספר סידורי. ההיסט הראשון הוא 0.
שולחים את הבקשה.
אם בקשת ההעלאה נקטעת או אם מקבלים 5xx
יש לבצע את התהליך שבקטע המשך של
ההעלאה הופסקה.
חוזרים על השלבים שלמעלה עבור כל המקטעים שנותרו בקובץ.
אם הבקשה תתבצע בהצלחה, תקבלו סטטוס HTTP 200 OK
ואסימון העלאה בגוף התגובה.
יצירה
פריט המדיה באמצעות אסימון ההעלאה הזה.
דוגמה
בקשה יחידה
הדוגמה הבאה מציגה בקשה שניתן להמשיך להעלאת קובץ
קובץ JPEG בגודל 3,039,417 בייטים בבקשה אחת.
הדוגמה הבאה מציגה בקשה שניתן להמשיך להעלאת קובץ
קובץ JPEG בגודל 3,039,417 בייטים במספר מקטעים, תוך שימוש בסשן שניתן להמשיך
כתובת ה-URL ורמת הפירוט של גודל המקטע הקביל שהתקבלו בשלב הקודם.
בדוגמה הזו נעשה שימוש בגודל מקטע של 262,144 בייטים שהוחזרו בפונקציה
שדה הכותרת, x-goog-upload-chunk-granularity, כאשר
אותחל סשן ההעלאה. חשוב לזכור שכל העלאה מכילה בייטים
בכפולות של 262,144.
הפעלה של סשן ההעלאה כדי לקבל את כתובת ה-URL להעלאה ואת גודל המקטע
כפי שהוסבר בשלב הקודם:
אם בקשת ההעלאה הופסקה או אם מקבלים סטטוס HTTP שאינו 200
שולחים שאילתה לשרת כדי לברר כמה אחוזים מההעלאה הצליחו.
הנה בקשת POST לכתובת ה-URL של הסשן שניתן להמשיך. 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
התגובה מהשרת כוללת קוד מצב HTTP 200 OK ואת
הגודל הנוכחי של ההעלאה.
HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100
לאחר מכן תוכלו להמשיך את ההעלאה בקיזוז הזה. צריך להמשיך את המשחק לאחר הקיזוז
שסופקו על ידי השרת, אלא אם תשלחו פקודת העלאה משולבת ומסיימים,
במקרה כזה אפשר להמשיך גם בהיסט 0.
אם הכותרת X-Goog-Upload-Status בתגובת ה-HTTP של פקודת השאילתה
קיים והערך אינו active, שמציין שההעלאה
כבר הופסק.
[[["התוכן קל להבנה","easyToUnderstand","thumb-up"],["התוכן עזר לי לפתור בעיה","solvedMyProblem","thumb-up"],["סיבה אחרת","otherUp","thumb-up"]],[["חסרים לי מידע או פרטים","missingTheInformationINeed","thumb-down"],["התוכן מורכב מדי או עם יותר מדי שלבים","tooComplicatedTooManySteps","thumb-down"],["התוכן לא עדכני","outOfDate","thumb-down"],["בעיה בתרגום","translationIssue","thumb-down"],["בעיה בדוגמאות/בקוד","samplesCodeIssue","thumb-down"],["סיבה אחרת","otherDown","thumb-down"]],["עדכון אחרון: 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."]]
