Liệt kê và truy xuất các mục nội dung nghe nhìn

Sau khi người dùng định cấu hình thiết bị môi trường xung quanh và chọn các nguồn nội dung nghe nhìn trong Google Photos, ứng dụng của bạn có thể liệt kê và truy xuất các mục nội dung nghe nhìn đó để hiển thị.

Trước khi bắt đầu

• Kiểm tra chế độ thiết lập thiết bị: Đảm bảo rằng bạn đã tạo và định cấu hình thiết bị thành công cho người dùng.
• Tìm hiểu quy trình của Ambient API: Xem lại Quy trình của Ambient API để hiểu rõ quy trình tổng thể, đặc biệt là bước liên quan đến việc thăm dò ý kiến về mediaSourcesSet.

Cuộc thăm dò ý kiến về mediaSourcesSet

Trước khi bạn có thể liệt kê các mục nội dung nghe nhìn cho một thiết bị, người dùng phải chọn ảnh mà họ muốn chia sẻ với ứng dụng của bạn trong ứng dụng Google Photos. Ứng dụng của bạn phải thăm dò ý kiến thiết bị để xác định thời điểm người dùng thực hiện lựa chọn này.

Định kỳ gọi phương thức devices.get cho deviceId cụ thể. Theo dõi trường mediaSourcesSet trong phản hồi AmbientDevice. Ban đầu, giá trị này sẽ là false. Sau khi người dùng chọn thành công nguồn nội dung đa phương tiện, trường này sẽ thay đổi thành true.

Phản hồi AmbientDevice bao gồm pollingConfig với pollInterval mà bạn nên sử dụng làm nguyên tắc cho tần suất thăm dò ý kiến.

Liệt kê các mục nội dung nghe nhìn

Khi mediaSourcesSet là true cho một thiết bị, bạn có thể bắt đầu tìm nạp các mục nội dung nghe nhìn mà người dùng đã chọn.

1. Sử dụng điểm cuối mediaItems.list: Tạo yêu cầu GET đến https://photosambient.googleapis.com/v1/mediaItems, cung cấp deviceId trong đường dẫn.

2. Xử lý phân trang (nếu cần): Phản hồi có thể được phân trang. Sử dụng thông số pageSize để chỉ định số lượng mục tối đa cần trả về và pageToken từ một phản hồi trước đó để truy xuất các trang kết quả tiếp theo.

3. Xử lý các mục nội dung nghe nhìn: Phản hồi sẽ chứa một mảng các đối tượng AmbientMediaItem, mỗi đối tượng đại diện cho một mục nội dung nghe nhìn đã chọn. Các đối tượng này bao gồm các thông tin chi tiết thiết yếu như:

   • id: Giá trị nhận dạng duy nhất cho mục nội dung nghe nhìn.
   • creationTime: Dấu thời gian tạo mục nội dung nghe nhìn.
   • mediaFile: Một đối tượng chứa thông tin chi tiết để truy cập vào nội dung thực tế.

Trường mediaFile bao gồm baseUrl. baseUrl này là nội dung bạn sẽ sử dụng để tạo URL truy cập vào nội dung của mục nội dung đa phương tiện ở nhiều độ phân giải hoặc định dạng.

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 Picker API:

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 Library API:

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 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 tỷ lệ thành 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 khoảng [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 được yêu cầu, thì hình ảnh sẽ được giảm tỷ lệ và cắt bớ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 chính xác là 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 video gốc đã chuyển mã, chất lượng cao. 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 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 nghe nhì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ả Lớp phủ xoá 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 thông 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ột mục nội dung đa phương tiện ảnh động, hãy sử dụng định dạng cho URL cơ sở của hình ảnh.

Các bước tiếp theo

• Ứng dụng mẫu: Ứng dụng mẫu của chúng tôi bao gồm một ví dụ về cách liệt kê và truy xuất các mục nội dung nghe nhìn. Hãy xem các hàm checkMediaSourcesSet và fetch_media_item_list để biết thêm thông tin.
• Tài liệu tham khảo: Xem lại tài liệu tham khảo toàn diện về các mục nội dung nghe nhìn để biết thông tin chi tiết về tất cả các phương thức, tham số yêu cầu và phản hồi cũng như mã lỗi hiện có.