Method: mediaItems.search

ค้นหารายการสื่อในคลังภาพ Google Photos ของผู้ใช้ หากไม่ได้ตั้งค่าตัวกรอง ระบบจะแสดงรายการสื่อทั้งหมดในคลังภาพของผู้ใช้ หากตั้งค่าอัลบั้มไว้ ระบบจะแสดงรายการสื่อทั้งหมดในอัลบั้มที่ระบุ หากระบุตัวกรอง ระบบจะแสดงรายการสื่อที่ตรงกับตัวกรองจากคลังภาพของผู้ใช้ หากคุณกำหนดทั้งอัลบั้มและตัวกรอง คำขอจะเกิดข้อผิดพลาด

คำขอ HTTP

POST https://photoslibrary.googleapis.com/v1/mediaItems:search

URL ใช้ไวยากรณ์การแปลง gRPC

เนื้อหาของคำขอ

เนื้อหาของคำขอมีข้อมูลที่มีโครงสร้างต่อไปนี้

การแสดง JSON 
{
  "albumId": string,
  "pageSize": integer,
  "pageToken": string,
  "filters": {
    object (Filters)
  },
  "orderBy": string
}
ช่อง
albumId

string

ตัวระบุของอัลบั้ม หากมีการป้อนข้อมูล ระบบจะแสดงรายการสื่อทั้งหมดในอัลบั้มที่ระบุ ตั้งค่าร่วมกับตัวกรองไม่ได้
pageSize

integer

จำนวนรายการสื่อสูงสุดที่จะแสดงในการตอบกลับ ระบบอาจแสดงรายการสื่อน้อยกว่าจำนวนที่ระบุ ค่าเริ่มต้นคือ pageSize คือ 25 ค่าสูงสุดคือ 100
pageToken

string

โทเค็นการดําเนินการต่อเพื่อรับหน้าถัดไปของผลการค้นหา การเพิ่มเงื่อนไขนี้ลงในคําขอจะแสดงแถวหลัง pageToken pageToken ควรเป็นค่าที่แสดงในพารามิเตอร์ nextPageToken ในการตอบกลับคําขอ searchMediaItems
filters

object (Filters)

ตัวกรองที่จะใช้กับคําขอ ตั้งค่าร่วมกับ albumId ไม่ได้
orderBy

string

ช่องที่ไม่บังคับสำหรับระบุลําดับการจัดเรียงของผลการค้นหา ช่อง orderBy จะใช้ได้เมื่อใช้ dateFilter เท่านั้น หากไม่ได้ระบุช่องนี้ ผลการค้นหาจะแสดงรายการใหม่สุดก่อน ตามด้วยรายการเก่าสุดตาม creationTime การให้ MediaMetadata.creation_time จะแสดงผลการค้นหาในลำดับที่ตรงกันข้ามกัน โดยเริ่มจากเก่าสุดก่อนใหม่สุดหลัง หากต้องการแสดงผลการค้นหาใหม่สุดก่อนแล้วตามด้วยรายการเก่าสุด ให้ใส่อาร์กิวเมนต์ desc ดังนี้ MediaMetadata.creation_time desc

ตัวกรองเพิ่มเติมที่ใช้ได้กับพารามิเตอร์นี้มีเพียง includeArchivedMedia และ excludeNonAppCreatedData ไม่รองรับตัวกรองอื่นๆ

เนื้อหาการตอบกลับ

รายการรายการสื่อที่ตรงกับพารามิเตอร์การค้นหา

หากทำสำเร็จ เนื้อหาการตอบกลับจะมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้

การแสดง JSON 
{
  "mediaItems": [
    {
      object (MediaItem)
    }
  ],
  "nextPageToken": string
}
ช่อง
mediaItems[]

object (MediaItem)

เอาต์พุตเท่านั้น รายการสื่อที่ตรงกับพารามิเตอร์การค้นหา
nextPageToken

string

