Method: mediaItems.search

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

คำขอ HTTP

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

URL ใช้ไวยากรณ์ gRPC Transcoding

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

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

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

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

excludeNonAppCreatedData

boolean

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

ตัวกรองวันที่

ตัวกรองนี้กําหนดวันที่หรือช่วงวันที่ที่อนุญาตสําหรับสื่อที่ส่งคืน คุณเลือกชุดวันที่ที่เจาะจงและชุดช่วงวันที่ได้

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

object (Date)

รายการวันที่ที่ตรงกับรายการสื่อ&#39 วันที่สร้าง โดยระบุวันที่ได้สูงสุด 5 คําขอต่อคําขอ

ranges[]

object (DateRange)

รายการช่วงวันที่ที่ตรงกับรายการสื่อ&#39 วันที่สร้าง ระบุช่วงวันที่ได้สูงสุด 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 หากระบุปี/เดือนที่ไม่มีนัยสําคัญสําหรับวันนั้นๆ

ช่วงวันที่

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

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

object (Date)

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

endDate

object (Date)

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

ตัวกรองเนื้อหา

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

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

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

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

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

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

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

enum (ContentCategory)

ชุดของหมวดหมู่ที่จะรวมอยู่ในผลการค้นหารายการสื่อ รายการในชุดคือ OR สูงสุด 10 includedContentCategories รายการต่อหนึ่งคําขอ

excludedContentCategories[]

enum (ContentCategory)

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

หมวดหมู่เนื้อหา

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

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 รายการสื่อที่ถ่ายในช่วงวันหยุด

ตัวกรอง MediaType

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

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

enum (MediaType)

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

ประเภทสื่อ

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

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

ตัวกรองฟีเจอร์

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

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

enum (Feature)

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

ฟีเจอร์

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

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