Liệt kê nội dung, album và mục nội dung đa phương tiện trong thư viện

Phạm vi uỷ quyền bắt buộc

API Thư viện Google Photos chứa nhiều phạm vi dùng để truy cập vào các mục nội dung đa phương tiện và album. Các mục nội dung đa phương tiện được trả về qua nhiều lệnh gọi sẽ khác nhau tuỳ theo phạm vi đã được nhà phát triển yêu cầu.

Phạm vi photoslibrary.readonly cho phép truy cập vào tất cả các mục nội dung đa phương tiện trong thư viện của người dùng. Phạm vi photoslibrary.readonly.appcreateddata cho phép truy cập chỉ với các mục nội dung đa phương tiện do ứng dụng tạo. Để biết thêm thông tin, hãy xem Phạm vi uỷ quyền.

Tổng quan

Một mục đích sử dụng quan trọng của API là liệt kê các mục nội dung đa phương tiện mà người dùng đã sao lưu vào Google Photos. Các mục trong một album cụ thể hoặc từ toàn bộ album của người dùng (chế độ xem mặc định trong ứng dụng Google Photos) có thể được liệt kê.

Bạn có thể sử dụng bộ lọc để chọn ảnh khớp với ngày, danh mục nội dung hoặc loại phương tiện được chỉ định khi bạn liệt kê các mục từ thư viện của người dùng. Tính năng này không được hỗ trợ khi bạn liệt kê các mặt hàng từ anbom.

Việc liệt kê nội dung thư viện và album sẽ trả về danh sách các mục nội dung nghe nhìn. Các tính năng bổ ích trong một đĩa nhạc không được bao gồm. Mục nội dung đa phương tiện mô tả ảnh, video hoặc nội dung nghe nhìn khác. Đáp mediaItem bao gồm một đường liên kết trực tiếp đến mặt hàng, một đường liên kết đến mặt hàng trong Google Photos và các siêu dữ liệu khác có liên quan. Để biết thêm thông tin, hãy xem Truy cập vào các mục nội dung đa phương tiện và mediaItems.

Thận trọng: Không được lưu ảnh và video của người dùng vào bộ nhớ đệm. Thay vào đó, hãy lưu trữ mục nội dung nghe nhìn id rồi yêu cầu lại thông tin chi tiết khi bạn cần. Hình ảnh có thể thay đổi và quyền truy cập trực tiếp qua baseUrl sẽ hết hạn sau 60 phút. Để biết thêm thông tin, xem Truy cập vào các mục nội dung đa phương tiện.

Album danh sách

Bạn có thể truy xuất danh sách album của người dùng bằng cách sử dụng albums.list.

Kiến trúc chuyển trạng thái đại diện (REST)

Dưới đây là yêu cầu mẫu:

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

Yêu cầu trả về kết quả sau:

{
  "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
}

Mỗi album trả về có một mã nhận dạng có thể dùng để truy xuất nội dung của như được hiển thị trong Danh sách nội dung album. Điều này cũng bao gồm tiêu đề và số lượng mục nội dung đa phương tiện có trong đó.

productUrl trỏ đến album trong Google Photos có thể là mà người dùng mở.

coverPhotoMediaItemId chứa mục nội dung đa phương tiện mã nhận dạng đó đại diện cho ảnh bìa của anbom này. Để truy cập vào ảnh bìa này, hãy sử dụng coverPhotoBaseUrl. Bạn không nên sử dụng trực tiếp coverPhotoBaseUrl mà không có chỉ định bổ sung tham số.

Album được tạo trong tài khoản của người dùng hoặc được thêm vào Tài khoản của bạn và ứng dụng của bạn đã chia sẻ bao gồm thêm một thuộc tính shareInfo. Để biết thêm thông tin, hãy xem bài viết Chia sẻ nội dung nghe nhìn.

