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

Để đăng nội dung do ứng dụng tạo, bạn cần có phạm vi photoslibrary.readonly.appcreateddata. Để biết thêm thông tin về phạm vi, hãy xem bài viết Phạm vi uỷ quyền.

Tổng quan

API Thư viện cho phép bạn liệt kê và truy cập vào các mục nội dung đa phương tiệ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 đăng các mục nội dung nghe nhìn:

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

  • Áp dụng bộ lọc (ngày, danh mục nội dung, loại nội dung nghe nhìn) khi đăng để thu hẹp 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à đĩa nhạc sẽ trả về danh sách các mục nội dung nghe nhìn. Không bao gồm Thông tin bổ sung thuộc một đĩa nhạc. Mục nội dung nghe nhìn mô tả một bức ả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, một đường liên kết đến mục trong Google Photos và các siêu dữ liệu 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.

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

Bạn có thể liệt kê các album do ứng dụng của bạn tạo bằng cách sử dụng albums.list.

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

Mỗi đĩa nhạc được trả về đều có một mã nhận dạng có thể dùng để truy xuất nội dung của đĩa nhạc như trong phần Danh sách nội dung đĩa nhạc. 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 mà người dùng có thể mở.

coverPhotoMediaItemId chứa mã nhận dạng mục nội dung nghe nhìn đại diện cho ảnh bìa của album 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 các tham 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 các đĩa nhạc trống sẽ 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.

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ả các mục nội dung nghe nhìn do ứng dụng của bạn tạo trong thư viện Google Photos của người dùng. Số 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 bộ lọc.

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

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

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. Tệp này cũng chứa nextPageToken, được mô tả chi tiết hơn trong phần Phân trang.

Liệt kê nội dung trong album

Để liệt kê tất cả các mục nội dung nghe nhìn trong một đĩa nhạc, 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 phần Liệt kê album. 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 không có album nào cho người dùng đã xác thực, thì lỗi Not Found sẽ được trả về. Để 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.

REST

Sau đây là một 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"
}

Phản hồi chứa nextPageToken và danh sách các mục nội dung nghe nhì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 đĩa nhạc. Để 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 thứ tự 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 của 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 lượng lớn kết quả (chẳng hạn như phương thức danh sách) có thể phân trang phản hồi. Số kết quả tối đa trong mỗi trang đượ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ố 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. nextPageToken này cho ứng dụng của bạn biết rằng có nhiều 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 số 1

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

Phản hồi #1

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

Yêu cầu 2

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

Phản hồi #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ỳ tham số nào thay đổi, thì bạn không nên dùng nextPageToken đã sử dụng trước đó trong cùng một yêu cầu.