Truy cập vào các mục nội dung nghe nhìn do ứng dụng tạo

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 nên lưu trữ mã nhận dạng của các mục nội dung đa phương tiện đó. Lý do là nội dung của các mục nội dung nghe nhìn có thể thay đổi và sau một khoảng thời gian nhất định, các URL có trong phản hồi sẽ hết hạn. Mã mục nội dung nghe nhìn xác định duy nhất một mục nội dung nghe nhìn, chẳng hạn như một bức ảnh hoặc một video trong thư viện của người dùng.

Lưu ý: Ứng dụng của bạn không được lưu ảnh hoặc video của người dùng vào bộ nhớ đệm trong thời gian dài. 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 khoảng thời gian cần thiết. Quyền truy cập vào dữ liệu người dùng được điều chỉnh theo các nghĩa vụ về quyền riêng tư.

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

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

Mục nội dung nghe nhìn

mediaItem là nội dung đại diện cho nội dung nghe nhìn như ảnh hoặc video đã được tải lên thư viện Google Photos. Đây là một đối tượng cấp cao nhất và các thuộc tính của đối tượng này có thể khác nhau dựa trên loại nội dung đa phương tiệ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, ổn định dùng để xác định đối tượng.
description	Nội dung mô tả về mục nội dung nghe nhì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 Đường liên kết cơ sở.
productUrl	Đường liên kết đến hình ảnh trong Google Photos. Nhà phát triển không thể mở đường liên kết này, chỉ người dùng mới có thể mở. URL trỏ đến một mục nội dung nghe nhìn trong thư viện. Nếu được truy xuất từ một tìm kiếm album, URL này sẽ trỏ đến mục trong album.
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 nghe nhìn (ví dụ: image/jpg).
filename	Tên tệp của mục nội dung nghe nhìn hiển thị cho người dùng trong ứng dụng Google Photos (trong phần thông tin của mục).
mediaMetadata	Tuỳ thuộc vào loại nội dung nghe nhìn cơ bản, chẳng hạn như photo hoặc video. Để giảm tải trọng, bạn có thể sử dụng mặt nạ trường.

Lấy 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 nghe nhìn.

mediaItem chứa các thuộc tính, chẳng hạn 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. Bạn có thể không sử dụng được một số thuộc tính.

Nếu mục nội dung nghe nhìn là video, thì trước tiên, bạn phải xử lý tệp video. mediaItem chứa trường status bên trong mediaMetadata mô tả trạng thái xử lý của tệp video. Tệp mới tải lên sẽ trả về videoProcessingStatus với giá trị PROCESSING trước khi chuyển sang READY để sử dụng. baseUrl của mục nội dung đa phương tiện video sẽ không có sẵn cho đến khi video được xử lý.

REST

Dưới đây là yêu cầu GET:

GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

Câu trả lời cho một mục nội dung nghe nhìn dạng ảnh sẽ 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ụ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"
  }
}

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 trả về danh sách MediaItemResults theo thứ tự mã 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 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 lệnh gọi. Danh sách 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.

REST

Dưới đây là một yêu cầu GET cho biết quyền truy cập thành công và không thành công vào các mục nội dung nghe nhìn. Chỉ định từng giá trị nhận dạng mục nội dung đa phương tiện làm 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."
      }
    }
  ]
}

URL cơ sở

URL cơ sở trong API Google Photos cung cấp quyền truy cập vào các byte thô của các mục nội dung nghe nhìn, cho phép ứng dụng của bạn tải xuống hoặc hiển thị các mục đó. Các URL này được đưa vào phản hồi khi liệt kê album (API Thư viện) hoặc truy cập vào các mục nội dung nghe nhìn (cả API Thư viện và API Bộ chọn). Hãy nhớ rằng URL cơ sở cần có thêm các tham số để hoạt động đúng cách.

Đối với API bộ chọn:

Tất cả đối tượng PickedMediaItem.mediaFile đều bao gồm một baseUrl.

