بعد إجراء طلبات من أجل إدراج محتوى مكتبة الصور أو الألبوم بدلاً من تخزين عناصر الوسائط التي تم عرضها، من المفترض أن يخزِّن التطبيق معرّفات ملفات الوسائط. ويرجع ذلك إلى أنّ محتوى عناصر الوسائط قد يتغيّر، وتنتهي صلاحية عناوين URL المضمّنة في الاستجابة بعد فترة معيّنة. يعرّف معرّف عنصر الوسائط بشكل فريد عنصر الوسائط، مثل صورة أو فيديو داخل مكتبة المستخدم.
تجدر الإشارة إلى أنّه يجب ألا يخزّن تطبيقك صورة المستخدم أو فيديو المستخدم في ذاكرة التخزين المؤقت لفترات زمنية طويلة، ولكن يمكنك تخزين معرّف عنصر الوسائط أو تخزينه مؤقتًا حسب الضرورة. ويجب أيضًا ملاحظة أن الوصول إلى بيانات المستخدمين يخضع لالتزامات الخصوصية.
نطاقات التفويض المطلوبة
للوصول إلى عناصر الوسائط، يجب أن يطلب تطبيقك واحدًا على الأقل من نطاقات التفويض التالية. يعتمد الوصول إلى عناصر الوسائط التي يتم عرضها في الرد على النطاقات التي طلبتها.
- تتيح ميزة
photoslibrary.readonly
الوصول إلى كل عناصر الوسائط في مكتبة المستخدم. photoslibrary.readonly.appcreateddata
يسمح بالوصول فقط إلى عناصر الوسائط التي أنشأها التطبيق
عناصر الوسائط
تمثّل السمة mediaItem
الوسائط، مثل صورة أو فيديو تم تحميله إلى مكتبة "صور Google". إنه كائن من المستوى الأعلى، ويمكن أن تختلف خصائصه بناءً على نوع الوسائط الأساسي.
يسرد الجدول التالي سمات mediaItem
:
أماكن إقامة | |
---|---|
id |
معرّف دائم وثابت لتحديد العنصر. |
description |
وصف لعنصر الوسائط كما يظهر في "صور Google". |
baseUrl |
تُستخدَم للوصول إلى وحدات البايت الأولية. لمزيد من المعلومات، راجع عناوين URL الأساسية. |
productUrl |
رابط إلى الصورة داخل "صور Google". لا يستطيع فتح هذا الرابط سوى المستخدم وحده. تشير عناوين URL إلى عنصر وسائط في المكتبة. إذا تم استرداد عنوان URL من بحث عن ألبوم، فإنّه يشير إلى العنصر داخل الألبوم. |
mimeType |
تمثّل هذه السمة نوع عنصر الوسائط الذي يساعد في التعرّف على نوع الوسائط بسهولة (على سبيل المثال: image/jpg ). |
filename |
اسم ملف الوسائط المعروض للمستخدم في تطبيق "صور Google" (ضمن قسم معلومات العنصر) |
mediaMetadata |
يختلف توفّرها حسب النوع الأساسي للوسائط، مثل photo
أو video .
لتقليل الحمولة، يمكن استخدام أقنعة الحقل.
|
contributorInfo |
لا تتم تعبئة هذا الحقل إلا إذا كان عنصر الوسائط في ألبوم مشترَك
أنشأه هذا التطبيق وإذا منح المستخدم
النطاق تحتوي على معلومات عن المساهم الذي أضاف عنصر الوسائط هذا. لمزيد من التفاصيل، يُرجى الاطّلاع على مشاركة الوسائط. |
الحصول على ملف وسائط
لاسترداد عنصر وسائط، يمكنك استدعاء
mediaItems.get باستخدام
mediaItemId
. يعرض الطلب عنصر وسائط واحدًا.
يحتوي mediaItem
على خصائص، مثل المعرّف والوصف وعنوان URL. وتستند المعلومات الإضافية ضمن السمة photo
أو video
إلى البيانات الوصفية ضمن الملف. قد لا تتوفّر بعض السمات. يحتوي ContributorInfo
على بيانات وصفية
للعناصر التي تشكّل جزءًا من ألبوم مشترك. لا يتم تضمين هذا الحقل إلا عند إدراج محتوى ألبوم مشترَك حيث منح المستخدم photoslibrary.sharing
نطاق التفويض.
إذا كان عنصر الوسائط عبارة عن فيديو، يجب معالجة ملف الفيديو أولاً. ويتضمّن
mediaItem
الحقل status
داخل mediaMetadata
الذي يصف
حالة معالجة ملف الفيديو. يعرض الملف الذي تم تحميله حديثًا الخطأ
videoProcessingStatus
بالقيمة PROCESSING
أولاً، قبل أن يصبح READY
للاستخدام. لا يكون baseUrl
لعنصر وسائط الفيديو متاحًا إلى أن تتم معالجة الفيديو.
راحة
إليك طلب GET:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-token
يبدو الرد على عنصر وسائط الصور كالتالي. تحتوي سمة الصورة على بيانات وصفية لعناصر الصور.
{ "id": "media-item-id", "description": "item-description", "productUrl": "url-to-open-in-google-photos", "baseUrl": "base-url_do-not-use-directly", "mimeType": "mime-type-of-media", "filename": "item-filename", "mediaMetadata": { "width": "media-item-width", "height": "media-item-height", "creationTime": "media-item-creation-time", "photo": { "cameraMake": "make-of-the-camera", "cameraModel": "model-of-the-camera", "focalLength": "focal-length-of-the-camera-lens", "apertureFNumber": "aperture-f-number-of-the-camera-lens", "isoEquivalent": "iso-of-the-camera", "exposureTime": "exposure-time-of-the-camera-aperture" } }, "contributorInfo": { "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly", "displayName": "name-of-user" } }
تظهر الاستجابة لعنصر وسائط الفيديو على النحو التالي. تحتوي سمة الفيديو على بيانات وصفية لعناصر الفيديو.
{ "id": "media-item-id", "description": "item-description", "productUrl": "url-to-open-in-google-photos", "baseUrl": "base-url_do-not-use-directly", "mimeType": "mime-type-of-media", "filename": "item-filename", "mediaMetadata": { "width": "media-item-width", "height": "media-item-height", "creationTime": "media-item-creation-time", "video": { "cameraMake": "make-of-the-camera", "cameraModel": "model-of-the-camera", "fps": "frame-rate-of-the-video", "status": "READY" }, }, "contributorInfo": { "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly", "displayName": "name-of-user" } }
Java
تحتوي سمة الصورة على بيانات وصفية لعناصر الصور.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasPhoto()) { // This media item is a photo and has additional photo metadata Photo photoMetadata = metadata.getPhoto(); String cameraMake = photoMetadata.getCameraMake(); String cameraModel = photoMetadata.getCameraModel(); float aperture = photoMetadata.getApertureFNumber(); int isoEquivalent = photoMetadata.getIsoEquivalent(); // ... } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
تحتوي سمة الفيديو على بيانات وصفية لعناصر الفيديو.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasVideo()) { // This media item is a video and has additional video metadata Video videoMetadata = metadata.getVideo(); VideoProcessingStatus status = videoMetadata.getStatus(); if (status.equals(VideoProcessingStatus.READY)) { // This video media item has been processed String cameraMake = videoMetadata.getCameraMake(); String cameraModel = videoMetadata.getCameraModel(); double fps = videoMetadata.getFps(); // ... } } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
PHP
تحتوي سمة الصورة على بيانات وصفية لعناصر الصور.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $photoMetadata = $metadata->getPhoto(); if (!is_null($photoMetadata)) { // This media item is a photo and has additional photo metadata $cameraMake = $photoMetadata->getCameraMake(); $cameraModel = $photoMetadata->getCameraModel(); $aperture = $photoMetadata->getApertureFNumber(); $isoEquivalent = $photoMetadata->getIsoEquivalent(); // ... } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
تحتوي سمة الفيديو على بيانات وصفية لعناصر الفيديو.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $videoMetadata = $metadata->getVideo(); if (!is_null($videoMetadata)) { // This media item is a video and has additional video metadata if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) { // This video media item has been processed $cameraMake = $videoMetadata->getCameraMake(); $cameraModel = $videoMetadata->getCameraModel(); $fps = $videoMetadata->getFps(); // ... } } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
الحصول على ملفات وسائط متعددة
لاسترداد عناصر وسائط متعددة حسب معرّفاتها، يمكنك استدعاء
mediaItems.batchGet
باستخدام mediaItemId
.
يعرض الطلب قائمة MediaItemResults
بترتيب معرفات عناصر الوسائط المقدمة في الطلب. وتحتوي كل نتيجة
على MediaItem
أو Status
إذا كان هناك خطأ.
الحدّ الأقصى لعدد ملفات الوسائط التي يمكنك طلبها في مكالمة واحدة هو 50 ملف وسائط. يجب ألا تحتوي قائمة عناصر الوسائط على معرّفات مكرّرة ولا يمكن أن تكون فارغة.
راحة
في ما يلي طلب GET يعرض الوصول الناجح وغير الناجح إلى
عناصر الوسائط. حدِّد كل معرّف عنصر وسائط كمَعلمة طلب بحث mediaItemIds
جديدة كجزء من الطلب:
GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id Content-type: application/json Authorization: Bearer oauth2-token
يعرض طلب GET الاستجابة التالية:
{ "mediaItemResults": [ { "mediaItem": { "id": "media-item-id", ... } }, { "mediaItem": { "id": "another-media-item-id", ... } }, { "status": { "code": 3, "message": "Invalid media item ID." } } ] }
Java
try { // List of media item IDs to retrieve List<String> mediaItemIds = Arrays .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"); // Get a list of media items using their IDs BatchGetMediaItemsResponse response = photosLibraryClient .batchGetMediaItems(mediaItemIds); // Loop over each result for (MediaItemResult result : response.getMediaItemResultsList()) { // Each MediaItemresult contains a status and a media item if (result.hasMediaItem()) { // The media item was successfully retrieved, get some properties MediaItem item = result.getMediaItem(); String id = item.getId(); // ... } else { // If the media item is not set, an error occurred and the item could not be loaded // Check the status and handle the error Status status = result.getStatus(); // ... } } } catch (ApiException e) { // Handle error }
PHP
try { // List of media item IDs to retrieve $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"]; // Get a list of media items using their IDs $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds); // Loop over each result foreach ($response->getMediaItemResults() as $itemResult) { // Each MediaItemresult contains a status and a media item $mediaItem = $itemResult->getMediaItem(); if(!is_null($mediaItem)){ // The media item was successfully retrieved, get some properties $id = $mediaItem->getId(); // ... } else { // If the media item is null, an error occurred and the item could not be loaded } } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
عناوين URL الأساسية
تسمح لك عناوين URL الأساسية ضمن واجهة برمجة التطبيقات لمكتبة صور Google بالوصول إلى وحدات البايت الخاصة بعناصر الوسائط. باستخدام عناوين URL الأساسية المختلفة، يمكن لتطبيقك إما تنزيل عناصر الوسائط أو عرض عناصر الوسائط داخل التطبيق. إنّ عناوين URL الأساسية هي سلاسل يتم تضمينها في الاستجابة عند إدراج الألبومات أو الوصول إلى عناصر الوسائط. وهي صالحة لمدة 60 دقيقة وتتطلب معلمات إضافية حيث لا يمكن استخدامها كما هي.
عناوين URL الأساسية المختلفة هي:
baseUrl
: الوصول مباشرةً إلى الصورة أو الصورة المصغّرة للفيديو أو تنزيل وحدات البايت الخاصة بالفيديوcoverPhotoBaseUrl
: الوصول مباشرةً إلى صورة غلاف الألبومprofilePictureBaseUrl
: الوصول مباشرةً إلى صورة الملف الشخصي لمالكmediaItem
عناوين URL الأساسية للصور
في ما يلي قائمة بالخيارات التي يمكنك استخدامها مع عناوين URL الأساسية للصور:
المَعلمة | |
---|---|
w ، h |
الوصف العرض و للوصول إلى عنصر وسائط مصور، مثل صورة أو صورة مصغّرة لفيديو، يجب تحديد الأبعاد التي تخطط لعرضها في تطبيقك (بحيث يمكن تحجيم الصورة إلى هذه الأبعاد مع الحفاظ على نسبة العرض إلى الارتفاع). لإجراء ذلك، اربط عنوان URL الأساسي بالسمات المطلوبة كما هو موضّح في الأمثلة. أمثلة: base-url=wmax-width-hmax-height في ما يلي مثال لعرض عنصر وسائط لا يزيد عرضه عن 2048 بكسل وألا يزيد طوله عن 1024 بكسل: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
الوصف الاقتصاص، معلمة إذا كنت تريد اقتصاص الصورة بسمتَي العرض والارتفاع بدقة
التي حدّدتها، يمكنك إجراء تسلسل لعنوان URL الأساسي مع
المَعلمة يجب أن يكون الحجم (بالبكسل) في النطاق [1، 16383]. إذا تجاوز عرض الصورة أو ارتفاعها الحجم المطلوب، سيتم تصغير الصورة واقتصاصها (مع الحفاظ على نسبة العرض إلى الارتفاع). أمثلة: base-url=wmax-width-hmax-height-c في هذا المثال، يعرض التطبيق عنصر وسائط يبلغ عرضه 256 بكسل × ارتفاع 256 بكسل بالضبط، مثل صورة مصغّرة: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
الوصف التنزيل، معلَمة إذا أردت تنزيل الصورة التي تحتفظ بجميع بيانات Exif الوصفية باستثناء البيانات الوصفية للموقع الجغرافي، يمكنك ربط عنوان URL الأساسي مع المَعلمة أمثلة: base-url=d في هذا المثال، ينزِّل التطبيق صورة تحتوي على جميع البيانات الوصفية باستثناء البيانات الوصفية للموقع الجغرافي: https://lh3.googleusercontent.com/p/Az....XabC=d |
عناوين URL الأساسية للفيديو
في ما يلي قائمة بالخيارات التي يمكنك استخدامها مع عناوين URL الأساسية للفيديو:
المَعلمة | |
---|---|
dv |
الوصف للوصول إلى وحدات البايت الخاصة بالفيديو تطلب المعلَمة dv الحصول على نسخة عالية الجودة تم تحويل ترميزها من الفيديو الأصلي. ويُرجى العِلم بأنّ المَعلمة غير متوافقة مع المعلّمتَين w وh. قد تستغرق عناوين URL الأساسية لتنزيل الفيديوهات مدة تصل إلى بضع ثوانٍ لعرض وحدات البايت. قبل استخدام هذه المَعلمة، تأكّد من أنّ حقل أمثلة: base-url=dv يوضح المثال التالي كيفية تنزيل وحدات البايت الخاصة بفيديو: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w وh وc
وd |
الوصف للوصول إلى الصورة المصغّرة للفيديو، استخدِم أيًا من مَعلمات عناوين URL لقاعدة الصورة. بشكل تلقائي، تتضمّن جميع الصور المصغّرة للفيديوهات طبقة على شكل زر تشغيل. اطّلِع على المَعلمة -no لإزالة هذا التراكب. أمثلة: راجِع جدول عناوين URL الأساسية للصور للاطّلاع على أمثلة. |
no |
الوصف طبقة إزالة الصورة المصغّرة، مَعلمة إذا أردت استرداد الصورة المصغّرة لفيديو بدون النقر على زرّ التشغيل، يمكنك إجراء تسلسل لعنوان URL الأساسي مع المعلمة no. يجب استخدام المَعلمة no مع مَعلمة عنوان URL لقاعدة الصورة على الأقل. أمثلة: base-url=wmax-width-hmax-height-no يعرض المثال التالي صورة مصغّرة للفيديو يبلغ عرضها 1280 بكسل وارتفاعها 720 بكسل بالضبط ولا تتضمّن تراكبًا لزر التشغيل: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
عناوين URL الأساسية للصور المتحركة
تحتوي الصور الحيّة على عناصر الصورة والفيديو. يمكنك استخدام معلَمات من عناوين URL الأساسية للصور أو عناوين URL الأساسية للفيديوهات لطلبات baseUrl
للصور المتحركة.
المَعلمة | |
---|---|
dv |
الوصف لاسترداد عنصر الفيديو لعنصر وسائط صور حيّة، استخدِم
المعلَمة |
w وh وc
وd |
الوصف لاسترداد عنصر الصورة لعنصر وسائط صور حيّة، استخدِم التنسيق لعناوين URL الأساسية للصور. |