เอาต์พุตเท่านั้น ใช้โทเค็นนี้เพื่อรับรายการสื่อชุดถัดไป สถานะนี้เป็นตัวบ่งชี้เดียวที่เชื่อถือได้ว่ามีรายการสื่อเพิ่มเติมในคำขอถัดไป

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth ต่อไปนี้

  • 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

ตัวกรอง

ตัวกรองที่ใช้กับการค้นหารายการสื่อได้ หากระบุตัวเลือกตัวกรองไว้หลายรายการ จะถือว่าเป็น "และ" เองร่วมกัน

การแสดง JSON 
{
  "dateFilter": {
    object (DateFilter)
  },
  "contentFilter": {
    object (ContentFilter)
  },
  "mediaTypeFilter": {
    object (MediaTypeFilter)
  },
  "featureFilter": {
    object (FeatureFilter)
  },
  "includeArchivedMedia": boolean,
  "excludeNonAppCreatedData": boolean
}
ช่อง
dateFilter

object (DateFilter)

กรองรายการสื่อตามวันที่สร้าง
contentFilter

object (ContentFilter)

กรองรายการสื่อตามเนื้อหา
mediaTypeFilter

object (MediaTypeFilter)

กรองรายการสื่อตามประเภทสื่อ
featureFilter

object (FeatureFilter)

กรองรายการสื่อตามฟีเจอร์
includeArchivedMedia

boolean

หากตั้งค่า ผลลัพธ์จะรวมรายการสื่อที่ผู้ใช้ได้เก็บถาวรไว้ ค่าเริ่มต้นคือ False (ไม่รวมรายการสื่อที่เก็บถาวร)
excludeNonAppCreatedData

boolean

หากตั้งค่าไว้ ผลลัพธ์จะไม่รวมรายการสื่อที่ไม่ได้สร้างโดยแอปนี้ ค่าเริ่มต้นคือเท็จ (ระบบจะแสดงรายการสื่อทั้งหมด) ระบบจะไม่สนใจช่องนี้หากใช้ขอบเขต photoslibrary.readonly.appcreateddata

DateFilter

ตัวกรองนี้จะกำหนดวันที่หรือช่วงวันที่ที่อนุญาตสำหรับสื่อที่แสดงผล คุณสามารถเลือกชุดวันที่ที่เจาะจงและชุดช่วงวันที่ได้ ระบบจะไม่แสดงรายการสื่อที่อัปโหลดโดยไม่มีข้อมูลเมตาที่ระบุวันที่บันทึกรายการสื่อในการค้นหาโดยใช้ตัวกรองวันที่ ในกรณีนี้ ระบบจะไม่ใช้เวลาอัปโหลดของเซิร์ฟเวอร์ Google Photos เป็นค่าสำรอง

การแสดง JSON 
{
  "dates": [
    {
      object (Date)
    }
  ],
  "ranges": [
    {
      object (DateRange)
    }
  ]
}
ช่อง
dates[]

object (Date)

รายการวันที่ที่ตรงกับวันที่สร้างรายการสื่อ ระบุวันที่ได้สูงสุด 5 วันต่อคำขอ
ranges[]

object (DateRange)

รายการช่วงวันที่ที่ตรงกับวันที่สร้างรายการสื่อ คุณรวมช่วงวันที่ได้สูงสุด 5 ช่วงต่อคำขอ

วันที่

แสดงวันที่ในปฏิทินทั้งวัน ตั้งค่า day เป็น 0 เมื่อเฉพาะเดือนและปีที่มีนัยสำคัญ เช่น ทุกเดือนธันวาคม 2018 ตั้งค่า day และ month เป็น 0 หากมีเฉพาะปีเท่านั้นที่มีนัยสำคัญ เช่น ทั้งปี 2018 ตั้งค่า year เป็น 0 เมื่อเฉพาะวันและเดือนเท่านั้นที่สำคัญ เช่น วันครบรอบหรือวันเกิด

ไม่รองรับ: การตั้งค่าทุกค่าเป็น 0, การตั้งค่าเฉพาะ month เป็น 0 หรือการตั้งค่าทั้ง day และ year เป็น 0 พร้อมกัน

