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ị xung quanh và chọn 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 những 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 Ambient API: Xem Quy trình Ambient API để hiểu quy trình tổng thể, đặc biệt là bước liên quan đến việc thăm dò 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ững bức ả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ò thiết bị để xác định thời điểm người dùng đã chọn.

Đị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, thời gian 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 một pollingConfig có pollInterval mà bạn nên 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

Sau 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: Thực hiện yêu cầu GET đến https://photosambient.googleapis.com/v1/mediaItems, cung cấp deviceId trong đường dẫn.

2. Xử lý việc phân trang (nếu cần): Phản hồi có thể được phân trang. Sử dụng tham số pageSize để chỉ định số lượng tối đa các mục cần trả về và pageToken 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 những thông tin chi tiết cần thiết 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 khi mục nội dung nghe nhìn được tạo.
   • 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. Đây là baseUrl mà bạn sẽ dùng để tạo URL truy cập vào nội dung của mục nội dung nghe nhìn ở nhiều độ phân giải hoặc định dạng.

URL cơ sở

Các URL cơ sở trong Google Photos API 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ó trong phản hồi khi liệt kê album (Library API) hoặc truy cập vào các mục nội dung nghe nhìn (cả Library API và Picker API). Xin lưu ý rằng URL cơ sở cần có các tham số bổ sung để hoạt động đúng cách.

Đối với Picker API:

Tất cả các đối tượng PickedMediaItem.mediaFile đều có một baseUrl.

Các URL cơ sở vẫn 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.

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

Đối với Library API:

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

Sau đây là các URL cơ sở:

• baseUrl: Truy cập trực tiếp vào ảnh, hình thu nhỏ của video hoặc tải các byte 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 lựa chọn bạn có thể sử dụng với URL cơ sở của hình ảnh:

Tham 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 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 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 phương diện bắt buộc như trong ví dụ. Ví dụ: base-url=wmax-width-hmax-height Dưới đây là một ví dụ về cách hiển thị một mục nội dung nghe nhìn có chiều rộng không quá 2048 px và chiều cao không quá 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 đúng kích thước chiều rộng và chiều cao 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 (vẫn giữ nguyên 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 chính xác là 256 px và chiều cao 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 mà vẫn giữ nguyên 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 tải một hình ảnh xuống cùng với 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 lựa chọn bạn có thể sử dụng với URL cơ sở của video:

Tham số
dv	Nội dung mô tả Để truy cập vào các byte của một video mediaItem, hãy nối baseUrl với video tải xuống, tham số dv. Tham số dv yêu cầu một phiên bản chất lượng cao, đã chuyển mã 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 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 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ể gặp lỗi. Ví dụ: base-url=dv Ví dụ sau đây cho bạn thấy 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 một trong các tham số URL cơ sở của hình ảnh. Theo mặc định, tất cả hình thu nhỏ của video đều có một lớp phủ là nút phát. Hãy xem tham số -no để xoá lớp phủ này. Ví dụ: Tham khảo bảng URL cơ sở của hình ảnh để xem ví dụ.
no	Nội dung mô tả Tham số xoá lớp phủ hình thu nhỏ, 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ủ nút phát, hãy nối URL cơ sở với tham số no. Bạn phải dùng tham số no 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 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 chính xác là 720 px, đồng thời không có 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ở của hình ảnh hoặc URL cơ sở của video cho các yêu cầu về ảnh động baseUrl.

Tham 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 là ảnh động, hãy sử dụng tham số dv như khi bạn tải xuống từ URL cơ sở của 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 nghe nhìn là ảnh động, hãy sử dụng định dạng cho URL cơ sở của hình ảnh.

Chính sách nội dung và tính năng lọc

Theo mặc định, Google Photos áp dụng bộ lọc nội dung tiêu chuẩn cho hình ảnh và video xuất hiện trên một thiết bị dùng chung, chẳng hạn như TV hoặc màn hình kỹ thuật số. Bộ lọc này được thiết kế để tối ưu hoá trải nghiệm xem bằng cách loại trừ những nội dung như:

• Hình ảnh chức năng (ví dụ: ảnh chụp màn hình, tài liệu, biên nhận).
• Hình ảnh có thể hiển thị kém trên màn hình lớn (ví dụ: độ phân giải rất thấp, bị mờ, quá nhiều hạt).
• Nội dung được xác định là mang tính cá nhân hoặc nhạy cảm cao, có thể không dành cho việc hiển thị chung trong một môi trường dùng chung.

Tất cả quy trình lọc nội dung đều được tự động hoá. Để cho phép người dùng kiểm soát nội dung hiển thị nhiều hơn, bạn có thể cho phép họ tự chọn và cập nhật các nguồn nội dung nghe nhìn được dùng cho chế độ hiển thị thông minh.

Các bước tiếp theo

• Ứng dụng mẫu: Ứng dụng mẫu của chúng tôi có một ví dụ về việc liệt kê và truy xuất các mục nội dung nghe nhìn. Hãy xem hàm checkMediaSourcesSet và fetch_media_item_list để biết thêm thông tin.
• Tài liệu tham khảo: Xem 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 hiện có, các tham số yêu cầu và phản hồi, cũng như mã lỗi.