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

ตัวกรองเพิ่มเติมเพียง 2 รายการที่ใช้ได้กับพารามิเตอร์นี้ ได้แก่ 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

ตัวกรอง

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

การแสดง 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 OR 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