تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
توضّح هذه الصفحة كيفية تقديم طلب تحميل قابل للاستئناف إلى 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.
يوضح المثال التالي طلبًا قابلاً للاستئناف لتحميل
ملف JPEG بحجم 3039417 بايت في أجزاء متعددة، باستخدام الجلسة القابلة للاستئناف
عنوان URL ودقة حجم المجموعة المقبولة التي تم الحصول عليها في الخطوة السابقة.
يستخدم هذا المثال حجم مقطع يبلغ 262144 بايت تم إرجاعه في
حقل العنوان، x-goog-upload-chunk-granularity، عندما
تم إعداد جلسة تحميل واحدة. لاحظ أن كل عملية تحميل تحتوي على وحدات بايت
في مضاعفات 262144.
يجب إعداد جلسة التحميل لتلقّي عنوان 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، ما يشير إلى أن التحميل
تم إنهاؤها بالفعل.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\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."]]
