หลักเกณฑ์ความเข้ากันได้แบบย้อนหลัง

คําขอ YouTube Data API แต่ละรายการสามารถระบุเวอร์ชันของ API ที่ YouTube ควรใช้เพื่อจัดการคําขอนั้นได้ หากคําขอไม่ได้ระบุเวอร์ชัน API ไว้ YouTube จะใช้ API เวอร์ชันเก่าที่สุดที่รองรับเพื่อจัดการคําขอนั้น เวอร์ชันเก่าที่สุดที่รองรับคือ 1 ลักษณะเฉพาะของหมายเลขเวอร์ชัน API มีดังนี้

• YouTube อาจเผยแพร่การอัปเดตสําหรับ API เวอร์ชันที่เฉพาะเจาะจงซึ่งไม่มีการระบุหมายเลขเวอร์ชันใหม่ การอัปเดตที่เข้ากันได้แบบย้อนหลังเหล่านี้อาจรวมถึงฟีเจอร์ API ที่ไม่บังคับ การแก้ไขข้อบกพร่อง หรือทั้ง 2 อย่าง

• การเพิ่มหมายเลขเวอร์ชัน API จะระบุรุ่นที่มีการเปลี่ยนแปลงซึ่งเข้ากันไม่ได้กับ API เวอร์ชันก่อนหน้า

เอกสารนี้จะระบุหลักเกณฑ์ความเข้ากันได้แบบย้อนหลังสําหรับการอัปเดต API เวอร์ชันที่เจาะจง ซึ่งเป็นรายการแรกที่ระบุไว้ข้างต้น หลักเกณฑ์จะพยายามแยกแยะความแตกต่างระหว่างฟังก์ชันการทํางานของ API ประเภทต่อไปนี้

• หลักเกณฑ์ระบุฟังก์ชันการทํางานของ API ที่อาจมีการเปลี่ยนแปลงแม้ว่าคุณจะไม่ได้แก้ไขเวอร์ชัน API ที่ควรใช้สําหรับจัดการคําขอ API ก็ตาม โค้ดของคุณควรจัดการกับการเปลี่ยนแปลงเหล่านี้โดยไม่ทําให้เสีย ตัวอย่างเช่น หาก YouTube เพิ่มแท็ก XML ใหม่ในการตอบกลับ API โค้ดก็ควรจะไม่สนใจแท็กเหล่านั้น

• หลักเกณฑ์เหล่านี้ยังกําหนดฟังก์ชันการทํางานของ API ที่ YouTube ไม่ได้ตั้งใจเปลี่ยนแปลงเมื่ออัปเดต API เวอร์ชันที่เจาะจง กล่าวคือ คุณควรคาดหวังว่าฟังก์ชันดังกล่าวจะเปลี่ยนแปลงก็ต่อเมื่อ YouTube เผยแพร่ API เวอร์ชันใหม่เท่านั้น และโค้ดไม่จําเป็นต้องพยายามจัดการกับการเปลี่ยนแปลงประเภทนี้

เกี่ยวกับเอกสารนี้

เอกสารนี้ประกอบด้วยส่วนต่างๆ ต่อไปนี้

• ส่วนคําขอ API กําหนดหลักเกณฑ์ความเข้ากันได้กับส่วนหัวซึ่งเกี่ยวข้องกับส่วนหัวของคําขอ HTTP, พารามิเตอร์คําขอ API, ชื่อองค์ประกอบ XML (ตามที่ปรากฏในคําขอ API) และคําขอ API ที่มีรูปแบบไม่ถูกต้อง

• ส่วนการตอบกลับ API กําหนดหลักเกณฑ์ความเข้ากันได้แบบย้อนหลังที่เกี่ยวข้องกับชื่อองค์ประกอบ XML (ตามที่ปรากฏในการตอบกลับ API) และลําดับแท็กและแอตทริบิวต์ XML จะปรากฏในการตอบกลับ API

