इस पेज का अनुवाद Cloud Translation API से किया गया है.

लाइब्रेरी के कॉन्टेंट, एल्बम, और मीडिया आइटम की सूची बनाना

अनुमति देने के ज़रूरी दायरे

Google Photos Library API में, मीडिया आइटम और एल्बम को ऐक्सेस करने के लिए कई स्कोप इस्तेमाल किए जाते हैं. अलग-अलग कॉल से लौटाए गए मीडिया आइटम, इस आधार पर अलग-अलग होते हैं कि डेवलपर ने किन दायरों का अनुरोध किया है.

photoslibrary.readonly का स्कोप, उपयोगकर्ता की लाइब्रेरी में मौजूद सभी मीडिया आइटम को ऐक्सेस करने की अनुमति देता है. photoslibrary.readonly.appcreateddata का स्कोप, सिर्फ़ उन मीडिया आइटम को ऐक्सेस करने की अनुमति देता है जिन्हें ऐप्लिकेशन ने बनाया है. ज़्यादा जानकारी के लिए, अनुमति के दायरे देखें.

खास जानकारी

इस एपीआई का एक अहम इस्तेमाल उन मीडिया आइटम की सूची बनाना है जिनका बैक अप उपयोगकर्ता ने Google Photos में लिया है. किसी खास एल्बम में या उपयोगकर्ता की पूरी लाइब्रेरी में मौजूद आइटम (Google Photos ऐप्लिकेशन में डिफ़ॉल्ट व्यू) सूची में डाले जा सकते हैं.

उपयोगकर्ता की लाइब्रेरी से आइटम को सूची में जोड़ते समय, किसी खास तारीख, कॉन्टेंट कैटगरी या मीडिया टाइप से मैच करने वाली फ़ोटो चुनने के लिए फ़िल्टर का इस्तेमाल करें. एल्बम के आइटम की सूची बनाते समय, यह सुविधा काम नहीं करती.

लाइब्रेरी और एल्बम के कॉन्टेंट को सूची में जोड़ने पर, मीडिया आइटम की सूची दिखती है. किसी एल्बम का हिस्सा जानकारी शामिल नहीं की जाती. मीडिया आइटम किसी फ़ोटो, वीडियो या अन्य मीडिया के बारे में बताते हैं. mediaItem में, आइटम का डायरेक्ट लिंक, Google Photos में मौजूद आइटम का लिंक, और काम का अन्य मेटाडेटा शामिल होता है. ज़्यादा जानकारी के लिए, मीडिया आइटम ऐक्सेस करना और mediaItems देखें.

एल्बम की लिस्टिंग

albums.list का इस्तेमाल करके उपयोगकर्ता के एल्बम की सूची फिर से पाई जा सकती है.

आराम

अनुरोध का एक नमूना यहां दिया गया है:

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 डिफ़ॉल्ट प्लेसहोल्डर इमेज पर ले जाता है.

लिस्टिंग लाइब्रेरी का कॉन्टेंट

आपके पास उपयोगकर्ता की Google Photos लाइब्रेरी से, सभी मीडिया आइटम की सूची बनाने का विकल्प होता है. इसमें संग्रहित और मिटाए गए आइटम शामिल नहीं किए जाते. फ़िल्टर लगाकर मीडिया आइटम को उनके कॉन्टेंट, तारीख, और अन्य प्रॉपर्टी के आधार पर सूची में रखा जा सकता है. अगर उपयोगकर्ता ने अपनी लाइब्रेरी में Google Photos के शेयर करना टैब में मौजूद आइटम को नहीं जोड़ा है, तो वह आइटम इस सूची में शामिल नहीं किया जाता है.

किसी मीडिया आइटम को वापस पाने के लिए, mediaItems.list को कॉल करें.

आराम

अनुरोध का एक नमूना यहां दिया गया है:

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

जीईटी अनुरोध से यह रिस्पॉन्स मिलता है:

{
  "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 गड़बड़ी दिखती है. गड़बड़ी ठीक करने के बारे में ज़्यादा जानकारी के लिए,परफ़ॉर्मेंस से जुड़ी सलाह और सबसे सही तरीके देखें.

आराम

अनुरोध का एक नमूना यहां दिया गया है:

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

पोस्ट अनुरोध करने पर यह रिस्पॉन्स मिलता है:

{
  "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 की मदद से, शेयर किए गए एल्बम की सूची बनाने के लिए नीचे दिया गया कॉल करें:

आराम

अनुरोध का एक नमूना यहां दिया गया है:

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 पर सेट किया जा सकता है:

आराम

यहां उपयोगकर्ता की Google Photos लाइब्रेरी से सभी एल्बम को लिस्ट करने के लिए, जीईटी अनुरोध दिया गया है, जिसे सिर्फ़ आपके ऐप्लिकेशन से बनाया गया है:

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

यहां एक जीईटी अनुरोध दिया गया है, जिसमें लोगों की 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 शामिल होता है. इससे आपके ऐप्लिकेशन को पता चलता है कि सर्वर से मिलने वाले ज़्यादा नतीजे हैं.

उदाहरण

आपको pageToken पैरामीटर में, बाद के अनुरोधों में nextPageToken को जोड़ना होगा, जैसा कि इस उदाहरण में दिखाया गया है. pageToken को कार्रवाई के लिए ज़रूरी अन्य पैरामीटर के साथ अनुरोध के मुख्य हिस्से में या क्वेरी पैरामीटर के तौर पर तय करें.

अनुरोध #1

{
  "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 मौजूद है, तो शुरुआती अनुरोध के बाद ज़्यादा नतीजों के लिए अनुरोध भेजा जा सकता है.