الوصول إلى ملفات الوسائط

بعد إجراء طلبات من أجل إدراج محتوى مكتبة الصور أو الألبوم بدلاً من تخزين عناصر الوسائط التي تم عرضها، من المفترض أن يخزِّن التطبيق معرّفات ملفات الوسائط. ويرجع ذلك إلى أنّ محتوى عناصر الوسائط قد يتغيّر، وتنتهي صلاحية عناوين 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

لا تتم تعبئة هذا الحقل إلا إذا كان عنصر الوسائط في ألبوم مشترَك أنشأه هذا التطبيق وإذا منح المستخدم النطاق photoslibrary.sharing.

تحتوي على معلومات عن المساهم الذي أضاف عنصر الوسائط هذا. لمزيد من التفاصيل، يُرجى الاطّلاع على مشاركة الوسائط.

الحصول على ملف وسائط

لاسترداد عنصر وسائط، يمكنك استدعاء 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 بالوصول إلى وحدات البايت الخاصة بعناصر الوسائط. باستخدام عناوين URL الأساسية المختلفة، يمكن لتطبيقك إما تنزيل عناصر الوسائط أو عرض عناصر الوسائط داخل التطبيق. إنّ عناوين 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

الوصف

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