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

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

الوصف

عملية التنزيل، مَعلمة 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 الأساسية لعمليات تنزيل الفيديوهات فترةً تصل إلى بضع ثوانٍ وحدات بايت للعودة. يتم ضبط خيار تنزيل الفيديوهات تلقائيًا على ترميز H.264. في حال تعذُّر ترميز H.264، سيتم استخدام VP9.

قبل استخدام هذه المعلمة، تحقق من أن عناصر الوسائط قيمة الحقل "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 لقاعدة الصور.