تتألف عملية تحميل عناصر الوسائط من خطوتين:
- يمكنك تحميل وحدات البايت من ملفات الوسائط إلى خادم Google باستخدام نقطة نهاية عمليات التحميل. يؤدي هذا إلى إرجاع رمز مميز للتحميل يحدد وحدات البايت التي تم تحميلها.
- استخدِم طلب batchCreate باستخدام الرمز المميّز للتحميل لإنشاء عنصر وسائط في حساب المستخدم على "صور Google".
توضّح هذه الخطوات عملية تحميل ملف وسائط واحد. إذا كنت تحمِّل عدة عناصر وسائط (من المرجّح جدًا لأي تطبيق إنتاجي)، ننصحك بمراجعة أفضل الممارسات المتعلّقة بالتحميل لتحسين كفاءة التحميل.
قبل البدء
نطاقات التفويض المطلوبة
يجب توفير نطاق photoslibrary.appendonly
أو photoslibrary
لتحميل عناصر الوسائط إلى مكتبة المستخدم أو ألبومه.
يمكن أيضًا إنشاء عناصر الوسائط باستخدام نطاق photoslibrary.sharing
. لإنشاء عناصر بنطاق photoslibrary.sharing
، يجب أولاً إنشاء ألبوم ووضع علامة عليه بأنّه تمّت مشاركته باستخدام shareAlbum
. يمكنك بعد ذلك إنشاء عناصر وسائط
تتم مشاركتها مع المستخدم في الألبوم. لا يمكنك إنشاء عناصر مباشرةً في مكتبة المستخدم
أو في الألبومات التي لم يشاركها تطبيقك.
عند إدراج الألبومات، تشير السمة isWriteable
إلى ما إذا كان
بإمكان التطبيق إنشاء وسائط في ألبوم معيّن.
أنواع الملفات وأحجامها المقبولة
يمكنك تحميل أنواع الملفات المدرَجة في الجدول أدناه.
نوع الوسائط | أنواع الملفات المقبولة | الحد الأقصى لحجم الملف |
---|---|---|
الصور | AVIF وBMP وGIF وHEIC وICO وJPG وPNG وTIFF وWEBP وبعض ملفات RAW. | 200 ميغابايت |
الفيديوهات | 3GP و3G2 وASF وAVI وDIVX وM2T وM2TS وM4V وMKV وMMV وMOD وMOV وMP4 وMPG وMTS وTOD وWMV. | 20 غيغابايت |
الخطوة 1: تحميل وحدات البايت
تحميل وحدات البايت إلى Google باستخدام طلبات التحميل يعرض طلب التحميل الناجح
رمزًا مميزًا للتحميل في شكل سلسلة نصية أولية. استخدِم الرموز المميّزة للتحميل
هذه لإنشاء عناصر وسائط من خلال طلب batchCreate
راحة
ضمِّن الحقول التالية في عنوان طلب POST:
حقول العناوين | |
---|---|
Content-type |
اضبط النوع على application/octet-stream . |
X-Goog-Upload-Content-Type |
يُنصح به. اضبط نوع MIME على وحدات البايت التي تحمِّلها.
تشمل أنواع MIME الشائعة image/jpeg وimage/png وimage/gif .
|
X-Goog-Upload-Protocol |
اضبط النوع على raw . |
إليك عنوان طلب POST:
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-type: application/octet-stream X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: raw
يجب تضمين البرنامج الثنائي للملف في نص الطلب:
media-binary-data
إذا نجح طلب POST هذا، يتم عرض رمز مميّز للتحميل في شكل سلسلة نصية أولية كنص للاستجابة. لإنشاء عناصر وسائط، استخدِم هذه السلاسل النصية في طلب batchCreate
.
upload-token
Java
// Open the file and automatically close it after upload try (RandomAccessFile file = new RandomAccessFile(pathToFile, "r")) { // Create a new upload request UploadMediaItemRequest uploadRequest = UploadMediaItemRequest.newBuilder() // The media type (e.g. "image/png") .setMimeType(mimeType) // The file to upload .setDataFile(file) .build(); // Upload and capture the response UploadMediaItemResponse uploadResponse = photosLibraryClient.uploadMediaItem(uploadRequest); if (uploadResponse.getError().isPresent()) { // If the upload results in an error, handle it Error error = uploadResponse.getError().get(); } else { // If the upload is successful, get the uploadToken String uploadToken = uploadResponse.getUploadToken().get(); // Use this upload token to create a media item } } catch (ApiException e) { // Handle error } catch (IOException e) { // Error accessing the local file }
PHP
try { // Create a new upload request by opening the file // and specifying the media type (e.g. "image/png") $uploadToken = $photosLibraryClient->upload(file_get_contents($localFilePath), null, $mimeType); } catch (\GuzzleHttp\Exception\GuzzleException $e) { // Handle error }
حجم الملف المقترَح للصور أقل من 50 ميغابايت. تكون الملفات التي يزيد حجمها عن 50 ميغابايت عرضة لمشاكل في الأداء.
تتيح واجهة برمجة التطبيقات لمكتبة صور Google عمليات التحميل القابلة للاستئناف. تتيح لك عملية التحميل القابلة للاستئناف تقسيم ملف الوسائط إلى أقسام متعددة وتحميل قسم واحد في كل مرة.
الخطوة 2: إنشاء ملف وسائط
بعد تحميل وحدات البايت لملفات الوسائط، يمكنك إنشاؤها كعناصر وسائط في "صور Google" باستخدام الرموز المميزة للتحميل. يكون الرمز المميز للتحميل صالحًا لمدة يوم واحد بعد إنشائه. وتتم دائمًا إضافة عنصر وسائط إلى مكتبة المستخدم. لا يمكن إضافة عناصر الوسائط إلى الألبومات إلا التي أنشأها تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على نطاقات التفويض.
لإنشاء عناصر وسائط جديدة، يمكنك استدعاء
mediaItems.batchCreate
من خلال تحديد قائمة newMediaItems
. ويحتوي كل newMediaItem
على رمز مميّز للتحميل يتم تحديده داخل simpleMediaItem
ووصف اختياري يتم عرضه للمستخدم.
يقتصر حقل الوصف على 1000 حرف، ويجب أن يتضمن فقط نصًا مفيدًا أنشأه المستخدمون. على سبيل المثال، "رحلتنا إلى الحديقة" أو "عشاء الأعياد". لا تضمِّن بيانات وصفية مثل أسماء الملفات أو العلامات الآلية أو أي نص آخر يتم إنشاؤه تلقائيًا.
للحصول على أفضل أداء، يمكنك تقليل عدد المكالمات إلى mediaItems.batchCreate
التي يتعيّن عليك إجراؤها من خلال تضمين عناصر وسائط متعددة في مكالمة واحدة. انتظِر دائمًا
حتى يكتمل الطلب السابق قبل إجراء اتصال لاحق
للمستخدم نفسه.
يمكنك إنشاء عنصر وسائط واحد أو عدة عناصر في مكتبة المستخدم من خلال تحديد الأوصاف والرموز المميّزة للتحميل الخاصة بها:
راحة
إليك عنوان طلب POST:
POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate Content-type: application/json Authorization: Bearer oauth2-token
يجب أن يحدّد نص الطلب قائمة newMediaItems
.
{ "newMediaItems": [ { "description": "item-description", "simpleMediaItem": { "fileName": "filename", "uploadToken": "upload-token" } } , ... ] }
Java
try { // Create a NewMediaItem with the following components: // - uploadToken obtained from the previous upload request // - filename that will be shown to the user in Google Photos // - description that will be shown to the user in Google Photos NewMediaItem newMediaItem = NewMediaItemFactory .createNewMediaItem(uploadToken, fileName, itemDescription); List<NewMediaItem> newItems = Arrays.asList(newMediaItem); BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems); for (NewMediaItemResult itemsResponse : response.getNewMediaItemResultsList()) { Status status = itemsResponse.getStatus(); if (status.getCode() == Code.OK_VALUE) { // The item is successfully created in the user's library MediaItem createdItem = itemsResponse.getMediaItem(); } else { // The item could not be created. Check the status and try again } } } catch (ApiException e) { // Handle error }
PHP
try { $newMediaItems = []; // Create a NewMediaItem with the following components: // - uploadToken obtained from the previous upload request // - filename that will be shown to the user in Google Photos // - description that will be shown to the user in Google Photos $newMediaItems[0] = PhotosLibraryResourceFactory::newMediaItemWithDescriptionAndFileName( $uploadToken, $itemDescription, $fileName); $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems); foreach ($response->getNewMediaItemResults() as $itemResult) { $status = $itemResult->getStatus(); if ($status->getCode() != Code::OK) { // Error while creating the item. } } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
يمكنك إضافة عناصر وسائط إلى المكتبة وإلى ألبوم من خلال تحديد
الألبوم id
. لمزيد من المعلومات، يُرجى الاطّلاع على
إنشاء ألبومات.
ويمكن أن يحتوي كل ألبوم على ما يصل إلى 20,000 ملف وسائط. وستتعذّر طلبات إنشاء عناصر وسائط في ألبوم تتجاوز هذا الحد.
راحة
{ "albumId": "album-id", "newMediaItems": [ { "description": "item-description", "simpleMediaItem": { "fileName": "filename", "uploadToken": "upload-token" } } , ... ] }
Java
try { // Create new media items in a specific album BatchCreateMediaItemsResponse response = photosLibraryClient .batchCreateMediaItems(albumId, newItems); // Check the response } catch (ApiException e) { // Handle error }
PHP
try { $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
يمكنك أيضًا تحديد albumId
وalbumPosition
لإدراج عناصر
وسائط في مكان معيّن في الألبوم.
راحة
{ "albumId": "album-id", "newMediaItems": [ { "description": "item-description", "simpleMediaItem": { "fileName": "filename", "uploadToken": "upload-token" } } , ... ], "albumPosition": { "position": "after-media-item", "relativeMediaItemId": "media-item-id" } }
Java
try { // Create new media items in a specific album, positioned after a media item AlbumPosition positionInAlbum = AlbumPositionFactory.createFirstInAlbum(); BatchCreateMediaItemsResponse response = photosLibraryClient .batchCreateMediaItems(albumId, newItems, positionInAlbum); // Check the response } catch (ApiException e) { // Handle error }
PHP
try { $albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId); $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId, 'albumPosition' => $albumPosition]); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
لمزيد من التفاصيل حول تحديد الموضع في الألبومات، يُرجى الاطّلاع على إضافة معلومات مفصّلة.
الرد على إنشاء العنصر
يعرض الاستدعاء mediaItems.batchCreate
النتيجة لكل عنصر من ملفات الوسائط التي حاولت إنشاؤها. تشير قائمة newMediaItemResults
إلى الحالة
وتتضمن uploadToken
للطلب. يشير رمز الحالة غير الصفري إلى
خطأ.
راحة
إذا تم إنشاء جميع عناصر الوسائط بنجاح، يعرض الطلب حالة HTTP 200 OK
. وإذا تعذّر إنشاء بعض عناصر الوسائط،
يعرض الطلب حالة HTTP 207 MULTI-STATUS
للإشارة إلى
النجاح الجزئي.
{ "newMediaItemResults": [ { "uploadToken": "upload-token", "status": { "message": "Success" }, "mediaItem": { "id": "media-item-id", "description": "item-description", "productUrl": "https://photos.google.com/photo/photo-path", "mimeType": "mime-type", "mediaMetadata": { "width": "media-width-in-px", "height": "media-height-in-px", "creationTime": "creation-time", "photo": {} }, "filename": "filename" } }, { "uploadToken": "upload-token", "status": { "code": 13, "message": "Internal error" } } ] }
Java
BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems); // The response contains a list of NewMediaItemResults for (NewMediaItemResult result : response.getNewMediaItemResultsList()) { // Each result item is identified by its uploadToken String uploadToken = result.getUploadToken(); Status status = result.getStatus(); if (status.getCode() == Code.OK_VALUE) { // If the request is successful, a MediaItem is returned MediaItem mediaItem = result.getMediaItem(); String id = mediaItem.getId(); String productUrl = mediaItem.getProductUrl(); // ... } }
PHP
// The response from a call to batchCreateMediaItems returns a list of NewMediaItemResults foreach ($response->getNewMediaItemResults() as $itemResult) { // Each result item is identified by its uploadToken $itemUploadToken = $itemResult->getUploadToken(); // Verify the status of each entry to ensure that the item has been uploaded correctly $itemStatus = $itemResult->getStatus(); if ($itemStatus->getCode() != Code::OK) { // Error when item is being created } else { // Media item is successfully created // Get the MediaItem object from the response $mediaItem = $itemResult->getMediaItem(); // It contains details such as the Id of the item, productUrl $id = $mediaItem->getId(); $productUrl = $mediaItem->getProductUrl(); // ... } }
إذا تمت إضافة عنصر بنجاح، يتم عرض mediaItem
الذي يحتوي على
mediaItemId
وproductUrl
وmediaMetadata
. لمزيد من المعلومات، يُرجى الاطّلاع على المقالة
الوصول إلى عناصر الوسائط.
إذا كان عنصر الوسائط عبارة عن فيديو، يجب معالجته أولاً. تحتوي mediaItem
على status
داخل mediaMetadata
تصف حالة معالجة ملف الفيديو. يعرض الملف الذي تم تحميله حديثًا الحالة PROCESSING
أولاً،
قبل أن يصبح READY
للاستخدام. لمعرفة التفاصيل، يُرجى الاطّلاع على المقالة
الوصول إلى عناصر الوسائط.
إذا حدث خطأ أثناء هذه المكالمة، يُرجى اتّباع أفضل الممارسات وإعادة محاولة تقديم طلبك. ويمكنك تتبع الإضافات الناجحة حتى يمكن إدراج الصورة في الألبوم في الموضع الصحيح أثناء الطلب التالي. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء ألبومات.
يتم دائمًا عرض النتائج بنفس الترتيب الذي تم إرسال رموز التحميل به.
أفضل الممارسات المتعلقة بعمليات التحميل
تساعد أفضل الممارسات والمراجع التالية في تحسين كفاءتك بشكل عام باستخدام عمليات التحميل:
- استخدام إحدى مكتبات العملاء المعتمَدة
- اتّبِع أفضل الممارسات المتعلقة بإعادة المحاولة ومعالجة الأخطاء،
مع وضع النقاط التالية في الاعتبار:
- يمكن أن تحدث أخطاء
429
عند نفاد حصتك أو عندما يكون معدّل المكالمات محدودًا بسبب إجراء عدد كبير جدًا من المكالمات بسرعة كبيرة. احرص على عدم استدعاءbatchCreate
للمستخدم نفسه حتى يكتمل الطلب السابق. - تتطلب
429
أخطاء مهلة30s
على الأقل قبل إعادة المحاولة. استخدم استراتيجية التراجع الأسي عند إعادة محاولة تقديم الطلبات. - يحدث
500
خطأ عندما يواجه الخادم خطأ. عند التحميل، يحدث ذلك على الأرجح بسبب إجراء طلبات كتابة متعددة (مثلbatchCreate
) للمستخدم نفسه في الوقت نفسه. راجِع تفاصيل طلبك ولا تجري اتصالات بـbatchCreate
في الوقت نفسه.
- يمكن أن تحدث أخطاء
- استخدِم تدفق التحميل القابل للاستئناف لجعل عمليات التحميل أكثر فعالية في حال انقطاع الاتصال بالشبكة، وتقليل استخدام النطاق الترددي من خلال السماح لك باستئناف عمليات التحميل المكتملة جزئيًا. يُعدّ ذلك مهمًا عند التحميل من الأجهزة الجوّالة للعميل أو عند تحميل ملفات كبيرة الحجم.
بالإضافة إلى ذلك، ننصحك باتّباع النصائح التالية لكلّ خطوة من عملية التحميل: تحميل وحدات البايت ثم إنشاء عناصر الوسائط.
جارٍ تحميل وحدات البايت
- يمكن تحميل وحدات البايت (لاسترداد رموز التحميل) بالتوازي.
- يجب دائمًا ضبط نوع MIME الصحيح في العنوان
X-Goog-Upload-Content-Type
لكل مكالمة تحميل.
جارٍ إنشاء ملفات الوسائط
لا تُجرِ اتصالات لمستخدم واحد بالتوازي مع
batchCreate
.- لكل مستخدم، عليك إجراء مكالمات مع
batchCreate
الواحد تلو الآخر (بالتسلسل). - بالنسبة إلى عدة مستخدمين، يمكنك دائمًا إجراء مكالمات
batchCreate
لكل مستخدم واحدًا تلو الآخر. قدِّم طلبات لمستخدمين مختلفين بالتوازي فقط.
- لكل مستخدم، عليك إجراء مكالمات مع
ننصحك بتضمين أكبر عدد ممكن من
NewMediaItems
في كل مكالمة إلى الرقم "batchCreate
" لتقليل إجمالي عدد المكالمات التي يجب إجراؤها. يمكنك تضمين 50 عنصرًا على الأكثر.اضبط نص وصف مفيدًا أنشأه المستخدمون. لا تضمِّن بيانات وصفية، مثل أسماء الملفات أو العلامات الآلية أو أي نص آخر يتم إنشاؤه تلقائيًا في حقل الوصف.
مثال على جولة تفصيلية
يستخدم هذا المثال الكود الزائف لمتابعة تحميل عناصر الوسائط لعدة مستخدمين. يكمن الهدف في توضيح كلّ من خطوتَي عملية التحميل (تحميل وحدات البايت الأولية وإنشاء عناصر وسائط) وتفصيل أفضل الممارسات لإنشاء عملية دمج فعّالة ومرونة في عملية التحميل.
الخطوة 1: تحميل وحدات البايت الأولية
أنشئ أولاً قائمة انتظار لتحميل وحدات البايت الأولية لعناصر الوسائط من جميع المستخدمين. تتبُّع كل uploadToken
منتج تم إرجاعه لكل مستخدم. تذكر هذه النقاط الرئيسية:
- يعتمد عدد سلاسل محادثات التحميل المتزامن على بيئة التشغيل في جهازك.
- يمكنك إعادة ترتيب قائمة انتظار التحميل حسب الحاجة. على سبيل المثال، يمكنك تحديد أولوية عمليات التحميل استنادًا إلى عدد عمليات التحميل المتبقّية لكل مستخدم أو مستوى التقدّم العام للمستخدم أو متطلبات أخرى.
رمز زائف
CREATE uploadQueue FROM users, filesToUpload // Upload media bytes in parallel. START multiple THREADS WHILE uploadQueue is not empty POP uploadQueue UPLOAD file for user GET uploadToken CHECK and HANDLE errors STORE uploadToken for user in uploadTokensQueue END
الخطوة 2: إنشاء ملفات وسائط
في الخطوة الأولى، يمكنك تحميل عدة وحدات بايت من عدة مستخدمين بشكل متوازٍ، ولكن في الخطوة الثانية، يمكنك إجراء مكالمة واحدة فقط لكل مستخدم في الوقت نفسه.
رمز زائف
// For each user, create media items once 50 upload tokens have been // saved, or no more uploads are left per user. WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user // Calls can be made in parallel for different users, // but only make a single call per user at a time. START new thread for (this) user if there is no thread yet POP 50 uploadTokens from uploadTokensQueue for user CALL mediaItems.batchCreate with uploadTokens WAIT UNTIL batchCreate call has completed CHECK and HANDLE errors (retry as needed) DONE.
تابِع هذه العملية إلى أن تكتمل جميع عمليات التحميل ومكالمات إنشاء الوسائط.