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

คำขอ 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 ที่มีอยู่

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

• ค่าแอตทริบิวต์ term ของแท็ก <category> ที่ระบุประเภทของรายการที่อธิบายไว้ในฟีดหรือรายการฟีด ภายในแท็ก <feed> หรือ <entry> แท็ก <id> จะระบุทรัพยากรที่ไม่ซ้ำกันซึ่งระบุโดยรายการ และแท็ก <category> จะระบุประเภททรัพยากรที่อธิบายโดยรายการ สำหรับแท็ก <category> นี้ ค่าของแอตทริบิวต์รูปแบบคือ 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 ของฟีดเองเนื่องจากอาจหยุดทํางานโดยไม่คาดคิด

  • /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 จัดเก็บค่าแท็กใดในคําขอนั้นจริง ตามที่ระบุไว้ในหลักเกณฑ์ความเข้ากันได้แบบย้อนหลังสำหรับคำขอ API ทาง YouTube อาจเปลี่ยนแปลงข้อมูลที่เก็บไว้ (จัดเก็บ) เมื่อแทรกหรืออัปเดตทรัพยากร ซึ่งหมายความว่าระบบอาจละเว้นแท็กบางรายการในคำขอ

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

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

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

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

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