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

بعد أن يضبط المستخدم جهازه المخصّص للعرض ومصادر الوسائط المحدّدة في "صور 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 و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 الأساسية للصور.

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

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