Search: list

ส่งกลับคอลเล็กชันของผลการค้นหาที่ตรงกับพารามิเตอร์การค้นหาที่ระบุในคําขอ API โดยค่าเริ่มต้น ชุดผลการค้นหาจะระบุทรัพยากร video, channel และ playlist ที่ตรงกัน แต่คุณสามารถกําหนดค่าการค้นหาให้ดึงเฉพาะประเภททรัพยากรที่เฉพาะเจาะจงได้ด้วย

ผลกระทบต่อโควต้า: การเรียกไปยังวิธีการนี้มีโควต้า 100 หน่วย

กรณีการใช้งานทั่วไป

ส่งคำขอ

คำขอ HTTP

GET https://www.googleapis.com/youtube/v3/search

พารามิเตอร์

ตารางต่อไปนี้จะแสดงพารามิเตอร์ที่คําค้นหานี้รองรับ พารามิเตอร์ทั้งหมดที่แสดงคือพารามิเตอร์การค้นหา

พารามิเตอร์
พารามิเตอร์ที่จําเป็น
part string
พารามิเตอร์ part ระบุรายการที่คั่นด้วยเครื่องหมายจุลภาคของพร็อพเพอร์ตี้ทรัพยากร search อย่างน้อย 1 รายการที่จะได้รับการตอบกลับจาก API ตั้งค่าพารามิเตอร์เป็น snippet
ตัวกรอง (ระบุ 0 หรือ 1 ของพารามิเตอร์ต่อไปนี้)
forContentOwner boolean
พารามิเตอร์นี้ใช้ได้เฉพาะในคําขอที่ได้รับอนุญาตที่เหมาะสมเท่านั้น และมีไว้สําหรับพาร์ทเนอร์เนื้อหาของ YouTube เท่านั้น

พารามิเตอร์ forContentOwner จะจํากัดการค้นหาให้ดึงเฉพาะวิดีโอที่เป็นของเจ้าของเนื้อหาที่ระบุโดยพารามิเตอร์ onBehalfOfContentOwner เท่านั้น หากตั้งค่า forContentOwner เป็น "จริง" คําขอต้องเป็นไปตามข้อกําหนดเหล่านี้ด้วย
  • ต้องระบุพารามิเตอร์ onBehalfOfContentOwner
  • ผู้ใช้ที่ให้สิทธิ์ตามคําขอต้องใช้บัญชีที่ลิงก์กับเจ้าของเนื้อหาที่ระบุ
  • ค่าพารามิเตอร์ type ต้องได้รับการกําหนดค่าเป็น video
  • ไม่สามารถตั้งค่าพารามิเตอร์อื่นๆ ต่อไปนี้ videoDefinition, videoDimension, videoDuration, videoEmbeddable, videoLicense, videoPaidProductPlacement, videoSyndicated, videoType
forDeveloper boolean
พารามิเตอร์นี้ใช้ได้เฉพาะในคําขอที่ได้รับอนุญาตเท่านั้น พารามิเตอร์ forDeveloper จํากัดการค้นหาให้ดึงเฉพาะวิดีโอที่อัปโหลดผ่านแอปพลิเคชันหรือเว็บไซต์ของนักพัฒนาซอฟต์แวร์เท่านั้น เซิร์ฟเวอร์ API ใช้ข้อมูลเข้าสู่ระบบของการให้สิทธิ์เพื่อระบุนักพัฒนาซอฟต์แวร์ พารามิเตอร์ forDeveloper สามารถใช้ร่วมกับพารามิเตอร์การค้นหาที่ไม่บังคับ เช่น พารามิเตอร์ q

ฟีเจอร์นี้จะอัปโหลดแต่ละแท็กโดยอัตโนมัติด้วยหมายเลขโปรเจ็กต์ที่เชื่อมโยงกับแอปพลิเคชันของนักพัฒนาซอฟต์แวร์ในGoogle Developers Console

