אחרי ביצוע קריאות להצגת התוכן של ספריית תמונות או של אלבום, במקום לאחסן את פריטי המדיה שהוחזרו, האפליקציה צריכה לאחסן את מזהי הפריטים. הסיבה לכך היא שהתוכן של פריטי המדיה עשוי להשתנות, ואחרי זמן מסוים פג התוקף של כתובות ה-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 .
כדי לצמצם את המטען הייעודי (payload), אפשר להשתמש במסכות של שדות.
|
contributorInfo |
השדה הזה יאוכלס רק אם פריט המדיה נמצא באלבום משותף שנוצר על ידי האפליקציה הזו והמשתמש העניק לו את ההיקף מכיל מידע על התורם שהוסיף את פריט המדיה הזה. מידע נוסף מופיע במאמר שיתוף מדיה. |
אחזור של פריט מדיה
כדי לאחזר פריט מדיה, צריך לקרוא לפונקציה mediaItems.get באמצעות mediaItemId
. הבקשה תחזיר פריט מדיה אחד.
השדה mediaItem
מכיל מאפיינים כמו מזהה, תיאור וכתובת URL. המידע הנוסף בתוך photo
או video
מבוסס על המטא-נתונים שבקובץ. ייתכן שלא כל הנכסים יופיעו. ContributorInfo
מכיל מטא-נתונים של פריטים שהם חלק מאלבום משותף. השדה הזה נכלל רק ברשימת התוכן של אלבום משותף שבו המשתמש העניק את היקף ההרשאה 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
כך התשובה לפריט מדיה עם תמונה נראית כך. המאפיין של תמונה מכיל מטא-נתונים של פריטים של תמונות.
{ "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" } }
התשובה לפריט מדיה בווידאו נראית כך. המאפיין video מכיל מטא-נתונים של פריטי וידאו.
{ "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 |
תיאור הפרמטרים של הרוחב, כדי לגשת לפריט מדיה של תמונה, כמו תמונה או תמונה ממוזערת של סרטון, צריך לציין את המימדים שאתם מתכוונים להציג באפליקציה (כדי שניתן יהיה לשנות את גודל התמונה לפי המימדים האלה תוך שמירה על יחס הגובה-רוחב). כדי לעשות זאת, משרשרים את כתובת ה-URL הבסיסית למאפיינים הנדרשים, כמו בדוגמאות. לדוגמה: base-url=wmax-width-hmax-height לדוגמה: אם רוצים שפריט מדיה יהיה בגודל שלא יעלה על 2,048 פיקסלים ובגודל של עד 1,024 פיקסלים: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
תיאור הפרמטר כדי לחתוך את התמונה לפי מידות הרוחב והגובה המדויקות, משרשרים את כתובת ה-URL הבסיסית עם
הפרמטר האופציונלי הגודל (בפיקסלים) צריך להיות בטווח [1, 16383]. אם הרוחב או הגובה של התמונה חורגים מהגודל המבוקש, התמונה תוקטן ותחתוך אותה (כדי לשמור על יחס הגובה-רוחב). לדוגמה: base-url=wmax-width-hmax-height-c בדוגמה הזו, האפליקציה מציגה פריט מדיה ברוחב של בדיוק 256 פיקסלים על גובה של 256 פיקסלים, כמו תמונה ממוזערת: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
תיאור הפרמטר אם רוצים להוריד את התמונה עם כל המטא-נתונים של Exif מלבד המטא-נתונים של המיקום, צריך לשרשר את כתובת ה-URL הבסיסית עם
הפרמטר לדוגמה: base-url=d בדוגמה הזו, האפליקציה מורידה תמונה עם כל המטא-נתונים מלבד המטא-נתונים של המיקום: https://lh3.googleusercontent.com/p/Az....XabC=d |
כתובות URL בסיסיות של סרטונים
הנה רשימת האפשרויות שתוכל להשתמש בהן עם כתובות האתר הבסיסיות של הסרטונים:
פרמטר | |
---|---|
dv |
תיאור כדי לגשת לבייטים של הסרטון הפרמטר dv מבקש גרסה באיכות גבוהה של הסרטון המקורי עם המרת קידוד. הפרמטר לא תואם לפרמטרים w ו-h. יכולות לעבור מספר שניות עד שכתובות URL בסיסיות להורדות של סרטונים יחזירו בייטים. לפני שמשתמשים בפרמטר הזה, צריך לוודא שהשדה לדוגמה: base-url=dv הדוגמה הבאה מראה איך להוריד את הבייטים של סרטון: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w , h , c וגם
d |
תיאור כדי לגשת לתמונה הממוזערת של הסרטון, משתמשים באחד מהפרמטרים של כתובת ה-URL הבסיסית של התמונה. כברירת מחדל, כל התמונות הממוזערות של הסרטונים כוללות שכבת-על של לחצן הפעלה. כדי להסיר את שכבת-העל הזו, אפשר לעיין בפרמטר -no. לדוגמה: אפשר לראות דוגמאות בטבלת כתובות ה-URL הבסיסיות של תמונות. |
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 |
תיאור כדי לאחזר את רכיב הווידאו של פריט מדיה עם תמונה עם תנועה, משתמשים בפרמטר |
w , h , c וגם
d |
תיאור כדי לאחזר את אלמנט התמונה של פריט מדיה עם תמונה עם תנועה, צריך להשתמש בפורמט של כתובות URL בסיסיות של תמונות. |