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

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

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

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

סקירה כללית

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

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

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

זהירות: אין לשמור תמונות וסרטונים של משתמשים במטמון. במקום זאת, אפשר לאחסן את קובץ המדיה id ולבקש את הפרטים שלו שוב כשצריך אותם. התמונות עשויות להשתנות, גישה ישירה דרך baseUrl יפוגה לאחר 60 דקות. לקבלת מידע נוסף מידע נוסף, ראה גישה לפריטי מדיה.

אלבומים של כרטיסי מוצר

ניתן לאחזר רשימה של האלבומים של המשתמש באמצעות 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 Photos מוחזרים גם בשיחה רשימת אלבומים. לכתוב הקריאה הבאה לרישום אלבומים משותפים באמצעות 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 בשיחות הבאות:

• albums.list
• sharedAlbums.list

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, שמציין לאפליקציה שלך שיש לאחזור תוצאות נוספות מהשרת.

הערה: הפרמטר pageSize הוא הערך המקסימלי — יכול להיות שיהיו פחות תוצאות מוחזרות ממה שהתבקש.

דוגמה

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

בקשה ראשונה

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

תשובה מס' 1

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

בקשה מס' 2

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

תשובה מס' 2

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

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

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

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