دسترسی به آیتم های رسانه ای

پس از برقراری تماس برای فهرست کردن محتویات یک کتابخانه یا آلبوم عکس ، به جای ذخیره آیتم های رسانه برگشتی، برنامه شما باید شناسه موارد رسانه را ذخیره کند. این به این دلیل است که محتوای آیتم های رسانه ممکن است تغییر کند و پس از مدتی مشخص، URL های موجود در پاسخ منقضی شوند. شناسه مورد رسانه به طور منحصربه‌فرد یک مورد رسانه مانند یک عکس یا یک ویدیو در کتابخانه کاربر را شناسایی می‌کند.

توجه داشته باشید که برنامه شما نباید عکس یا ویدیوی کاربر را برای مدت طولانی در حافظه پنهان نگه دارد، اما بسته به مورد استفاده خود، می‌توانید شناسه مورد رسانه را تا زمانی که لازم است ذخیره یا ذخیره کنید . همچنین باید توجه داشته باشید که دسترسی به داده های کاربر توسط تعهدات حفظ حریم خصوصی کنترل می شود.

محدوده مجوز مورد نیاز

برای دسترسی به موارد رسانه، برنامه شما باید حداقل یکی از حوزه‌های مجوز زیر را درخواست کند. دسترسی به آیتم های رسانه ای که در پاسخ بازگردانده شده اند بستگی به دامنه های درخواستی شما دارد.

  • photoslibrary.readonly اجازه دسترسی به تمام موارد رسانه ای در کتابخانه کاربر را می دهد
  • photoslibrary.readonly.appcreateddata فقط به آیتم‌های رسانه‌ای که توسط برنامه ایجاد شده‌اند اجازه دسترسی می‌دهد

آیتم های رسانه ای

mediaItem نمایشی از رسانه هایی مانند عکس یا ویدیویی است که در کتابخانه Google Photos آپلود شده است. این یک شی سطح بالا است و ویژگی های آن می تواند بر اساس نوع رسانه زیرین متفاوت باشد.

جدول زیر ویژگی های mediaItem را فهرست می کند:

خواص
id شناسه دائمی و پایدار که برای شناسایی شی مورد استفاده قرار می گیرد.
description شرح مورد رسانه همانطور که در Google Photos دیده می شود.
baseUrl برای دسترسی به بایت های خام استفاده می شود. برای اطلاعات بیشتر، URL های پایه را ببینید.
productUrl

پیوندی به تصویر داخل Google Photos. این پیوند توسط توسعه دهنده باز نمی شود، فقط توسط کاربر. URL ها به یک آیتم رسانه در کتابخانه اشاره می کنند. اگر URL از جستجوی آلبوم بازیابی شده باشد، به مورد داخل آلبوم اشاره می کند.

mimeType نوع آیتم رسانه برای کمک به شناسایی آسان نوع رسانه (به عنوان مثال: image/jpg ).
filename نام فایل مورد رسانه در برنامه Google Photos (در بخش اطلاعات مورد) به کاربر نشان داده شده است.
mediaMetadata بسته به نوع اصلی رسانه، مانند photo یا video ، متفاوت است. برای کاهش بار، می توان از ماسک های میدانی استفاده کرد.
contributorInfo

این قسمت فقط در صورتی پر می شود که مورد رسانه در آلبوم مشترک ایجاد شده توسط این برنامه باشد و کاربر محدوده photoslibrary.sharing را اعطا کرده باشد.

حاوی اطلاعاتی درباره مشارکت کننده ای است که این مورد رسانه را اضافه کرده است. برای جزئیات بیشتر، به اشتراک گذاری رسانه مراجعه کنید.

یک آیتم رسانه ای دریافت کنید

برای بازیابی یک مورد رسانه، با mediaItems.get با استفاده از mediaItemId تماس بگیرید. درخواست یک مورد رسانه ای را برمی گرداند.

mediaItem دارای ویژگی هایی مانند شناسه، توضیحات و URL است. اطلاعات اضافی در photo یا video بر اساس فراداده درون فایل است. ممکن است همه خواص وجود نداشته باشد. ContributorInfo حاوی ابرداده برای مواردی است که بخشی از یک آلبوم مشترک هستند. این فیلد فقط برای فهرست کردن محتویات آلبوم مشترکی که کاربر محدوده مجوز photoslibrary.sharing را اعطا کرده است شامل می‌شود.

اگر مورد رسانه یک ویدیو است، ابتدا باید فایل ویدیویی پردازش شود. mediaItem حاوی یک فیلد status در mediaMetadata است که وضعیت پردازش فایل ویدیویی را توصیف می کند. فایلی که به تازگی آپلود شده است، قبل از READY برای استفاده، ابتدا videoProcessingStatus با مقدار PROCESSING برمی گرداند. 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"
  }
}

جاوا

ویژگی عکس حاوی ابرداده برای موارد عکس است.

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 s فراخوانی کنید.

این درخواست فهرستی از 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."
      }
    }
  ]
}

جاوا 

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 های پایه رشته هایی هستند که هنگام فهرست کردن آلبوم ها یا دسترسی به آیتم های رسانه در پاسخ گنجانده می شوند. آنها به مدت 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

توضیحات

پارامتر crop، 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 سازگار نیست.

نشانی‌های وب پایه برای بارگیری ویدیو ممکن است تا چند ثانیه طول بکشد تا بایت‌ها را بازگردانند.

قبل از استفاده از این پارامتر، بررسی کنید که قسمت 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 های پایه تصویر استفاده کنید.