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

ตัวกรอง

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

การแสดง 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 รูปภาพ
PHOTO รายการสื่อทั้งหมดที่ถือว่าเป็นรูปภาพ ซึ่งรวมถึง .bmp, .gif, .ico, .jpg (และการสะกดอื่นๆ), .tiff, .webp และประเภทรูปภาพพิเศษ เช่น iOS Live Photos, รูปภาพเคลื่อนไหวบน Android, พาโนรามา, Photo sphere

FeatureFilter

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

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

enum (Feature)

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

ฟีเจอร์

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

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