Album cũng có thể có cờ isWriteable để cho biết bạn có thể tạo nội dung nghe nhìn hay không mục trong album. Cờ này mặc định là false nếu không được trả về. Đó là phụ thuộc vào quyền truy cập đã cấp cho ứng dụng của bạn, bao gồm:

• Người đã tạo album.
• Nội dung đó có được chia sẻ hay không.
• Phạm vi phạm vi người dùng đã phê duyệt.

Cờ này có thể thay đổi nếu bất kỳ tiêu chí nào trong số này thay đổi. Để biết thêm thông tin, hãy xem Tạo album. Chiến lược phát hành đĩa đơn phản hồi cũng chứa nextPageToken. Để biết thêm thông tin, hãy xem Phân trang.

Phản hồi cho album trống khác nhau ở chỗ, mediaItemsCount và Theo mặc định, coverPhotoMediaItemId được đặt thành 0 và bị bỏ qua trong REST của bạn. Ngoài ra, xin lưu ý rằng coverPhotoBaseUrl trỏ đến một phần giữ chỗ mặc định hình ảnh.

Nội dung trong thư viện trang thông tin

Bạn có thể liệt kê tất cả mục nội dung đa phương tiện trong thư viện Google Photos của người dùng. Dữ liệu này không bao gồm các mục đã lưu trữ và đã xoá. Bạn có thể liệt kê các mục nội dung nghe nhìn dựa trên nội dung, ngày và các thuộc tính khác bằng cách áp dụng . Nếu người dùng chưa thêm mục có trong thẻ Chia sẻ trong Google Photos với thư viện, mục đó không có trong danh sách này.

Để truy xuất một mục nội dung nghe nhìn, hãy gọi mediaItems.list.

Kiến trúc chuyển trạng thái đại diện (REST)

Dưới đây là yêu cầu mẫu:

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

Yêu cầu GET trả về phản hồi sau:

{
  "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
}

Phản hồi chứa danh sách các mục nội dung đa phương tiện, được sắp xếp theo thứ tự từ gần đây nhất đến gần đây nhất. Để biết thêm thông tin, hãy xem mediaItems. Điều này cũng chứa nextPageToken, được mô tả chi tiết hơn trong Phân trang.

Nội dung album danh sách

Để liệt kê tất cả mục nội dung nghe nhìn trong một album, hãy thêm trường albumId vào yêu cầu tìm kiếm. Để biết thêm thông tin về albumId, hãy xem bài viết Trang thông tin album và Liệt kê các album chia sẻ. Nếu albumId không hợp lệ, hệ thống sẽ trả về lỗi Bad Request. Nếu mã nhận dạng hợp lệ, nhưng album này không tồn tại cho người dùng đã xác thực, lỗi Not Found là bị trả lại. Để biết thêm thông tin chi tiết về cách xử lý lỗi,hãy xem phần Hiệu suất mẹo và Tốt nhất .

Kiến trúc chuyển trạng thái đại diện (REST)

Dưới đây là yêu cầu mẫu:

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

Yêu cầu POST trả về phản hồi sau:

{
  "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
}

Phản hồi chứa nextPageToken và danh sách các mục nội dung nghe nhìn. Không thích khi nội dung thư viện liệt kê, các mục nội dung đa phương tiện được trả về theo thứ tự trong lệnh của bạn. Để biết thêm thông tin, hãy xem mediaItems và Phân trang. Người dùng có thể chỉnh sửa thứ tự trong Giao diện Google Photos.

Nếu đặt albumId thì bạn không thể áp dụng bộ lọc khi liệt kê nội dung album. Việc này sẽ dẫn đến lỗi Bad Request.

Liệt kê các album được chia sẻ

Bạn có thể truy xuất danh sách tất cả anbom mà người dùng đã chia sẻ hoặc đã được được chia sẻ với một người dùng. Việc này tương tự như thẻ Chia sẻ trong Ứng dụng Google Photos.

