سرد ملفات الوسائط واستردادها

بعد أن يضبط المستخدم جهاز العرض المحيطي ويختار مصادر الوسائط في "صور Google"، يمكن لتطبيقك عرض عناصر الوسائط هذه واسترجاعها.

قبل البدء

  • التحقّق من إعداد الجهاز: تأكَّد من أنّك أنشأت جهازًا وقمت بضبطه للمستخدم بنجاح.
  • التعرّف على مسار Ambient API: راجِع مسار Ambient API للتعرّف على العملية بشكل عام، خاصةً الخطوة التي تتضمّن طلب بيانات mediaSourcesSet.

استطلاع بشأن "mediaSourcesSet"

قبل أن تتمكّن من إدراج عناصر الوسائط لجهاز معيّن، يجب أن يكون المستخدم قد اختار الصور التي يريد مشاركتها مع تطبيقك ضمن تطبيق "صور Google". يجب أن يطلب تطبيقك من الجهاز بشكل متكرّر تحديد ما إذا تم إجراء هذا الاختيار.

استدعِ طريقة devices.get بشكل دوري من أجل deviceId معيّن. راقِب الحقل mediaSourcesSet في الردّ AmbientDevice. ستكون القيمة الأولية false. بعد أن يختار المستخدم مصادر الوسائط بنجاح، سيتغيّر هذا الحقل إلى true.

تتضمّن استجابة AmbientDevice قيمة pollingConfig مع pollInterval يجب استخدامها كإرشادات بشأن معدّل تكرار الاستطلاع.

عرض قائمة ملفات الوسائط

بعد أن يصبح mediaSourcesSet true لجهاز، يمكنك البدء في جلب عناصر الوسائط التي اختارها المستخدم.

  1. استخدِم نقطة النهاية mediaItems.list: أرسِل طلب GET إلى https://photosambient.googleapis.com/v1/mediaItems، مع توفير deviceId في المسار.

  2. التعامل مع تقسيم المحتوى إلى صفحات (إذا لزم الأمر): قد يتم تقسيم الردّ إلى صفحات. استخدِم المَعلمة pageSize لتحديد الحد الأقصى لعدد العناصر المطلوب عرضها، واستخدِم pageToken من استجابة سابقة لاسترداد الصفحات اللاحقة من النتائج.

  3. معالجة ملفات الوسائط: سيتضمّن الردّ مصفوفة من عناصر AmbientMediaItem، يمثّل كل منها ملف وسائط محدّدًا. تتضمّن هذه الكائنات تفاصيل أساسية، مثل:

    • ‫id: المعرّف الفريد لملف الوسائط.
    • ‫creationTime: الطابع الزمني لوقت إنشاء وسائط العنصر.
    • ‫mediaFile: عنصر يحتوي على تفاصيل للوصول إلى المحتوى الفعلي.

يتضمّن الحقل mediaFile baseUrl. هذا baseUrl هو ما ستستخدمه لإنشاء عناوين URL للوصول إلى محتوى عنصر الوسائط بدقة عرض أو تنسيقات مختلفة.

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

توفّر عناوين URL الأساسية في واجهات برمجة التطبيقات الخاصة بـ "صور Google" إمكانية الوصول إلى وحدات البايت الأولية لعناصر الوسائط، ما يتيح لتطبيقك تنزيلها أو عرضها. يتم تضمين عناوين URL هذه في الردود عند عرض قائمة بالألبومات (Library API) أو الوصول إلى عناصر الوسائط (كل من Library API وPicker API). يُرجى العِلم أنّ عناوين 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

الوصف

المَعلمة crop، 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 الأساسية للصور.

سياسة المحتوى والفلترة

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

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

تتم فلترة كل المحتوى بشكل آلي. لمنح المستخدمين المزيد من التحكّم في المحتوى المعروض، يمكنك السماح لهم باختيار مصادر الوسائط المستخدَمة في "عرض شاشة الاستراحة" وتعديلها يدويًا.

الخطوات التالية

  • تطبيق نموذجي: يتضمّن تطبيقنا النموذجي مثالاً على عرض عناصر الوسائط واستردادها. يمكنك الاطّلاع على الدالتَين checkMediaSourcesSet وfetch_media_item_list للحصول على مزيد من المعلومات.
  • المستندات المرجعية: يمكنك مراجعة المستندات المرجعية الشاملة حول عناصر الوسائط للحصول على معلومات مفصّلة حول جميع الطرق المتاحة ومعلّمات الطلب والاستجابة ورموز الأخطاء.