เมื่อคําขอการค้นหาตั้งค่าพารามิเตอร์ forDeveloper เป็น true ในภายหลัง เซิร์ฟเวอร์ API จะใช้ข้อมูลเข้าสู่ระบบการให้สิทธิ์ของคําขอเพื่อระบุนักพัฒนาซอฟต์แวร์ ดังนั้น นักพัฒนาซอฟต์แวร์จึงสามารถจํากัดผลลัพธ์ของวิดีโอที่อัปโหลดผ่านแอปหรือเว็บไซต์ของนักพัฒนาซอฟต์แวร์ของตน แต่ไม่สามารถจํากัดให้อัปโหลดผ่านแอปหรือเว็บไซต์อื่นๆ ได้
forMine boolean
พารามิเตอร์นี้ใช้ได้เฉพาะในคําขอที่ได้รับอนุญาตเท่านั้น พารามิเตอร์ forMine จํากัดการค้นหาให้ดึงเฉพาะวิดีโอที่เป็นของผู้ใช้ที่ตรวจสอบสิทธิ์แล้วเท่านั้น หากคุณตั้งค่าพารามิเตอร์นี้เป็น true ค่าของพารามิเตอร์ type จะต้องตั้งค่าเป็น video ด้วย นอกจากนี้ ยังตั้งค่าพารามิเตอร์อื่นๆ ต่อไปนี้ในคําขอเดียวกันไม่ได้: videoDefinition, videoDimension, videoDuration, videoEmbeddable, videoLicense, videoPaidProductPlacement, videoSyndicated, videoType
พารามิเตอร์ที่ไม่บังคับ
channelId string
พารามิเตอร์ channelId ระบุว่าการตอบกลับ API ควรมีเฉพาะทรัพยากรที่ช่องทางสร้างขึ้นเท่านั้น

หมายเหตุ: ผลการค้นหาจะถูกจํากัดไว้ที่วิดีโอสูงสุด 500 รายการ หากคําขอของคุณระบุค่าพารามิเตอร์ channelId และตั้งค่าพารามิเตอร์ type เป็น video แต่ไม่ได้ตั้งค่าตัวกรอง forContentOwner, forDeveloper หรือ forMine รายการใดรายการหนึ่ง
channelType string
พารามิเตอร์ channelType ให้คุณจํากัดการค้นหาสําหรับช่องบางประเภทได้

ค่าที่ยอมรับได้มีดังนี้
  • any – ส่งคืนช่องทั้งหมด
  • show – เรียกดูเฉพาะรายการ
eventType string
พารามิเตอร์ eventType จํากัดการค้นหาไว้สําหรับเหตุการณ์การออกอากาศ หากคุณระบุค่าสําหรับพารามิเตอร์นี้ คุณต้องตั้งค่าของพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้ ได้แก่
  • completed – รวมเฉพาะการออกอากาศที่สมบูรณ์
  • live – รวมเฉพาะการออกอากาศที่ใช้งานอยู่
  • upcoming – รวมเฉพาะการประกาศที่กําลังจะมาถึง
location string
พารามิเตอร์ location เมื่อใช้ร่วมกับพารามิเตอร์ locationRadius จะกําหนดพื้นที่ทางภูมิศาสตร์แบบวงกลมและจํากัดการค้นหาเฉพาะวิดีโอที่ระบุสถานที่ตั้งทางภูมิศาสตร์ที่อยู่ในพื้นที่นั้นๆ ในข้อมูลเมตาเท่านั้น ค่าพารามิเตอร์คือสตริงที่ระบุพิกัดละติจูด/ลองจิจูด (37.42307,-122.08427)

  • ค่าพารามิเตอร์ location จะระบุจุดศูนย์กลางของพื้นที่นั้น
  • พารามิเตอร์ locationRadius ระบุระยะทางสูงสุดที่ตําแหน่งที่เกี่ยวข้องกับวิดีโอสามารถเป็นได้จากจุดนั้น เพื่อที่วิดีโอจะยังคงปรากฏในผลการค้นหา
API จะแสดงผลข้อผิดพลาด หากคําขอของคุณระบุค่าสําหรับพารามิเตอร์ location แต่ไม่ได้ระบุค่าสําหรับพารามิเตอร์ locationRadius ด้วย

หมายเหตุ: หากระบุค่าสําหรับพารามิเตอร์นี้ คุณต้องตั้งค่าค่าพารามิเตอร์ type เป็น video ด้วย
locationRadius string
พารามิเตอร์ locationRadius ร่วมกับพารามิเตอร์ location จะกําหนดพื้นที่ทางภูมิศาสตร์แบบวงกลม

ค่าพารามิเตอร์ต้องเป็นจํานวนทศนิยมตามด้วยหน่วยวัด หน่วยวัดที่ใช้ได้คือ m, km, ft และ mi เช่น ค่าพารามิเตอร์ที่ถูกต้องรวมถึง 1500m, 5km, 10000ft และ 0.75mi API ไม่รองรับค่าพารามิเตอร์ locationRadius ที่เกิน 1000 กิโลเมตร

หมายเหตุ: ดูคําจํากัดความของพารามิเตอร์ location สําหรับข้อมูลเพิ่มเติม
maxResults unsigned integer
พารามิเตอร์ maxResults จะระบุจํานวนสูงสุดของรายการที่ควรแสดงในชุดผลลัพธ์ ค่าที่ยอมรับได้คือ 0 ถึง 50 ค่าเริ่มต้นคือ 5
onBehalfOfContentOwner string
พารามิเตอร์นี้ใช้ได้เฉพาะในคําขอที่ได้รับอนุญาตเท่านั้น หมายเหตุ: พารามิเตอร์นี้มีไว้สําหรับพาร์ทเนอร์เนื้อหาของ YouTube เท่านั้น