Album chia sẻ mà người dùng đã thêm vào thư viện Google Photos của họ cũng được trả lại trong lệnh gọi album danh sách. Làm cho lệnh gọi sau đây để liệt kê album chia sẻ thông qua API Thư viện:

Kiến trúc chuyển trạng thái đại diện (REST)

Dưới đây là yêu cầu mẫu:

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

Yêu cầu trả về kết quả sau:

{
  "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
}

Danh sách album có trong sharedAlbums. Để biết thêm thông tin, hãy xem Album danh sách. Phản hồi này cũng chứa nextPageToken. Để biết thêm thông tin, hãy xem phần Phân trang.

Album mà ứng dụng của bạn đã tạo và chia sẻ bao gồm shareInfo bổ sung thuộc tính này. Để biết thêm chi tiết, hãy xem phần Chia sẻ nội dung đa phương tiện.

Album do ứng dụng liệt kê tạo

Bạn có thể liệt kê những album đã được ứng dụng của bạn tạo bằng Đã đặt excludeNonAppCreatedData thành true trong các lệnh gọi sau:

• albums.list
• sharedAlbums.list

Kiến trúc chuyển trạng thái đại diện (REST)

Đây là yêu cầu GET liệt kê tất cả album trong Thư viện Google Photos chỉ do ứng dụng của bạn tạo:

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

Đây là yêu cầu GET liệt kê tất cả album được chia sẻ từ Thư viện Google Photos chỉ do ứng dụng của bạn tạo:

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
}

Phân trang cho REST

Để cải thiện hiệu suất, các phương thức trả về một số lượng lớn kết quả (chẳng hạn như list method) có thể phân trang phản hồi. Số lượng kết quả tối đa trong mỗi được cung cấp bởi tham số pageSize.

Đối với các lệnh gọi đến mediaItems:search và mediaItems:list, kích thước trang mặc định là 25 mục. Bạn nên sử dụng kích thước trang này vì kích thước này sẽ tạo ra sự cân bằng giữa kích thước của phản hồi và tỷ lệ lấp đầy. Kích thước trang tối đa cho mục nội dung đa phương tiện yêu cầu tìm kiếm và liệt kê là 100 mục.

Kích thước trang mặc định và được đề xuất khi liệt kê album là 20 album, với tối đa 50 anbom.

Khi số kết quả có sẵn lớn hơn kích thước trang, phản hồi bao gồm nextPageToken, cho ứng dụng của bạn biết rằng có kết quả khác cần tìm nạp từ máy chủ.

Lưu ý: Tham số pageSize là tối đa — kết quả có thể ít hơn trả về nhiều hơn yêu cầu.

Ví dụ:

Bạn phải thêm nextPageToken vào các yêu cầu tiếp theo trong tham số pageToken, như trong ví dụ sau. Chỉ định pageToken cùng nhau cùng với các tham số khác cần thiết cho thao tác, ở trong phần nội dung của lệnh hoặc dưới dạng tham số truy vấn.

Yêu cầu số 1

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

Phản hồi số 1

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

Yêu cầu số 2

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

Phản hồi số 2

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

Tiếp tục mẫu này cho đến khi không còn đối tượng nextPageToken nào nữa.

nextPageToken chỉ hợp lệ đối với cùng một yêu cầu. Nếu có bất kỳ thông số nào là đã thay đổi, bạn không nên sử dụng nextPageToken đã sử dụng trước đó cho cùng một của bạn.

Lưu ý: Sự tồn tại của nextPageToken là chỉ báo duy nhất cho biết liệu có hay không có thêm kết quả khác cần được tìm nạp từ máy chủ. Không đếm số lượng kết quả để xác định xem bạn có nên sử dụng nextPageToken hay không. Yêu cầu có thể trả về ít kết quả hơn so với yêu cầu về kích thước trang. Nếu một nextPageToken là hiện tại, bạn có thể gửi yêu cầu xem thêm kết quả sau yêu cầu ban đầu.