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

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