พารามิเตอร์ onBehalfOfContentOwner ระบุว่าข้อมูลรับรองการให้สิทธิ์ของคําขอระบุผู้ใช้ CMS ของ YouTube ที่ดําเนินการในนามของเจ้าของเนื้อหาที่ระบุในค่าพารามิเตอร์ พารามิเตอร์นี้มีไว้สําหรับพาร์ทเนอร์เนื้อหาของ YouTube ที่เป็นเจ้าของและจัดการช่อง YouTube ต่างๆ มากมาย ช่วยให้เจ้าของเนื้อหาตรวจสอบสิทธิ์ได้เพียงครั้งเดียวและเข้าถึงข้อมูลวิดีโอและช่องทั้งหมดได้ โดยไม่ต้องระบุข้อมูลเข้าสู่ระบบของแต่ละช่อง บัญชี CMS ที่ผู้ใช้ตรวจสอบสิทธิ์ด้วยจะต้องลิงก์กับเจ้าของเนื้อหาใน YouTube ที่ระบุ
order string
พารามิเตอร์ order ระบุวิธีที่จะใช้เพื่อเรียงลําดับทรัพยากรในการตอบกลับ API ค่าเริ่มต้นคือ relevance

ค่าที่ยอมรับได้มีดังนี้
  • date – ระบบจะจัดเรียงทรัพยากรตามลําดับเวลาย้อนกลับตามวันที่ที่สร้าง
  • rating – จัดเรียงทรัพยากรจากคะแนนสูงสุดไปต่ําสุด
  • relevance – จัดเรียงทรัพยากรตามความเกี่ยวข้องกับคําค้นหา นี่คือค่าเริ่มต้นของพารามิเตอร์นี้
  • title – จัดเรียงทรัพยากรตามลําดับตัวอักษรของชื่อ
  • videoCount – ระบบจะจัดเรียงช่องจากมากไปหาน้อยตามจํานวนวิดีโอที่อัปโหลด
  • viewCount – จัดเรียงทรัพยากรจากยอดดูสูงสุดไปต่ําสุด สําหรับการถ่ายทอดสด วิดีโอต่างๆ จะจัดเรียงตามจํานวนผู้ชมพร้อมกันขณะที่กําลังถ่ายทอดสด
pageToken string
พารามิเตอร์ pageToken จะระบุหน้าที่เฉพาะเจาะจงในชุดผลลัพธ์ที่ควรจะแสดง ในการตอบกลับ API พร็อพเพอร์ตี้ nextPageToken และ prevPageToken จะระบุหน้าเว็บอื่นๆ ที่สามารถดึงข้อมูลได้
publishedAfter datetime
พารามิเตอร์ publishedAfter ระบุว่าการตอบกลับ API ควรมีเฉพาะทรัพยากรที่สร้างขึ้นในเวลาหรือหลังจากเวลาที่ระบุไว้เท่านั้น ค่านี้จะเป็นค่าวันที่และเวลาในรูปแบบ RFC 3339 (1970-01-01T00:00:00Z)
publishedBefore datetime
พารามิเตอร์ publishedBefore ระบุว่าการตอบกลับ API ควรมีเฉพาะทรัพยากรที่สร้างขึ้นก่อนหรือในเวลาที่กําหนด ค่านี้จะเป็นค่าวันที่และเวลาในรูปแบบ RFC 3339 (1970-01-01T00:00:00Z)
q string
พารามิเตอร์ q ระบุข้อความค้นหาที่ต้องการค้นหา

