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

بعد أن يختار المستخدم عناصر وسائط باستخدام Picker API، يمكنك استرداد معلومات عنه والوصول إلى محتواه. يوضح هذا الدليل عملية سرد عناصر الوسائط واستردادها.

قبل البدء

  • فهم العملية: راجِع البدء باستخدام Picker API للحصول على نظرة عامة على عملية اختيار الصور بالكامل.
  • إكمال اختيار عنصر الوسائط: تأكَّد من أنّ المستخدم قد اختار ملفات الوسائط من جلسته بنجاح. يُرجى الرجوع إلى الدليل حول الجلسات للحصول على مزيد من التفاصيل.
  • مراجعة نطاقات التفويض المطلوبة: يتطلّب العمل مع الجلسات نطاق photospicker.mediaitems.readonly. لمزيد من المعلومات عن النطاقات، اطّلِع على نطاقات التفويض.

إدراج ملفات الوسائط التي تم اختيارها

  1. استخدام نقطة النهاية mediaItems.list: قدِّم طلب GET إلى https://photospicker.googleapis.com/v1/mediaItems، مع توفير sessionId كمعلمة طلب بحث.

  2. معالجة تقسيم الصفحات (إذا لزم الأمر):

    إذا اختار المستخدم عددًا كبيرًا من العناصر، قد يتم تقسيم الردّ إلى صفحات. استخدِم nextPageToken في الردّ لاسترداد صفحات النتائج التالية.

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

    • id: المعرّف الفريد لملف الوسائط
    • baseUrl: عنوان URL الأساسي الذي يمكنك من خلاله إنشاء عناوين URL للوصول إلى محتوى الوسائط بدرجات دقة مختلفة.
    • mimeType: نوع MIME لعنصر الوسائط (مثلاً image/jpeg أو video/mp4).

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

تأكَّد من توفّر رمز دخول صالح عبر OAuth 2.0 مع نطاق https://www.googleapis.com/auth/photospicker.mediaitems.readonly لمنح الإذن بطلباتك.

  • إنشاء عنوان URL للمحتوى: استخدِم baseUrl من العنصر PickedMediaItem. أضِف درجة الدقة أو تنسيق الملف إلى baseUrl. راجِع القسم الخاص بعناوين URL الأساسية للحصول على مزيد من التفاصيل.

  • جلب المحتوى: يمكنك إرسال طلب GET إلى عنوان URL الأساسي لعنصر الوسائط. سيتضمّن الجواب وحدات البايت الخاصة بعنصر الوسائط (الصورة أو الفيديو). هناك عدد من خيارات baseURL المختلفة المتاحة.

عناوين 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 الأساسية للصور.