Method: mediaItems.search

Tìm kiếm các mục nội dung đa phương tiệ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 (Filters)
  },
  "orderBy": string
}
Trường
albumId

string

Giá trị nhận dạng của một 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

integer

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. pageSize mặc định là 25 và tối đa là 100.
pageToken

string

Mã thông báo tiếp tục để nhận trang tiếp theo của kết quả. Việc thêm thông tin này vào yêu cầu sẽ trả về các hàng sau pageToken. pageToken phải là giá trị được trả về trong tham số nextPageToken khi phản hồi yêu cầu searchMediaItems.
filters

object (Filters)

Các bộ lọc để áp dụng cho yêu cầu. Không thể đặt cùng lúc với albumId.
orderBy

string

Một trường không bắt buộc để chỉ định thứ tự sắp xếp của kết quả tìm kiếm. Trường orderBy chỉ hoạt động khi sử dụng dateFilter. Khi trường này không được chỉ định, kết quả sẽ hiển thị mới nhất xếp trước, cũ nhất xếp sau creationTime của kết quả. Việc cung cấp MediaMetadata.creation_time sẽ hiển thị các kết quả tìm kiếm theo thứ tự ngược lại, cũ nhất xếp trước rồi mới nhất xếp trước. Để hiển thị kết quả mới nhất xếp trước rồi cũ nhất xếp trước, hãy thêm đối số desc như sau: MediaMetadata.creation_time desc.

Chỉ có thể sử dụng bộ lọc bổ sung với tham số này là includeArchivedMedia và excludeNonAppCreatedData. Không có bộ lọc nào khác được hỗ trợ.

Nội dung phản hồi

Danh sách các mục nội dung nghe nhìn khớp với các tham 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 (MediaItem)
    }
  ],
  "nextPageToken": string
}
Trường
mediaItems[]

object (MediaItem)

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

string

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 của thuộc tính này là chỉ báo đáng tin cậy duy nhất cho biết có thêm các 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

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 (DateFilter)
  },
  "contentFilter": {
    object (ContentFilter)
  },
  "mediaTypeFilter": {
    object (MediaTypeFilter)
  },
  "featureFilter": {
    object (FeatureFilter)
  },
  "includeArchivedMedia": boolean,
  "excludeNonAppCreatedData": boolean
}
Trường
dateFilter

object (DateFilter)

Lọc các mục nội dung đa phương tiện dựa trên ngày tạo.
contentFilter

object (ContentFilter)

Lọc các mục nội dung nghe nhìn dựa trên nội dung của các mục đó.
mediaTypeFilter

object (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

object (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

boolean

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 nghe nhìn đã lưu trữ).
excludeNonAppCreatedData

boolean

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 mà hệ thống trả về. Bạn có thể chọn một nhóm ngày cụ thể và một nhóm 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 (Date)
    }
  ],
  "ranges": [
    {
      object (DateRange)
    }
  ]
}
Trường
dates[]

object (Date)

Danh sách ngày khớp với các mục nội dung đa phương tiện ngày tạo. Bạn có thể thêm tối đa 5 ngày cho mỗi yêu cầu.
ranges[]

object (DateRange)

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ỉ có tháng và năm là quan trọng, ví dụ: tất cả 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

integer

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

integer

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

integer

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 (Date)
  },
  "endDate": {
    object (Date)
  }
}
Trường
startDate

object (Date)

Ngày bắt đầu (có trong phạm vi) ở một trong các định dạng được mô tả.
endDate

object (Date)

Ngày kết thúc (nằm trong 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 mục nội dung đa phương tiện chứa (c1 OR c2) AND NOT (c3 OR c4). Danh mục xuất hiện trong includedContentategories không được xuất hiện trong excludedContentCategories.

Biểu diễn dưới dạng JSON 
{
  "includedContentCategories": [
    enum (ContentCategory)
  ],
  "excludedContentCategories": [
    enum (ContentCategory)
  ]
}
Trường
includedContentCategories[]

enum (ContentCategory)

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 includedContentCategories.
excludedContentCategories[]

enum (ContentCategory)

Nhóm danh mục khô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 này được OR. Mỗi yêu cầu chỉ được có tối đa 10 excludedContentCategories.

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 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 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 trong chuyến đi.
ANIMALS Mục nội dung đa phương tiện có chứa động vật.
FOOD Mục nội dung đa phương tiện có chứa thực phẩm.
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 đa phương tiệ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 Mục nội dung đa phương tiện chứa đồ thủ công.
FASHION Các mục nội dung đa phương tiệ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 sẽ được trả về, ví dụ: 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 (MediaType)
  ]
}
Trường
mediaTypes[]

enum (MediaType)

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, lỗi sẽ xảy ra.

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. Điều này cũng áp dụng cho các video mà 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 (Feature)
  ]
}
Trường
includedFeatures[]

enum (Feature)

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 này có giá trị OR và có thể khớp với bất kỳ đối tượ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. Bao gồm tất cả tính năng.
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.