דף זה תורגם על ידי Cloud Translation API.

הצגת רשימת תכנים, אלבומים ופריטי מדיה של ספרייה

היקפי ההרשאות הנדרשים

ה-Google Photos Library API כולל מספר היקפים שמשמשים לגישה לפריטי מדיה ולאלבומים. פריטי המדיה שמוחזרים מקריאות שונות משתנים בהתאם להיקפי ההרשאות שהתבקשו על ידי המפתח.

ההיקף photoslibrary.readonly מאפשר גישה לכל פריטי המדיה בספריית המשתמש. ההיקף של photoslibrary.readonly.appcreateddata מאפשר גישה רק לפריטי מדיה שהאפליקציה יצרה. מידע נוסף זמין בהיקפי ההרשאות.

סקירה

אחד השימושים החשובים ב-API הוא הצגת רשימת פריטי מדיה שהמשתמש גיבית ב-Google Photos. ניתן לראות ברשימה פריטים מאלבום מסוים או מכל הספרייה של המשתמש (תצוגת ברירת המחדל באפליקציית Google Photos).

אתם יכולים להשתמש במסננים כדי לבחור תמונות שתואמות לתאריך, לקטגוריית תוכן או לסוג המדיה, כשאתם יוצרים רשימה של פריטים מספריית המשתמש. התכונה הזו לא נתמכת כשיוצרים רשימה של פריטים מאלבומים.

רישום תוכן הספרייה והאלבום מחזיר רשימה של פריטי מדיה. העשרות שהן חלק מאלבום לא כלולות. פריטי מדיה מתארים תמונה, סרטון או מדיה אחרת. mediaItem כולל קישור ישיר לפריט, קישור לפריט ב-Google Photos ומטא-נתונים רלוונטיים נוספים. מידע נוסף זמין בגישה לפריטי מדיה ובקטע mediaItems.

הצגת רשימת האלבומים

אפשר לאחזר את רשימת האלבומים של המשתמש באמצעות albums.list.

REST

הנה בקשה לדוגמה:

GET https://photoslibrary.googleapis.com/v1/albums

הבקשה מחזירה את התוצאה הבאה:

