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

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

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

ต้องใช้ขอบเขต OAuth อย่างใดอย่างหนึ่งต่อไปนี้

  • https://www.googleapis.com/auth/photoslibrary
  • https://www.googleapis.com/auth/photoslibrary.readonly
  • https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata

ฟิลเตอร์

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

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

กำหนดช่วงวันที่ วันที่ทั้งสองต้องอยู่ในรูปแบบเดียวกัน ดูข้อมูลเพิ่มเติมได้ที่ 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 หรือ 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, พาโนรามา, Photosphere

FeatureFilter

ตัวกรองนี้กำหนดฟีเจอร์ที่รายการสื่อควรมี

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

enum (Feature)

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

ฟีเจอร์

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

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