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

ฟิลเตอร์

ตัวกรองที่สามารถใช้กับการค้นหารายการสื่อ หากมีการระบุตัวเลือกตัวกรองหลายรายการ ระบบจะถือว่าตัวเลือกเหล่านั้นเป็นแบบ 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.appGeneratedata

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

ตัวกรองนี้กำหนดวันที่หรือช่วงวันที่ที่อนุญาตสำหรับสื่อที่แสดงผล คุณจะเลือกชุดวันที่ที่เฉพาะเจาะจงและช่วงวันที่ที่ต้องการได้ รายการสื่อที่อัปโหลดโดยไม่มีข้อมูลเมตาที่ระบุวันที่ที่บันทึกรายการสื่อจะไม่แสดงผลในการค้นหาโดยใช้ตัวกรองวันที่ เวลาอัปโหลดของเซิร์ฟเวอร์ 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 หากระบุปี/เดือนที่วันไม่มีนัยสำคัญ

ช่วงวันที่

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

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

object (Date)

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

endDate

object (Date)

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

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

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

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

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

ตัวกรองเนื้อหา excludedContentCategories: [c1, c2, c3] จะไม่ได้รับรายการสื่อที่มี (c1 OR c2 OR 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 รายการต่อคำขอ

ประเภทเนื้อหา

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

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 รายการสื่อที่เกิดขึ้นในวันหยุด

ตัวกรองประเภทสื่อ

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

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