Biện pháp tốt nhất để sử dụng API Danh mục của Microsoft Learn

Bài viết này mô tả các biện pháp tốt nhất để sử dụng API Danh mục Tìm hiểu.

Hiểu rõ Điều khoản Dịch vụ

Mặc dù API Danh mục Learn được cung cấp công khai và miễn phí để sử dụng, người dùng vẫn phải tuân theo Điều khoản Sử dụng API microsoft. Đọc và hiểu Điều khoản Sử dụng API trước khi sử dụng API Danh mục Learn và trước khi đưa đầu ra vào bất kỳ môi trường sản xuất nào.

Tìm hiểu về các giới hạn của API Danh mục Learn

Hãy xem Giới hạn trong bài viết tổng quan về Tính năng API Danh mục này.

Tìm hiểu về mô hình nội dung Learn

Để sử dụng phản hồi API Danh mục Learn một cách hiệu quả, điều quan trọng là phải hiểu rõ các loại nội dung có sẵn trong Microsoft Learn và mối quan hệ của họ với nhau. Xem lại bài viết Learn content model để biết thêm thông tin.

Đáng chú ý:

UID là viết tắt của Unique ID và là duy nhất cho mỗi đối tượng nội dung. Nếu UID thay đổi, ngay cả khi tiêu đề hoặc siêu dữ liệu khác vẫn giữ nguyên, nội dung đó được coi là đối tượng mới.
Mô-đun là đối tượng cốt lõi trong danh mục đào tạo Learn. Họ đều có khả năng đứng một mình, theo nghĩa là họ dạy một kịch bản hoặc khái niệm từ đầu đến cuối bên trong chúng và không yêu cầu thực hiện các mô-đun điều kiện tiên quyết. Đối với một số người, đây là nó và họ không phải là một phần của một lộ trình học tập. Đối với những người khác, chúng đi kèm với nhau trong một hoặc nhiều lộ trình học tập đưa người dùng thông qua việc xây dựng các khái niệm nâng cao hơn. Mô-đun không nhất thiết phải là một phần của lộ trình học tập hoặc mô-đun đó có thể là một phần của một hoặc nhiều mô-đun.
Các đơn vị không được viết dưới dạng nội dung độc lập. Chúng được dự định sẽ được thực hiện theo một thứ tự cụ thể cho mô-đun. Vì lý do này, chúng tôi bao gồm liên kết đến trang chi tiết mô-đun và đơn vị đầu tiên để người dùng có thể bắt đầu ở đó và tiếp tục qua nội dung.

Tìm hiểu cách hoạt động của bản địa hóa trong Tìm hiểu và cách phản ánh nội dung được bản địa hóa trong đầu ra API

Microsoft Learn hỗ trợ hơn 65 ngôn ngữ trên trang web và phần lớn nội dung được dịch sang các ngôn ngữ này. Chúng tôi mong muốn làm cho nội dung có sẵn trong tất cả các ngôn ngữ mà các sản phẩm đang được dạy trong nội dung có sẵn, nhưng không phải tất cả các trải nghiệm bản địa đều có sẵn nội dung được bản địa hóa.

Khi bản ghi bản địa không có sẵn bản dịch liên quan, nội dung trên trang web và phản hồi API "quay trở lại" thành tiếng Anh như mặc định. Trong đầu ra API, bạn sẽ thấy siêu dữ liệu tiếng Anh ở các phản hồi bản địa khác khi điều này xảy ra trở lại. Tuy nhiên, URL đến nội dung vẫn trỏ đến ngôn ngữ, mặc dù nội dung chính có thể bị thu hồi và lý do là để cho phép người dùng vẫn dẫn hướng trang trong ngôn ngữ đó (hiển thị đầu trang/chân trang được dịch và bất kỳ liên kết nào khác có bản dịch).

Khi các bản cập nhật được phát hành lên nội dung tiếng Anh, quy trình bản địa hóa của chúng tôi sẽ hoạt động để cập nhật các phiên bản đã bản địa hóa càng sớm càng tốt – thường là trong vòng vài ngày sau thay đổi ban đầu. Bạn có thể xem danh sách đầy đủ các ngôn ngữ được hỗ trợ trong chân trang của Microsoft Learn (chọn trên ngôn ngữ bạn đang xem). Mỗi ngôn ngữ trong số này có thể được truy vấn bằng API Ca-ta-lô Học tập bằng cách sử locale lọc.