{
  "albums": [
    {
      "id": "album-id",
      "title": "album-title",
      "productUrl": "album-product-url",
      "coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly",
      "coverPhotoMediaItemId": "album-cover-media-item-id",
      "isWriteable": "whether-you-can-write-to-this-album",
      "mediaItemsCount": "number-of-media-items-in-album"
    },
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all albums in the user's library
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums();

  for (Album album : response.iterateAll()) {
    // Get some properties of an album
    String id = album.getId();
    String title = album.getTitle();
    String productUrl = album.getProductUrl();
    String coverPhotoBaseUrl = album.getCoverPhotoBaseUrl();
    // The cover photo media item id field may be empty
    String coverPhotoMediaItemId = album.getCoverPhotoMediaItemId();
    boolean isWritable = album.getIsWriteable();
    long mediaItemsCount = album.getMediaItemsCount();
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums in the user's library
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // Get some properties of an album
        $albumId = $album->getId();
        $title = $album->getTitle();
        $productUrl = $album->getProductUrl();
        $coverPhotoBaseUrl = $album->getCoverPhotoBaseUrl();
        // The cover photo media item id field may be empty
        $coverPhotoMediaItemId = $album->getCoverPhotoMediaItemId();
        $isWriteable = $album->getIsWriteable();
        $totalMediaItems = $album->getTotalMediaItems();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

לכל אלבום שמוחזר יש מזהה שיכול לשמש לאחזור תוכן האלבום, כפי שמוצג בקטע הצגת תוכן האלבום. הוא כולל גם את השם ואת מספר פריטי המדיה שהוא מכיל.

productUrl מפנה לאלבום ב-Google Photos שהמשתמש יכול לפתוח.

השדה coverPhotoMediaItemId מכיל את מזהה פריט המדיה שמייצג את תמונת השער של האלבום. כדי לגשת לתמונת השער הזו, צריך להשתמש ב-coverPhotoBaseUrl. אין להשתמש ישירות ב-coverPhotoBaseUrl בלי לציין פרמטרים נוספים.

אלבומים שנוצרו בחשבון המשתמש או נוספו לחשבון המשתמש ושהאפליקציה שיתפה כוללים מאפיין shareInfo נוסף. מידע נוסף מופיע במאמר שיתוף מדיה.

באלבומים עשויים להופיע גם דגל isWriteable שמציין אם אפשר ליצור פריטים של מדיה באלבום. אם הסימון לא מוחזר, ברירת המחדל של הסימון הזה היא false. השימוש בה תלוי בגישה שהוענקה לאפליקציה, כולל:

מי יצר את האלבום.
אם הוא משותף או לא.
אילו היקפים המשתמש אישר.

סימון זה עשוי להשתנות אם אחד מהקריטריונים האלה ישתנה. פרטים נוספים זמינים במאמר יצירת אלבומים. התשובה מכילה גם nextPageToken. למידע נוסף ראו את המאמר עימוד.

התשובה במקרה של אלבומים ריקים משתנה בכך שהערכים של mediaItemsCount ו-coverPhotoMediaItemId מוגדרים כברירת מחדל ל-0 ולא נכללים בתגובה ל-REST. שימו לב גם ש-coverPhotoBaseUrl מפנה לתמונת ה-placeholder שמוגדרת כברירת מחדל.

תוכן ספרייה של דף

ניתן להציג רשימה של כל פריטי המדיה מספריית Google Photos של המשתמש. היא לא כוללת פריטים שהועברו לארכיון או נמחקו. אפשר לרשום פריטי מדיה על סמך התוכן, התאריך ומאפיינים אחרים שלהם על ידי החלת מסננים. אם המשתמש לא הוסיף לספרייה שלו פריט זמין בכרטיסייה שיתוף ב-Google Photos, הפריט לא ייכלל ברשימה הזו.

כדי לאחזר פריט מדיה, צריך לקרוא לפונקציה mediaItems.list.

REST

הנה בקשה לדוגמה:

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

בקשת ה-GET מחזירה את התגובה הבאה:

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all media items in the user's library
  // Iterate over all the retrieved media items
  // Pagination is handled automatically
  ListMediaItemsPagedResponse response = photosLibraryClient.listMediaItems();
  for (MediaItem item : response.iterateAll()) {
    // Get some properties of a media item
    String id = item.getId();
    String description = item.getDescription();
    String mimeType = item.getMimeType();
    String productUrl = item.getProductUrl();
    String filename = item.getFilename();
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all media items in the user's library
    // Iterate over all the retrieved media items
    // Pagination is handled automatically
    $response = $photosLibraryClient->listMediaItems();
    foreach ($response->iterateAllElements() as $item) {
        // Get some properties of a media item
        /* @var $item \Google\Photos\Library\V1\MediaItem */
        $id = $item->getId();
        $description = $item->getDescription();
        $mimeType = $item->getMimeType();
        $productUrl = $item->getProductUrl();
        $filename = $item->getFilename();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

התשובה מכילה רשימה של פריטי מדיה, מסודרים מהחדש לישן. למידע נוסף: mediaItems. הוא מכיל גם nextPageToken, שמתואר בפירוט בקטע עימוד.

פירוט של תוכן האלבום

על מנת להציג את כל פריטי המדיה באלבום, מוסיפים את השדה albumId לבקשת החיפוש. למידע נוסף על albumId, ראה הצגת אלבומים ורשימת אלבומים משותפים. אם השדה albumId לא תקין, תוחזר השגיאה Bad Request. אם המזהה תקין, אבל האלבום לא קיים אצל המשתמש המאומת, תוחזר השגיאה Not Found. פרטים נוספים על טיפול בשגיאות זמינים בטיפים לשיפור הביצועים ובשיטות מומלצות.

REST

הנה בקשה לדוגמה:

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "albumId": "album-id"
}

בקשת ה-POST מחזירה את התגובה הבאה:

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all media items in an album
  // Provide the ID of the album as a parameter in the searchMediaItems call
  // Iterate over all the retrieved media items
  SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(albumId);

  for (MediaItem item : response.iterateAll()) {
    // ...
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all media items in an album
    // Provide the ID of the album as a parameter in the searchMediaItems call
    // Iterate over all the retrieved media items
    $response = $photosLibraryClient->searchMediaItems(['albumId' => $albumId]);
    foreach ($response->iterateAllElements() as $item) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

התשובה מכילה nextPageToken ורשימת פריטי המדיה. בניגוד למקרים שבהם תוכן הספרייה מוחזר, פריטי המדיה מוחזרים לפי הסדר שלהם באלבום. לפרטים נוספים ראו mediaItems ועימוד. המשתמש יכול לערוך את ההזמנה בממשק של Google Photos.

אם המדיניות albumId מוגדרת, אי אפשר להחיל מסנן על הצגת תוכן האלבום. הפעולה הזו תוביל לשגיאה Bad Request.

הצגת רשימה של אלבומים משותפים

אפשר לאחזר רשימה של כל האלבומים שהמשתמש שיתף או ששותפו עם משתמש. הכרטיסייה הזו דומה לכרטיסייה 'שיתוף' באפליקציית Google Photos.

האלבומים המשותפים שהמשתמש הוסיף לספריית תמונות Google שלו מוחזרים גם בקריאה לאלבומים. כדי להציג אלבומים משותפים באמצעות Library API, מבצעים את הקריאה הבאה:

REST

הנה בקשה לדוגמה:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums

הבקשה מחזירה את התוצאה הבאה:

{
  "sharedAlbums": [...]
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all albums that have been shared by the user
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums();

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums that have been shared by the user
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listSharedAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

רשימת האלבומים כלולה ב-sharedAlbums. למידע נוסף, ראו רשימת אלבומים. התשובה מכילה גם nextPageToken. למידע נוסף, אפשר לעיין בעימוד.

אלבומים שהאפליקציה שלך יצרה ושותפת כוללים נכס shareInfo נוסף. למידע נוסף, ראו שיתוף מדיה.

אלבומים שנוצרו באפליקציה של דף האפליקציה

אפשר לרשום אלבומים שנוצרו על ידי האפליקציה שלך כאשר excludeNonAppCreatedData מוגדר ל-true באמצעות הקריאות הבאות:

REST

הנה בקשת GET להצגת כל האלבומים מספריית Google Photos של המשתמש, שנוצרו רק על ידי האפליקציה שלך:

GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

הנה בקשת GET להצגת כל האלבומים המשותפים מספריית Google Photos של המשתמש, שנוצרה רק על ידי האפליקציה שלך:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

Java

try {
  // Make a request to list all albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

try {
  // Make a request to list all shared albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response =
      photosLibraryClient.listSharedAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums that have been created by your app
    $response = $photosLibraryClient->listAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

try {
    // Make a request to list all shared albums that have been created by your app
    $response = $photosLibraryClient->listSharedAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

עימוד ל-REST

כדי לשפר את הביצועים, שיטות שמחזירות מספר גדול של תוצאות (כמו שיטות להצגת רשימה) יכולות לחלק את התשובות לדפים. הפרמטר pageSize מספק את המספר המקסימלי של תוצאות בכל דף.

לקריאות אל mediaItems:search ואל mediaItems:list, גודל הדף המוגדר כברירת מחדל הוא 25 פריטים. אנחנו ממליצים על גודל הדף הזה כי הוא יוצר איזון בין גודל התגובה לקצב המילוי. גודל הדף המקסימלי לחיפוש פריטי מדיה ובקשות לרשימות הוא 100 פריטים.

ברירת המחדל וגודל הדף המומלץ לאלבומים הם 20 אלבומים, עד 50 אלבומים.

כאשר מספר התוצאות הזמינות גדול מהגודל של הדף, התגובה כוללת את השדה nextPageToken, שמציין לאפליקציה שיש עוד תוצאות אחזור מהשרת.

דוגמה

צריך לצרף את nextPageToken לבקשות הבאות בפרמטר pageToken, כמו בדוגמה הבאה. מציינים את pageToken יחד עם פרמטרים אחרים שנדרשים לפעולה, בגוף הבקשה או כפרמטר של שאילתה.

בקשה מס' 1

{
  "pageSize": "5",
  "filters": { … }
}

תשובה ראשונה

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

בקשה מס' 2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

תשובה מס' 2

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

צריך להמשיך את התבנית הזו עד שלא יהיו עוד אובייקטים מסוג nextPageToken.

השדה nextPageToken תקף רק לאותה בקשה. אם שיניתם פרמטרים כלשהם, אין להשתמש ב-nextPageToken שהשתמשתם בו בעבר באותה בקשה.