بعد إجراء مكالمات على إدراج محتوى مكتبة الصور أو الألبومات بدلاً من تخزين عناصر الوسائط التي تم إرجاعها، يجب على التطبيق تخزين ومعرّفات ملفات الوسائط. ويرجع هذا إلى أن محتوى عناصر الوسائط تتغير بعد فترة معيّنة، وتنتهي صلاحية عناوين 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 Photos Library API تتيح لك الوصول إلى وحدات البايت الخاصة بالوسائط. عناصر. باستخدام عناوين 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 الأساسية لعمليات تنزيل الفيديوهات فترةً تصل إلى بضع ثوانٍ وحدات بايت للعودة. يتم ضبط خيار تنزيل الفيديوهات تلقائيًا على ترميز H.264. في حال تعذُّر ترميز H.264، سيتم استخدام VP9. قبل استخدام هذه المعلمة، تحقق من أن عناصر الوسائط
قيمة الحقل " أمثلة: 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 لقاعدة الصور. |