Hồ sơ hoàn thành nội dung đào tạo của chúng tôi là miền địa phương- agnostic, có nghĩa là, chúng tôi không phân biệt các phiên bản nội dung được bản địa hóa dưới dạng các đối tượng riêng biệt trong hồ sơ hoàn thành đào tạo người dùng của chúng tôi. Cho dù người dùng hoàn thành đào tạo bằng ngôn ngữ nào, họ vẫn sẽ nhận được tín dụng cho đối tượng tổng thể và chúng tôi không lưu trữ tham chiếu đến ngôn ngữ đã hoàn thành. Hoàn thành locale-agnostic này có nghĩa là nếu bạn thực hiện API Danh mục Learn trong trải nghiệm học tập của mình, bạn cần tính đến điều này và nếu bạn tải các đối tượng nội dung dưới dạng đối tượng riêng biệt, hãy thực hiện sự tương đương giữa chúng để cho dù người dùng hoàn thành đào tạo bằng ngôn ngữ nào, họ sẽ nhận được tín dụng cho đối tượng bằng các ngôn ngữ khác và không phải lấy lại nó.

Tìm hiểu cách lập phiên bản nội dung hoạt động trong Tìm hiểu và cách nội dung được phản ánh trong đầu ra API

Đáng chú ý là nội dung đang được cập nhật liên tục. Chúng tôi phát hành các bản cập nhật khả dụng hai lần một ngày. Chúng có thể nhỏ, chẳng hạn như thay đổi văn bản phụ hoặc chính, chẳng hạn như hiệu đính, bổ sung hoặc xóa chính. Nói chung, danh mục nội dung được quản lý như một dự án mã nguồn mở lớn, được quản lý cao với hàng ngàn người đóng góp, và như vậy, thay đổi đang diễn ra mọi lúc. Nếu bạn sử dụng API Danh mục Learn trong hệ thống sản xuất của mình, bạn nên biết điều này và có thể xử lý hệ thống của mình.

Khi các đối tượng nội dung mới được thêm vào, chúng sẽ xuất hiện dưới dạng một đối tượng mới (được xác định bởi UID) trong phản hồi. Khi nội dung được sửa đổi, bạn có thể biết dựa trên giá last_modified của nó. Khi nội dung bị xóa, đối tượng nội dung sẽ bị loại bỏ khỏi phản hồi. Mặc dù đôi khi có một chút chậm trễ về nội dung được cập nhật trong phản hồi API, khi người dùng tuân theo URL đến nội dung, họ sẽ luôn thấy thông tin mới nhất. Trong trường hợp xóa, URL cũ sẽ chuyển hướng đến nội dung hoặc trải nghiệm mới hoặc đến tùy chọn tốt nhất tiếp theo.

Không có tham chiếu đến các phiên bản nội dung tại thời điểm này ngoài ngày last_modified nội dung.

Làm mới dữ liệu thường xuyên

Nếu bạn đang sử dụng thông tin ca-ta-lô từ API Danh mục Learn để hỗ trợ các quy trình kinh doanh của bạn hoặc hiển thị cho khách hàng như là một phần của trải nghiệm site của bạn, hãy đảm bảo rằng bạn làm mới nội dung ít nhất một lần một ngày.

Xem lại các đề xuất về tài liệu dành cho nhà phát triển

Tài liệu dành cho nhà phát triển API Danh mục Tìm hiểu có danh sách đầy đủ các dữ liệu được cung cấp như một phần của phản hồi và đề xuất về cách từng trường được khuyến nghị sử dụng để hỗ trợ trải nghiệm học tập tuyệt vời.

Hiểu lô-gic truy vấn

Có sẵn nhiều bộ lọc để sử dụng để lọc trước phản hồi, để bạn chỉ có được những gì mình đang tìm kiếm và có thể xử lý kích cỡ tệp nhỏ hơn. Bạn có thể xem danh sách đầy đủ các bộ lọc truy vấn trong bài viết tham khảo api danh mục nhà phát triển. Đáng chú ý, bạn cần phải tạo truy vấn chính xác và nếu bạn đang sử dụng nhiều tham số truy vấn trong yêu cầu, truy vấn sẽ được đánh giá bằng toán tử AND.

Các bước tiếp theo

Để biết thêm thông tin hỗ trợ bạn về API Danh mục Learn, hãy xem lại các bài viết sau:

Last updated on 2025-02-18