คําขอของคุณยังสามารถใช้โอเปอเรเตอร์บูลีน NOT (-) และ OR (|) เพื่อยกเว้นวิดีโอ หรือค้นหาวิดีโอที่เชื่อมโยงกับข้อความค้นหาข้อใดข้อหนึ่งต่อไปนี้ เช่น หากต้องการค้นหาวิดีโอที่ตรงกับ "การพายเรือ" หรือ "การแล่นเรือใบ" ให้ตั้งค่าค่าพารามิเตอร์ q เป็น boating|sailing ในทํานองเดียวกัน หากต้องการค้นหาวิดีโอที่ตรงกับ "พายเรือ" หรือ "แล่นเรือใบ" แต่ไม่ใช่ "ตกปลา" ให้ตั้งค่าค่าพารามิเตอร์ q เป็น boating|sailing -fishing โปรดทราบว่าอักขระไปป์ต้องเป็นอักขระหลีกกับ URL เมื่อส่งไปในคําขอ API ค่า Escape สําหรับ URL สําหรับอักขระไปป์คือ %7C
regionCode string
พารามิเตอร์ regionCode จะสั่งให้ API แสดงผลการค้นหาของวิดีโอที่ดูได้ในประเทศที่ระบุ ค่าพารามิเตอร์คือรหัสประเทศตามมาตรฐาน ISO 3166-1 alpha-2
relevanceLanguage string
พารามิเตอร์ relevanceLanguage จะสั่งให้ API แสดงผลการค้นหาที่เกี่ยวข้องกับภาษาที่ระบุมากที่สุด ค่าพารามิเตอร์มักจะเป็นรหัสภาษา ISO 639-1 สองตัวอักษร แต่คุณควรใช้ค่า zh-Hans สําหรับจีนตัวย่อและ zh-Hant สําหรับจีนตัวเต็ม โปรดทราบว่าผลการค้นหาในภาษาอื่นจะยังคงแสดงผลอยู่หากมีความเกี่ยวข้องอย่างมากกับข้อความค้นหา
safeSearch string
พารามิเตอร์ safeSearch ระบุว่าผลการค้นหาควรมีเนื้อหาที่ถูกจํากัด รวมถึงเนื้อหามาตรฐาน

ค่าที่ยอมรับได้มีดังนี้
  • moderate – YouTube จะกรองเนื้อหาบางส่วนออกจากผลการค้นหา และอย่างน้อยก็จะกรองเนื้อหาที่ถูกจํากัดในพื้นที่ของคุณ ระบบอาจนําผลการค้นหาออกจากผลการค้นหาหรือลดระดับในผลการค้นหาตามเนื้อหา นี่คือค่าพารามิเตอร์เริ่มต้น
  • none – YouTube จะไม่กรองชุดผลการค้นหา
  • strict – YouTube จะพยายามยกเว้นเนื้อหาที่ถูกจํากัดทั้งหมดจากชุดผลการค้นหา ระบบอาจนําผลการค้นหาออกจากผลการค้นหาหรือลดระดับในผลการค้นหาตามเนื้อหา
topicId string
พารามิเตอร์ topicId ระบุว่าการตอบกลับ API ควรมีเฉพาะทรัพยากรที่เชื่อมโยงกับหัวข้อที่ระบุ ค่าจะระบุรหัสหัวข้อ Freebase

สําคัญ: เนื่องจากการเลิกใช้งาน Freebase และ API ของ Freebase พารามิเตอร์ topicId จึงเริ่มทํางานแตกต่างกันตั้งแต่วันที่ 27 กุมภาพันธ์ 2017 ในตอนนั้น YouTube เริ่มรองรับชุดรหัสหัวข้อที่คัดสรรมาจํานวนไม่มาก และคุณสามารถใช้รหัสชุดเล็กๆ นั้นเป็นค่าสําหรับพารามิเตอร์นี้เท่านั้น

type string
พารามิเตอร์ type จะจํากัดคําค้นหาให้ดึงทรัพยากรประเภทหนึ่งๆ เท่านั้น ค่าคือรายการประเภททรัพยากรที่คั่นด้วยจุลภาค ค่าเริ่มต้นคือ video,channel,playlist

ค่าที่ยอมรับได้มีดังนี้
  • channel
  • playlist
  • video
videoCaption string
พารามิเตอร์ videoCaption จะระบุว่า API ควรกรองผลการค้นหาวิดีโอไหม หากคุณระบุค่าสําหรับพารามิเตอร์นี้ คุณต้องตั้งค่าของพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้ ได้แก่
  • any – ไม่ต้องกรองผลการค้นหาตามคําอธิบายภาพ
  • closedCaption – รวมเฉพาะวิดีโอที่มีคําบรรยาย
  • none – รวมเฉพาะวิดีโอที่ไม่มีคําบรรยาย
videoCategoryId string
พารามิเตอร์ videoCategoryId จะกรองผลการค้นหาวิดีโอตามหมวดหมู่ หากคุณระบุค่าสําหรับพารามิเตอร์นี้ คุณต้องตั้งค่าของพารามิเตอร์ type เป็น video ด้วย
videoDefinition string
พารามิเตอร์ videoDefinition ให้คุณจํากัดการค้นหาให้รวมเฉพาะวิดีโอความละเอียดสูง (HD) หรือวิดีโอความละเอียดมาตรฐาน (SD) เท่านั้น วิดีโอ HD สามารถเล่นที่ความละเอียดอย่างน้อย 720p แต่ความละเอียดที่สูงขึ้น เช่น 1080p ก็อาจใช้ได้ หากคุณระบุค่าสําหรับพารามิเตอร์นี้ คุณต้องตั้งค่าของพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้ ได้แก่
  • any – แสดงวิดีโอทั้งหมดโดยไม่คํานึงถึงความละเอียด
  • high – เรียกดูเฉพาะวิดีโอ HD
  • standard – เรียกข้อมูลวิดีโอแบบความละเอียดมาตรฐานเท่านั้น
