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

หากตั้งค่า ผลลัพธ์จะรวมรายการสื่อที่ผู้ใช้ได้เก็บถาวรไว้ ค่าเริ่มต้นคือ "เท็จ" (ไม่รวมรายการสื่อที่เก็บถาวร)
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 OR c2 หรือ c3)

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

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

ตัวอย่างก่อนหน้านี้จะได้รับรายการสื่อที่มี (c1 OR c2) AND NOT (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 และรูปภาพประเภทพิเศษ เช่น รูปภาพสดของ iOS, รูปภาพเคลื่อนไหวของ Android, พาโนรามา, ฟีเจอร์ภาพ 360 องศา

FeatureFilter

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

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

enum (Feature)

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

ฟีเจอร์

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

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