• ส่วนแนวทางปฏิบัติแนะนําจะแสดงคําแนะนําเกี่ยวกับการผสานรวม YouTube API กับแอปพลิเคชันไคลเอ็นต์

คําขอ API

ฟังก์ชันการทํางานที่ไม่ได้ตั้งใจจะเปลี่ยนแปลง

• พารามิเตอร์คําขอที่มีอยู่

• ค่าพารามิเตอร์ที่มีอยู่สําหรับพารามิเตอร์ที่มีค่าแจกแจงหรือความหมายของค่าพารามิเตอร์เหล่านั้น

• ชื่อองค์ประกอบ XML ที่ใช้ในคําขอ API POST (แทรก) หรือ PUT (อัปเดต)

• ชุดส่วนหัวของคําขอ HTTP ที่จําเป็นสําหรับคําขอ API แต่ละประเภท หลักเกณฑ์นี้หมายความว่า YouTube ไม่ได้ตั้งใจจะเพิ่มส่วนหัวของคําขอ HTTP ที่จําเป็นหรือเปลี่ยนส่วนหัวคําขอที่ไม่บังคับที่มีอยู่ให้จําเป็น

• การละเว้นพารามิเตอร์ที่ไม่รองรับในคําขอ API เว้นแต่คําขอจะใช้พารามิเตอร์ strict ซึ่งเป็นการสั่งให้ YouTube ปฏิเสธคําขอ API ที่มีพารามิเตอร์คําขอที่ไม่ถูกต้อง

ฟังก์ชันการทํางานที่อาจมีการเปลี่ยนแปลง

• YouTube อาจเพิ่มพารามิเตอร์คําขอที่ไม่บังคับ

• YouTube อาจเพิ่มค่าใหม่สําหรับพารามิเตอร์ที่มีอยู่ซึ่งมีชุดค่าที่แจกแจง

• YouTube สามารถปฏิเสธคําขอที่พารามิเตอร์ที่ถูกต้องมีค่าพารามิเตอร์ที่ไม่ถูกต้อง ด้วยเหตุนี้ คําขอที่มีรูปแบบไม่ถูกต้องซึ่งได้รับการยอมรับเนื่องจากมีการแยกวิเคราะห์แบบผ่อนปรนมากเกินไปอาจถูกปฏิเสธหากตรรกะการแยกวิเคราะห์ถูกต้อง

• YouTube อาจเพิ่มส่วนหัวของคําขอ HTTP หรือไม่ก็ได้

• YouTube อาจเปลี่ยนแปลงข้อมูลที่เก็บรักษาไว้ (ร้านค้า) เมื่อแทรกหรืออัปเดตทรัพยากร อย่างไรก็ตาม การตัดสินใจดังกล่าวจะไม่ส่งผลกระทบหรือต้องเปลี่ยนแปลงไวยากรณ์ของคําขอ API ที่เกี่ยวข้อง

• YouTube อาจเปลี่ยนชุดหมวดหมู่ที่เรียกดูได้หรือชุดหมวดหมู่สําหรับวิดีโอที่อัปโหลดใหม่

• ฟังก์ชันการทํางานที่ไม่ได้บันทึกไว้อาจถูกนําออกหรือเปลี่ยนแปลงได้ตลอดเวลา

การตอบกลับ API

ฟังก์ชันการทํางานที่ไม่ได้ตั้งใจจะเปลี่ยนแปลง

• ชื่อแท็ก XML ที่มีอยู่

• การปฏิบัติตามข้อกําหนด RSS ของสื่อเพื่อกําหนดลําดับองค์ประกอบที่กําหนดไว้ในข้อกําหนดนั้นและปรากฏขึ้นหลายครั้งในรายการฟีด เช่น หากรายการมีแท็ก <media:thumbnail> หลายรายการ ระบบจะจัดลําดับตามความสําคัญ