videoDimension string
พารามิเตอร์ videoDimension ช่วยให้คุณจํากัดการค้นหาเพื่อเรียกดูเฉพาะวิดีโอ 2 มิติหรือ 3 มิติ หากคุณระบุค่าสําหรับพารามิเตอร์นี้ คุณต้องตั้งค่าของพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้ ได้แก่
  • 2d – จํากัดผลการค้นหาให้ยกเว้นวิดีโอ 3 มิติ
  • 3d – จํากัดผลการค้นหาให้แสดงเฉพาะวิดีโอ 3 มิติเท่านั้น
  • any – แสดงทั้งวิดีโอ 3 มิติและที่ไม่ใช่ 3 มิติในผลลัพธ์ที่แสดง นี่คือค่าเริ่มต้น
videoDuration string
พารามิเตอร์ videoDuration จะกรองผลการค้นหาวิดีโอตามระยะเวลา หากคุณระบุค่าสําหรับพารามิเตอร์นี้ คุณต้องตั้งค่าของพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้ ได้แก่
  • any – อย่ากรองผลการค้นหาวิดีโอตามระยะเวลา นี่คือค่าเริ่มต้น
  • long – รวมเฉพาะวิดีโอที่มีความยาวเกิน 20 นาทีเท่านั้น
  • medium – รวมเฉพาะวิดีโอที่มีความยาวระหว่าง 4 ถึง 20 นาที (รวม)
  • short – รวมเฉพาะวิดีโอที่มีความยาวน้อยกว่า 4 นาที
videoEmbeddable string
พารามิเตอร์ videoEmbeddable ช่วยให้คุณจํากัดการค้นหาเฉพาะวิดีโอที่ฝังในหน้าเว็บได้ หากคุณระบุค่าสําหรับพารามิเตอร์นี้ คุณต้องตั้งค่าของพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้ ได้แก่
  • any – ส่งคืนวิดีโอทั้งหมด ฝังได้ หรือฝังไว้
  • true – เรียกดูเฉพาะวิดีโอที่ฝังได้
videoLicense string
พารามิเตอร์ videoLicense จะกรองผลการค้นหาให้รวมเฉพาะวิดีโอที่มีใบอนุญาตบางรายการเท่านั้น YouTube ให้ผู้อัปโหลดวิดีโอเลือกแนบใบอนุญาตครีเอทีฟคอมมอนส์หรือใบอนุญาต YouTube แบบมาตรฐานกับวิดีโอแต่ละรายการได้ หากคุณระบุค่าสําหรับพารามิเตอร์นี้ คุณต้องตั้งค่าของพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้ ได้แก่
  • any – แสดงวิดีโอทั้งหมด ไม่ว่าจะมีสัญญาอนุญาตแบบใด ซึ่งตรงกับพารามิเตอร์การค้นหา
  • creativeCommon - แสดงเฉพาะวิดีโอที่มีใบอนุญาตครีเอทีฟคอมมอนส์ ผู้ใช้จะนําวิดีโอที่มีใบอนุญาตนี้ไปใช้ซ้ําในวิดีโออื่นได้ ดูข้อมูลเพิ่มเติม
  • youtube – คืนวิดีโอที่มีใบอนุญาต YouTube แบบมาตรฐานเท่านั้น
videoPaidProductPlacement string
พารามิเตอร์ videoPaidProductPlacement จะกรองผลการค้นหาให้แสดงเฉพาะวิดีโอที่ครีเอเตอร์ระบุว่ามีการโปรโมตแบบเสียค่าใช้จ่ายเท่านั้น หากคุณระบุค่าสําหรับพารามิเตอร์นี้ คุณต้องตั้งค่าของพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้ ได้แก่
  • any - แสดงวิดีโอทั้งหมด ไม่ว่าจะมีการโปรโมตแบบเสียค่าใช้จ่ายหรือไม่ก็ตาม
  • true – รับเฉพาะวิดีโอที่มีการโปรโมตแบบเสียค่าใช้จ่าย