การแสดง JSON 
{
  "year": integer,
  "month": integer,
  "day": integer
}
ช่อง
year

integer

ปีของวันที่ ต้องอยู่ในช่วง 1 ถึง 9999 หรือ 0 เพื่อระบุวันที่โดยไม่มีปี
month

integer

เดือนของปี ต้องมีค่าระหว่าง 1 ถึง 12 หรือ 0 เพื่อระบุปีโดยไม่มีเดือนและวัน
day

integer

วันของเดือน ต้องมีค่าระหว่าง 1 ถึง 31 และใช้ได้กับปีและเดือน หรือ 0 หากระบุปี/เดือนที่วันไม่มีนัยสำคัญ

DateRange

กำหนดช่วงวันที่ วันที่ทั้ง 2 วันต้องเป็นรูปแบบเดียวกัน ดูข้อมูลเพิ่มเติมได้ที่ Date

การแสดง JSON 
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
ช่อง
startDate

object (Date)

วันที่เริ่มต้น (รวมอยู่ในช่วง) ในรูปแบบใดรูปแบบหนึ่งที่อธิบายไว้
endDate

object (Date)

วันที่สิ้นสุด (รวมอยู่ในช่วง) โดยต้องระบุในรูปแบบเดียวกับวันที่เริ่มต้น

ContentFilter

ตัวกรองนี้ช่วยให้คุณแสดงรายการสื่อตามประเภทเนื้อหาได้

คุณสามารถระบุรายการหมวดหมู่ที่จะรวมและ/หรือรายการหมวดหมู่ที่จะยกเว้นได้ ในแต่ละรายการ หมวดหมู่ต่างๆ จะรวมด้วยคำสั่ง OR

ตัวกรองเนื้อหา includedContentCategories: [c1, c2, c3] จะได้รับรายการสื่อที่มี (c1 หรือ c2 หรือ c3)

ตัวกรองเนื้อหา excludedContentCategories: [c1, c2, c3] จะไม่ได้รับรายการสื่อที่มี (c1 OR c2 หรือ c3)

นอกจากนี้ คุณยังรวมบางหมวดหมู่ไว้ในขณะที่ยกเว้นบางหมวดหมู่ได้ด้วย ดังตัวอย่างต่อไปนี้ includedContentCategories: [c1, c2], excludedContentCategories: [c3, c4]

ตัวอย่างก่อนหน้านี้จะได้รับรายการสื่อที่มี (c1 หรือ c2) และไม่ใช่ (c3 หรือ c4) หมวดหมู่ที่ปรากฏใน includedContentategories ต้องไม่ปรากฏใน excludedContentCategories

การแสดง JSON 
{
  "includedContentCategories": [
    enum (ContentCategory)
  ],
  "excludedContentCategories": [
    enum (ContentCategory)
  ]
}
ช่อง
includedContentCategories[]

enum (ContentCategory)

ชุดหมวดหมู่ที่จะรวมอยู่ในผลการค้นหารายการสื่อ รายการในชุดเป็น OR โดยจะมี includedContentCategories สูงสุด 10 รายการต่อคำขอ
excludedContentCategories[]

enum (ContentCategory)

ชุดหมวดหมู่ที่จะไม่รวมอยู่ในผลการค้นหารายการสื่อ รายการในชุดเป็น OR โดยจะมี excludedContentCategories สูงสุด 10 รายการต่อคำขอ

ContentCategory

ซึ่งเป็นชุดหมวดหมู่เนื้อหาที่กําหนดไว้ล่วงหน้าซึ่งคุณใช้กรองได้