• ค่าแอตทริบิวต์ term ของแท็ก <category> ที่ระบุประเภทรายการที่อธิบายไว้ในรายการฟีดหรือฟีด ภายในแท็ก <feed> หรือ <entry> แท็ก <id> จะระบุทรัพยากรที่ไม่ซ้ํากันที่รายการระบุไว้ และแท็ก <category> จะระบุประเภทของทรัพยากรที่รายการนี้อธิบาย สําหรับแท็ก <category> นี้ ค่าของแอตทริบิวต์ Scheme คือ http://schemas.google.com/g/2005#kind และค่าของแอตทริบิวต์คําระบุว่ารายการฟีดอธิบายถึงวิดีโอ ลิงก์ของเพลย์ลิสต์ การติดตาม รายชื่อติดต่อ หรือเอนทิตีประเภทอื่นหรือไม่

ฟังก์ชันการทํางานที่อาจมีการเปลี่ยนแปลง

• YouTube อาจเพิ่มแท็ก XML ใหม่ในการตอบกลับ API

• YouTube อาจเพิ่มแอตทริบิวต์ใหม่ลงในแท็ก XML ที่มีอยู่

• แท็ก API ที่มีอยู่อาจซ้ํากับค่าอื่น เช่น YouTube อาจเพิ่มแท็ก <media:restriction> ใหม่ด้วยค่า type อื่น หรือแท็ก <media:credit> ใหม่ซึ่งมี scheme และ role อื่น

• ลําดับของแท็กและแอตทริบิวต์ XML ในการตอบกลับ API อาจเปลี่ยนแปลง

• ระบบอาจนําแท็กย่อยที่ไม่บังคับออกจากการตอบกลับ API

• ฟังก์ชันการทํางานที่ไม่ได้บันทึกไว้อาจถูกนําออกหรือเปลี่ยนแปลงได้ตลอดเวลา

แนวทางปฏิบัติแนะนำ

• ใช้ค่าแท็ก <id> ในการระบุรายการ

• ใช้ลิงก์ self เพื่อดึงข้อมูลรายการ

• ใช้ลิงก์ edit เพื่อแก้ไขหรืออัปเดตรายการ

• ใช้ค่าแท็ก <yt:videoid> สําหรับรายการวิดีโอเพื่อรับค่าที่ YouTube ใช้เพื่อระบุวิดีโอแต่ละรายการ อย่าแยกวิเคราะห์รหัสวิดีโอจากลิงก์

• ใช้ URL ที่ระบุในแท็ก <link>, <content> และ <gd:feedLink> เพื่อไปยังส่วนต่างๆ ของฟีด YouTube รองรับ URL จํานวนที่จํากัดเพื่อให้คุณสร้างฟีดที่เฉพาะเจาะจงได้อย่างน่าเชื่อถือ นอกจาก URL ฟีดเหล่านั้นในรายการด้านล่างแล้ว คุณไม่ควรสร้าง URL ฟีดของคุณเองเนื่องจาก URL เหล่านั้นอาจหยุดทํางานโดยไม่คาดคิด

  • /feeds/api/videos/<videoid>
  • /feeds/api/users/default
  • /feeds/api/users/default/uploads
  • /feeds/api/users/default/favorites
  • /feeds/api/users/default/contacts
  • /feeds/api/users/default/inbox
  • /feeds/api/users/default/playlists
  • /feeds/api/users/default/subscriptions
  • /feeds/api/users/default/newsubscriptionvideos
  • /feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME (ดูข้อมูลเพิ่มเติมในคู่มืออ้างอิง)

• อย่าพยายามแยกวิเคราะห์ตัวเลขหรือตัวอักษรและตัวเลขคละกันจาก URL ในการตอบกลับ API การตอบกลับ API ประกอบด้วยแท็กที่เฉพาะเจาะจงสําหรับตัวระบุที่ลิงก์ไปยังทรัพยากรในเว็บไซต์ YouTube เช่น รหัสวิดีโอ (<yt:videoid>) และชื่อผู้ใช้ (<name> และ <media:credit>).

