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