videoSyndicated string
พารามิเตอร์ videoSyndicated ให้คุณจํากัดการค้นหาเฉพาะวิดีโอที่เล่นภายนอก youtube.com ได้ หากคุณระบุค่าสําหรับพารามิเตอร์นี้ คุณต้องตั้งค่าของพารามิเตอร์เป็น video ด้วย

ค่าที่ยอมรับได้ ได้แก่
    type
  • any – ดูวิดีโอทั้งหมดที่เผยแพร่หรือไม่
  • true – เรียกดูเฉพาะวิดีโอที่เผยแพร่เท่านั้น
videoType string
พารามิเตอร์ videoType ช่วยให้คุณจํากัดการค้นหาวิดีโอบางประเภทได้ หากคุณระบุค่าสําหรับพารามิเตอร์นี้ คุณต้องตั้งค่าของพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้ ได้แก่
  • any – ส่งคืนวิดีโอทั้งหมด
  • episode – ดึงเฉพาะตอนของรายการ
  • movie – เรียกดูเฉพาะภาพยนตร์

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

ไม่ต้องระบุเนื้อความของคําขอเมื่อเรียกใช้เมธอดนี้

คำตอบ

หากทําสําเร็จ เมธอดนี้จะแสดงเนื้อหาการตอบกลับที่มีโครงสร้างดังต่อไปนี้

{
  "kind": "youtube#searchListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "regionCode": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    search Resource
  ]
}

พร็อพเพอร์ตี้

ตารางต่อไปนี้กําหนดพร็อพเพอร์ตี้ที่ปรากฏในผลการค้นหา

พร็อพเพอร์ตี้
kind string
ระบุประเภทของทรัพยากร API ค่าจะเป็น youtube#searchListResponse
etag etag
แท็ก Etag ของทรัพยากรนี้
nextPageToken string
โทเค็นที่จะใช้เป็นค่าของพารามิเตอร์ pageToken เพื่อดึงหน้าถัดไปในชุดผลลัพธ์ได้
prevPageToken string
โทเค็นที่จะใช้เป็นค่าของพารามิเตอร์ pageToken เพื่อดึงหน้าก่อนหน้าในชุดผลลัพธ์ได้
regionCode string
รหัสภูมิภาคที่ใช้สําหรับคําค้นหา ค่าพร็อพเพอร์ตี้คือรหัสประเทศ ISO 2 ตัวอักษรที่ระบุภูมิภาค เมธอด i18nRegions.list จะแสดงรายการภูมิภาคที่รองรับ ค่าเริ่มต้นคือ US หากระบุภูมิภาคที่ไม่รองรับ YouTube อาจยังคงเลือกภูมิภาคอื่นเพื่อจัดการปัญหาแทนค่าเริ่มต้น
pageInfo object
ออบเจ็กต์ pageInfo สรุปข้อมูลการแบ่งหน้าสําหรับชุดผลลัพธ์
pageInfo.totalResults integer
จํานวนผลลัพธ์ทั้งหมดในชุดผลลัพธ์ โปรดทราบว่าค่าเป็นการประมาณและอาจไม่ใช่ค่าที่แน่นอน นอกจากนี้ ค่าสูงสุดคือ 1,000,000

คุณไม่ควรใช้ค่านี้ในการสร้างลิงก์หน้า โปรดใช้ค่าพร็อพเพอร์ตี้ nextPageToken และ prevPageToken เพื่อกําหนดว่าจะแสดงลิงก์การใส่เลขหน้าหรือไม่
pageInfo.resultsPerPage integer
จํานวนผลลัพธ์ที่รวมอยู่ในการตอบกลับ API
items[] list
รายการผลการค้นหาที่ตรงกับเกณฑ์การค้นหา

ตัวอย่าง

หมายเหตุ: ตัวอย่างโค้ดต่อไปนี้อาจไม่แสดงภาษาโปรแกรมที่รองรับทั้งหมด โปรดดูรายการภาษาที่รองรับในเอกสารประกอบไลบรารีของไคลเอ็นต์

Apps Script

ฟังก์ชันนี้จะค้นหาวิดีโอที่เกี่ยวข้องกับคําหลัก "สุนัข" รหัสวิดีโอและชื่อของผลการค้นหาจะได้รับการบันทึกไว้ในบันทึกของ Apps Script

โปรดทราบว่าตัวอย่างนี้จํากัดผลลัพธ์แค่ 25 รายการ หากต้องการส่งผลลัพธ์เพิ่มเติม ให้ส่งพารามิเตอร์เพิ่มเติมตามที่บันทึกไว้ที่ https://developers.google.com/youtube/v3/docs/search/list
function searchByKeyword() {
  var results = YouTube.Search.list('id,snippet', {q: 'dogs', maxResults: 25});

  for(var i in results.items) {
    var item = results.items[i];
    Logger.log('[%s] Title: %s', item.id.videoId, item.snippet.title);
  }
}