• หากคุณส่งคําขอ API เพื่อแทรก (POST) หรืออัปเดตข้อมูล (PUT) ให้ใช้การตอบสนอง XML กับคําขอดังกล่าวเพื่อระบุว่า YouTube ได้จัดเก็บค่าแท็กใดในคําขอนั้น YouTube อาจเปลี่ยนแปลงข้อมูลที่เก็บรักษาไว้ (จัดเก็บ) เมื่อแทรกหรืออัปเดตทรัพยากร ซึ่งหมายความว่าระบบไม่สนใจแท็กบางรายการในคําขอในหลักเกณฑ์ความเข้ากันได้แบบย้อนหลังสําหรับคําขอ API

• เมื่อคุณดึงข้อมูลฟีด XML ให้จัดเก็บแท็กและแอตทริบิวต์ XML ที่ไม่รู้จักซึ่งเกี่ยวข้องกับรายการฟีด หากแอปพลิเคชันของคุณช่วยให้ผู้ใช้อัปเดตรายการนั้นได้ หากผู้ใช้อัปเดตทรัพยากร แอปพลิเคชันของคุณควรมีแท็กและแอตทริบิวต์ที่ไม่รู้จักในคําขออัปเดต เนื่องจากจะทําให้แอปพลิเคชันไม่ลบข้อมูลที่เกี่ยวข้องกับฟีเจอร์ API ใหม่ในขั้นตอนการอัปเดตทรัพยากรโดยไม่ได้ตั้งใจ

  ตัวอย่างต่อไปนี้แสดงแนวทางปฏิบัติแนะนํานี้

  1. แอปพลิเคชันของคุณช่วยให้ผู้ใช้อัปเดตคําอธิบายวิดีโอได้
  2. แอปพลิเคชันของคุณจะดึงรายการวิดีโอโดยใช้ API แต่ไม่รู้จักแท็กใดแท็กหนึ่งในรายการ
  3. ผู้ใช้แก้ไขคําอธิบายวิดีโอ
  4. แอปพลิเคชันต้องส่งรายการวิดีโอที่สมบูรณ์กลับไปยัง API รายการต้องรวมแท็กที่ไม่รู้จักจากขั้นตอนที่ 2 มิฉะนั้นค่านี้อาจถูกลบ

• ยืนยันว่ามีแท็กอยู่และมีค่าที่ไม่เป็นค่าว่างก่อนที่จะพยายามแสดงค่าแท็ก

