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 và album nội dung nghe nhìn. Các mục nội dung nghe nhìn được trả về từ nhiều lệnh gọi sẽ khác nhau dựa trên phạm vi mà 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 chỉ cho phép truy cập vào các mục nội dung đa phương tiện mà ứng dụng tạo. Để biết thêm thông tin, hãy xem bài viết 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 nghe nhìn mà người dùng đã sao lưu vào Google Photos. Bạn có thể liệt kê các mục trong một album cụ thể hoặc trong toàn bộ thư viện của người dùng (chế độ xem mặc định trong ứng dụng Google Photos).

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 nội dung nghe nhìn được chỉ định khi liệt kê các mục trong 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ục trong album.

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 đa phương tiện. Nội dung bổ sung thuộc album không được thêm vào. Các mục nội dung đa phương tiện mô tả một ảnh, video hoặc nội dung nghe nhìn khác. mediaItem bao gồm một đường liên kết trực tiếp đến mục, đường liên kết đến mục trong Google Photos và các siêu dữ liệu có liên quan khác. Để biết thêm thông tin, hãy xem phần 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 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 đa phương tiện id và 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 thông qua baseUrl sẽ hết hạn sau 60 phút. Để biết thêm thông tin, hãy xem bài viết Truy cập vào các mục nội dung đa phương tiện.

Album trang thông tin

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
}

1.199

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 được trả về có một mã nhận dạng có thể dùng để truy xuất nội dung của album như minh hoạ trong phần Liệt kê nội dung album. Báo cáo này cũng bao gồm tiêu đề và số lượng mục nội dung đa phương tiện trong đó.

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

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

Các 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 người dùng mà ứng dụng của bạn đã chia sẻ sẽ có thêm một thuộc tính shareInfo. Để biết thêm chi tiết, 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 liệu bạn có thể tạo các mục nội dung nghe nhìn trong album hay không. Cờ này mặc định là false nếu không được trả về. Việc này tuỳ thuộc vào quyền truy cập được cấp cho ứng dụng của bạn, bao gồm:

• Người tạo album.
• Việc tệp có được chia sẻ hay không.
• Người dùng đã phê duyệt những phạm vi nào.

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 chi tiết, vui lòng xem phần Tạo album. Phản hồi cũng chứa nextPageToken. Để biết thêm thông tin, hãy xem phần Phân trang.

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

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

Bạn có thể liệt kê tất cả các mục nội dung nghe nhìn trong thư viện Google Photos của người dùng. Không bao gồm các mục đã lưu trữ và đã bị xóa. 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 bộ lọc. Nếu người dùng chưa thêm mục có trong thẻ Chia sẻ của Google Photos vào thư viện, thì mục đó sẽ 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
}

1.199

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 nghe nhìn, được sắp xếp theo thứ tự gần đây nhất đến ít nhất. Để biết thêm thông tin, hãy xem mediaItems. Lớp này cũng chứa nextPageToken được mô tả chi tiết hơn trong phần Phân trang.

Nội dung album trang thông tin

Để liệt kê tất cả các mục nội dung đa phương tiện trong một album, hãy thêm trường albumId vào yêu cầu tìm kiếm của bạn. Để biết thêm thông tin về albumId, hãy xem phần Liệt kê album và Tạo danh sách 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 là hợp lệ, nhưng album không tồn tại cho người dùng đã xác thực, thì hệ thống sẽ trả về lỗi Not Found. Để biết thêm thông tin chi tiết về cách xử lý lỗi,hãy xem Mẹo về hiệu suất và Các phương pháp hay 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
}

1.199

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 mục nội dung đa phương tiện. Không giống như khi liệt kê nội dung thư viện, các mục nội dung đa phương tiện được trả về theo thứ tự trong album. Để biết thêm thông tin chi tiết, hãy xem mediaItems và Phân trang. Người dùng có thể chỉnh sửa đơn đặt hàng trong giao diện Google Photos.

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

Liệt kê album chia sẻ

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

Những album chia sẻ mà người dùng đã thêm vào thư viện Google Photos cũng được trả về trong lệnh gọi album danh sách. Thực hiện lệnh gọi sau để liệt kê các 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
}

1.199

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 phần Album trang thông tin. 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.

Các album mà ứng dụng của bạn đã tạo và chia sẻ bao gồm một thuộc tính shareInfo bổ sung. Để biết thêm thông tin chi tiết, hãy xem bài viết Chia sẻ nội dung nghe nhìn.

Liệt kê album do ứng dụng tạo

Bạn có thể liệt kê các album mà ứng dụng của bạn đã tạo với excludeNonAppCreatedData được đặt 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)

Dưới đây là yêu cầu GET để liệt kê tất cả album trong thư viện Google Photos của người dùng mà chỉ ứng dụng của bạn tạo ra:

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

Dưới đây là yêu cầu GET để liệt kê tất cả album chia sẻ trong thư viện Google Photos của người dùng mà chỉ ứng dụng của bạn tạo ra:

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
}

1.199

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ư các phương thức danh sách) có thể phân trang cho phản hồi. Số lượng kết quả tối đa trong mỗi trang do tham số pageSize cung cấp.

Đố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 dùng kích thước trang này vì nó tạo ra sự cân bằng giữa kích thước của phản hồi và tỷ lệ đáp ứng. Kích thước trang tối đa cho các yêu cầu danh sách và tìm kiếm mục nội dung nghe nhìn là 100 mục.

Kích thước trang mặc định và nên dùng khi liệt kê album là 20 album, với tối đa 50 album.

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

Lưu ý: Tham số pageSize là giá trị tối đa – có thể kết quả trả về sẽ ít hơn so với 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ư minh hoạ trong ví dụ sau. Hãy chỉ định pageToken cùng với các tham số cần thiết khác cho thao tác, có thể là trong phần nội dung của yêu cầu hoặc dưới dạng tham số truy vấn.

Yêu cầu 1

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

Câu trả lời #1

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

Yêu cầu 2

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

Câu trả lời #2

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

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

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

Lưu ý: Sự tồn tại của nextPageToken là chỉ báo duy nhất về việc liệu có thêm kết quả cần tìm nạp từ máy chủ hay không. Không tính 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 trong kích thước trang. Nếu có nextPageToken, bạn có thể gửi yêu cầu để có thêm kết quả sau yêu cầu ban đầu.