แนวทางปฏิบัติที่ดีที่สุดสําหรับการใช้แค็ตตาล็อก API Microsoft Learn
บทความนี้อธิบายแนวทางปฏิบัติที่ดีที่สุดสําหรับการใช้ API แค็ตตาล็อก Learn
ทําความเข้าใจข้อกําหนดการใช้บริการ
แม้ว่าแค็ตตาล็อก API Learn จะพร้อมใช้งานแบบสาธารณะและใช้งานได้ฟรี ผู้ใช้จะอยู่ภายใต้ ข้อกําหนดการใช้ของ Microsoft API อ่านและทําความเข้าใจเงื่อนไขการใช้ API ก่อนที่จะใช้ Learn Catalog API และก่อนรวมเอาท์พุทในสภาพแวดล้อมการผลิตใด ๆ
ทําความเข้าใจเกี่ยวกับข้อจํากัดของแค็ตตาล็อก API Learn
โปรดดูข้อจํากัดในบทความ ภาพรวมคุณลักษณะแค็ตตาล็อก API Learn
ทําความเข้าใจกับแบบจําลองเนื้อหา Learn
ในการใช้การตอบสนองของแค็ตตาล็อก API การเรียนรู้อย่างมีประสิทธิภาพ สิ่งสําคัญคือต้องทําความเข้าใจชนิดของเนื้อหาที่มีอยู่ใน Microsoft Learn และความสัมพันธ์ของพวกเขากับอีกชนิดหนึ่ง ตรวจทานบทความ เรียนรู้แบบจําลองเนื้อหา สําหรับข้อมูลเพิ่มเติม
โดยเฉพาะอย่างยิ่ง:
- UID ย่อมาจาก Unique ID และจะไม่ซ้ํากันสําหรับแต่ละวัตถุเนื้อหา ถ้า UID เปลี่ยนแปลง แม้ว่าชื่อเรื่องหรือเมตาดาต้าอื่น ๆ จะยังคงเหมือนเดิม เนื้อหาจะถือว่าเป็นออบเจ็กต์ใหม่
- โมดูลเป็นวัตถุหลักภายในแค็ตตาล็อกการฝึกอบรม Learn พวกเขาทั้งหมดมีความสามารถในการยืนอยู่คนเดียวในแง่ที่ว่าพวกเขาสอนสถานการณ์หรือแนวคิดแบบ end-to-end ภายในและไม่จําเป็นต้องใช้มอดูลข้อกําหนดเบื้องต้น สําหรับบางคนนี่คือและพวกเขาไม่ได้เป็นส่วนหนึ่งของเส้นทางการเรียนรู้ สําหรับผู้อื่น พวกเขาจะรวมกันในเส้นทางการเรียนรู้อย่างน้อยหนึ่งเส้นทางที่นําผู้ใช้ผ่านการสร้างแนวคิดขั้นสูงเพิ่มเติม โมดูลไม่จําเป็นต้องเป็นส่วนหนึ่งของเส้นทางการเรียนรู้หรืออาจเป็นส่วนหนึ่งของอย่างน้อยหนึ่งรายการ
- หน่วยจะไม่ถูกเขียนเป็นเนื้อหาแบบสแตนด์อโลน โดยมีวัตถุประสงค์เพื่อดําเนินการตามลําดับที่เฉพาะเจาะจงสําหรับโมดูล ด้วยเหตุนี้ เราจึงมีลิงก์ไปยังหน้ารายละเอียดโมดูลและหน่วยแรกเพื่อให้ผู้ใช้สามารถเริ่มต้นและดําเนินการผ่านเนื้อหาได้
ทําความเข้าใจวิธีการทํางานของการแปลเป็นภาษาท้องถิ่นใน Learn และวิธีการสะท้อนเนื้อหาที่แปลเป็นภาษาท้องถิ่นในผลลัพธ์ของ API
Microsoft Learn สนับสนุนตําแหน่งที่ตั้งมากกว่า 65 ตําแหน่งที่ตั้งบนไซต์ และเนื้อหาส่วนใหญ่จะถูกแปลเป็นตําแหน่งที่ตั้งเหล่านี้ เราตั้งใจที่จะทําให้เนื้อหาพร้อมใช้งานในทุกภาษาที่ผลิตภัณฑ์ได้รับการสอนในเนื้อหาให้พร้อมใช้งาน แต่ไม่ใช่ทุกประสบการณ์การใช้งานตําแหน่งที่ตั้งที่มีเนื้อหาที่แปลเป็นภาษาท้องถิ่นพร้อมใช้งาน
เมื่อระเบียนตําแหน่งที่ตั้งไม่มีคําแปลที่เกี่ยวข้องพร้อมใช้งาน เนื้อหาในไซต์และการตอบสนอง API "กลับไป" เป็นภาษาอังกฤษเป็นค่าเริ่มต้น ในผลลัพธ์ API คุณจะเห็นเมตาดาต้าภาษาอังกฤษในการตอบสนองตําแหน่งที่ตั้งอื่น ๆ เมื่อกลับมาทํางานอีกครั้ง อย่างไรก็ตาม URL ไปยังเนื้อหายังคงชี้ไปยังตําแหน่งที่ตั้ง แม้ว่าเนื้อหาหลักอาจถอยหลัง และเหตุผลคือการอนุญาตให้ผู้ใช้ยังคงนําทางไปยังไซต์ในตําแหน่งที่ตั้งนั้น (ซึ่งแสดงการแปลส่วนหัว/ส่วนท้าย และลิงก์อื่น ๆ ที่มีการแปลที่พร้อมใช้งาน)
เมื่อมีการเผยแพร่การอัปเดตไปยังเนื้อหาภาษาอังกฤษ ไปป์ไลน์การแปลของเราจะทํางานเพื่อรับการอัปเดตเวอร์ชันที่แปลเป็นภาษาท้องถิ่นโดยเร็วที่สุด – โดยปกติภายในสองสามวันจากการเปลี่ยนแปลงเดิม
คุณสามารถดูรายการตําแหน่งที่ตั้งที่รองรับทั้งหมดได้ในส่วนท้ายของไซต์ Microsoft Learn (เลือกภาษาที่คุณกําลังดูอยู่) แต่ละตําแหน่งที่ตั้งเหล่านี้สามารถคิวรีด้วย API แค็ตตาล็อก Learn โดยใช้ตัวกรอง locale ได้
บันทึกการดําเนินการเนื้อหาการฝึกอบรมของเราเป็นการวินิจฉัยตําแหน่งที่ตั้ง ซึ่งหมายความว่าเราไม่ได้แยกความแตกต่างของเนื้อหาที่เป็นภาษาท้องถิ่นเป็นวัตถุแยกต่างหากในบันทึกการเสร็จสิ้นการฝึกอบรมของผู้ใช้ของเรา ไม่ว่าภาษาใดที่ผู้ใช้การฝึกอบรมเสร็จสมบูรณ์แล้ว พวกเขาจะได้รับเครดิตสําหรับออบเจ็กต์โดยรวม และเราจะไม่จัดเก็บการอ้างอิงถึงภาษาที่เสร็จสมบูรณ์ การดําเนินการการวินิจฉัยตําแหน่งที่ตั้งนี้หมายความว่าถ้าคุณใช้ Learn Catalog API ในประสบการณ์การเรียนรู้ของคุณ คุณต้องคํานึงถึงและถ้าคุณโหลดวัตถุเนื้อหาในเป็นออบเจ็กต์แยกต่างหาก ให้นําความเทียบเท่าระหว่างกันมาใช้เพื่อไม่ว่าภาษาใดที่ผู้ใช้เสร็จสิ้นการฝึกอบรมพวกเขาจะได้รับเครดิตในภาษาอื่น ๆ และไม่จําเป็นต้องสร้างใหม่
ทําความเข้าใจวิธีการกําหนดรุ่นเนื้อหาใน Learn และวิธีมีผลในเอาต์พุต API
โดยเฉพาะอย่างยิ่ง มีการอัปเดตเนื้อหาตลอดเวลา เราเผยแพร่อัปเดตที่พร้อมใช้งานวันละสองครั้ง ซึ่งอาจเล็กน้อย เช่น การเปลี่ยนแปลงข้อความเล็กน้อย หรือรายการหลัก เช่น การแก้ไขหลัก การเพิ่ม หรือการลบ โดยทั่วไปพอร์ตเนื้อหาได้รับการจัดการเป็นโครงการโอเพนซอร์สที่มีการควบคุมสูงและมีผู้สนับสนุนหลายพันคนและด้วยเหตุนี้การเปลี่ยนแปลงเกิดขึ้นตลอดเวลา ถ้าคุณใช้แค็ตตาล็อก API Learn ในระบบการผลิตของคุณ คุณควรทราบและให้ระบบของคุณสามารถจัดการได้
เมื่อเพิ่มวัตถุเนื้อหาใหม่ วัตถุเหล่านั้นจะปรากฏเป็นวัตถุใหม่ (ระบุโดย UID) ในการตอบสนอง เมื่อมีการปรับเปลี่ยนเนื้อหา คุณสามารถบอกได้ตามค่า last_modified เมื่อลบเนื้อหา วัตถุเนื้อหาจะถูกเอาออกจากการตอบสนอง แม้ว่าจะมีความล่าช้าเล็กน้อยในการปรับปรุงเนื้อหาในการตอบกลับ API เมื่อผู้ใช้ติดตาม URL ไปยังเนื้อหา ผู้ใช้จะเห็นข้อมูลล่าสุดเสมอ ในกรณีของการลบ URL เก่าจะเปลี่ยนเส้นทางไปยังเนื้อหาหรือประสบการณ์ใหม่หรือไปยังตัวเลือกที่ดีที่สุดถัดไป
ไม่มีการอ้างอิงไปยังเวอร์ชันเนื้อหาในขณะนี้นอกเหนือจากวันที่ last_modified
รีเฟรชข้อมูลเป็นประจํา
หากคุณกําลังใช้ข้อมูลแค็ตตาล็อกจากแค็ตตาล็อก API การเรียนรู้เพื่อสนับสนุนกระบวนการทางธุรกิจของคุณ หรือการแสดงผลสําหรับลูกค้าในฐานะส่วนหนึ่งของประสบการณ์การใช้งานเว็บไซต์ของคุณ ตรวจสอบให้แน่ใจว่าคุณรีเฟรชเนื้อหาอย่างน้อยหนึ่งครั้งต่อวัน
โดยเฉพาะอย่างยิ่ง มีการอัปเดตเนื้อหาตลอดเวลา เราเผยแพร่อัปเดตที่พร้อมใช้งานวันละสองครั้ง ซึ่งอาจเล็กน้อย เช่น การเปลี่ยนแปลงข้อความเล็กน้อย หรือรายการหลัก เช่น การแก้ไขหลัก การเพิ่ม หรือการลบ โดยทั่วไปพอร์ตเนื้อหาได้รับการจัดการเป็นโครงการโอเพนซอร์สที่มีการควบคุมสูงและมีผู้สนับสนุนหลายพันคนและด้วยเหตุนี้การเปลี่ยนแปลงเกิดขึ้นตลอดเวลา ถ้าคุณใช้แค็ตตาล็อก API Learn ในระบบการผลิตของคุณ คุณควรทราบและให้ระบบของคุณสามารถจัดการได้
ตรวจทานคําแนะนําเอกสารสําหรับนักพัฒนา
เอกสารประกอบสําหรับนักพัฒนา Learn Catalog API มีรายการทั้งหมดของข้อมูลที่ระบุเป็นส่วนหนึ่งของการตอบกลับ และคําแนะนําเกี่ยวกับวิธีการแนะนําให้ใช้แต่ละเขตข้อมูลเพื่อสนับสนุนประสบการณ์การเรียนรู้ที่ยอดเยี่ยม
ทําความเข้าใจตรรกะคิวรี
มีตัวกรองมากมายที่พร้อมใช้งานเพื่อกรองการตอบกลับไว้ล่วงหน้า เพื่อให้คุณได้เฉพาะสิ่งที่คุณกําลังค้นหาและสามารถจัดการขนาดไฟล์ที่มีขนาดเล็กลงได้ คุณสามารถดูรายการตัวกรองคิวรีทั้งหมดได้ในบทความการอ้างอิงแค็ตตาล็อก API Learn โดยเฉพาะอย่างยิ่ง คุณจําเป็นต้องสร้างคิวรีอย่างถูกต้อง และถ้าคุณกําลังใช้พารามิเตอร์คิวรีมากกว่าหนึ่งพารามิเตอร์ในคําขอ คิวรีจะถูกประเมินโดยใช้ตัวดําเนินการ AND
ขั้นตอนถัดไป
สําหรับข้อมูลเพิ่มเติมเพื่อสนับสนุนคุณด้วย Learn Catalog API โปรดอ่านบทความต่อไปนี้: