Liệt kê các mục và album nội dung nghe nhìn do ứng dụng tạo

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

Nội dung do ứng dụng tạo trong trang thông tin yêu cầu photoslibrary.readonly.appcreateddata phạm vi. Để biết thêm thông tin về phạm vi, hãy xem phần Uỷ quyền các phạm vi.

Tổng quan

Thư viện API cho phép bạn liệt kê và truy cập vào các mục nội dung nghe nhìn mà ứng dụng của bạn đã tạo.

Sau đây là một số tính năng chính của việc liệt kê các mục nội dung đa phương tiện:

• Liệt kê các mục nội dung nghe nhìn trong các album do ứng dụng tạo cụ thể hoặc toàn bộ ứng dụng do ứng dụng tạo thư viện

• Áp dụng bộ lọc (ngày, danh mục nội dung, nội dung nghe nhìn loại) khi liệt kê để thu hẹp phạm vi kết quả

• Truy xuất các đối tượng mediaItem có các thông tin chi tiết cần thiết như đường liên kết trực tiếp và siêu dữ liệu.

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.

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

Bạn có thể liệt kê những album do ứng dụng của bạn tạo bằng cách sử dụng 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"
}

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 album như được hiển thị trong Liệt kê nội dung album. Tiêu đề và số lượng mục nội dung nghe nhìn cũng được đưa vào.

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 bìa ảnh của anbom này. Để truy cập vào hình ả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 chỉ định thông số bổ sung.

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 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.

Liệt kê nội dung thư viện do ứng dụng tạo

Bạn có thể liệt kê tất cả mục nội dung nghe nhìn trong thư viện Google Photos của người dùng do ứng dụng của bạn tạo ra. Không bao gồm các mục đã lưu trữ và đã xóa. Bạn có thể liệt kê các mục nội dung đa phương tiện dựa trên nội dung, ngày và các thuộc tính khác của chúng bằng cách áp dụng bộ lọc.

Để liệt kê một mục nội dung nghe nhìn, hãy gọi mediaItems.list.

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

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

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.

Liệt kê nội dung trong album

Để 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. Nếu albumId không hợp lệ, lỗi Bad Request sẽ được trả về. Nếu giấy tờ tuỳ thân hợp lệ nhưng album đã xác thực không tồn tại người dùng, thì hệ thống sẽ trả về lỗi Not Found. Để biết thêm chi tiết về lỗi hãy xem Mẹo về hiệu suất và Các phương pháp hay nhất.

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

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.

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 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 tìm kiếm và danh sách mục nội dung nghe nhìn là 100 mục.

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

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ủ.

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 với các tham số khác cần thiết cho thao tác, 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": { … }
}

Phản hồi số 1

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

Yêu cầu #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ệ cho cùng một yêu cầu. Nếu có bất kỳ thông số nào là đã thay đổi, nên bạn không nên sử dụng nextPageToken đã sử dụng trước đó cho cùng một yêu cầu.