Sau khi thực hiện lệnh gọi để liệt kê nội dung của thư viện ảnh hoặc album, thay vì lưu trữ các mục nội dung đa phương tiện được trả về, ứng dụng của bạn sẽ lưu trữ mã nhận dạng của các mục nội dung đa phương tiện. Nguyên nhân là do nội dung của các mục nội dung đa phương tiện có thể thay đổi và sau một khoảng thời gian nhất định, các URL được đưa vào phản hồi sẽ hết hạn. Mã mục nội dung đa phương tiện xác định duy nhất một mục nội dung đa phương tiện, chẳng hạn như ảnh hoặc video bên trong thư viện của người dùng.
Xin lưu ý rằng ứng dụng không nên lưu ảnh hoặc video của người dùng vào bộ nhớ đệm trong thời gian dài, nhưng tuỳ thuộc vào trường hợp sử dụng, bạn có thể lưu trữ hoặc lưu vào bộ nhớ đệm mã mục nội dung đa phương tiện trong thời gian nếu cần. Bạn cũng nên lưu ý rằng quyền truy cập vào dữ liệu người dùng chịu sự điều chỉnh của các nghĩa vụ về quyền riêng tư.
Phạm vi uỷ quyền bắt buộc
Để truy cập vào các mục nội dung đa phương tiện, ứng dụng của bạn phải yêu cầu ít nhất một trong các phạm vi uỷ quyền sau. Quyền truy cập vào các mục nội dung đa phương tiện được trả về trong phản hồi sẽ phụ thuộc vào phạm vi mà bạn đã yêu cầu.
photoslibrary.readonlycho phép truy cập vào tất cả mục nội dung đa phương tiện trong thư viện của người dùngphotoslibrary.readonly.appcreateddatachỉ cho phép truy cập vào các mục nội dung nghe nhìn do ứng dụng tạo
Mục nội dung nghe nhìn
mediaItem là nội dung đại diện cho nội dung nghe nhìn, chẳng hạn như ảnh hoặc video đã được tải lên thư viện Google Photos. Đây là đối tượng cấp cao nhất và các thuộc tính của đối tượng đó có thể khác nhau tuỳ theo loại nội dung nghe nhìn cơ bản.
Bảng sau đây liệt kê các thuộc tính mediaItem:
| Thuộc tính | |
|---|---|
id |
Mã nhận dạng cố định, cố định được dùng để nhận dạng đối tượng. |
description |
Nội dung mô tả về mục nội dung đa phương tiện như trong Google Photos. |
baseUrl |
Dùng để truy cập vào các byte thô. Để biết thêm thông tin, hãy xem phần URL cơ sở. |
productUrl |
Đường liên kết đến hình ảnh trong Google Photos. Nhà phát triển chỉ có thể mở đường liên kết này. URL trỏ đến một mục nội dung đa phương tiện trong thư viện. Nếu được truy xuất thông qua tính năng tìm kiếm đĩa nhạc, thì URL sẽ trỏ đến mục đó trong đĩa nhạc. |
mimeType |
Loại mục nội dung đa phương tiện giúp dễ dàng xác định loại nội dung đa phương tiện (ví dụ: image/jpg). |
filename |
Tên tệp của mục nội dung đa phương tiện mà người dùng thấy trong ứng dụng Google Photos (trong phần thông tin của mục). |
mediaMetadata |
Khác nhau tuỳ thuộc vào loại nội dung đa phương tiện cơ bản, chẳng hạn như photo hoặc video.
Để giảm tải trọng, có thể sử dụng mặt nạ thực địa (field mask).
|
contributorInfo |
Trường này chỉ được điền nếu mục nội dung nghe nhìn nằm trong một album chia sẻ do ứng dụng này tạo và người dùng đã cấp phạm vi Chứa thông tin về người đóng góp đã thêm mục nội dung đa phương tiện này. Để biết thêm chi tiết, hãy xem bài viết Chia sẻ nội dung nghe nhìn. |
Tải một mục nội dung nghe nhìn
Để truy xuất một mục nội dung đa phương tiện, hãy gọi mediaItems.get bằng mediaItemId. Yêu cầu này trả về một mục nội dung đa phương tiện.
mediaItem chứa các thuộc tính như mã nhận dạng, nội dung mô tả và URL. Thông tin bổ sung trong photo hoặc video dựa trên siêu dữ liệu trong tệp. Không phải cơ sở lưu trú nào cũng có mặt. ContributorInfo chứa siêu dữ liệu cho các mục thuộc album chia sẻ. Trường này chỉ được đưa vào khi liệt kê nội dung của một album chia sẻ mà người dùng đã cấp phạm vi uỷ quyền photoslibrary.sharing.
Nếu mục nội dung đa phương tiện là video, trước tiên, tệp video phải được xử lý. mediaItem chứa trường status bên trong mediaMetadata mô tả trạng thái xử lý tệp video. Tệp mới tải lên sẽ trả về videoProcessingStatus có giá trị PROCESSING trước, trước khi giá trị này là READY để sử dụng. baseUrl của mục nội dung nghe nhìn ở dạng video không dùng được cho đến khi video được xử lý.
Kiến trúc chuyển trạng thái đại diện (REST)
Dưới đây là một yêu cầu GET:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-token
Phản hồi cho một mục nội dung nghe nhìn dạng ảnh có dạng như sau. Thuộc tính ảnh chứa siêu dữ liệu cho các mục ảnh.
{
"id": "media-item-id",
"description": "item-description",
"productUrl": "url-to-open-in-google-photos",
"baseUrl": "base-url_do-not-use-directly",
"mimeType": "mime-type-of-media",
"filename": "item-filename",
"mediaMetadata": {
"width": "media-item-width",
"height": "media-item-height",
"creationTime": "media-item-creation-time",
"photo": {
"cameraMake": "make-of-the-camera",
"cameraModel": "model-of-the-camera",
"focalLength": "focal-length-of-the-camera-lens",
"apertureFNumber": "aperture-f-number-of-the-camera-lens",
"isoEquivalent": "iso-of-the-camera",
"exposureTime": "exposure-time-of-the-camera-aperture"
}
},
"contributorInfo": {
"profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
"displayName": "name-of-user"
}
}
Phản hồi cho một mục nội dung đa phương tiện dạng video có dạng như sau. Thuộc tính video chứa siêu dữ liệu cho các mục video.
{
"id": "media-item-id",
"description": "item-description",
"productUrl": "url-to-open-in-google-photos",
"baseUrl": "base-url_do-not-use-directly",
"mimeType": "mime-type-of-media",
"filename": "item-filename",
"mediaMetadata": {
"width": "media-item-width",
"height": "media-item-height",
"creationTime": "media-item-creation-time",
"video": {
"cameraMake": "make-of-the-camera",
"cameraModel": "model-of-the-camera",
"fps": "frame-rate-of-the-video",
"status": "READY"
},
},
"contributorInfo": {
"profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
"displayName": "name-of-user"
}
}
Java
Thuộc tính ảnh chứa siêu dữ liệu cho các mục ảnh.
try {
// Get a media item using its ID
String mediaItemId = "...";
MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
// Get some properties from the retrieved media item
String id = item.getId();
String description = item.getDescription();
String baseUrl = item.getBaseUrl();
String productUrl = item.getProductUrl();
// ...
if (item.hasMediaMetadata()) {
// The media item contains additional metadata, such as the height and width
MediaMetadata metadata = item.getMediaMetadata();
long height = metadata.getHeight();
long width = metadata.getWidth();
Timestamp creationTime = metadata.getCreationTime();
// ...
if (metadata.hasPhoto()) {
// This media item is a photo and has additional photo metadata
Photo photoMetadata = metadata.getPhoto();
String cameraMake = photoMetadata.getCameraMake();
String cameraModel = photoMetadata.getCameraModel();
float aperture = photoMetadata.getApertureFNumber();
int isoEquivalent = photoMetadata.getIsoEquivalent();
// ...
}
}
if (item.hasContributorInfo()) {
// A user has contributed this media item to a shared album
ContributorInfo contributorInfo = item.getContributorInfo();
String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
String displayName = contributorInfo.getDisplayName();
}
} catch (ApiException e) {
// Handle error
}
Tài sản video chứa siêu dữ liệu cho các mục video.
try {
// Get a media item using its ID
String mediaItemId = "...";
MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
// Get some properties from the retrieved media item
String id = item.getId();
String description = item.getDescription();
String baseUrl = item.getBaseUrl();
String productUrl = item.getProductUrl();
// ...
if (item.hasMediaMetadata()) {
// The media item contains additional metadata, such as the height and width
MediaMetadata metadata = item.getMediaMetadata();
long height = metadata.getHeight();
long width = metadata.getWidth();
Timestamp creationTime = metadata.getCreationTime();
// ...
if (metadata.hasVideo()) {
// This media item is a video and has additional video metadata
Video videoMetadata = metadata.getVideo();
VideoProcessingStatus status = videoMetadata.getStatus();
if (status.equals(VideoProcessingStatus.READY)) {
// This video media item has been processed
String cameraMake = videoMetadata.getCameraMake();
String cameraModel = videoMetadata.getCameraModel();
double fps = videoMetadata.getFps();
// ...
}
}
}
if (item.hasContributorInfo()) {
// A user has contributed this media item to a shared album
ContributorInfo contributorInfo = item.getContributorInfo();
String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
String displayName = contributorInfo.getDisplayName();
}
} catch (ApiException e) {
// Handle error
}
1.199
Thuộc tính ảnh chứa siêu dữ liệu cho các mục ảnh.
try {
// Get a media item using its ID
$mediaItemId = "...";
$item = $photosLibraryClient->getMediaItem($mediaItemId);
// Get some properties from the retrieved media item
$id = $item->getId();
$description = $item->getDescription();
$baseUrl = $item->getBaseUrl();
$productUrl = $item->getProductUrl();
// ...
$metadata = $item->getMediaMetadata();
if (!is_null($metadata)) {
// The media item contains additional metadata, such as the height and width
$height = $metadata->getHeight();
$width = $metadata->getWidth();
$creationTime = $metadata->getCreationTime();
// ...
$photoMetadata = $metadata->getPhoto();
if (!is_null($photoMetadata)) {
// This media item is a photo and has additional photo metadata
$cameraMake = $photoMetadata->getCameraMake();
$cameraModel = $photoMetadata->getCameraModel();
$aperture = $photoMetadata->getApertureFNumber();
$isoEquivalent = $photoMetadata->getIsoEquivalent();
// ...
}
}
$contributorInfo = $item->getContributorInfo();
if (!is_null($contributorInfo)) {
// A user has contributed this media item to a shared album
$profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
$displayName = $contributorInfo->getDisplayName();
}
} catch (\Google\ApiCore\ApiException $e) {
// Handle error
}
Tài sản video chứa siêu dữ liệu cho các mục video.
try {
// Get a media item using its ID
$mediaItemId = "...";
$item = $photosLibraryClient->getMediaItem($mediaItemId);
// Get some properties from the retrieved media item
$id = $item->getId();
$description = $item->getDescription();
$baseUrl = $item->getBaseUrl();
$productUrl = $item->getProductUrl();
// ...
$metadata = $item->getMediaMetadata();
if (!is_null($metadata)) {
// The media item contains additional metadata, such as the height and width
$height = $metadata->getHeight();
$width = $metadata->getWidth();
$creationTime = $metadata->getCreationTime();
// ...
$videoMetadata = $metadata->getVideo();
if (!is_null($videoMetadata)) {
// This media item is a video and has additional video metadata
if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) {
// This video media item has been processed
$cameraMake = $videoMetadata->getCameraMake();
$cameraModel = $videoMetadata->getCameraModel();
$fps = $videoMetadata->getFps();
// ...
}
}
}
$contributorInfo = $item->getContributorInfo();
if (!is_null($contributorInfo)) {
// A user has contributed this media item to a shared album
$profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
$displayName = $contributorInfo->getDisplayName();
}
} catch (\Google\ApiCore\ApiException $e) {
// Handle error
}
Tải nhiều mục nội dung nghe nhìn
Để truy xuất nhiều mục nội dung đa phương tiện theo giá trị nhận dạng, hãy gọi mediaItems.batchGet bằng các mediaItemId.
Yêu cầu này sẽ trả về một danh sách MediaItemResults theo thứ tự của các giá trị nhận dạng mục nội dung đa phương tiện được cung cấp trong yêu cầu. Mỗi kết quả chứa một MediaItem hoặc Status nếu có lỗi.
Bạn có thể yêu cầu tối đa 50 mục nội dung nghe nhìn trong một cuộc gọi. Danh sách các mục nội dung đa phương tiện không được chứa giá trị nhận dạng trùng lặp và không được để trống.
Kiến trúc chuyển trạng thái đại diện (REST)
Đây là một yêu cầu GET cho thấy việc truy cập thành công và không thành công vào các mục nội dung đa phương tiện. Chỉ định mỗi giá trị nhận dạng mục nội dung đa phương tiện dưới dạng một tham số truy vấn mediaItemIds mới trong yêu cầu:
GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id Content-type: application/json Authorization: Bearer oauth2-token
Yêu cầu GET trả về phản hồi sau:
{
"mediaItemResults": [
{
"mediaItem": {
"id": "media-item-id",
...
}
},
{
"mediaItem": {
"id": "another-media-item-id",
...
}
},
{
"status": {
"code": 3,
"message": "Invalid media item ID."
}
}
]
}
Java
try {
// List of media item IDs to retrieve
List<String> mediaItemIds = Arrays
.asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID");
// Get a list of media items using their IDs
BatchGetMediaItemsResponse response = photosLibraryClient
.batchGetMediaItems(mediaItemIds);
// Loop over each result
for (MediaItemResult result : response.getMediaItemResultsList()) {
// Each MediaItemresult contains a status and a media item
if (result.hasMediaItem()) {
// The media item was successfully retrieved, get some properties
MediaItem item = result.getMediaItem();
String id = item.getId();
// ...
} else {
// If the media item is not set, an error occurred and the item could not be loaded
// Check the status and handle the error
Status status = result.getStatus();
// ...
}
}
} catch (ApiException e) {
// Handle error
}
1.199
try {
// List of media item IDs to retrieve
$mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"];
// Get a list of media items using their IDs
$response = $photosLibraryClient->batchGetMediaItems($mediaItemIds);
// Loop over each result
foreach ($response->getMediaItemResults() as $itemResult) {
// Each MediaItemresult contains a status and a media item
$mediaItem = $itemResult->getMediaItem();
if(!is_null($mediaItem)){
// The media item was successfully retrieved, get some properties
$id = $mediaItem->getId();
// ...
} else {
// If the media item is null, an error occurred and the item could not be loaded
}
}
} catch (\Google\ApiCore\ApiException $e) {
// Handle error
}
URL cơ sở
URL cơ sở trong API Thư viện Google Photos cho phép bạn truy cập vào các byte của các mục nội dung nghe nhìn. Bằng cách sử dụng nhiều URL cơ sở, ứng dụng của bạn có thể tải các mục nội dung đa phương tiện xuống hoặc hiển thị các mục nội dung đa phương tiện trong ứng dụng. URL cơ sở là các chuỗi được đưa vào phản hồi khi bạn liệt kê các album hoặc truy cập vào các mục nội dung đa phương tiện. Các phương thức này có hiệu lực trong 60 phút và cần thêm các tham số vì không thể sử dụng nguyên trạng.
Có các URL cơ sở sau:
baseUrl: Truy cập trực tiếp vào ảnh, hình thu nhỏ của một video hoặc tải các byte video xuống.coverPhotoBaseUrl: Truy cập trực tiếp vào ảnh bìa cho album.profilePictureBaseUrl: Truy cập trực tiếp vào ảnh hồ sơ của chủ sở hữumediaItem.
URL cơ sở của hình ảnh
Sau đây là danh sách các lựa chọn mà bạn có thể sử dụng với URL cơ sở của hình ảnh:
| Thông số | |
|---|---|
w, h |
Nội dung mô tả Tham số chiều rộng, Để truy cập vào một mục nội dung nghe nhìn dạng hình ảnh, chẳng hạn như ảnh hoặc hình thu nhỏ của video, bạn phải chỉ định kích thước mà bạn dự định hiển thị trong ứng dụng (để hình ảnh có thể được điều chỉnh theo tỷ lệ theo các kích thước này trong khi vẫn giữ nguyên tỷ lệ khung hình). Để thực hiện việc này, hãy nối URL cơ sở với các kích thước bắt buộc như minh hoạ trong các ví dụ. Ví dụ: base-url=wmax-width-hmax-height Dưới đây là ví dụ hiển thị một mục nội dung đa phương tiện có kích thước không quá 2048 px và không cao hơn 1024 px: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Nội dung mô tả Cắt, tham số Nếu bạn muốn cắt hình ảnh theo kích thước chính xác chiều rộng và chiều cao
bạn đã chỉ định, hãy nối URL cơ sở với
tham số Kích thước (tính bằng pixel) phải nằm trong phạm vi [1, 16383]. Nếu chiều rộng hoặc chiều cao của hình ảnh vượt quá kích thước yêu cầu, thì hình ảnh sẽ được thu nhỏ và cắt (duy trì tỷ lệ khung hình). Ví dụ: base-url=wmax-width-hmax-height-c Trong ví dụ này, ứng dụng hiển thị một mục nội dung đa phương tiện có kích thước chính xác là 256 px x 256 px cao, chẳng hạn như một hình thu nhỏ: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Nội dung mô tả Tham số tải xuống, Nếu bạn muốn tải hình ảnh xuống và giữ lại tất cả siêu dữ liệu Exif, ngoại trừ siêu dữ liệu vị trí, hãy nối URL cơ sở với tham số Ví dụ: base-url=d Trong ví dụ này, ứng dụng tải một hình ảnh có tất cả siêu dữ liệu, ngoại trừ siêu dữ liệu vị trí: https://lh3.googleusercontent.com/p/Az....XabC=d |
URL cơ sở của video
Dưới đây là danh sách các tuỳ chọn mà bạn có thể sử dụng với URL cơ sở của video:
| Thông số | |
|---|---|
dv |
Nội dung mô tả Để truy cập vào các byte của video Thông số dv yêu cầu phiên bản đã chuyển mã chất lượng cao của video gốc. Tham số này không tương thích với tham số w và h. URL cơ sở để tải video xuống có thể mất đến vài giây để trả về byte. Trước khi sử dụng tham số này, hãy kiểm tra để đảm bảo rằng trường Ví dụ: base-url=dv Ví dụ sau đây cho bạn biết cách tải các byte của một video xuống: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w, h, c và d |
Nội dung mô tả Để truy cập vào hình thu nhỏ của video, hãy sử dụng bất kỳ tham số url cơ sở của hình ảnh nào. Theo mặc định, mọi hình thu nhỏ video đều có lớp phủ của nút phát. Xem thông số -no để loại bỏ lớp phủ này. Ví dụ: Hãy tham khảo bảng URL cơ sở của hình ảnh để xem ví dụ. |
no |
Nội dung mô tả Xoá lớp phủ hình thu nhỏ, tham số Nếu bạn muốn truy xuất hình thu nhỏ của video mà không có lớp phủ của nút phát, hãy nối URL cơ sở với tham số no. Tham số no phải được sử dụng với ít nhất một trong các tham số url cơ sở của hình ảnh. Ví dụ: base-url=wmax-width-hmax-height-no Ví dụ sau đây hiển thị một hình thu nhỏ video có kích thước chính xác là 1280 px x 720 px rộng và không có lớp phủ nút phát: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
URL cơ sở ảnh chuyển động
Ảnh chuyển động chứa cả thành phần ảnh và video. Bạn có thể sử dụng các tham số từ URL cơ sở hình ảnh hoặc URL cơ sở video cho các yêu cầu baseUrl ảnh chuyển động.
| Thông số | |
|---|---|
dv |
Nội dung mô tả Để truy xuất phần tử video của một mục nội dung nghe nhìn dạng ảnh chuyển động, hãy sử dụng tham số |
w, h, c và d |
Nội dung mô tả Để truy xuất phần tử ảnh của một mục nội dung nghe nhìn dạng ảnh chuyển động, hãy sử dụng định dạng cho URL cơ sở của hình ảnh. |