تتألف عملية تحميل ملفات الوسائط من خطوتَين:
- حمِّل وحدات البايت لملفات الوسائط إلى خادم 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 Photos Library API المتوافقة عمليات التحميل القابلة للاستئناف لعبة قابلة للاستئناف يسمح لك "تحميل" بتقسيم ملف الوسائط إلى أقسام متعددة وتحميل قسم كل قسم في كل مرة.
الخطوة 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: إنشاء ملفات وسائط
في الخطوة 1، يمكنك تحميل وحدات بايت متعددة من مستخدمين متعددين بالتوازي، ولكن في الخطوة 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.
استمر في هذه العملية إلى أن تكتمل جميع عمليات التحميل ومكالمات إنشاء الوسائط.