الوصول إلى ملفات الوسائط التي أنشأها التطبيق

بعد إجراء طلبات لعرض محتوى مكتبة صور أو álbum، بدلاً من تخزين عناصر الوسائط المعروضة، يجب أن يخزِّن تطبيقك أرقام تعريف عناصر الوسائط. ويعود السبب في ذلك إلى أنّه قد يتغيّر محتوى عناصر الوسائط، وبعد مرور فترة معيّنة، تنتهي صلاحية عناوين URL المضمّنة في الاستجابة. يحدِّد رقم تعريف عنصر الوسائط عنصر وسائط بشكل فريد، مثل صورة أو فيديو داخل مكتبة المستخدم.

نطاقات التفويض المطلوبة

للوصول إلى ملفات الوسائط التي أنشأها التطبيق، يجب توفُّر نطاق photoslibrary.readonly.appcreateddata. لمزيد من المعلومات عن النطاقات، اطّلِع على نطاقات التفويض.

عناصر الوسائط

تمثل العلامة mediaItem الوسائط مثل صورة أو فيديو تم تحميله إلى مكتبة "صور Google". وهو عنصر من المستوى الأعلى ويمكن أن تختلف خصائصه استنادًا إلى نوع الوسائط الأساسي.

يسرد الجدول التالي سمات mediaItem:

أماكن إقامة
id معرّف دائم وثابت يتم استخدامه لتحديد الكائن.
description وصف لعنصر الوسائط كما يظهر في "صور Google"
baseUrl تُستخدَم للوصول إلى وحدات البايت الأوّلية. لمزيد من المعلومات، يُرجى الاطّلاع على عناوين URL الأساسية.
productUrl

رابط يؤدي إلى الصورة داخل "صور Google" لا يمكن للمطوّر فتح هذا الرابط، بل يمكن للمستخدم فقط فتحه. تشير عناوين URL إلى عنصر وسائط في المكتبة. إذا تم استرداد عنوان URL من بحث في الألبوم، فإنه يشير إلى العنصر ضمن الألبوم.

mimeType تمثّل هذه السمة نوع عنصر الوسائط للمساعدة في التعرّف على نوع الوسائط بسهولة (على سبيل المثال: image/jpg).
filename اسم ملف عنصر الوسائط الذي يظهر للمستخدم في تطبيق "صور Google" (ضمن قسم معلومات العنصر).
mediaMetadata يختلف ذلك حسب النوع الأساسي للوسائط، مثل photo أو video. لتقليل الحمولة، يمكن استخدام أقنعة الحقول.

الحصول على عنصر وسائط

لاسترداد عنصر وسائط، يمكنك استدعاء mediaItems.get باستخدامmediaItemId. يعرض الطلب عنصر وسائط واحدًا.

يحتوي mediaItem على سمات، مثل رقم التعريف والوصف وعنوان URL. وتستند المعلومات الإضافية ضمن photo أو video إلى البيانات الوصفية داخل الملف. قد لا تكون جميع المواقع متوفرة.

إذا كان عنصر الوسائط فيديو، يجب معالجة ملف الفيديو أولاً. يحتوي العنصر mediaItem على حقل status داخل mediaMetadata يصف حالة معالجة ملف الفيديو. يعرض الملف الذي تم تحميله حديثًا الرمز videoProcessingStatus بالقيمة PROCESSING أولاً، قبل أن يتم READY لاستخدامه. لا تتوفّر baseUrl لعنصر وسائط الفيديو إلى أن تتم معالجة الفيديو.

REST

في ما يلي طلب 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"
  }
}

الحصول على عناصر وسائط متعددة

لاسترداد عناصر وسائط متعددة حسب معرّفاتها، يمكنك استدعاء mediaItems.batchGet باستخدام mediaItemId.

يعرض الطلب قائمة بملفّات MediaItemResults بترتيب معرّفات عناصر الوسائط المقدَّمة في الطلب. تحتوي كل نتيجة على MediaItem أو Status إذا كان هناك خطأ.

الحد الأقصى لعدد عناصر الوسائط التي يمكنك طلبها في مكالمة واحدة هو 50. يجب ألا تحتوي قائمة عناصر الوسائط على معرّفات مكرّرة، ولا يمكن أن تكون فارغة.

REST

في ما يلي طلب 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."
      }
    }
  ]
}

عناوين URL الأساسية

توفّر عناوين URL الأساسية في واجهات برمجة تطبيقات "صور Google" إمكانية الوصول إلى الوحدات البايتية الأوّلية لعناصر الوسائط، ما يتيح لتطبيقك تنزيلها أو عرضها. يتم تضمين عناوين URL هذه في الاستجابات عند إدراج الألبومات (Library API) أو الوصول إلى عناصر الوسائط (كل من واجهتَي برمجة التطبيقات Library وPicker). تذكَّر أنّ عناوين URL الأساسية تتطلّب مَعلمات إضافية لكي تعمل بشكل صحيح.

بالنسبة إلى Picker API:

تتضمّن جميع عناصر PickedMediaItem.mediaFile رمز baseUrl.