Enum
NONE หมวดหมู่เนื้อหาเริ่มต้น ระบบจะไม่สนใจหมวดหมู่นี้เมื่อมีการใช้หมวดหมู่อื่นในตัวกรอง
LANDSCAPES รายการสื่อที่มีรูปภาพแนวนอน
RECEIPTS รายการสื่อที่มีใบเสร็จ
CITYSCAPES รายการสื่อที่มีทิวทัศน์เมือง
LANDMARKS รายการสื่อที่มีจุดสังเกต
SELFIES รายการสื่อที่เป็นรูปเซลฟี
PEOPLE รายการสื่อที่มีผู้คน
PETS รายการสื่อที่มีสัตว์เลี้ยง
WEDDINGS รายการสื่อจากงานแต่งงาน
BIRTHDAYS รายการสื่อจากวันเกิด
DOCUMENTS รายการสื่อที่มีเอกสาร
TRAVEL รายการสื่อที่ถ่ายระหว่างเดินทาง
ANIMALS รายการสื่อที่มีสัตว์
FOOD รายการสื่อที่มีอาหาร
SPORT รายการสื่อจากการแข่งขันกีฬา
NIGHT รายการสื่อที่ถ่ายในเวลากลางคืน
PERFORMANCES รายการสื่อจากการแสดง
WHITEBOARDS รายการสื่อที่มีไวท์บอร์ด
SCREENSHOTS รายการสื่อที่เป็นภาพหน้าจอ
UTILITY รายการสื่อที่ถือว่ามีประโยชน์ ซึ่งรวมถึงแต่ไม่จำกัดเพียงเอกสาร ภาพหน้าจอ ไวท์บอร์ด เป็นต้น
ARTS รายการสื่อที่มีอาร์ตเวิร์ก
CRAFTS รายการสื่อที่มีงานฝีมือ
FASHION รายการสื่อที่เกี่ยวข้องกับแฟชั่น
HOUSES รายการสื่อที่มีบ้าน
GARDENS รายการสื่อที่มีสวน
FLOWERS รายการสื่อที่มีดอกไม้
HOLIDAYS รายการสื่อที่ถ่ายในวันหยุด

MediaTypeFilter

ตัวกรองนี้กำหนดประเภทของรายการสื่อที่จะแสดง เช่น วิดีโอหรือรูปภาพ รองรับสื่อได้เพียงประเภทเดียวเท่านั้น

การแสดง JSON 
{
  "mediaTypes": [
    enum (MediaType)
  ]
}
ช่อง
mediaTypes[]

enum (MediaType)

ประเภทของรายการสื่อที่จะรวม ช่องนี้ควรป้อนข้อมูลสื่อเพียงประเภทเดียว หากคุณระบุสื่อหลายประเภทจะทำให้เกิดข้อผิดพลาด

MediaType

ชุดประเภทสื่อที่ค้นหาได้

Enum
ALL_MEDIA ระบบจะถือว่าไม่ได้ใช้ตัวกรอง รวมสื่อทุกประเภท
VIDEO รายการสื่อทั้งหมดที่ถือว่าเป็นวิดีโอ ซึ่งรวมถึงภาพยนตร์ที่ผู้ใช้สร้างขึ้นโดยใช้แอป Google Photos ด้วย
PHOTO รายการสื่อทั้งหมดที่ถือว่าเป็นรูปภาพ ซึ่งรวมถึง .bmp, .gif, .ico, .jpg (และรูปแบบอื่นๆ), .tiff, .webp และรูปภาพประเภทพิเศษ เช่น Live Photos ของ iOS, รูปภาพเคลื่อนไหวของ Android, พาโนรามา, ฟีเจอร์ภาพ 360 องศา

FeatureFilter

ตัวกรองนี้จะระบุฟีเจอร์ที่รายการสื่อควรจะมี

การแสดง JSON 
{
  "includedFeatures": [
    enum (Feature)
  ]
}
ช่อง
includedFeatures[]

enum (Feature)

ชุดฟีเจอร์ที่จะรวมไว้ในผลการค้นหารายการสื่อ รายการในชุดมีการใช้ OR และอาจตรงกับรายการใดรายการหนึ่งที่ระบุ

ฟีเจอร์

ชุดฟีเจอร์ที่คุณกรองได้

Enum
NONE ระบบจะถือว่าไม่ได้ใช้ตัวกรอง ฟีเจอร์ทั้งหมดรวมอยู่ด้วย
FAVORITES รายการสื่อที่ผู้ใช้ทำเครื่องหมายเป็นรายการโปรดในแอป Google Photos