• ดังที่ระบุไว้ข้างต้น YouTube อาจเพิ่มค่าใหม่สําหรับแท็กหรือแอตทริบิวต์ที่มีอยู่ซึ่งแจกแจงชุดค่าไว้ ตามกฎ โค้ดควรแยกวิเคราะห์ค่าขององค์ประกอบ XML ที่มีชุดค่าต่างๆ แล้วกําหนดการกระทําที่เหมาะกับค่าเหล่านั้น เราขอแนะนําให้ใช้แนวทางปฏิบัตินี้แม้ว่าระบบจะแจกแจงค่าที่เป็นไปได้เพียงรายการเดียวสําหรับองค์ประกอบก็ตาม

  เช่น แท็ก <media:credit> ระบุเจ้าของวิดีโอ ค่าเดียวที่บันทึกไว้สําหรับแอตทริบิวต์ role ของแท็กคือ uploader ซึ่งระบุว่าวิดีโออัปโหลดโดยพาร์ทเนอร์ YouTube แนวทางปฏิบัติแนะนํานี้กําหนดให้แอปพลิเคชันควรยืนยันว่าค่าของแอตทริบิวต์ role ของแท็กเป็น uploader จริงๆ ก่อนระบุผู้ใช้ที่เกี่ยวข้องว่าเป็นเจ้าของวิดีโอ (ข้อควรระวังนี้ช่วยให้แน่ใจว่าโค้ดไม่ได้ระบุเจ้าของวิดีโอไม่ถูกต้องหาก YouTube เพิ่มเครดิตประเภทอื่นๆ เช่น ผู้อํานวยการสําหรับวิดีโอ)

  • หากแท็กมีชุดค่าที่แจกแจงไว้และคุณไม่รู้จักค่าของแท็กนั้น คุณควรละเว้น <entry> ทั้งหมดที่แท็กนั้นปรากฏ

  • ไม่ต้องสนใจรายการฟีดการสมัครใช้บริการหากคุณไม่รู้จักค่าของแอตทริบิวต์ term สําหรับแท็ก <category> ที่มีค่าแอตทริบิวต์ scheme เป็น http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat แท็กดังกล่าวจะระบุประเภทการสมัครใช้บริการที่รายการระบุไว้ หากแอปพลิเคชันของคุณไม่รู้จักประเภทการสมัครใช้บริการ แอปพลิเคชันก็ไม่ควรแสดงข้อมูลเกี่ยวกับรายการนั้น

  • หากแอตทริบิวต์อื่นมีชุดค่าที่แจกแจงไว้และคุณไม่รู้จักค่าของแอตทริบิวต์ดังกล่าว คุณควรละเว้นแท็กที่แอตทริบิวต์ปรากฏ

• รหัสแอปพลิเคชันของคุณควรมีข้อความ yt:error เมื่อใดก็ได้ ในกรณีที่การดําเนินการ API ล้มเหลว แอปพลิเคชันของคุณควรระบุข้อผิดพลาดและแสดงข้อความที่มีความหมายต่อผู้ใช้

• YouTube อาจเพิ่มหมวดหมู่ใหม่สําหรับการจัดประเภทวิดีโอได้ทุกเมื่อ YouTube อาจอัปเดตหรือเลิกใช้งานหมวดหมู่ที่มีอยู่ด้วย คุณสามารถเรียกดูไฟล์หมวดหมู่ปัจจุบันได้จาก http://gdata.youtube.com/schemas/2007/categories.cat

  • หากแอปพลิเคชันของคุณช่วยให้ผู้ใช้เรียกดูวิดีโอตามหมวดหมู่หรืออัปโหลดวิดีโอ ให้เรียกดูไฟล์หมวดหมู่ที่อัปเดตทุกสัปดาห์

  • หากแอปพลิเคชันของคุณช่วยให้ผู้ใช้เรียกดูวิดีโอตามหมวดหมู่ได้ ให้เรียกดูไฟล์หมวดหมู่ที่อัปเดตด้วยหาก API แสดงฟีดว่างสําหรับการค้นหาหมวดหมู่

  • หากแอปพลิเคชันของคุณอนุญาตให้ผู้ใช้อัปโหลดวิดีโอ ให้เรียกดูไฟล์หมวดหมู่ที่อัปเดตก่อนที่จะอัปโหลดวิดีโอ และยืนยันว่าคุณยังคงกําหนดหมวดหมู่ที่เชื่อมโยงกับวิดีโอที่อัปโหลดได้ โปรดดูข้อมูลเพิ่มเติมในคู่มือข้อมูลอ้างอิง (โปรดทราบว่าหากคุณพยายามกําหนดวิดีโอให้กับหมวดหมู่ที่กําหนดไม่ได้ API จะแสดงผลข้อความแสดงข้อผิดพลาดที่ค่าของแท็ก <code> คือ deprecated)

• ใช้แท็ก <link> ในการตอบกลับ API เพื่อระบุลิงก์การใส่เลขหน้าสําหรับหน้าก่อนหน้าและ/หรือถัดไปของรายการในฟีด ดูข้อมูลเพิ่มเติมได้ในส่วนการแบ่งหน้าในผลการค้นหาของคู่มืออ้างอิง