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 bạn đặt mộ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 nghe nhìn khớp với bộ lọc trong thư viện của người dùng sẽ được liệt kê. 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

Số nhận dạng của album. Nếu được điền sẵn, hãy liệt kê tất cả các mục nội dung nghe nhìn trong album đã chỉ định. 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. Số lượng mục nội dung nghe nhìn được trả về có thể ít hơn số lượng đã chỉ định. pageSize mặc định là 25, 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 trong phản hồi cho yêu cầu searchMediaItems.
filters

object (Filters)

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 bạn không chỉ định trường này, kết quả sẽ hiển thị theo thứ tự mới nhất trước, cũ nhất sau theo creationTime của chúng. Việc cung cấp MediaMetadata.creation_time sẽ hiển thị kết quả tìm kiếm theo thứ tự ngược lại, kết quả cũ nhất trước rồi đến kết quả mới nhất sau cùng. Để hiển thị kết quả mới nhất trước rồi đến kết quả cũ nhất, hãy thêm đối số desc như sau: MediaMetadata.creation_time desc.

Các bộ lọc bổ sung duy nhất có thể sử dụng với tham số này là includeArchivedMedia và excludeNonAppCreatedData. Không hỗ trợ bộ lọc nào khác.

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 (MediaItem)
    }
  ],
  "nextPageToken": string
}
Trường
mediaItems[]

object (MediaItem)

Chỉ có đầu ra. 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.
nextPageToken

string

Chỉ có đầu ra. Sử dụng mã thông báo này để nhận nhóm mục nội dung đa phương tiệ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 nội dung tìm kiếm về 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 được đặt, 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 được đặt, kết quả sẽ loại trừ các mục nội dung nghe nhìn không phải do ứng dụng này tạo. Mặc định là false (tất cả các mục nội dung nghe nhì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.appcreateddata.

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 nhóm ngày cụ thể và một nhóm phạm vi ngày. Các mục nội dung nghe nhìn được tải lên mà không có siêu dữ liệu chỉ định ngày chụp mục nội dung nghe nhìn 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 phương án 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 ngày tạo của mục nội dung đa phương tiện. 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 các phạm vi ngày khớp với ngày tạo của mục nội dung nghe nhìn. Mỗi yêu cầu có thể bao gồm tối đa 5 dải ngày.

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ỉ năm là quan trọng, ví dụ: toàn bộ năm 2018. Đặt year thành 0 khi chỉ ngày và tháng là quan trọng, ví dụ: 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ỉ chỉ định giá trị năm/tháng, trong đó ngày là 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 (được đưa vào phạm vi). Ngày kết thúc phải có 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.

Bạn có thể chỉ định danh sách danh mục cần đưa vào 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 toán tử 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ể đưa một số danh mục vào 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 chứa (c3 HOẶC 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)

Tập hợp danh mục sẽ đượ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 được nối với nhau bằng toán tử OR. Mỗi yêu cầu chỉ được có tối đa 10 includedContentCategories.
excludedContentCategories[]

enum (ContentCategory)

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 được nối với nhau bằng toán tử OR. Mỗi yêu cầu 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ể dùng để lọc.

Enum
NONE Danh mục nội dung mặc định. Danh mục này sẽ 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 Các mục nội dung nghe nhìn chứa biên lai.
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 nghe nhìn là ảnh chân dung tự chụp.
PEOPLE Các mục nội dung nghe nhìn có chứa người.
PETS Mục nội dung đa phương tiện có chứa thú cưng.
WEDDINGS Vật phẩm truyền thông trong lễ 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 nghe nhì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 Nội dung nghe nhìn có chứa đồ ăn.
SPORT Nội dung nghe nhì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 nghe nhìn từ các màn trình diễn.
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 nghe nhì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 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 Các mục nội dung nghe nhìn có chứa hình ảnh vườn.
FLOWERS Mục nội dung nghe nhìn có 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 coi là không áp dụng bộ lọc nào. Tất cả các loại nội dung nghe nhìn đều được hỗ trợ.
VIDEO Tất cả các mục nội dung nghe nhì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ả các mục nội dung nghe nhì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 nghe nhìn phải có.

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

enum (Feature)

Tập hợp các tính năng sẽ được đưa vào kết quả tìm kiếm về mục nội dung nghe nhì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 Các mục nội dung nghe nhìn mà người dùng đã đánh dấu là mục yêu thích trong ứng dụng Google Photos.