تظلّ عناوين URL الأساسية نشطة لمدة 60 دقيقة، ولكن يمكن أن تنتهي صلاحيتها في وقت أقرب إذا ألغى المستخدم أذونات تطبيقك من خلال إعدادات حسابه على Google.

بالنسبة إلى Library API:

تظل عناوين URL الأساسية نشطة لمدة 60 دقيقة.

في ما يلي عناوين URL الأساسية المختلفة:

  • baseUrl: الوصول مباشرةً إلى صورة أو صورة مصغّرة لفيديو أو تنزيل ملف فيديو بايت
  • coverPhotoBaseUrl: الوصول مباشرةً إلى صورة غلاف الألبوم
  • profilePictureBaseUrl: الوصول مباشرةً إلى صورة الملف الشخصي لمالك mediaItem

عناوين URL لقاعدة الصور

في ما يلي قائمة بالخيارات التي يمكنك استخدامها مع عناوين URL الأساسية للصور:

المَعلمة
w، h

الوصف

مَعلمتَا العرض، w والارتفاع، h

للوصول إلى عنصر وسائط صورة، مثل صورة أو صورة مصغّرة لفيديو، عليك تحديد الأبعاد التي تريد عرضها في تطبيقك (بحيث يمكن تغيير حجم الصورة إلى هذه الأبعاد مع الحفاظ على نسبة العرض إلى الارتفاع). لإجراء ذلك، ادمج عنوان URL الأساسي مع السمات المطلوبة كما هو موضّح في الأمثلة.

أمثلة:

base-url=wmax-width-hmax-height

في ما يلي مثال لعرض عنصر وسائط لا يزيد عرضه عن 2048 بكسل ولا يزيد ارتفاعه عن 1024 بكسل:

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

الوصف

الاقتصاص، مَعلمة c

إذا كنت تريد اقتصاص الصورة وفقًا لبُعدَي العرض والارتفاع اللذين حددتهما، عليك ربط عنوان URL الأساسي مع مَعلمة -c الاختيارية مع المَعلمتَين w وh الإلزاميتَين.

يجب أن يكون الحجم (بالبكسل) ضمن النطاق [1، 16383]. إذا كان عرض الصورة أو ارتفاعها يتجاوزان الحجم المطلوب، يتم تصغير الصورة واقتصاصها (مع الحفاظ على نسبة العرض إلى الارتفاع).

أمثلة:

base-url=wmax-width-hmax-height-c

في هذا المثال، يعرض التطبيق عنصر وسائط قياسه 256 بكسل بالضبط في العرض و256 بكسل في الارتفاع، مثل صورة مصغّرة:

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

الوصف

المَعلمة download, d

إذا كنت تريد تنزيل الصورة مع الاحتفاظ بجميع البيانات الوصفية في Exif باستثناء البيانات الوصفية للموقع الجغرافي، يمكنك تسلسل عنوان URL الأساسي مع المَعلمة d.

أمثلة:

base-url=d

في هذا المثال، ينزّل التطبيق صورة تتضمّن جميع البيانات الوصفية باستثناء البيانات الوصفية للموقع الجغرافي:

https://lh3.googleusercontent.com/p/Az....XabC=d

عناوين URL الأساسية للفيديو

في ما يلي قائمة بالخيارات التي يمكنك استخدامها مع عناوين URL الأساسية للفيديو:

المَعلمة
dv

الوصف

للوصول إلى وحدات البايت في فيديو mediaItem، يمكنك تسلسل العنصر baseUrl مع مَعلمة تنزيل الفيديو dv.

تطلب المَعلمة dv نسخة مُعاد تحويلها بجودة عالية من الفيديو الأصلي. المَعلمة ليست متوافقة مع المَعلمتَين w وh

قد يستغرق عرض وحدات البايت في عناوين URL الأساسية لتنزيل الفيديوهات بضع ثوانٍ.

قبل استخدام هذه المَعلمة، تأكَّد من أنّ الحقل mediaMetadata.status لعناصر الوسائط هو READY. في حال عدم انتهاء معالجة ملف الوسائط، قد تظهر لك رسالة خطأ.

أمثلة:

base-url=dv

يوضّح لك المثال التالي كيفية تنزيل وحدات البايت الخاصة بأحد الفيديوهات:

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w وh وc d

الوصف

للوصول إلى الصورة المصغّرة للفيديو، استخدِم أيًا من مَعلمات عنوان URL الأساسي للصورة.

تعرض كل الصور المصغّرة للفيديو بشكل تلقائي زرًّا للتشغيل. اطّلِع على المَعلمة -no لإزالة هذا التراكب.

أمثلة:

راجِع جدول عناوين URL الأساسية للصور للاطّلاع على أمثلة.
no

الوصف

مَعلمة 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

الوصف

لاسترداد عنصر الفيديو من عنصر وسائط صورة متحركة، استخدِم المَعلمة dv كما تفعل عند التنزيل من عناوين URL الأساسية للفيديوهات.
w وh وc d

الوصف

لاسترداد عنصر الصورة لعنصر وسائط صورة متحركة، استخدِم تنسيق عناوين URL الأساسية للصور.