Go

โค้ดตัวอย่างนี้จะเรียกใช้เมธอด search.list ของ API เพื่อดึงผลการค้นหาที่เชื่อมโยงกับคีย์เวิร์ดหนึ่งๆ

ตัวอย่างนี้ใช้ไลบรารี Go Client

package main

import (
	"flag"
	"fmt"
	"log"
	"net/http"

	"google.golang.org/api/googleapi/transport"
	"google.golang.org/api/youtube/v3"
)

var (
	query      = flag.String("query", "Google", "Search term")
	maxResults = flag.Int64("max-results", 25, "Max YouTube results")
)

const developerKey = "YOUR DEVELOPER KEY"

func main() {
	flag.Parse()

	client := &http.Client{
		Transport: &transport.APIKey{Key: developerKey},
	}

	service, err := youtube.New(client)
	if err != nil {
		log.Fatalf("Error creating new YouTube client: %v", err)
	}

	// Make the API call to YouTube.
	call := service.Search.List("id,snippet").
		Q(*query).
		MaxResults(*maxResults)
	response, err := call.Do()
	handleError(err, "")

	// Group video, channel, and playlist results in separate lists.
	videos := make(map[string]string)
	channels := make(map[string]string)
	playlists := make(map[string]string)

	// Iterate through each item and add it to the correct list.
	for _, item := range response.Items {
		switch item.Id.Kind {
		case "youtube#video":
			videos[item.Id.VideoId] = item.Snippet.Title
		case "youtube#channel":
			channels[item.Id.ChannelId] = item.Snippet.Title
		case "youtube#playlist":
			playlists[item.Id.PlaylistId] = item.Snippet.Title
		}
	}

	printIDs("Videos", videos)
	printIDs("Channels", channels)
	printIDs("Playlists", playlists)
}

// Print the ID and title of each result in a list as well as a name that
// identifies the list. For example, print the word section name "Videos"
// above a list of video search results, followed by the video ID and title
// of each matching video.
func printIDs(sectionName string, matches map[string]string) {
	fmt.Printf("%v:\n", sectionName)
	for id, title := range matches {
		fmt.Printf("[%v] %v\n", id, title)
	}
	fmt.Printf("\n\n")
}

.NET

ตัวอย่างโค้ดต่อไปนี้เรียกเมธอด search.list ของ API เพื่อดึงผลการค้นหาที่เชื่อมโยงกับคีย์เวิร์ดหนึ่งๆ

ตัวอย่างนี้ใช้ไลบรารีของไคลเอ็นต์ .NET

using System;
using System.Collections.Generic;
using System.IO;
using System.Reflection;
using System.Threading;
using System.Threading.Tasks;

using Google.Apis.Auth.OAuth2;
using Google.Apis.Services;
using Google.Apis.Upload;
using Google.Apis.Util.Store;
using Google.Apis.YouTube.v3;
using Google.Apis.YouTube.v3.Data;

namespace Google.Apis.YouTube.Samples
{
  /// <summary>
  /// YouTube Data API v3 sample: search by keyword.
  /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher.
  /// See https://developers.google.com/api-client-library/dotnet/get_started
  ///
  /// Set ApiKey to the API key value from the APIs & auth > Registered apps tab of
  ///   https://cloud.google.com/console
  /// Please ensure that you have enabled the YouTube Data API for your project.
  /// </summary>
  internal class Search
  {
    [STAThread]
    static void Main(string[] args)
    {
      Console.WriteLine("YouTube Data API: Search");
      Console.WriteLine("========================");

      try
      {
        new Search().Run().Wait();
      }
      catch (AggregateException ex)
      {
        foreach (var e in ex.InnerExceptions)
        {
          Console.WriteLine("Error: " + e.Message);
        }
      }

      Console.WriteLine("Press any key to continue...");
      Console.ReadKey();
    }

    private async Task Run()
    {
      var youtubeService = new YouTubeService(new BaseClientService.Initializer()
      {
        ApiKey = "REPLACE_ME",
        ApplicationName = this.GetType().ToString()
      });

      var searchListRequest = youtubeService.Search.List("snippet");
      searchListRequest.Q = "Google"; // Replace with your search term.
      searchListRequest.MaxResults = 50;

      // Call the search.list method to retrieve results matching the specified query term.
      var searchListResponse = await searchListRequest.ExecuteAsync();

      List<string> videos = new List<string>();
      List<string> channels = new List<string>();
      List<string> playlists = new List<string>();

      // Add each result to the appropriate list, and then display the lists of
      // matching videos, channels, and playlists.
      foreach (var searchResult in searchListResponse.Items)
      {
        switch (searchResult.Id.Kind)
        {
          case "youtube#video":
            videos.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.VideoId));
            break;

          case "youtube#channel":
            channels.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.ChannelId));
            break;

