- Yêu cầu HTTP
- Nội dung yêu cầu
- Nội dung phản hồi
- Phạm vi uỷ quyền
- Bộ lọc
- DateFilter
- Ngày
- DateRange
- ContentFilter
- ContentCategory
- MediaTypeFilter
- MediaType
- FeatureFilter
- Tính năng
- Hãy làm thử!
Tìm kiếm các mục nội dung nghe nhìn trong thư viện Google Photos của người dùng. Nếu không có bộ lọc nào được đặt, thì 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 đều được trả về. Nếu đặt album, tất cả các mục nội dung nghe nhìn trong album chỉ định sẽ được trả về. Nếu bạn chỉ định bộ lọc, thì các mục nội dung đa phương tiện khớp với bộ lọc trong thư viện của người dùng sẽ có trong danh sách. Nếu bạn đặt cả album và bộ lọc, yêu cầu sẽ dẫn đến lỗi.
Yêu cầu HTTP
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
URL sử dụng cú pháp Chuyển mã gRPC.
Nội dung yêu cầu
Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:
Biểu diễn dưới dạng JSON |
---|
{
"albumId": string,
"pageSize": integer,
"pageToken": string,
"filters": {
object ( |
Trường | |
---|---|
albumId |
Số nhận dạng của album. Nếu đã điền sẵn thông tin, danh sách này sẽ liệt kê tất cả các mục nội dung nghe nhìn trong album cụ thể. Không thể đặt cùng với bất kỳ bộ lọc nào. |
pageSize |
Số mục nội dung đa phương tiện tối đa cần trả về trong phản hồi. Có thể trả về ít mục nội dung đa phương tiện hơn so với số lượng đã chỉ định. |
pageToken |
Mã thông báo tiếp tục để xem trang kết quả tiếp theo. Việc thêm mã này vào yêu cầu sẽ trả về các hàng sau |
filters |
Các bộ lọc để áp dụng cho yêu cầu. Không thể đặt cùng lúc với |
orderBy |
Trường tuỳ chọn để chỉ định thứ tự sắp xếp của các kết quả tìm kiếm. Trường Chỉ có thể sử dụng bộ lọc bổ sung với tham số này là |
Nội dung phản hồi
Danh sách các mục nội dung đa phương tiện khớp với thông số tìm kiếm.
Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:
Biểu diễn dưới dạng JSON |
---|
{
"mediaItems": [
{
object ( |
Trường | |
---|---|
mediaItems[] |
Chỉ có đầu ra. Danh sách các mục nội dung đa phương tiện khớp với thông số tìm kiếm. |
nextPageToken |
Chỉ có đầu ra. Hãy dùng mã thông báo này để nhận tập hợp mục nội dung nghe nhìn tiếp theo. Sự hiện diện này là chỉ báo đáng tin cậy duy nhất cho biết sẽ có thêm mục nội dung nghe nhìn trong yêu cầu tiếp theo. |
Phạm vi uỷ quyền
Yêu cầu một trong các phạm vi OAuth sau:
https://www.googleapis.com/auth/photoslibrary
https://www.googleapis.com/auth/photoslibrary.readonly
https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata
https://www.googleapis.com/auth/photoslibrary.readonly.originals
Bộ lọc
Các bộ lọc có thể áp dụng cho một lượt tìm kiếm mục nội dung nghe nhìn. Nếu bạn chỉ định nhiều tuỳ chọn bộ lọc, thì các tuỳ chọn đó sẽ được coi là AND với nhau.
Biểu diễn dưới dạng JSON |
---|
{ "dateFilter": { object ( |
Trường | |
---|---|
dateFilter |
Lọc các mục nội dung đa phương tiện dựa trên ngày tạo. |
contentFilter |
Lọc các mục nội dung nghe nhìn dựa trên nội dung của chúng. |
mediaTypeFilter |
Lọc các mục nội dung nghe nhìn dựa trên loại nội dung nghe nhìn. |
featureFilter |
Lọc các mục nội dung nghe nhìn dựa trên tính năng tương ứng. |
includeArchivedMedia |
Nếu bạn đặt chính sách này, kết quả sẽ bao gồm các mục nội dung nghe nhìn mà người dùng đã lưu trữ. Giá trị mặc định là false (không bao gồm các mục nội dung đa phương tiện đã lưu trữ). |
excludeNonAppCreatedData |
Nếu bạn đặt chính sách này, kết quả sẽ loại trừ những mục nội dung nghe nhìn không phải do ứng dụng này tạo ra. Giá trị mặc định là false (tất cả mục nội dung đa phương tiện đều được trả về). Trường này sẽ bị bỏ qua nếu bạn sử dụng phạm vi photoslibrary.readonly.app tạodata. |
DateFilter
Bộ lọc này xác định ngày hoặc phạm vi ngày được phép cho nội dung nghe nhìn được trả về. Bạn có thể chọn một tập hợp các ngày cụ thể và một tập hợp phạm vi ngày. Các mục nội dung đa phương tiện đã tải lên mà không chỉ định ngày mà mục nội dung đa phương tiện được ghi lại sẽ không được trả về trong các truy vấn sử dụng bộ lọc ngày. Thời gian tải lên máy chủ Google Photos không được dùng làm thời gian dự phòng trong trường hợp này.
Biểu diễn dưới dạng JSON |
---|
{ "dates": [ { object ( |
Trường | |
---|---|
dates[] |
Danh sách ngày khớp với ngày tạo của các mục nội dung nghe nhìn. Mỗi yêu cầu có thể bao gồm tối đa 5 ngày. |
ranges[] |
Danh sách phạm vi ngày phù hợp với các mục nội dung đa phương tiện ngày tạo. Bạn có thể chọn tối đa 5 phạm vi ngày cho mỗi yêu cầu. |
Ngày
Đại diện cho toàn bộ một ngày theo lịch. Đặt day
thành 0 khi chỉ tháng và năm là quan trọng, ví dụ: toàn bộ tháng 12 năm 2018. Đặt day
và month
thành 0 nếu chỉ có năm là quan trọng, ví dụ: toàn bộ năm 2018. Đặt year
thành 0 khi chỉ có ngày và tháng quan trọng, chẳng hạn như ngày kỷ niệm hoặc sinh nhật.
Không được hỗ trợ: Đặt tất cả các giá trị thành 0, chỉ month
thành 0 hoặc cả day
và year
thành 0 cùng một lúc.
Biểu diễn dưới dạng JSON |
---|
{ "year": integer, "month": integer, "day": integer } |
Trường | |
---|---|
year |
Năm của ngày. Giá trị phải từ 1 đến 9999 hoặc bằng 0 để chỉ định ngày không có năm. |
month |
Tháng trong năm. Giá trị phải từ 1 đến 12 hoặc bằng 0 để chỉ định một năm không có tháng và ngày. |
day |
Ngày trong tháng. Giá trị phải từ 1 đến 31 và có giá trị trong năm và tháng, hoặc bằng 0 nếu chỉ định một năm/tháng mà ngày đó không quan trọng. |
DateRange
Xác định một phạm vi ngày. Cả hai ngày phải có cùng định dạng. Để biết thêm thông tin, hãy xem Date
.
Biểu diễn dưới dạng JSON |
---|
{ "startDate": { object ( |
Trường | |
---|---|
startDate |
Ngày bắt đầu (nằm trong phạm vi) ở một trong các định dạng được mô tả. |
endDate |
Ngày kết thúc (được đưa vào phạm vi). Ngày này phải được chỉ định theo cùng định dạng với ngày bắt đầu. |
ContentFilter
Bộ lọc này cho phép bạn trả về các mục nội dung nghe nhìn dựa trên loại nội dung.
Có thể chỉ định danh sách danh mục để bao gồm và/hoặc danh sách danh mục cần loại trừ. Trong mỗi danh sách, các danh mục được kết hợp với OR.
Bộ lọc nội dung includedContentCategories
: [c1, c2, c3] sẽ nhận được các mục nội dung đa phương tiện chứa (c1 OR c2 OR c3).
Bộ lọc nội dung excludedContentCategories
: [c1, c2, c3] sẽ KHÔNG nhận được các mục nội dung đa phương tiện có chứa (c1 OR c2 OR c3).
Bạn cũng có thể thêm một số danh mục trong khi loại trừ các danh mục khác, như trong ví dụ sau: includedContentCategories
: [c1, c2], excludedContentCategories
: [c3, c4]
Ví dụ trước sẽ nhận được các mục nội dung nghe nhìn chứa (c1 HOẶC c2) VÀ KHÔNG (c3 HOẶC c4). Danh mục xuất hiện trong includedContentategories
không được xuất hiện ở excludedContentCategories
.
Biểu diễn dưới dạng JSON |
---|
{ "includedContentCategories": [ enum ( |
Trường | |
---|---|
includedContentCategories[] |
Nhóm danh mục sẽ được đưa vào kết quả tìm kiếm mục nội dung đa phương tiện. Các mục trong tập hợp này được OR. Mỗi yêu cầu chỉ được có tối đa 10 |
excludedContentCategories[] |
Tập hợp các danh mục không được đưa vào kết quả tìm kiếm mục nội dung nghe nhìn. Các mục trong tập hợp này được OR. Mỗi yêu cầu chỉ được có tối đa 10 |
ContentCategory
Đây là một tập hợp các danh mục nội dung được xác định trước mà bạn có thể lọc.
Enum | |
---|---|
NONE |
Danh mục nội dung mặc định. Danh mục này bị bỏ qua khi bất kỳ danh mục nào khác được sử dụng trong bộ lọc. |
LANDSCAPES |
Mục nội dung đa phương tiện chứa hướng ngang. |
RECEIPTS |
Mục nội dung đa phương tiện có chứa biên nhận. |
CITYSCAPES |
Các mục nội dung đa phương tiện chứa cảnh quan thành phố. |
LANDMARKS |
Mục nội dung đa phương tiện chứa các mốc. |
SELFIES |
Mục nội dung đa phương tiện là ảnh chân dung tự chụp. |
PEOPLE |
Mục nội dung đa phương tiện chứa người. |
PETS |
Mục nội dung đa phương tiện có chứa thú cưng. |
WEDDINGS |
Các mục nội dung nghe nhìn trong đám cưới. |
BIRTHDAYS |
Các mục nội dung nghe nhìn từ ngày sinh nhật. |
DOCUMENTS |
Mục nội dung đa phương tiện chứa tài liệu. |
TRAVEL |
Các mục nội dung nghe nhìn được chụp/quay trong lúc di chuyển. |
ANIMALS |
Mục nội dung đa phương tiện có chứa động vật. |
FOOD |
Nội dung nghe nhìn có chứa đồ ăn. |
SPORT |
Các mục nội dung đa phương tiện từ các sự kiện thể thao. |
NIGHT |
Các mục nội dung nghe nhìn được chụp vào ban đêm. |
PERFORMANCES |
Mục nội dung đa phương tiện trong phần hiệu suất. |
WHITEBOARDS |
Các mục nội dung đa phương tiện có chứa bảng trắng. |
SCREENSHOTS |
Mục nội dung đa phương tiện là ảnh chụp màn hình. |
UTILITY |
Các mục nội dung nghe nhìn được coi là tiện ích. Các tiện ích này bao gồm nhưng không giới hạn ở tài liệu, ảnh chụp màn hình, bảng trắng, v.v. |
ARTS |
Mục nội dung đa phương tiện chứa tác phẩm nghệ thuật. |
CRAFTS |
Các mục nội dung nghe nhìn có chứa đồ thủ công. |
FASHION |
Nội dung nghe nhìn liên quan đến thời trang. |
HOUSES |
Mục nội dung đa phương tiện chứa ngôi nhà. |
GARDENS |
Mục nội dung đa phương tiện có chứa các khu vườn. |
FLOWERS |
Các mục nội dung đa phương tiện có chứa hoa. |
HOLIDAYS |
Các mục nội dung nghe nhìn được chụp vào dịp lễ. |
MediaTypeFilter
Bộ lọc này xác định loại mục nội dung nghe nhìn cần trả về, ví dụ như video hoặc ảnh. Chỉ hỗ trợ một loại nội dung nghe nhìn.
Biểu diễn dưới dạng JSON |
---|
{
"mediaTypes": [
enum ( |
Trường | |
---|---|
mediaTypes[] |
Các loại mục nội dung nghe nhìn cần đưa vào. Trường này chỉ được điền một loại nội dung nghe nhìn. Nếu bạn chỉ định nhiều loại nội dung nghe nhìn thì sẽ xảy ra lỗi. |
MediaType
Tập hợp các loại nội dung nghe nhìn có thể tìm kiếm.
Enum | |
---|---|
ALL_MEDIA |
Được xử lý như thể không có bộ lọc nào được áp dụng. Tất cả các loại nội dung nghe nhìn đều được bao gồm. |
VIDEO |
Tất cả mục nội dung đa phương tiện được coi là video. Danh mục này cũng bao gồm phim người dùng đã tạo bằng ứng dụng Google Photos. |
PHOTO |
Tất cả mục nội dung đa phương tiện được coi là ảnh. Định dạng này bao gồm ảnh .bmp, .gif, .ico, .jpg (và các cách viết khác), .tiff, .webp và các loại ảnh đặc biệt như ảnh trực tiếp trên iOS, ảnh chuyển động Android, ảnh toàn cảnh, ảnh toàn cảnh 360 độ. |
FeatureFilter
Bộ lọc này xác định các tính năng mà các mục nội dung đa phương tiện cần có.
Biểu diễn dưới dạng JSON |
---|
{
"includedFeatures": [
enum ( |
Trường | |
---|---|
includedFeatures[] |
Bộ tính năng được đưa vào kết quả tìm kiếm mục nội dung đa phương tiện. Các mục trong tập hợp được nối với nhau bằng toán tử OR và có thể khớp với bất kỳ tính năng nào được chỉ định. |
Tính năng
Tập hợp các tính năng mà bạn có thể lọc.
Enum | |
---|---|
NONE |
Được xử lý như thể không có bộ lọc nào được áp dụng. Tất cả các tính năng đều được bao gồm. |
FAVORITES |
Mục nội dung đa phương tiện mà người dùng đã đánh dấu là yêu thích trong ứng dụng Google Photos. |