URL cơ sở vẫn đang hoạt động trong 60 phút, nhưng có thể hết hạn sớm hơn nếu người dùng thu hồi quyền của ứng dụng thông qua phần cài đặt Tài khoản Google của họ.

Lưu ý: Các yêu cầu đến baseUrl PickedMediaItem.mediaFile phải bao gồm tiêu đề Uỷ quyền có mã thông báo mang theo OAuth 2.0 hợp lệ.

Đối với API Thư viện:

URL cơ sở vẫn hoạt động trong 60 phút.

Có nhiều URL cơ sở như sau:

• baseUrl: Truy cập trực tiếp vào ảnh, hình thu nhỏ của video hoặc tải video xuống.
• coverPhotoBaseUrl: Truy cập trực tiếp vào ảnh bìa của album.
• profilePictureBaseUrl: Truy cập trực tiếp vào ảnh hồ sơ của chủ sở hữu mediaItem.

Cảnh báo: Nếu sử dụng URL cơ sở, bạn phải chỉ định một tham số tải xuống hoặc cả chiều rộng tối đa và chiều cao tối đa.

URL cơ sở của hình ảnh

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 hình ảnh:

Thông số
w, h	Nội dung mô tả Các tham số chiều rộng, w và chiều cao, h. Để truy cập vào một mục nội dung đa phương tiện hình ảnh, chẳng hạn như ảnh hoặc hình thu nhỏ của một 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 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ư trong ví dụ. Ví dụ: base-url=wmax-width-hmax-height Dưới đây là ví dụ về cách hiển thị một mục nội dung nghe nhìn không rộng hơn 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ả Tham số cắt, c. Nếu bạn muốn cắt hình ảnh theo kích thước chiều rộng và chiều cao chính xác mà bạn đã chỉ định, hãy nối URL cơ sở với tham số -c không bắt buộc cùng với các tham số w và h bắt buộc. 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 nghe nhìn có chiều rộng và chiều cao bằng đúng 256 px, chẳng hạn như 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, d. 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ố d. Ví dụ: base-url=d Trong ví dụ này, ứng dụng sẽ tải một hình ảnh xuống 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 mediaItem, hãy nối baseUrl với tham số tải video xuống dv. Tham 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 các tham số w và h. URL cơ sở để tải video xuống có thể mất đến vài giây để trả về các byte. Trước khi sử dụng tham số này, hãy kiểm tra để đảm bảo trường mediaMetadata.status của các mục nội dung đa phương tiện là READY. Nếu không, nếu mục nội dung nghe nhìn của bạn chưa xử lý xong, bạn có thể nhận được lỗi. 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ỳ thông số URL cơ sở của hình ảnh nào. Theo mặc định, tất cả hình thu nhỏ video đều có lớp phủ của nút phát. Hãy xem tham số -no để xoá lớp phủ này. Ví dụ: Hãy tham khảo bảng URL cơ sở của hình ảnh để biết ví dụ.
no	Nội dung mô tả Xoá lớp phủ hình thu nhỏ, tham số no. Nếu bạn muốn truy xuất hình thu nhỏ của một 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. Bạn phải sử dụng tham số no với ít nhất một trong các tham số URL cơ sở hình ảnh. Ví dụ: base-url=wmax-width-hmax-height-no Ví dụ sau đây cho thấy một hình thu nhỏ video có chiều rộng chính xác là 1280 px và chiều cao là 720 px, không bao gồm lớp phủ nút phát: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

URL cơ sở của ảnh chuyển động

Ảnh chuyển động chứa cả phần tử ả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 độ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 đa phương tiện ảnh động, hãy sử dụng tham số dv như khi bạn tải xuống từ URL cơ sở video.
w, h, c và d	Nội dung mô tả Để truy xuất phần tử ảnh của mục nội dung nghe nhìn ảnh chuyển động, hãy sử dụng định dạng cho URL cơ sở của hình ảnh.