Method: mediaItems.search

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 bạn không đặt bộ lọc nào, thì mọi mục nội dung đa phương tiện trong thư viện của người dùng sẽ được trả về. Nếu một album được đặt, 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, các mục nội dung nghe nhìn phù hợ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

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

string

Mã thông báo tiếp tục để xem trang tiếp theo của kết quả. Việc thêm đoạn mã 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 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 với albumId.
orderBy

string

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 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ẽ được hiển thị mới nhất xếp trước, cũ nhất xếp sau creationTime. 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 và mới nhất xếp sau. Để cho thấy kết quả mới nhất xếp trước rồi đến kết quả cũ nhất cuối cùng, 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 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 đ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 đ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 nhóm mục nội dung đa phương tiện tiếp theo. Sự hiện diện của thẻ này là chỉ báo đáng tin cậy duy nhất cho biết có thêm mục nội dung đa phương tiệ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 đây:

  • 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 khi tìm kiếm mục nội dung đa phương tiện. Nếu bạn chỉ định nhiều tùy chọn bộ lọc, thì các tùy chọn này đượ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 nghe nhì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 chúng.
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 của các mục đó.
includeArchivedMedia

boolean

Nếu bạn đặt chính sách này, thì 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à sai (không bao gồm các mục nội dung nghe nhìn được lưu trữ).
excludeNonAppCreatedData

boolean

Nếu bạn đặt chính sách này, kết quả sẽ loại trừ các mục nội dung nghe nhìn không do ứng dụng này tạo. Giá trị mặc định là false (tất cả mục nội dung nghe nhìn đều được trả về). Trường này sẽ bị bỏ qua nếu phạm vi photoslibrary.readonly.appcreateddata được sử dụng.

DateFilter

Bộ lọc này xác định ngày hoặc phạm vi ngày được cho 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 đa phương tiện được tải lên mà không có siêu dữ liệu chỉ định ngày mục nội dung đa phương tiện được ghi sẽ không được trả về trong các truy vấn sử dụng bộ lọc ngày. Trong trường hợp này, thời gian tải lên trên máy chủ Google Photos không được dùng làm phương án dự phòng.

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 mục nội dung đa phương tiện. Mỗi yêu cầu có thể thêm tối đa 5 ngày.
ranges[]

object (DateRange)

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

Ngày

Đại diện cho toàn bộ ngày theo lịch. Đặt day thành 0 khi chỉ có 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, 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 tháng. Giá trị phải từ 1 đến 9999 hoặc từ 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 từ 0 để chỉ định 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ị cho năm và tháng hoặc bằng 0 nếu chỉ định năm/tháng trong đó ngày là không quan trọng.

DateRange

Xác định 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 bao gồm như một phần của phạm vi) ở một trong các định dạng được mô tả.
endDate

object (Date)

Ngày kết thúc (được bao gồm như một phần của phạm vi). Ngày bắt đầu 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.

Bạn có thể chỉ định một danh sách các danh mục cần bao gồm và/hoặc một danh sách các danh mục cần loại trừ. Trong mỗi danh sách, các danh mục được kết hợp bằng lệnh 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 lấy được các mục nội dung đa phương tiện chứa (c1 OR c2 OR c3).

Bạn cũng có thể bao gồ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 đ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)

Tập hợp các 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. Bạn có thể tạo tối đa 10 includedContentCategories cho mỗi yêu cầu.
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 đa phương tiện. Các mục trong tập hợp này được OR. Bạn có thể tạo tối đa 10 excludedContentCategories cho mỗi yêu cầu.

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 ngang.
RECEIPTS Mục nội dung đa phương tiện 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 điểm 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 Mục nội dung đa phương tiện từ đám cưới.
BIRTHDAYS Các mục nội dung nghe nhìn từ 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 đa phương tiện đã chụp trong khi di chuyển.
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 đồ ăn.
SPORT Mục nội dung đa phương tiện từ sự kiện thể thao.
NIGHT Các mục nội dung đa phương tiện được chụp vào ban đêm.
PERFORMANCES Mục nội dung đa phương tiện từ các buổi biểu diễn.
WHITEBOARDS Mục nội dung đa phương tiện có chứa bảng trắng.
SCREENSHOTS Các 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à phần mềm tiện ích. Các thành phần 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 có chứa ảnh.
CRAFTS Mục nội dung đa phương tiện chứa đồ thủ công.
FASHION 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 nhà.
GARDENS Mục nội dung đa phương tiện có vườn.
FLOWERS Mục nội dung đa phương tiện có chứa hoa.
HOLIDAYS Nội dung nghe nhìn được chụp trong ngày lễ.

MediaTypeFilter

Bộ lọc này xác định loại mục nội dung đa phương tiệ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 được đưa vào. Bạn chỉ được điền sẵn một loại nội dung đa phương tiện vào trường này. 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 đưa vào.
VIDEO Tất cả các mục nội dung đa phương tiện được coi là video. Danh sách này cũng bao gồm các phim 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 đa phương tiện được coi là ảnh. Điều này bao gồm .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 động trên iOS, ảnh chuyển động của 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 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 mục nội dung đa phương tiện. Các mục trong nhóm được đánh dấu bằng 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 Các mục nội dung đa phương tiện mà người dùng đã đánh dấu là mục yêu thích trong ứng dụng Google Photos.