          case "youtube#playlist":
            playlists.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.PlaylistId));
            break;
        }
      }

      Console.WriteLine(String.Format("Videos:\n{0}\n", string.Join("\n", videos)));
      Console.WriteLine(String.Format("Channels:\n{0}\n", string.Join("\n", channels)));
      Console.WriteLine(String.Format("Playlists:\n{0}\n", string.Join("\n", playlists)));
    }
  }
}

Ruby

ตัวอย่างนี้เรียกเมธอด search.list ของ API เพื่อดึงผลการค้นหาที่เชื่อมโยงกับคีย์เวิร์ดหนึ่งๆ

ตัวอย่างนี้ใช้ไลบรารีของไคลเอ็นต์ Ruby

#!/usr/bin/ruby

require 'rubygems'
gem 'google-api-client', '>0.7'
require 'google/api_client'
require 'trollop'

# Set DEVELOPER_KEY to the API key value from the APIs & auth > Credentials
# tab of
# {{ Google Cloud Console }} <{{ https://cloud.google.com/console }}>
# Please ensure that you have enabled the YouTube Data API for your project.
DEVELOPER_KEY = 'REPLACE_ME'
YOUTUBE_API_SERVICE_NAME = 'youtube'
YOUTUBE_API_VERSION = 'v3'

def get_service
  client = Google::APIClient.new(
    :key => DEVELOPER_KEY,
    :authorization => nil,
    :application_name => $PROGRAM_NAME,
    :application_version => '1.0.0'
  )
  youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION)

  return client, youtube
end

def main
  opts = Trollop::options do
    opt :q, 'Search term', :type => String, :default => 'Google'
    opt :max_results, 'Max results', :type => :int, :default => 25
  end

  client, youtube = get_service

  begin
    # Call the search.list method to retrieve results matching the specified
    # query term.
    search_response = client.execute!(
      :api_method => youtube.search.list,
      :parameters => {
        :part => 'snippet',
        :q => opts[:q],
        :maxResults => opts[:max_results]
      }
    )

    videos = []
    channels = []
    playlists = []

    # Add each result to the appropriate list, and then display the lists of
    # matching videos, channels, and playlists.
    search_response.data.items.each do |search_result|
      case search_result.id.kind
        when 'youtube#video'
          videos << "#{search_result.snippet.title} (#{search_result.id.videoId})"
        when 'youtube#channel'
          channels << "#{search_result.snippet.title} (#{search_result.id.channelId})"
        when 'youtube#playlist'
          playlists << "#{search_result.snippet.title} (#{search_result.id.playlistId})"
      end
    end

    puts "Videos:\n", videos, "\n"
    puts "Channels:\n", channels, "\n"
    puts "Playlists:\n", playlists, "\n"
  rescue Google::APIClient::TransmissionError => e
    puts e.result.body
  end
end

main

ข้อผิดพลาด

ตารางต่อไปนี้ระบุข้อความแสดงข้อผิดพลาดที่ API อาจส่งคืนมาเมื่อมีการเรียกวิธีนี้ โปรดดูรายละเอียดเพิ่มเติมในเอกสารประกอบข้อความแสดงข้อผิดพลาด

ประเภทข้อผิดพลาด รายละเอียดข้อผิดพลาด คำอธิบาย
badRequest (400) invalidChannelId พารามิเตอร์ channelId ระบุรหัสช่องไม่ถูกต้อง
badRequest (400) invalidLocation ค่าพารามิเตอร์ location และ/หรือ locationRadius มีรูปแบบที่ไม่ถูกต้อง
badRequest (400) invalidRelevanceLanguage ค่าพารามิเตอร์ relevanceLanguage มีรูปแบบที่ไม่ถูกต้อง
badRequest (400) invalidSearchFilter คําขอมีชุดค่าผสมของตัวกรองการค้นหาและ/หรือข้อจํากัดที่ไม่ถูกต้อง โปรดทราบว่าคุณจะต้องตั้งค่าพารามิเตอร์ type เป็น video หากตั้งค่าพารามิเตอร์ forContentOwner หรือ forMine เป็น true และต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วยหากคุณตั้งค่าพารามิเตอร์ eventType, videoCaption, videoCategoryId, videoDefinition, videoDimension, videoDuration, videoEmbeddable, videoLicense, videoSyndicated หรือ videoType

ลองใช้เลย

ใช้ APIs Explorer เพื่อเรียกใช้ API นี้และดูคําขอ API และการตอบกลับ