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

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

إذا كان عنصر الوسائط فيديو، يجب معالجة ملف الفيديو أولاً. يحتوي العنصر 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

يبدو الردّ على عنصر وسائط صورة هكذا. يحتوي عنصر photo (الصورة) على بيانات وصفية لعناصر الصور.

{
  "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. يجب ألا تحتوي قائمة عناصر الوسائط على معرّفات مكرّرة، ولا يمكن أن تكون فارغة.

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."
      }
    }
  ]
}

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 Photos Library API إمكانية الوصول إلى وحدات البايت الخاصة بعناصر الوسائط. باستخدام عناوين 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

الوصف

المَعلمة 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 لقاعدة الصور.